> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/haloitsm.md).

# HaloITSM

Connect to HaloITSM to create and triage tickets, post replies and notes, and search the knowledge base.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| HaloITSM  | Credentials    |

#### HaloITSM

Connect to HaloITSM to create and triage tickets, post replies and notes, and search the knowledge base.

**Set up in HaloITSM**

1. Prepare the HaloITSM account or service that the workflow will access. Grant access to the required resources and operations.
2. **Client ID:** Create an API application in Halo under Configuration > Integrations > Halo API > View Applications. Set its authentication method to 'Client ID and Secret (Services)', choose the agent it logs in as, and grant it the permissions your workflows need (for example Ticket Read, Ticket Modify, Customers Read, KB Read). Stack AI requests the 'all' scope; what the connection can actually do is limited by the application's own permissions and its agent's role.
3. **Authorisation Server URL:** Only set this when Halo shows a different Authorisation Server URL under Configuration > Integrations > Halo API. Defaults to '\<Halo URL>/auth'.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **HaloITSM**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field            | Required                 | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Halo URL                 | Yes                      | The address you use to open Halo. If Halo showed you a Resource Server URL instead (ending in /api), that also works: Stack AI removes the /api suffix.                                                                                                                                                                                                                                                                                                                   |
| Client ID                | Yes                      | Create an API application in Halo under Configuration > Integrations > Halo API > View Applications. Set its authentication method to 'Client ID and Secret (Services)', choose the agent it logs in as, and grant it the permissions your workflows need (for example Ticket Read, Ticket Modify, Customers Read, KB Read). Stack AI requests the 'all' scope; what the connection can actually do is limited by the application's own permissions and its agent's role. |
| Client Secret            | Yes                      | Client Secret of the same Halo API application.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Tenant                   | Optional / as applicable | Only for Halo-hosted instances: the Tenant shown in Configuration > Integrations > Halo API. Leave empty for a self-hosted (on-premise) instance.                                                                                                                                                                                                                                                                                                                         |
| Authorisation Server URL | Optional / as applicable | Only set this when Halo shows a different Authorisation Server URL under Configuration > Integrations > Halo API. Defaults to '\<Halo URL>/auth'.                                                                                                                                                                                                                                                                                                                         |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **HaloITSM** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Ticket

Open a new HaloITSM ticket for a customer.

**Inputs**

| Field            | Type            | Required | Description                                                                                                                                         |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summary          | string          | Yes      | Short subject line for the ticket.                                                                                                                  |
| Ticket Type      | select (string) | Yes      | The kind of ticket, for example Incident or Service Request. Options load from the selected connection.                                             |
| Client           | select (string) | Yes      | The customer or organisation the ticket belongs to. Options load from the selected connection.                                                      |
| Details          | textarea        | No       | Full description of the issue or request.                                                                                                           |
| End User         | select (string) | No       | The person who reported the issue. Options load from the selected connection.                                                                       |
| Category         | select (string) | No       | Category as shown in Halo. Some ticket types require one; Halo says which when it rejects the ticket. Options load from the selected connection.    |
| Impact           | select (string) | No       | How widely the issue is felt. Some ticket types require it; together with Urgency it sets the priority. Options load from the selected connection.  |
| Urgency          | select (string) | No       | How quickly it needs attention. Some ticket types require it; together with Impact it sets the priority. Options load from the selected connection. |
| Agent            | select (string) | No       | Agent to assign the ticket to. Options load from the selected connection.                                                                           |
| Team             | select (string) | No       | Team to assign the ticket to. Options load from the selected connection.                                                                            |
| Advanced options | boolean         | No       | Reveal fields to set the starting status or override the priority. Default: false.                                                                  |
| Status           | select (string) | No       | Starting status. Leave empty to use the ticket type's default. Options load from the selected connection.                                           |
| Priority         | select (string) | No       | Set the priority explicitly. When Impact and Urgency are given, Halo's priority matrix takes precedence. Options load from the selected connection. |

**Outputs**

| Field          | Type     | Description                     |
| -------------- | -------- | ------------------------------- |
| Ticket ID      | integer  | The HaloITSM ticket number.     |
| Summary        | string   | Ticket subject line.            |
| Details        | string   | Ticket description.             |
| Status ID      | integer  | Current status.                 |
| Ticket Type ID | integer  | Ticket type.                    |
| Priority ID    | integer  | Priority.                       |
| Client ID      | integer  | Customer the ticket belongs to. |
| Client         | string   | Customer name.                  |
| User ID        | integer  | End user who reported it.       |
| User           | string   | End user name.                  |
| Agent ID       | integer  | Assigned agent.                 |
| Team           | string   | Assigned team.                  |
| Opened At      | datetime | When the ticket was opened.     |

#### Update Ticket

Change a ticket's status, priority, assignment, category or text.

**Inputs**

