HaloPSA Roadmap

Custom integrations and Integration Runbooks are now available

Custom Integrations & Integration Runbooks allow you to define your own set of API calls to third-party applications and chain them together using the results of the previous API calls.

A new "Custom Integrations" config area has been added to Config > Integrations. Here you can configure 3 new entities;

• Custom Integration: this record holds a collection of Methods, and defines the authentication used for each Method.
• Method: this is a single API call where the request can be customised
• Integration Runbook: this contains a workflow (similar to the Chatbot flow) that the automation follows, and includes steps to either execute a method or advance based on Conditions.

Custom Integrations

The Custom Integration record acts as a group for methods and is where Authorisation on its methods is defined. A base URL for all methods in the Integration can also be set here. The available Authorization types are;

• None
• API Key
• Bearer Token
• Basic Authentication
• OAuth2 - Client Credentials, Password Credentials or Authorization Code
• Signature with X.509 Certificate
• Signature with a Secret Key

Methods

In a Method you can choose between a HTTP GET, POST, PUT, PATCH or DELETE, and customise the Url, Query Parameters, Request Headers, Authentication (inherited from the Custom integration record), the Request Body and Define output variables. The available content types for the body of a method are;

• None
• Json
• XML
• x-www-form-urlencoded
• Plain

Variables can be used in any part of the request. These variables are separate from ordinary $-variables, and start and end with << and >>. Variables include the Halo API json response for the /tickets and /actions endpoints and nested properties in those responses, and the responses of other methods that have been run already in the Runbook. Available variables show on the right-hand side of the method config screen and are split into categories. You can click a variable to insert it to wherever you are typing.

These variables accept a few different operations to access nested objects/properties and array indexes in a response;

• ^ can be used to access a property of an object
• [x] where x is an integer can be used to access a specific index of an array
• [id=value] where id is a property name in an object in an array and value is a value can be used to find a specific object in an array
• ! can be used at the end of a variable to remove start/end string characters from the variable output

For example, if a ticket level field doesn't show in the variables list you can still access it using knowledge of the Halo API, E.g <<ticket^tickettype^name>> will give the ticket type name.

Each method automatically has a variable which represents the entire response of the request, but more variables can be defined in Output Variables for a method. This allows you to create an easy way of accessing a particular value from a response across the runbook without typing out the full calculation, and Conditions in a runbook can be based on these Output variables.

In the example screenshot above, this will assign a nested property called summary in the response of the method to the variable <<ResultSummary>>, and the value of <<ResultSummary>> can be used in Integration Runbook Conditions and other Methods in the same runbook.

The method config screen has a test button, where variable values can be manually input to try out different values for variables.

Integration Runbooks

In an Integration runbook you can define the following types of steps;

• Condition: create a set of conditions from either Variable value or Ticket field values, and advance the flow based on whether the condition is met or not. These conditions are like rule criteria, with some additional rule types specifically for Runbooks.
• Action: Execute a method, and advance the flow based on whether a response with a status code between 200-299 was returned or not
• End: The end of the runbook has been reached.

Custom Integrations and methods can be added and modified on the Runbook config screen as you go. As you add methods to a runbook a set of Runbook-level variables will become available on the Method details screen showing which variables are accessible in that Runbook, and Conditions will only contain variables for methods in the runbook.

Integration runbook's run in the background using the same engine as Action Automations, with a queue and retries on failure.

An integration runbook can be started in a few different ways;

1. From a Workflow, choose an Automation and choose the type of Integration Runbook instead of the usual Quick action automation. This can be used to advance a workflow upon completion of the runbook.

2. From an Action, you can use the system use "Send Webhook/Queue Automation" and the Runbook will be queued when the action is done.

3. From an Event, in the same way that a Webhook can be queued from an Event, such as "New Ticket Logged". This is configured from the Integration Runbook config screen.

4. From a third party. In the Integration runbook config screen, you can choose to expose an API URL to start the Runbook, which allows third-party apps to start a Halo runbook by doing a HTTP POST to that URL. This URL can be protected with Basic Authentication, or by Verifying a signed payload with a Secret Key (No authentication is not recommended for use in production).

When using method 4, since there is no Ticket linked to the runbook, you can instead use the initial payload that started the runbook as a variable and define more variables based on this on the Integration Runbook config screen. Using this method you can get Halo to accept webhooks from a third party by adding Halo as a custom integration.

Request logs can be viewed from the Integration Runbook, a Method, or an Automation record. The new entities have change tracking enabled and can be exported to/imported from JSON. Minor improvements to Webhooks and other related features have also been made.

Requires NHServer v13.55+ for compatibility for queueing from a workflow when using email.

