HaloCRM Guides

Custom Integrations/Runbooks

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.

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.

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

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:

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:

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:

Integration Runbooks

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:

Halo API Actions

Direct changes can be made to your Halo instance via runbooks. The following can be acheived 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)

Configuration

This can be configured within the runbook step by using the following:

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):

Then this can be actioned from a ticket to create the customer:

Checking our customer list, we can see that the new customer is there:

Another type of action that can be acheived 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 acheived 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"

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:

As of v2.153

There is the abiltiy 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: