InTouch Hub · Blue Isle Software

HaloITSM Knowledge Base

Read HaloITSM knowledge base articles 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.

helpdeskitsmknowledge-basesupport-helpdesk

HaloITSM Knowledge Base Tool

Read HaloITSM knowledge base articles. This is the tool for questions about self-service documentation — what exists, what is stale, and what is missing.

Tool ID

haloitsm-knowledge

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 the Knowledge Base on the Halo API application.

Operations

1. list_kb_articles — List knowledge base articles

Every article, with its metadata. Calls GET /KBArticle.

Properties:

Property Type Default Description
operation string — Required. list_kb_articles
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_kb_article — Get one article

A single article by id, including the full body. Calls GET /KBArticle/{id}.

Properties:

Property Type Default Description
operation string — Required. get_kb_article
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

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

Two operations on purpose. The knowledge base would disappear inside a larger connector, but it answers a question nothing else can: whether self-service material is keeping up with what people actually raise. Pairing list_kb_articles with the haloitsm connector's list_tickets is how a desk finds the articles it should have written.

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.