| Field            | Type            | Required | Description                                                                                             |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Ticket ID        | integer         | Yes      | Number of the ticket to update.                                                                         |
| Status           | select (string) | No       | New status for the ticket. Options load from the selected connection.                                   |
| Priority         | select (string) | No       | New priority for the ticket. Options load from the selected connection.                                 |
| Agent            | select (string) | No       | Agent to assign the ticket to. Options load from the selected connection.                               |
| Team             | select (string) | No       | Team to assign the ticket to. Options load from the selected connection.                                |
| Advanced options | boolean         | No       | Reveal fields to change the summary, details, ticket type, category, impact or urgency. Default: false. |
| Summary          | string          | No       | Replace the ticket's subject line.                                                                      |
| Details          | textarea        | No       | Replace the ticket's description.                                                                       |
| Ticket Type      | select (string) | No       | Move the ticket to another type. Options load from the selected connection.                             |
| Category         | select (string) | No       | Re-categorise the ticket, using a category as shown in Halo. Options load from the selected connection. |
| Impact           | select (string) | No       | Change how widely the issue is felt. Options load from the selected connection.                         |
| Urgency          | select (string) | No       | Change how quickly it needs attention. Options load from the selected connection.                       |

**Outputs**

| Field          | Type     | Description                     |
| -------------- | -------- | ------------------------------- |
| Ticket ID      | integer  | The HaloITSM ticket number.     |
| Summary        | string   | Ticket subject line.            |
| Details        | string   | Ticket description.             |
| Status ID      | integer  | Current status.                 |
| Ticket Type ID | integer  | Ticket type.                    |
| Priority ID    | integer  | Priority.                       |
| Client ID      | integer  | Customer the ticket belongs to. |
| Client         | string   | Customer name.                  |
| User ID        | integer  | End user who reported it.       |
| User           | string   | End user name.                  |
| Agent ID       | integer  | Assigned agent.                 |
| Team           | string   | Assigned team.                  |
| Opened At      | datetime | When the ticket was opened.     |

#### Get Ticket

Read a ticket's details and its recent conversation.

**Inputs**

| Field                | Type    | Required | Description                                                                               |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| Ticket ID            | integer | Yes      | Number of the ticket to read.                                                             |
| Include Conversation | boolean | No       | Also return the ticket's replies and notes. Default: true.                                |
| Conversation Limit   | integer | No       | How many of the latest replies and notes to return. Minimum: 1. Maximum: 50. Default: 20. |

**Outputs**

| Field          | Type          | Description                             |
| -------------- | ------------- | --------------------------------------- |
| Ticket ID      | integer       | The HaloITSM ticket number.             |
| Summary        | string        | Ticket subject line.                    |
| Details        | string        | Ticket description.                     |
| Status ID      | integer       | Current status.                         |
| Ticket Type ID | integer       | Ticket type.                            |
| Priority ID    | integer       | Priority.                               |
| Client ID      | integer       | Customer the ticket belongs to.         |
| Client         | string        | Customer name.                          |
| User ID        | integer       | End user who reported it.               |
| User           | string        | End user name.                          |
| Agent ID       | integer       | Assigned agent.                         |
| Team           | string        | Assigned team.                          |
| Opened At      | datetime      | When the ticket was opened.             |
| Conversation   | object\_array | Latest replies and notes on the ticket. |

#### List Tickets

Find tickets by status, client, agent, team, type, text or date.

**Inputs**

| Field            | Type            | Required | Description                                                                                    |
| ---------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| Search           | string          | No       | Words to look for in tickets.                                                                  |
| Open or Closed   | select (string) | No       | Which tickets to include. Available values: Open, Closed, All. Default: open.                  |
| Status           | select (string) | No       | Only tickets in this status. Options load from the selected connection.                        |
| Client           | select (string) | No       | The customer or organisation the ticket belongs to. Options load from the selected connection. |
| Agent            | select (string) | No       | Only tickets assigned to this agent. Options load from the selected connection.                |
| Advanced options | boolean         | No       | Show team, ticket type, date and paging filters. Default: false.                               |
| Team             | select (string) | No       | Only tickets assigned to this team. Options load from the selected connection.                 |
| Ticket Type      | select (string) | No       | Only tickets of this type. Options load from the selected connection.                          |
| Opened After     | datetime        | No       | Only tickets opened at or after this date and time.                                            |
| Opened Before    | datetime        | No       | Only tickets opened before this date and time.                                                 |
| Max Results      | integer         | No       | Maximum number of tickets to return. Minimum: 1. Maximum: 100. Default: 25.                    |
| Page             | integer         | No       | Continue from a previous search. Minimum: 1.                                                   |

**Outputs**

| Field         | Type          | Description                      |
| ------------- | ------------- | -------------------------------- |
| Tickets       | object\_array | Matching tickets.                |
| Total Matches | integer       | How many tickets match in total. |
| Next Page     | integer       | Page to request to continue.     |

