InTouch Hub · Blue Isle Software

HaloITSM

Read HaloITSM service desk tickets, actions, users, clients and reference data, and raise tickets from automation, through the HaloITSM REST API.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

helpdeskit-supportitsmsupport-helpdeskticket

HaloITSM Tool

Read HaloITSM service desk tickets, the updates on them, the people they belong to, and the vocabulary that makes them readable — and raise a ticket from automation. This is the tool for open-ticket counts, SLA breach reporting and escalation digests on installations running HaloITSM.

Tool ID

haloitsm

Credential Required

Yes — the shared haloitsm credential, owned by the haloitsm connector. Configure the tenant once and every haloitsm-* tool uses it; rotating the client secret is one edit rather than four.

It is a server-managed OAuth credential: InTouch mints and refreshes the access token itself and the connector never sees the secret. Halo uses the OAuth2 client credentials grant, so set grant_type to client_credentials. The token endpoint is on YOUR tenant host, which is why it lives in the credential rather than in the connector.

Credential Properties

Property Type Default Description
client_id string — Required. Halo → Configuration → Integrations → HaloITSM API → View Applications → your application.
client_secret string — Required. Generated beside the client id and shown once. Regenerating invalidates the previous secret.
token_url string — Required. https://<tenant>.haloitsm.com/auth/token — your own host, shown on the API page as the Authorisation Server.
grant_type string (blank) client_credentials for unattended use.
scope string — all, or narrower if the application's Permissions tab was restricted.
access_token string — Machine-managed. Leave empty; the server mints and persists it.
refresh_token string — Not used by the client-credentials grant.
expires_at string 0 Machine-managed expiry, epoch seconds. Halo tokens last 9 hours.

Halo setup

  1. Configuration → Integrations → HaloITSM API. The page shows your Resource Server, your Authorisation Server and your tenant name — the first two are the values this credential needs.
  2. View Applications → New. On Details choose Client ID and Secret (Services); the other six methods either act as a signed-in person (and so cannot be scheduled) or are not OAuth.
  3. Generate, then copy the secret before saving — Halo shows it once.
  4. Prefer Application identity over logging in as a named agent, so the integration does not break when that person leaves. Anything create_ticket raises is attributed to whatever it logs in as.
  5. On Permissions, tick only what is needed. Halo's own warning is worth heeding: "'all' and 'admin' should not be used in production as they expose administration level access."

Permissions

Whatever the API application is granted in Halo. The read operations need read access to Tickets, Actions, Users, Clients and the reference tables; create_ticket needs ticket-creation rights.

Operations

1. list_tickets — List tickets

Every ticket on the desk. The SLA target rides on the ticket as fixbydate, so this is what a breach or escalation report reads. Calls GET /Tickets.

Properties:

Property Type Default Description
operation string — Required. list_tickets
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

2. get_ticket — Get one ticket

A single ticket in full — 108 fields on the tenant this was measured against. Calls GET /Tickets/{id}.

Properties:

Property Type Default Description
operation string — Required. get_ticket
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
id string — Required. Record id. Required by get_ticket, get_action, get_user and get_client.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

3. create_ticket — Raise a ticket

Open a ticket from automation, so a failed nightly job becomes an incident somebody sees. Halo expects an ARRAY of ticket objects here, even for one. Calls POST /Tickets.

Properties:

Property Type Default Description
operation string — Required. create_ticket
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
body string — Required. Ticket to create, as a JSON object string. Halo expects an ARRAY of ticket objects on POST /Tickets — e.g. [{"summary": "Nightly load failed", "details": "Run 481 exited 1", "tickettype_id": 1}]. Only used by create_ticket.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

4. list_actions — List ticket actions

The updates ON tickets — notes, status changes, reassignment. 'Untouched for three days' is an actions question. Calls GET /Actions.

Properties:

Property Type Default Description
operation string — Required. list_actions
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

5. get_action — Get one action

Needs BOTH ids: an action is identified by its own id and the ticket it belongs to. Calls GET /Actions/{id}?ticket_id={ticketId}.

Properties:

Property Type Default Description
operation string — Required. get_action
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
id string — Required. Record id. Required by get_ticket, get_action, get_user and get_client.
ticketId string — Required. The ticket an action belongs to. Required by get_action — Halo rejects an action lookup without it. Every action in a list_actions result carries ticket_id.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

6. list_users — List users

The end users who raise tickets. Calls GET /Users.

Properties:

Property Type Default Description
operation string — Required. list_users
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

7. get_user — Get one user

A single user by id. Calls GET /Users/{id}.

Properties:

Property Type Default Description
operation string — Required. get_user
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
id string — Required. Record id. Required by get_ticket, get_action, get_user and get_client.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

8. list_clients — List clients

The organisations tickets belong to — one row in a single-institution install, the tenancy boundary in an MSP. Calls GET /Client.

Properties:

Property Type Default Description
operation string — Required. list_clients
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

9. get_client — Get one client

A single client by id. Calls GET /Client/{id}.

Properties:

Property Type Default Description
operation string — Required. get_client
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
id string — Required. Record id. Required by get_ticket, get_action, get_user and get_client.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