The Process Street Integration is now available

To setup this integration, enable the module and navigate inside to acquire the URL and setup the two mandatory fields:

Then navigate to Process Street > your organisation > Settings > Integrations > Webhooks and enable webhooks and send them to the URL you copied earlier:

Any combination of the options will be accepted however we would recommend "When a workflow is run" as a minimum so tickets are created when workflows are created.

Redesigned the Facebook integration

Each Facebook page that you connect to can now turn direct messages and page posts into tickets.

Direct Messages:

By enabling the creation of tickets via direct messages, your Facebook page will be automatically subscribed to webhooks that will be sent to your Halo instance.

An action can be created with a system use of Reply to Facebook Message/Post. This action can be used to send a reply via Facebook on tickets created from both direct messages and also page posts.

An option has been added for each connected Facebook page to decide whether or not a ticket should be reopened if the same user sends another direct message to your account.

Page Posts:

Similarly to direct messages, by enabling creation of tickets from Page posts, your Facebook page will be automatically subscribed to webhooks that will be sent to your Halo instance.

Tickets can be created from posts that are created by users, your page, or both.

Any comments added to the post will then be converted to actions and added to the ticket.

You can set a limit on the number of days after a post is created for comments to continue to be threaded to the ticket. You can also choose to include/exclude certain posts by adding them to a list of words/phrases.

If a comment has been added to a comment, the action will show a thread for the reply chain. You can reply to individual replies by selecting the Reply to Comment option on the action: 

This option doesn't show for the initial message - to reply to the initial message, you must use an action that has a system use of Reply to Facebook Message/Post.

You can also move a comment to a separate ticket. Any future replies in the chain for that reply will then be added to your new ticket.

All legacy functionality for the Facebook integration has now been removed.

Added Jira Service Management integration

A Jira Service Management integration is now available, which allows the creation of requests and actions in a customer's/supplier's Jira Service Management instance, as well as syncing back any updates to the request.

Configuration

The integration needs to be enabled from the integration configuration area, but the credentials and field mappings are configured per customer/supplier.

Once the integration is enabled, a Jira Service Management tab will appear on the customer/suppliers details page. Here you can enter the credentials for their instance of Jira Service Management. These credentials must be validated before setting up any of the mappings.

Once validated, you can configure mappings for request type, priority, and status, as well as a default reporter and service desk for the requests.

There is also a button to automatically create the in the Jira Service Management instance.

Syncing to Jira Service Management

Customers

To sync requests, you can create an action with the system use 'Send ticket to Jira Service Management'. This will send the current ticket to the Jira Service Management of the customer of the ticket. Only one incident may be linked to a ticket at a time. If the 'Send ticket to Jira Service Management ' is used again the existing link will be overwritten.

The user of the incident will try to match on the email of the ticket in Halo but will fall back to the default if one with that email does not exist in Jira Service Management.

To send an action to the Jira Service Management request, you can create an action with the note and 'Sync to Jira Service Management' fields. There is a default setting at the action level for the 'Sync to Jira Service Management'  checkbox. If checked, the action will be sent to the linked request. If the action is private it will be private in Jira Service Management.

No other updates to the ticket in Halo will be synced to the incident in Jira Service Management.

Suppliers

The suppliers function similarly to the customers, except instead of requiring the specific Jira Service Management system use and field, the request will be created when using the 'Log to Supplier' system use if the selected supplier is connected to Jira Service Management. Similarly, actions can be sent to the request by using the 'Email supplier' system use if the supplier linked to the ticket is connected to Jira Service Management.

Syncing back to Halo

To sync updates back to the linked tickets, webhooks must be configured in Jira Service Management. Only updates to tickets created from Halo will be synced back. This will include all the mapped fields, as well as any comments that were added.

Improvements to the Azure DevOps integration

The following functionality is now available in the Azure DevOps integration:

1. You can now connect to multiple Azure DevOps instances. This has involved a redesign of the integration's configuration screen.  

2. The product and release setup screen now has an Azure DevOps tab. Here you can manually link a Halo product to an Azure DevOps instance and project. You can also create field mappings for the project if custom field syncing has been enabled for the linked instance.

3. Webhook usernames and passwords are now stored in a different way. Any previous usernames and passwords will continue to work. The existing username and password configuration for the integration can be removed at any time by navigating to Config > Integrations > HaloAPI > Applications and removing the Azure DevOps application.

4. All inbound webhooks from Azure DevOps are now recorded against the Azure DevOps instance record. They are maintained for 2 weeks before being removed.

You can click into each request to see more details about the webhook that was received, including the request body and headers.

