Documentation to assist with the setup and configuration of the HaloITSM platform
The first thing to consider when connecting to a 3rd party API is 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.
There are several different Authorization methods available - based on the Auth method you select, you will find the relevant fields dynamically appear:
For our example, we will use the Bearer Token auth method:
Once you have saved your Custom Integration, the Methods tab will become available.
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.
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:
Click 'Test' to make sure you get a successful response & to check the response body:
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:
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:
Now when testing my method, I will also be able to see what my Output Variable returns:
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':
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:
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':
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:
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:
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:
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.
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:
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Syncing Exchange Calendars