<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><p id="isPasted"><strong>In this guide we will cover:</strong></p><p><strong>- Introduction</strong></p><p><strong>- How to trigger a Runbook from the chatbot</strong></p><p><strong>- Use Chat Data in a Runbook</strong></p><p><strong>- Keep the User updated on Runbook progress</strong></p><p><strong>- Auditing the Runbook</strong></p><p><strong>- Restrict the chat progress based on Runbook Result message</strong></p><p><br></p><p><br></p><p><strong>Related Guides: </strong></p><ul><li><strong><a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2335" id="isPasted" target="_blank" rel="noopener noreferrer">Chat Bot and Chat Profiles</a></strong></li><li><strong><a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2336" id="isPasted" target="_blank" rel="noopener noreferrer">Virtual Agents in the Chat Bot</a></strong></li></ul><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">Introduction</span></strong></p><p>From versions 2.188+ of Halo you can have a runbook execute when the chat reaches a certain step. Being able to trigger runbooks from within a chat profile increases the functionality and customisation available for the chat bot. </p><p><br></p><p>This can be beneficial for agent chat profiles as it provides an easy and accessible way for agents to trigger automations in your instance. This can be beneficial for users as they can trigger automations themselves based on their request. For example, if you have an automation runbook that retrieves data from an external application/integration, this runbook can be triggered when a user requests information from this application through the chatbot. </p><p><br></p><p>Runbooks can also be triggered from chats using AI Virtual agents, for information on virtual agents and how to utilise these to trigger automations see our guide <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2336" target="_blank" rel="noopener noreferrer">Virtual Agents in the Chat Bot</a>. </p><p><br></p><p><strong><span style="font-size: 14pt;">How to trigger a Runbook from the chatbot</span></strong></p><p>A runbook can be set to be executed at a set step of the chat profile, therefore you will need to configure this step to execute a runbook. </p><p><br></p><p>Open up your chat profile (configuration > chat > chat profiles > select profile) and head to the bot flow tab. From here add or edit the step you would like the runbook to be triggered at. </p><p><br></p><p>The step will need to have 'Type' action, then you can select the action type 'Execute a Runbook'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI1OWRkOGYyLWNlZjgtNDc4Zi1hZWU1LTgwNjYwYWRlYWNkOSJ9.tf-oBWdaTo5Im9ogLSka0l8iHICJZVeej2qQaJNAOck" class="fr-fic fr-fil fr-dib" width="1380" style="width: 1382px; height: 702.893px;" height="703"></p><p><strong><span style="font-size: 10pt;">Fig 1. Chat step to trigger a runbook</span></strong></p><p><br></p><p>Now you will be able to choose which runbook is triggered at this step. </p><p><br></p><p>The chat will then move to the next step based on the outcome of the runbook, whether it is successful or unsuccessful. Set where the chat profile moves to following the runbook execution under the 'outcomes' section of the chat step. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM2ZjljNmM5LWNmZWYtNGM2Ny1iYzMyLTJiN2YxMWVjN2FhZCJ9.AmD9G_B0m_mFHFguXPinfF32R-Q9tU-cE8-RHL-GYAI" class="fr-fic fr-fil fr-dib" width="1243" style="width: 1245px; height: 495.598px;" height="496"></p><p><strong><span style="font-size: 10pt;">Fig 2. Outcomes of step </span></strong></p><p><br></p><p><strong><em>Note: As the chat can only move on based on the outcome of the runbook, the chat flow will not progress until the runbook has finished running. Therefore, we recommend only triggering short runbooks from end user chats as users will have to wait for the runbook to complete before continuing the chat flow. Shorter wait times will reduce the number of abandoned chats. </em></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Use Chat Data in a Runbook</span></strong></p><p>When a runbook has been triggered from a chat profile, properties of the chat can be used as variables in the runbook, allowing chat specific information to be used as part of the automation. </p><p><br></p><p>The variables that are available for chat data within a runbook are visible against the method within a runbook step by toggling the 'Available Variables' menu. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVmYmE4Mjk2LWNjN2EtNGM0Ny1hZDlmLTE3NGYyYTkyZmE0MCJ9.z7DXH7AtWpg7fh6qHcG2UkwwcPtNHJ0dRWoh3-GodNQ" class="fr-fic fr-fil fr-dib" width="1300" style="width: 1302px; height: 586.182px;" height="586"></p><p><strong><span style="font-size: 10pt;">Fig 3. Chat variables available against runbook method</span></strong></p><p><br></p><p>For example, if this runbook is being used to allow users to update entities in another application (external to Halo) you may want to push the chat properties over to the application as part of the update, to ensure you have a record of where the update came from. </p><p><br></p><p><strong><em>Note: Ticket and customer variables will also be available for runbooks triggered from chat if the chat is linked to a ticket, and the user who logged the chat is authenticated (not an anonymous user or agent chat) (respectively). </em></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Keep the User updated on Runbook progress</span></strong></p><p>Whilst the runbook is running you can keep the user updated with progress by adding more messages to the chat from the runbook using the new "Add Live Chat Message" Halo API Action. Utilise this to add a new message to the chat from the bot every few steps whilst the user is waiting for the runbook to complete.</p><p><br></p><p>To do this you will need to add additional steps to your runbook with type 'Action'. Then set the 'Action Type' to be 'Halo API Action' and the 'Action to be 'Add Live Chat Message'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZmNTgyMGNiLTg5YzgtNGNiNS1iMTlkLTI3NGFkMzg3NzI3NiJ9.kpLWY16gAH1laNSK50l_rzirz5n6GcleBReYE33cH8o" class="fr-fic fr-fil fr-dib" width="1185" style="width: 1187px; height: 630.44px;" height="630"></p><p><strong><span style="font-size: 10pt;">Fig 4. Runbook step to post a message into the chat</span></strong></p><p><br></p><p>In the JSON Body you can configure the message that will be posted into the chat. When this action is selected the JSON body will populate automatically with the content shown in figure 4. Line 2 of the body should not be edited as this is used to post the message to the chat that triggered the runbook. Line 3 should be edited to contain your desired message. </p><p><br></p><p>Now, each time the runbook reaches this step, this message will be posted into the chat with the user, and the runbook will continue to run. </p><p><br></p><p><strong><span style="font-size: 14pt;">Auditing the Runbook</span></strong></p><p>Runbook result messages can be posted into the chat or associated ticket to assist with auditing. This is useful for agent chat profiles as it allows agents to easily when the runbook automation has failed along with a message/reasoning for failure. </p><p><br></p><p>Any runbook steps with the type 'End' are classed as the end of the automation, result messages are set against this end step. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzN2Q5MTc0LTkzMzgtNGQ1OS05Y2VmLWU5MzliMmYxYTFkZiJ9.WY45PmqtjyQUSbKdtr4mF3vNKsVmpf1fSE9K5AsfOfs" class="fr-fic fr-fil fr-dib" width="1348" style="width: 1350px; height: 669.901px;" height="670"></p><p><strong><span style="font-size: 10pt;">Fig 5. Result message against end step of runbook </span></strong></p><p><br></p><p>Your runbook will have multiple end steps, for each point in the flow that the automation fails or completes. You can set a result message against each step to provide more detail about when the automation failed. </p><p><br></p><p>If this runbook is set to advance the workflow against a ticket, the result message against the step the runbook ends at will be added to the ticket as a note action (or as a note within the configured action). In the context of chat, this result message will only be added to the ticket that is linked to the chat, if a ticket has not been raised from the chat, the result message will not be posted. </p><p><br></p><p>However, you can have runbook result messages posted into the chat as a message. This can help to notify the agent/user of failures/issues in automations without them having to navigate away from the chat screen. This is done using the variable $RUNBOOKRESULT . </p><p><br></p><p>$RUNBOOKRESULT will return the result message of the last runbook run for the conversation, so the user/agent will be able to see the result message for the step the runbook failed on. </p><p><br></p><p>To make use of this, add a step to your chat profile, following the step triggering the runbook, that posts a message into the chat containing this variable. As shown in figure x. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjRlODk4NGMyLTkyNDUtNDQyNi1iN2MyLTk1YTY4Yzk1NmMyOCJ9.T48SskqbovY7lj5q8Qil5pFf1vnUs_ZqIjqT7hGuZ-Q" class="fr-fic fr-fil fr-dib" width="953" style="width: 955px; height: 611.512px;" height="612"></p><p><strong><span style="font-size: 10pt;">Fig 6. Chat profile step to post message into chat containing the result message of the runbook</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Restrict the chat progress based on Runbook Result message</span></strong></p><p>The flow or progress of the chat can also be restricted based on the data that is pulled from the variable $RUNBOOKRESULT. This is done by adding a condition step to your chat profile in which the field 'Runbook Result message' is checked. </p><p><br></p><p>In the figure 7 example if the runbook result message contains the string 'failed' the chat flow will move back to step 1. However, if the runbook result message does not contain this string, the chat will continue to the next step. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY2YjA3YTIxLTFlOTMtNGIyZS05MjJkLTlhMDhlYjJiNDFhOSJ9.d6E7X4nOK29ew72eSCAxzyVWq4RSqjzQIi29mR-vg14" class="fr-fic fr-fil fr-dib" width="1600" style="width: 1602px; height: 778.75px;" height="779"></p><p><strong><span style="font-size: 10pt;">Fig 7. Condition in chat flow based on Runbook result message</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Additional Points to Note</span></strong></p><p>Runbooks triggered from a chat profile cannot be retried, so any runbooks executed this way should complete in a single attempt. </p><p><br></p><p>Longer running runbooks should use the Asynchronous runbook method to run the runbook in the background whilst the conversation continues, to prevent the user having to wait for prolonged periods. You can then notify the end-user that it has completed via the ticket using an email action for example.</p>
