HaloITSM Ticketing Integration

What

The HaloITSM ticketing integration lets Ploy create and update tickets in Halo through its API. Tickets raised from Ploy (for example by an automation flow, Luna or an access request) appear in Halo like any other ticket. Status changes your agents make in Halo are sent back to Ploy, so a flow can wait for a Halo ticket to be resolved before carrying on.

This is not the integration that reads your Halo tickets so Luna can learn from them. For that, see HaloITSM ticket data import (Beta).

Before you start

• You need to be a Halo administrator who can create API applications (Configuration > Integrations > Halo API).

• Your Halo must be hosted by Halo, at an address ending in haloitsm.com, halopsa.com, haloservicedesk.com or usehalo.com. Self-hosted Halo and custom domains are not supported yet.

• Decide which Halo agent Ploy should act as. Everything Ploy writes is attributed to that agent, and Halo only lets it update tickets it can see. We recommend a dedicated service agent with access to every team Ploy will raise tickets for.

Create an API application in Halo

Step 1: In Halo go to Configuration > Integrations > Halo API > View Applications > New.

Step 2: Set the authentication method to Client ID and Secret (Services) and the login type to Agent, then choose the agent Ploy should act as.

Step 3: On the Permissions tab allow read:tickets, edit:tickets and read:customers.

Step 4: Save, then copy the Client ID and the Client Secret. Halo may only show the secret once.

Connect Halo to Ploy

Step 5: On the Ploy Ticketing Integrations page, choose HaloITSM and click + Add.

Step 6: Enter your Halo address (the address you use to sign in, for example yourcompany.haloitsm.com), the Client ID and the Client secret, and give the connection a name.

Step 7: Click Test Connection to confirm Ploy can reach Halo, then continue. Ploy reads your Halo statuses, ticket types and categories at this point so the next page can offer them.

Choose the defaults

Step 8: Pick the Default ticket type. Ploy raises tickets as this type unless a flow picks another.

Step 9: Pick a Default category if your ticket type makes Category mandatory in Halo.

Step 10: Check the Status mapping. Each Ploy status (Open, In Progress, Resolved, Closed and Cancelled) needs a Halo status. Ploy fills in the ones whose names match; choose the rest. A Halo status you leave out of the mapping never moves a Ploy ticket.

When you save, Ploy asks Halo whether it would accept a ticket raised with these defaults, without creating one. If Halo would refuse it (for example because the ticket type needs a field Ploy does not fill), Ploy tells you why so you can choose a different type or category.

Sync ticket status changes back to Ploy

Halo tells Ploy about status changes through a webhook you create once. Without it, Ploy never hears about changes made in Halo, and flows waiting on a ticket's status never move on.

Step 11: In Halo go to Configuration > Integrations > Webhooks > New.

Step 12: Set:

• Webhook Type: Standard webhook

• Method: POST

• Payload: Event information only

• Payload URL: copy the Payload URL from the Ploy setup page

• Authentication: Basic Authentication, with the Username and Password from the Ploy setup page

Step 13: Keep one delivery for each occurrence, add the event Ticket Status Changed with no conditions, and save.

Step 14: Save the configuration in Ploy.

How Ploy writes to Halo

• Requester: Ploy looks up the requester's email among your Halo users. If no Halo user has that email, the ticket keeps Halo's default requester and the description starts with "Requested for" and the email. Ploy never creates users in your Halo directory.

• Comments: added to the ticket as a public or private note.

• Deleting a ticket in Ploy: deletes it in Halo, with the reason "Deleted from Ploy".

Permissions and security

This section sets out exactly what access Ploy has, so it can be shared with your security, change-control or audit teams.

How the connection is secured

Ploy exchanges the API application's client ID and secret for a short-lived access token at https://<your-halo-address>/auth/token, and calls the Halo API at https://<your-halo-address>/api over HTTPS. You can revoke Ploy's access at any time by deleting the API application in Halo. Status updates Halo sends to Ploy are secured with the Basic Authentication username and password generated for your connection.

Minimum access

Ploy does not ask for Halo's admin permission. That is also why you create the webhook yourself: registering it from Ploy would need admin.

What is not included

Ploy works with tickets only. It does not change your Halo configuration, create users, or see anything the chosen agent cannot see.

Troubleshooting

• Test Connection fails with "Halo rejected the API application": check the client ID and secret, and that the application's Permissions tab allows read:tickets, edit:tickets and read:customers.

• "Enter your Halo address": enter only the address, for example yourcompany.haloitsm.com, with no path after it. It must end in one of Halo's hosted domains listed above.

• "Halo would refuse tickets raised with these defaults": the message names what Halo is missing. A missing category is fixed by choosing a default category. Anything else (for example "Cost Centre is mandatory") is a field your ticket type makes mandatory, which Ploy does not fill yet. Choose a ticket type without mandatory fields of its own, or make those fields optional on the ticket type in Halo.

• Tickets are created but status changes don't reach Ploy: check the webhook in Halo uses the Payload URL, username and password shown in Ploy exactly, includes the Ticket Status Changed event, and that the Halo status is in your status mapping.

• Ploy can't update a ticket: the agent the API application logs in as can't see it. Give that agent access to the ticket's team.