10. list_sites — List sites

Locations under a client — the campus, building or office a ticket came from. Calls GET /Site.

Properties:

Property Type Default Description
operation string — Required. list_sites
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

11. list_agents — List agents

Service desk staff. Needed to turn an assignment id into a name. Calls GET /Agent.

Properties:

Property Type Default Description
operation string — Required. list_agents
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

12. list_teams — List teams

The queues tickets are assigned to. Calls GET /Team.

Properties:

Property Type Default Description
operation string — Required. list_teams
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

13. list_statuses — List statuses

This installation's status vocabulary. Configurable per install — read it, never hardcode an id. Calls GET /Status.

Properties:

Property Type Default Description
operation string — Required. list_statuses
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

14. list_ticket_types — List ticket types

Incident, request, change and whatever else this install defines. Calls GET /TicketType.

Properties:

Property Type Default Description
operation string — Required. list_ticket_types
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

15. list_reports — List saved reports

Reporting the service desk already built, for a workflow that would rather reuse it than recompute it. Calls GET /Report.

Properties:

Property Type Default Description
operation string — Required. list_reports
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

16. list_priorities — List priorities

Resolves the priority_id carried on every ticket. Calls GET /Priority.

Properties:

Property Type Default Description
operation string — Required. list_priorities
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

17. list_slas — List SLA definitions

The SLAs themselves — what the targets on tickets are measured against. Calls GET /SLA.

Properties:

Property Type Default Description
operation string — Required. list_slas
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

18. list_holidays — List holidays

SLA targets are measured in WORKING time, and this is the calendar that decides which days count. Calls GET /Holiday.

Properties:

Property Type Default Description
operation string — Required. list_holidays
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

19. list_workdays — List working days

The working-hours definition behind the same calculation. Calls GET /WorkDay.

Properties:

Property Type Default Description
operation string — Required. list_workdays
host string — Required. Your HaloITSM hostname, e.g. acme.haloitsm.com. Required by every operation. No scheme, no trailing slash.
query string — Optional. Halo query parameters as a JSON object string, e.g. {"open_only": true} or {"client_id": 12}. Sent as-is on the URL. You do NOT need pagination parameters — listings are drained automatically and the result carries complete:true. Halo's own default is dangerous (it returns 50 rows and a record_count that agrees with the truncation), which is why this connector always paginates. Supplying paginate/page_size/page_no yourself switches that off and hands you one page.

Published Outputs: - result — the JSON response body - status — HTTP status code

Paging

Listings are drained automatically, and on Halo that is not a nicety — it is the difference between a report and a wrong report.

Halo pages by number, and its unpaginated answer misstates its own size. Measured against a live tenant on 2026-08-22:

Call Returned record_count says Actually
GET /Tickets 50 50 420
GET /Asset 50 50 115
GET /Actions 0 0 1085

The count agrees with the truncation, so nothing in the response suggests anything is missing — and page_size on its own is ignored. Only paginate=true makes the count tell the truth. /Actions is the starkest: unflagged it reports an empty service desk.

So this connector always requests with the flag set, reads the real total, and walks to it. The result carries pagesFetched and complete: true. If it ever stops at the page cap it says so — complete: false with a warning, and the step returns WARNING rather than SUCCESS.

You do not need pagination parameters. Supplying them yourself turns this off and hands you a single page, which is occasionally what you want and usually not.

Endpoints that answer with a bare array rather than an envelope — the reference vocabularies — are not paged and are returned untouched.

Notes

Tickets carry ids, not names. status_id, priority_id, the team, the type and the agent are all numeric. A report a person will read needs the matching list_* operation to resolve them, and those vocabularies are per-installation — an id meaning "Resolved" in one Halo is not the same id in another.

Read the SLA target; never recompute it. A ticket carries fixbydate — the deadline Halo calculated — along with sla_id, excludefromsla and slaholdtime. There is no precomputed breach flag: a breach report is fixbydate < now, which on the measured tenant was 177 of 420 tickets. Do not derive a target from dateoccurred plus a duration instead. Targets are measured in working time against /Holiday (97 entries there) and /WorkDay, so a naive calculation breaches tickets that spanned a weekend and are perfectly on time.

The other half of an SLA digest already exists. helpdesk-sla-digest is source-agnostic, so list_tickets → digest → Teams message is a working escalation with nothing else written.

Family. haloitsm-assets (CMDB), haloitsm-services (service catalogue) and haloitsm-knowledge share this connector's credential. Unlike the Microsoft Graph family the split is not about consent — Halo issues one application and one scope — it is about keeping each tool's purpose narrow enough to be chosen correctly.

Verification status. Every operation in this document was executed against a live HaloITSM tenant on 2026-08-22 and returned HTTP 200 with real data. That includes the by-id lookups and the paged listings; counts quoted above are what came back. What has NOT been exercised is create_ticket (it writes, and the tenant is somebody's) and behaviour on a self-hosted Halo.

Self-Contained JAR

The jar bundles all runtime dependencies; only intouch-tool-api is provided by the server.

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.