InTouch Hub · Blue Isle Software

HaloITSM Services

Read the HaloITSM service catalogue — services, their categories and per-service status history — 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.

helpdeskitsmservice-cataloguestatussupport-helpdesk

HaloITSM Services Tool

Read the HaloITSM service catalogue — services, their categories, and the status values services report against. This is the tool for 'what do we offer', catalogue reviews and service status reporting.

Tool ID

haloitsm-services

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

Read access to Services on the Halo API application.

Operations

1. list_services — List services

Every service in the catalogue. Calls GET /Service.

Properties:

Property Type Default Description
operation string — Required. list_services
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. You do NOT need pagination parameters — listings are drained automatically. 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_service — Get one service

A single service by id. Calls GET /Service/{id}.

Properties:

Property Type Default Description
operation string — Required. get_service
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 the get_* operations.
query string — Optional. Halo query parameters as a JSON object string. You do NOT need pagination parameters — listings are drained automatically. 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. list_service_categories — List service categories

How the catalogue is grouped. Calls GET /ServiceCategory.

Properties:

Property Type Default Description
operation string — Required. list_service_categories
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. You do NOT need pagination parameters — listings are drained automatically. 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. get_service_category — Get one category

A single category by id. Calls GET /ServiceCategory/{id}.

Properties:

Property Type Default Description
operation string — Required. get_service_category
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 the get_* operations.
query string — Optional. Halo query parameters as a JSON object string. You do NOT need pagination parameters — listings are drained automatically. 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. list_service_statuses — List service statuses

The status values services report against. Calls GET /ServiceStatus.

Properties:

Property Type Default Description
operation string — Required. list_service_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. You do NOT need pagination parameters — listings are drained automatically. 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

There is no by-id route for service statuses. /ServiceStatus lists them but /ServiceStatus/{id} answers 404, measured 2026-08-22 — so only the listing is offered. Inventing the operation would have shipped a guaranteed failure.

The catalogue is what users see; tickets are what the desk sees. Ranking services by ticket volume means combining this with list_tickets from the haloitsm connector.

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.