HaloITSM

First create the API token authentication in Halo.

1. In Halo, go to Configuration > Integrations > HaloITSM API.

   

2. In the Configuration tab, click View Applications.
3. Click Add to add a new application.
4. On the Details tab of the Add an Application window, fill in the following fields:
   • Application Name: Give the application a unique name.
   • Authentication Method: Select Client ID and Secret (Services).
     • Click Generate.
     • Copy the Client ID and Client Secret to an easy-to-find location.
   • Login Type: From the drop-down menu, select Agent. Select an agent from the drop-down menu of options.

   

5. Go to the Permission tab. Select the edit:tickets checkbox.

   

6. Click Save.
7. On the main API page, copy your Authorization Server and Tenant information to an easy-to-find location.

Now configure a webhook to send Halo tickets to xMatters.

To have HaloITSM send alerts to the flow trigger, you need to configure two webhooks and set them to use the trigger URLs. One webhook is for Halo tickets with an assigned agent, and the other is for tickets without an assigned agent.

First let's create a webhook for Halo tickets with assigned agents.

1. In Halo, go to Configuration > Integrations > Webhooks.

   

2. In the top-right corner, click New.

   

3. On the New Webhook window, give the webhook a unique name. For example, "xMatters - Assigned" or "xMatters - Unassigned".
4. In the Payload URL field, paste the trigger URL.
   • Add the target names of any recipients you want to notify when the alert fires. You can either add them to the end of the URL, or in the Parameters tab.
     • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
     • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
     • You must URL-encode any special characters or spaces in the target names.

   

5. Ensure the Enabled checkbox is selected and the Use a custom payload is deselected.

   

Use the Events section to add any business rules for the webhook. A business rule is logic that determines when the webhook is used. The following steps describe creating a business rule for when a new ticket is logged in Halo.

6. In the Events section click Add.
7. On the New Event window, expand the Event drop-down menu and select New Ticket Logged.

   

8. Click Add to add the following criteria to the event: 
   • For tickets with assigned agents:
     • Field: Agent
     • Rule Type: Is equal to
     • Value: Name of the assigned agent.
   • For tickets unassigned to agents: 
     • Field: Agent
     • Rule Type: Is equal to
     • Value: Unassigned
9. Click Save to save the Event and return to the New Webhook window.
10. Click Save.
11. Repeat steps 2 - 10 to create a webhook for the Unassigned Agent.

The xMatters custom user property associates the agent ID of your Halo account with your xMatters account. Once the property is created, any user can add their Halo agent ID to their xMatters profile to receive notifications.

1. Open the xMatters Admin menu and select Custom User Properties.

   

2. On the Custom User Properties window, click Add Property and fill in the following fields: 
   • Name: HaloITSM User ID
     • For the workflow to successfully send updates to Halo, the name of the property must be HaloITSM User ID. If you give this property a different name, you must update the workflow constant with the new name.
   • Type: Select Text from the drop-down menu.

   

3. Click Save.

Now that the property is saved in your system, you need to populate the field with the users' Halo agent ID. There are two ways to do this: 

• Batch upload: 
  • Export a list of all users in your system. The file will contain a column for the custom property you just created.
  • Add the Halo agent ID for each user.
    • To find an agent ID in Halo go to the Configuration >Teams & Agents > Agents. Open the record for the agent then copy the agent ID portion of the URL. For example in the URL: <your-instance>.haloitsm.com/config/agents/agents?agentid=20964 the agent ID is 20964.
  • Upload the file to xMatters.
• Manually add each user's agent ID to their account.

Here's how to manually add a Halo agent ID to an xMatters account profile.

1. To access your user profile, click on your username at the top-right corner of the xMatters, then select Profile.

   

2. Click Edit Profile.

   

3. Scroll to the bottom of the Edit Profile screen to the new HaloITSM User ID field.

   

4. Enter the Halo agent ID into the HaloITSM User ID field.
5. Click Save.

The HaloITSM workflow comes with two pre-configured constants. The first constant uses the HaloITSM User ID for tickets with assigned agents. The second constant sends notifications for tickets without assigned agents to an xMatters group. You'll need to configure this constant with the name of the group.

1. Open your HaloITSM workflow.
2. Click the Flow Designer tab, and open the HaloITSM Alerts canvas.
3. Expand the Components menu and select Constants.

   

4. Select the Unassigned HaloITSM tickets tab.

   

5. In the Value field, enter the name of a valid xMatters group.
   • If you need to create a group, see Manage Groups for instructions on creating and populating groups.
6. If you named the custom user property something other than "HaloITSM User ID", click the HaloITSM User ID Property tab and update the Value field.
7. Click Save then Close.

The constant values are used in various steps throughout the workflow.

When you look at the workflow, you'll notice each Halo step has configuration error that must be resolved before the flow will work. To clear these errors, you'll need the Client ID, Client Secret, and Authorization Tenant you saved when you configured HaloITSM.

1. Open each step by double-clicking on it, or click the pencil icon to edit.

   

2. On the Setup tab, enter the Client ID, Client Secret, and Authorization Tenant.
3. Click Done.
4. Save your flow.

Continue adding the Client ID, Client Secret, and Authorization Tenant to each step in the flow to clear the configuration errors.

When a signal is received from HaloITSM and a new incident is created, the person responding to the notification has the following response options available:

• Assign to me: Acknowledges the notifications and stops escalations. The HaloITSM incident is updated with a note containing the xMatters incident ID and information about the authenticating user.
• Escalate: Immediately escalates the alert to the next on-call resolver in a targeted group.
• Resolve: Ends the xMatters alert and stops notifying all targeted recipients. The HaloITSM incident is resolved and a note is added for the change in status.
• Close: Ends the xMatters alert and stops notifying all targeted recipients. Both the xMatters and HaloITSM incidents are closed and a note is added for the change in status.