HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Custom Integrations/Runbooks
In this lesson we will cover:
- Videos on Runbooks
- Building blocks of runbooks
- Worked Example
- Actions that can be completed through the API
- Using Previous output variables in subsequent steps
Step By Step Videos
The following video series (Part 1 attached below) contains the theory and practical applications of custom integrations/ runbooks. This video is Part 1 of the 4 Part series by Connor from Renada, where he explains how to setup runbooks by using a worked example.
This video is by Rising Tide Consulting and it covers runbooks, looking at the Halo API actions that can be used on Halo, there are also many other useful videos on both of the youtube channels featured on this guide.
The first thing to consider when connecting to a 3rd party API is Authentication.
The Building Blocks of Runbooks
Authentication
Head to Configuration>Integrations>Custom Integrations & create a new Custom Integration. When creating a new Custom integration, you will be prompted to input:
- A Name for the Custom Integration.
- Base Resource URL.
- Authorization.
Fig 1. New custom integration
There are several different Authorization methods available - based on the Auth method you select, you will find the relevant fields dynamically appear:
Fig 2. Authorisation method for application
For our example, we will use the Bearer Token auth method:
Fig 3. Bearer Token method
Once you have saved your Custom Integration, the Methods tab will become available.
Methods
Methods define a series of different API requests that can be made for a given custom integration. Each Method allows you to
- specify a HTTP Method (GET, POST, PUT etc..)
- Send requests to a particular endpoint.
- Include Query Parameters for the requested resource.
- Include request headers, and a request body (if the HTTP method permits).
- Specify Output variables, which can be used further on down the road.
Fig 4. Method
In the below example, I am making a request to the Completions endpoint of OpenAI's API. Authentication is already handled by the fact that I have selected my 'Integration' as 'OpenAI' (& already added in the bearer token in the previous step). As I am making a POST Request, I am permitted to include a Request Body:
Fig 5. Request body example
Click 'Test' to make sure you get a successful response & to check the response body:
Fig 6. Response body following test
Output Variables
The chances are you are not going to want the entire response body, but only particular parts of the response. In the above example, I'm really only concerned with the 'Text', within the 'Choices' array.
Output variables can be used at this point, to define a particular part of a response body:
Fig 7. Output variables example
There are some details in this window outlining the required syntax, the key points are:
- Variables must start with response.
- Child properties are referenced using ^
- Arrays can be indexed using [x]
- Conditions can be added to return a specific object in an array where prop=value via [prop=value], i.e: response[id=123]
- Append ! to your variable value to remove the leading/trailing " character from the value.
Continuing with the above example, I am looking to return the 'Text' from the 'Choices' array of the response. So my output variable would look like:
response^choices[0]^text
Now when testing my method, I will also be able to see what my Output Variable returns:
Fig 8. Output variable in response body
Worked Example- Post a response from ChatGPT into the ticket
Now we have an understanding of the building blocks towards creating a 'Custom Integration' (i.e: we can make requests to protected endpoints and create output variables from response data), let's look at tying multiple methods together via Runbooks.
Runbooks are similar to Ticket Workflows, in that you have a flow chart composed of 'Steps'. The core difference is instead of each step containing Ticket Actions, they contain Custom Integration Methods.
Let's build on the previous example to create the following functionality:
"I want to create an Action - 'Ask ChatGPT a Question' - that takes the contents of the note field from the action as the question/prompt and posts ChatGPT's response back to the Ticket"
Functionally, this would be composed of 2 Methods:
- An initial POST to OpenAI's API
- We will want to do this from a Ticket via an Action & set the Prompt based on the Action text.
- A Post back to our own API
- This Post should create an Action on the same ticket with the text being OpenAI's response text to our Prompt.
We have already seen how to create the first request, the only difference would be that our prompt should now take the note of the Action it will be triggered from. This can be handled by using a variable for the 'Prompt':
Fig 9. using variable for prompt
To POST back "ChatGPT's" response to the Ticket in question, you would have to create a 'Custom Integration' to your own instance's API:
Fig 10. create new custom integration
The method required for this example would be a POST request to '/api/actions', passing in the Ticket ID as a variable & utilising the previously created Output Variable - 'ResponseText':
Fig 11. Method required
So we now have the two methods required for our 'Integration', next is to tie them together in a Runbook.
Head to the 'Integration Runbooks' section of the Custom Integration configuration. Upon creating a new Runbook, you will first be presented with the 'Details' tab. In here, you can establish a 'Runbook Start Access' & specify events that can occur in Halo that would trigger the Runbook:
Fig 12. Runbook start access
Runbook Start Access has two options:
- Can only be Started from Halo - This option will mean that Runbooks can only be triggered from an Action, Event or Workflow.
- Can only be Started from Halo and from a public Endpoint - When this option is selected, some new configuration options will be presented:
Fig 13. Runbook can only be Started from Halo and from a public Endpoint
Firstly, a url will be presented. This is the URL that would need to be called, if triggering the runbook from outside of Halo. this url will only accept POST requests. N.B: If triggering a runbook from an extenral source, Ticket variables cannot be used.
You can also specify an authentication method required for the POST to this endpoint. Current methods include Basic Auth & Signature Validation via Secret Key. Below this Authenitcation opion, you will see an 'Input Variables' table - this table will allow you to create variables from the initial payload of the POST request, that can be used in subsequent methods within the Runbook (the variables established here are only valid when the Runbook is triggered from the external source).
You will also see a 'Flow Chart' tab - this is where you construct the Runbook logic. Similar to Ticket Workflows, the Flow Chart of a Runbook is composed of 'Steps', where each Step corresponds to a Condition or Integration method. Conditions being met or integration Methods returning successful responses can then move the runbook to a new step in the flow chart.
Lets look at the Runbook Flow Chart for our Custom Integration:
Fig 14. Runbook flow chart
Again, our custom Integration is composed of two methods:
- An intial POST to OpenAI
- A POST back to our own API with ChatGPT's response.
So we can see here that our initial step, 'Ask Question', is configured such that we are executing an Integration Method - Post Completions. If we get a successful response, we then move on to our next step.
Fig 15. Step example
In the next step, we are executing a different method - 'Post ChatGPT Action to Ticket'.
Finally, we need to see how the Runbook is actually triggered. In this example, we are Triggering the Runbook from an Action in Halo. The Action is configured such that the System Use is 'Queue Webhook/runbook', at which point you can select the Runbook to queue:
Fig 16. Runbook trigger
Halo API Actions
Direct changes can be made to your Halo instance via runbooks. The following can be achieved by using the Halo API action on a runbook step:
These are the actions which can be added to a runbook
- Create Customer
- Edit Customer
- Create site
- Edit Site
- Create User
- Edit User
- Create Asset
- Edit Asset
- Create Lookup
- Edit Lookup
- Create Knowledge Base Article
- Edit Knowledge Base Article
- Edit Custom Table Data
- Create Ticket rule
- Edit Ticket Rule
- Get Control (Global Settings)
Action Configuration
This can be configured within the runbook step by using the following:
Fig 17. Action configuration
After the action has been set on the single select field "Create Customer" The name can be added to the JSON (The JSON will auto populate based on the action chosen)
The next step is to create an action to execute the runbook (make sure to add this to the workflow if your ticket contains one, or add it to the Allowed actions if there are restrictions set on actions):
Fig 18. Action to execute Runbook
Then this can be actioned from a ticket to create the customer:
Fig 19. Using action to execute runbook
Checking our customer list, we can see that the new customer is there:
Fig 20. New customer made
Another type of action that can be achieved could be the one explained in the rising tide video on this guide, it covers "Marking a ticket as spam via a runbook". This is achieved using the "Update Ticket" action shown in the Halo API actions list above.
All of the keys that can be added to the "Actions" JSON Body can be found in the dev tools using "Fn + F12"
Fig 21. Keys visible in dev tools
An example JSON Body for creating an action via a runbook, as you can see the "note_html" on the dev tools is shown on the JSON Body as well, this is where the note would go for the action being created:
Fig 22. Example JSON body for creating action via runbook
Use Previous output variables in subsequent steps
There is the ability to use previous output variables from custom integration methods, as part of the subsequent steps:
Set up a custom integration runbook and create a method for it. Then use this variable in a subsequent method of the runbook. Adding the custom integration method's variable here:
Fig 23. Custom integration method's variable
Then use the custom integration variable as part of the next method:
Fig 24. variable being used in following method
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments and Teams
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers