HaloCRM Guides

Example Video

The following video contains the theory and practical applications of creating an iterative runbook.

 

Runbooks can be used to iterate through an array of data. This can be acheived by following the guide below. The first thing to consider when configuring runbooks is the authorization of the API.

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

For the purposes of this guide, the custom integration will be integrating with Halo, to do this, first head over to Configuration>Integrations>Halo Service Desk API>Applications and click "New" on the top right:

Read the below instructions before configuring your API Application:

Creating an API Only Agent:

In Halo, navigate to Configuration > Teams & Agents > Agents and create an Agent that you will use for the integration.

Make sure the Agent has the Administrator Role, as displayed above.

It is also important to turn on API-only Halo Agent (This is found just below the roles input on the details tab of an agent (Beware that API-only Agents may not log into the Web or Mobile Applications nor can they be assigned tickets. However, they do not take up a licence).

Now Input the following into your API Application

• Name (arbitrary)
• Client ID and Secret (Services)
• Generate (Generates a new client secret, must be done when creating a new custom integration)
• Copy (Copies the client secret to clipboard)
• Login Type: Agent
• Agent to log in as (Pick an agent)
• Permissions:
  

Custom Integration

The next step is to create a new custom integration in Configuration>Integrations>Custom Integrations, this is how the Halo instance is connected to the runbook and how the API can be used to GET or POST things in halo.

The following credentials should be set:

Input the following:

• Base Resource URL: Your Halo instance URL i.e. https://[Your Halo Domain].com
• Authorization: OAuth 2.0
• Authorization header name *LEAVE BLANK*
• Header Prefix: Bearer (Should already appear as "Bearer")
• Grant Type: Client Credentials
• Access Token URL: https://[Your Halo Domain].com/auth/token?tenant=[Your Tenant Name],  The tenant_id can be found by going to: 
  • https://[Your Halo Domain].com/api/instanceinfo (look for the key value pair "tenant_id"  :  "[Your tenant_id]" )

Found here:

• Client ID (Found in the Halo API Application created)
• Client Secret (Need to paste it from clipboard) NB: If the custom integration doesn't work when saving, you may need to input a new client secret by generating a new one in the Halo API Application
• Scope: all

Creating a Method

Switch to the "Method" Tab on the custom integration and this should be the view:

This worked example is for creating a runbook that returns a list of clients on a Halo instance. In the text box beside the Halo domain, input /api/client:

In the above photo the name of the method is "Get Clients" and the API method has been set to "GET"

The next thig to do is set the output variables, again solely for this example the output variable is:

"response" must be the prefix of all output variable values that are inputted. This "Value" shown above translates to access the response of the GET on the clients, then get all of the properties of type clients within that GET, the "^" refers to a child property of an object.

Integration Runbooks

Now that the custom integration is set up and the method has been created. The next step is to create the runbook. Click into the "Integration Runbooks" button on the main page of custom integrations.

The first step to make in the runbook is the method step, this will pull in the arrays we have accessed from the output variable of the method:

NB: The "Move to Step" will change after the step has been created to reflect the correct flow. Make sure to mark this as the start step.

Next pick the step which has tailed of from the successful outcome, and configure it in the following way:

The array iteration start is the first step in iterating through the array we got from the method step. For context "!" denotes getting the value of the name property.

If the array has no elements it will be sent to a different step as nothing was returned:

The next configurable sep will be set up the following way:

This is making an action to GET the name element in the form of a note field in Halo. 

NB: The "note_html" section has the value "<<Name>>" this is the output variable from step 2 and it is placed in quotations ("") so that Halo can process it correctly.

Iterating through the runbook

In order to iterate through the runbook we add an end step and this then knows to connect back to our original start iteration step. This will then continue to run until no more elements are found in the array based off of the criteria set.

This step should look like the following:

This step defines which array to iterate through, and because the action type is set to "Array Iteration Next/ End" it knows to iterate through.

Here is a high leveloverview of the entire runbook, notice the steps that the program will be sent to if the step fails/ returns no elements:

This concludes the setup of the runbook for iterating through an array.

Example of the Outcome

Click into the "Log" tab of the runbook and then click into a log, you can see the different logs that were returned:

The top 3 responses on the log represent the customers being pulled from the array and onto an action, the bottom response (which is the first one) is the GET on the clients array.

An array will not be visible if the method "Test" doesn't return anything.

Runbook Scheduling

Runbooks can now be scheduled, similar to other scheduling services in Halo, there are many ways to configure this schedule. For this service to be available, the scheduling service on Halo must be enabled, it can be configured under Configuration > Advanced Settings:

In order to run the schedule daily, the schedule can be set up the following way, where the start date and time are arbitrary:

NB: 

Runbooks that run via a schedule cannot access Ticket variables or Input variables, so they are only suited to tasks which fetch data from an API on the first step, and then do something with that data. Runbooks that do not depend on Ticket or Input variables can now be tested from the config screen from the Schedule settings area.

Extra Information

• Each path of the runbook flow after an Array Iteration Start step must finish up at either an Array Iteration Next/End step or an Array Iteration Break step for the same runbook variable that the iteration was started for.
• Array Iteration Next/End allows you to continue on to the next element in the array. This step will go back to the Array Iteration Start step but move on to the next element in the array. Once all elements have been iterated the runbook flow will proceed to the next step after the Array Iteration Next/End step.
• Array Iteration Break allows you to escape the array iteration without reaching the end of the array. Use this if you're looking for a particular value in an array, rather than operating on the entire array.
• Array iterations can be nested inside other array iterations.
• Array iteration steps are shown in Orange on the diagram.