5. All outbound POST/PATCH requests sent from Halo to Azure DevOps are now recorded against the Azure DevOps instance record. They are maintained for 2 weeks before being removed. You can click into each request to see more details about the request that was sent, including the request body and headers and the response from Azure DevOps.

6. Fixed a few minor bugs with creating field mappings on the product screen.

The Etilize Integration is now available

Improvements to the Microsoft CSP integration to support GDAP relationships, along with various other improvements

The Microsoft CSP integration now requires 2 Azure applications to be created. The first application is used to retrieve data from the Microsoft Partner Center, and the second is used to retrieve data from your partner tenants' Azure Active Directories and Intune.

Once you have connected to your application that has been created for the Partner Center, additional instructions are displayed showing how to create the second application for Azure Active Directory and Intune.

Above the tenant mapping table, you can now choose a default relationship type for any new mappings. The relationship type can also be selected when manually adding a tenant mapping.

When GDAP is selected as the relationship type for a tenant, a Grant Admin Consent button will show in the mapping table for that tenant.

Clicking this button will open the Microsoft login screen on a separate tab. By logging in as an administrator of the tenant you are granting admin consent for, your Azure application will be registered as an Enterprise Application in your partner's Azure tenant and admin consent will be granted for the application permissions you have added to the Azure application. This process must be completed for any customer you share a GDAP relationship with in order to retrieve any user or device data from that customer.

These changes are backward compatible, meaning the existing setup of this integration will continue to work after upgrading to a version with these changes. 

Other improvements/fixes are as follows:

1. User licences retrieved during the user import are now retrieved from the Microsoft Graph API rather than the Partner Center API to improve the speed of the import.

2. Added additional instruction steps to the Azure Active Directory and Intune tabs in case a customer wishes to enable additional functionality in the future.

3. Reduced the number of columns in the site mapping table to improve readability.

4. Removed the setting to retrieve user sign-in activity due to the Microsoft endpoint not returning this data accurately. This also means the AuditLog.Read.All permission is no longer required in the Azure application.

5. Removed the below setting from the Tenants, Licences and Subscriptions tab due to duplication across multiple tabs. It can now be found on the Halo Integrator tab.

6. Fixed an issue where user addresses would fail to add/delete correctly if mapping an address field from Azure to an address field in Halo.

7. Fixed a display issue that could occur if connected to multiple CSP instances, where all Azure tenants were listed on the site mapping screen regardless of the tenant they were partnered with.

Enhancements to the PagerDuty integration

The PagerDuty integration now allows for separate configurations per service in Pagerduty. Each service mapping can have a default ticket type, agent for outgoing syncs, user for new tickets, as well as a signature for securely receiving webhooks. The outgoing agent must have an email that matches the email of an agent in PagerDuty.

There is also now a new option for webhook method, either NHServer or webhooks. The new version utilises the webhooks configurable from within PagerDuty. This supports webhooks for: incident triggered, incident acknowledged, incident resolved, incident reopened, and incident annotated. Please note that the NHServer method is now deprecated and will no longer be supported. When creating the webhook in PagerDuty, copy the signature and add it to the mapping for your service.

Tickets now have a field for the 'PagerDuty Service', as well as a default setting for this at the ticket type level. This must be set for the ticket and actions to sync to PagerDuty. Tickets and actions can have the 'Send to PagerDuty' field added to them to send them to Pagerduty.

If a ticket linked to a Pagerduty incident is acknowledged or closed in Halo, then this change will also be carried over to the incident.

Report "Query Builder" added

Basic ticket and action reports can now be created without using SQL by using the "Query Builder" Datasource option.

Selecting this option will prompt you to choose an entity to report on, currently either Tickets or Actions.

Ticket fields and fields for linked entities (e.g Client, Agent, Ticket Type) will then be available in the Field list. Add the fields you want to see in the report.

Conditions will show underneath the Fields. These work like report Filters except the field does not have to be in the Field list to filter on it.

A query is built from the chosen entity, fields and conditions, and all report features are supported with the Query Builder method. The query which is built can be seen by changing the data source to "Write a custom query" after the report has been run.

Fields can also be renamed by editing them. You can also count, sum or average numeric columns using the "Operation" setting when editing a column, which will automatically add the necessary groupings to the report.

Using this you can also create reports that look at the total Time Taken per Team as per the below example;

Scheduled Reports using the Query builder require NHServer version 13.53+ to run.

Available fields and entities will be added to over time.

Improvements to Optional Services

Optional Services against a service now have creation rules. These optional services will only create after all rules applied to it are met.

New setting at optional service level 'Expanded by default'. When true this will expand the service logging section of the optional service by default.

Other minor UI improvement to the optional services ticket logging area.