#### Add Note or Reply

Post a private note or a reply to the end user on a ticket.

**Inputs**

| Field               | Type            | Required | Description                                                                                                           |
| ------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| Ticket ID           | integer         | Yes      | Number of the ticket to post on.                                                                                      |
| Note                | textarea        | Yes      | The text of the note or reply.                                                                                        |
| Action Type         | select (string) | No       | The kind of action, as configured in Halo. Leave empty for a private note. Options load from the selected connection. |
| Visible to End User | boolean         | No       | Let the end user see this on the portal. Default: false.                                                              |
| Send Email          | boolean         | No       | Also email this reply to the end user. Default: false.                                                                |
| Change Status To    | select (string) | No       | Move the ticket to this status when posting. Options load from the selected connection.                               |

**Outputs**

| Field       | Type     | Description                        |
| ----------- | -------- | ---------------------------------- |
| Action ID   | integer  | ID of the new note or reply.       |
| Ticket ID   | integer  | Ticket it was posted on.           |
| Action Type | string   | The action type used.              |
| Note        | string   | Text that was posted.              |
| Private     | boolean  | Whether the end user can't see it. |
| Posted At   | datetime | When it was posted.                |

#### Search Knowledge Base

Find knowledge base articles that answer a question.

**Inputs**

| Field           | Type    | Required | Description                                                                                          |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------- |
| Search          | string  | Yes      | What to look for, for example 'reset password'.                                                      |
| Include Content | boolean | No       | Fetch each article's full description and resolution (one extra request per article). Default: true. |
| Max Results     | integer | No       | Maximum number of articles to return. Minimum: 1. Maximum: 20. Default: 5.                           |
| Page            | integer | No       | Continue from a previous search. Minimum: 1.                                                         |

**Outputs**

| Field     | Type          | Description                  |
| --------- | ------------- | ---------------------------- |
| Articles  | object\_array | Matching articles.           |
| Next Page | integer       | Page to request to continue. |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### New Ticket

Starts the workflow for every new HaloITSM ticket, however it was logged (portal, email, API or an agent), optionally narrowed to a ticket type, client or team.

Setup only needs a HaloITSM connection. Optionally narrow to a ticket type, client or team; leave all three empty to fire for every new ticket.

**Configuration**

| Field       | Type            | Required | Description                                                                                                                                                                                             |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ticket Type | select (string) | No       | Only trigger for this ticket type. Pick it from the dropdown, or paste its numeric id (names are not accepted here). Options load from the selected connection.                                         |
| Client      | select (string) | No       | Only trigger for this client. Pick it from the dropdown, or paste its numeric id (names are not accepted here; the dropdown shows the id next to each name). Options load from the selected connection. |
| Team        | select (string) | No       | Only trigger for tickets assigned to this team. Pick it from the dropdown, or paste its numeric id (names are not accepted here). Options load from the selected connection.                            |

**Event inputs**

| Field          | Type    | Required | Description                                            |
| -------------- | ------- | -------- | ------------------------------------------------------ |
| Ticket ID      | integer | Yes      | The HaloITSM ticket number. Default: 0.                |
| Summary        | string  | Yes      | Ticket subject line. Default: .                        |
| Details        | string  | No       | Ticket description.                                    |
| Status ID      | integer | No       | Current status.                                        |
| Ticket Type ID | integer | No       | Ticket type.                                           |
| Priority ID    | integer | No       | Priority.                                              |
| Client ID      | integer | No       | Customer the ticket belongs to.                        |
| Client         | string  | No       | Customer name.                                         |
| User ID        | integer | No       | End user who reported it.                              |
| User           | string  | No       | End user name.                                         |
| Agent ID       | integer | No       | Assigned agent.                                        |
| Team           | string  | No       | Assigned team.                                         |
| Opened At      | string  | No       | When the ticket was opened.                            |
| Full Ticket    | object  | Yes      | Every field Halo returned for the ticket. Default: {}. |

**Outputs**

| Field          | Type     | Description                               |
| -------------- | -------- | ----------------------------------------- |
| Ticket ID      | integer  | The HaloITSM ticket number.               |
| Summary        | string   | Ticket subject line.                      |
| Details        | string   | Ticket description.                       |
| Status ID      | integer  | Current status.                           |
| Ticket Type ID | integer  | Ticket type.                              |
| Priority ID    | integer  | Priority.                                 |
| Client ID      | integer  | Customer the ticket belongs to.           |
| Client         | string   | Customer name.                            |
| User ID        | integer  | End user who reported it.                 |
| User           | string   | End user name.                            |
| Agent ID       | integer  | Assigned agent.                           |
| Team           | string   | Assigned team.                            |
| Opened At      | datetime | When the ticket was opened.               |
| Full Ticket    | object   | Every field Halo returned for the ticket. |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/haloitsm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
