> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/servicenow-ticketing.md).

# ServiceNow ticketing system

Connect OpenIAM's ticketing integration to a ServiceNow instance, so ticket rules create, update and close incidents, catalog tasks or other task records through the ServiceNow Table API or a custom c

The **ticket connector** (`ticket-connector-rabbitmq`) lets OpenIAM open, update and close tickets in an external ticketing system when something happens to a person or their access — an access request submitted, approved or rejected, a user terminated, a provisioning operation failed. One connector serves Jira, ServiceNow and [Freshservice](https://docs.openiam.com/connector-configuration/freshservice-ticketing.md); the managed system's **Ticketing system** field picks which one. This page covers **ServiceNow**: the connector talks to the ServiceNow REST Table API (`/api/now/table`) and works on any table that extends **Task** — Incident, Catalog Task, Requested Item, Problem, Change Request or your own.

Data flows one way for content (OpenIAM writes the ticket) and back for status: the ticket's state, resolution and assignee are read back for display in OpenIAM. Nothing that happens to the ticket in ServiceNow changes access in OpenIAM.

| Operation                              | Supported                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Create ticket                          | ✅ in the table the rule names                                                                                      |
| Update ticket (fields and a work note) | ✅                                                                                                                  |
| Close / move a ticket (transition)     | ✅ by setting its **State**, optionally with other fields                                                           |
| Read ticket status back (sync-back)    | ✅ state, resolution (close code), assignee, last update                                                            |
| Test connection                        | ✅                                                                                                                  |
| Labels                                 | ❌ ServiceNow has no labels; only the two OpenIAM markers are kept, see [How labels are kept](#how-labels-are-kept) |
| User and group provisioning            | ❌ Not what this connector is for — use a provisioning connector                                                    |

The acronyms on this page — REST, API and JSON — are defined in the [*Glossary*](https://docs.openiam.com/glossary.md#acronyms).

## Versions and compatibility

The connector uses the ServiceNow **Table API** at `<instance URL>/api/now/table/…`, which every current ServiceNow release provides. It needs no plugin or scoped application on the instance and pins no ServiceNow release.

**Test connection** reports the release of the instance's most recent platform upgrade, read from `sys_upgrade_history` — a `glide-…` string such as `glide-zurich-07-01-2025__patch10`, not a release name such as *Xanadu*. ServiceNow keeps no build-name system property on current releases, so this is the nearest thing to a version the instance will give. Batch plugin installs share that table and are filtered out. The release is left blank when the account may not read `sys_upgrade_history`; that alone does not fail the test.

## Prerequisites

* [ ] The ticket connector is running — it is the same connector as for Jira. If OpenIAM already creates Jira tickets, nothing more is installed.
* [ ] Network access from the connector host to `https://<instance>.service-now.com` on port 443.
* [ ] A ServiceNow **integration user** (a *web service access only* user is enough) with:
  * create, read and write on the tables your rules use — the `itil` role covers Incident, Problem, Change Request and Catalog Task on an out-of-the-box instance;
  * read on **Task** (`task`), which the connector uses to find a ticket from its number;
  * read on **Choice** (`sys_choice`), for priorities, states and categories.
* [ ] Optional: read on **Tables** (`sys_db_object`) and **Dictionary** (`sys_dictionary`). With them the rule editor lists every Task table and its fields; without them it offers the standard ITSM tables and no field list, and you type field names instead.

## Installing the connector

The ticket connector ships as the container image `ticket-connector-rabbitmq`. Install it once per environment; Jira and ServiceNow managed systems share it.

| Deployment | What to deploy                                                              |
| ---------- | --------------------------------------------------------------------------- |
| Kubernetes | The `ticket-connector-rabbitmq` Helm chart (a StatefulSet of the same name) |
| Docker     | The `ticket-connector` service of the OpenIAM Docker compose stack          |

## Starting, stopping, and restarting

| Deployment | Commands                                                        |
| ---------- | --------------------------------------------------------------- |
| Kubernetes | `kubectl rollout restart statefulset/ticket-connector-rabbitmq` |
| Docker     | `docker compose restart ticket-connector`                       |

## Command-line parameters and properties

The connector is a Spring Boot application and takes no connector-specific command-line flags. Its settings are read from `${confpath}/conf/properties/ticket-connector-rabbitmq.properties`, which overrides the defaults below.

| Property                                | Default | Purpose                                                                                 |
| --------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `ticket.servicenow.connect.timeout.ms`  | `10000` | TCP connect timeout to the instance                                                     |
| `ticket.servicenow.read.timeout.ms`     | `30000` | How long to wait for an answer; raise it if large searches time out                     |
| `ticket.servicenow.max.retries`         | `3`     | Retries after a rate limit (`429`), a server error or an I/O failure; `0` disables them |
| `ticket.servicenow.retry.base.delay.ms` | `1000`  | First wait between retries; doubles on every retry                                      |
| `ticket.servicenow.retry.max.delay.ms`  | `30000` | Cap of any single wait, including a `Retry-After` the instance sends                    |

A ticket **create** is never repeated after a server error or an I/O failure, because ServiceNow may already have created the record. OpenIAM's own retry finds that record by its correlation id instead of creating a second one.

## Verifying the connector is running

1. Open the ServiceNow managed system and select **Test connection**. It reports success once the instance accepts the integration user's credentials.
2. Create a ticket rule for a test trigger, such as **Access request submitted**, and submit one request.
3. Check that the record appears in ServiceNow, and that its **Correlation ID** reads `openiam-<request id>`.
4. Open **Tickets** on the managed system: the ticket shows its number and links to the record.

## Troubleshooting

| Symptom                                                                                | Likely cause                                                 | Resolution                                                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ServiceNow rejected the credentials (HTTP 401)`                                       | Wrong user name or password, or the user is locked           | Correct **User name** and **Password** on the managed system; check the user can sign in to the instance                                                                                                                                                                                                    |
| `ServiceNow denied access (HTTP 403)`                                                  | The integration user lacks a role on the table               | Grant create and write on the table, for example the `itil` role                                                                                                                                                                                                                                            |
| `Table <name> does not exist or is not readable by the account` on **Test connection** | Typing error in the table name, or no read access            | Use the table's system name (`incident`, not `Incident`)                                                                                                                                                                                                                                                    |
| `ServiceNow has no task record <number> visible to the account`                        | The record was deleted, or the user cannot read **Task**     | Grant read on `task`; a deleted record cannot be updated                                                                                                                                                                                                                                                    |
| `Priority '<value>' is not a priority of <table>; available: …`                        | The rule's priority does not match a choice of that table    | Pick a value from the list in the message — `High` matches `2 - High`                                                                                                                                                                                                                                       |
| `State '<value>' is not a state of <table> <number>; available: …`                     | The rule's transition names a state the table does not have  | Use a state from the list in the message                                                                                                                                                                                                                                                                    |
| `ServiceNow transition '…' is not '<state> \| <field>=<value> \| ...'`                 | Malformed transition                                         | Write the state first, then `\|`-separated `field=value` pairs                                                                                                                                                                                                                                              |
| The rule editor offers only five tables and no fields                                  | The user may not read `sys_db_object` or `sys_dictionary`    | Grant read on both, or type the table and field names yourself                                                                                                                                                                                                                                              |
| The incident's priority is not the one the rule set                                    | ServiceNow derives incident priority from impact and urgency | The connector sets both to match the priority, **but only when the rule sets neither**. If the rule sets either one as an additional field, the connector sets neither, and ServiceNow derives the priority from the one the rule gave plus its own default for the other. Set both in the rule, or neither |
| `No ServiceNow REST API serves the create endpoint <path>` on **Test connection**      | `TICKET_CREATE_PATH` names a path no REST API serves         | Copy the resource path from the Scripted REST API record, including its namespace and version segments                                                                                                                                                                                                      |
| `ServiceNow endpoint <path> answered without a record number or sys_id`                | The custom endpoint does not return the new record           | Return `number` or `sys_id` from the endpoint; check ServiceNow for a ticket the call may already have created                                                                                                                                                                                              |

For problems common to all connectors — the queue, the connector not starting — see [Connector troubleshooting](https://docs.openiam.com/connector-configuration/4-troubleshootingconnector.md).

## Registering the connector in OpenIAM

The ticket connector is registered out of the box as **Ticket Connector** with the queue **base name** `TICKET_Connector_1`. Nothing needs to be registered for ServiceNow.

That base name is what the connector record holds; it is not a queue. The queues derived from it are `TICKET_Connector_1_Request`, which the connector consumes, and `TICKET_Connector_1_Response`, which it replies on. Look for those two names when checking the broker — searching for the base name alone finds nothing.

## Configuring the managed system

**Provisioning → Managed System → New**, at `/webconsole/mngsystem`.

| Field                | Value                                                         |
| -------------------- | ------------------------------------------------------------- |
| **Connector**        | Ticket Connector                                              |
| **Ticketing system** | ServiceNow                                                    |
| **Instance URL**     | `https://<instance>.service-now.com`                          |
| **User name**        | The integration user's **User ID**, for example `svc.openiam` |
| **Password**         | The integration user's password; it is stored in Vault        |

Save, then select **Test connection**.

### Creating tickets through a custom endpoint

Some instances create tickets through their own REST API — a Scripted REST API that applies routing or field mapping — instead of writing the table directly. To create through such an endpoint, add a row to the managed system's **Attributes** table, which appears once the managed system has been saved:

| Name                 | Value                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `TICKET_CREATE_PATH` | The endpoint's path below the **Instance URL**, for example `/api/x_acme/tickets/create` |

The path must start with `/api/` and carry no query string. Leave the attribute out to create through the table.

With a create path set:

* Only the create call goes to the endpoint. Updates, state changes, work notes and sync-back still use the table, so the integration user must be able to read and write the created record there.
* The endpoint receives a reduced body: `short_description`, `description` and the rule's **Additional fields**. The rule's category, priority and labels are not sent; set what the endpoint expects as additional fields, under the names the endpoint reads.
* The endpoint must answer with the new record's `number` or `sys_id`, either as the table does (`{"result": {"number": "INC0010001", "sys_id": "…"}}`) or flat (`{"number": "INC0010001"}`). The connector looks the rest up by number. An answer with neither is reported as a failure, and the create is not repeated, because the endpoint may already have created a ticket.
* The correlation fields are not set, so a retried create cannot recognise a ticket it already opened. If the endpoint stores them, add the additional fields `correlation_display` = `OpenIAM` and `correlation_id` = `openiam-${ticket.subjectKey}`; see [How labels are kept](#how-labels-are-kept).

**Test connection** also checks that a REST API serves the path, without calling it.

## Attribute mapping and policy map

A ServiceNow managed system gets the same read-only TICKET policy map as Jira. The connector maps its eight standard attributes to ServiceNow fields:

| OpenIAM attribute | ServiceNow                              | Notes                                                                                                                                                                                                                                                         |
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`         | the table                               | Required on create. A table extending Task, by system name: `incident`, `sc_task`, `change_request`, …                                                                                                                                                        |
| `issuetype`       | `category`                              | Optional. The rule editor offers the table's categories; tables without categories leave it empty                                                                                                                                                             |
| `summary`         | `short_description`                     | Required on create                                                                                                                                                                                                                                            |
| `description`     | `description`                           | Plain text; line breaks are kept                                                                                                                                                                                                                              |
| `priority`        | `priority`                              | A label (`2 - High`, or just `High`) or a value (`2`). On `incident` the connector also sets the matching **impact** and **urgency**, unless the rule sets either of them itself — then it sets neither. Nothing is written at all when the priority is blank |
| `labels`          | `correlation_display`, `correlation_id` | See [How labels are kept](#how-labels-are-kept)                                                                                                                                                                                                               |
| `transition`      | `state`                                 | See [Closing and moving tickets](#closing-and-moving-tickets)                                                                                                                                                                                                 |
| `comment`         | `work_notes`                            | Added as a work note, visible to fulfillers only                                                                                                                                                                                                              |

In the rule editor, a ServiceNow system shows **Table** and **Category** instead of **Project** and **Issue type**, and no **Labels** field.

**Additional fields** on a rule set any other column of the table by its system name, for example `assignment_group`, `caller_id` or a custom `u_cost_center`. Values are sent as ServiceNow stores them:

* a **choice** field takes the choice value (the rule editor lists the values when it may read the dictionary);
* a **reference** field, such as `assignment_group` or `caller_id`, takes the referenced record's `sys_id` or its display value — a group name such as `Service Desk`, which ServiceNow resolves itself;
* a **date/time** field takes `yyyy-MM-dd HH:mm:ss` in UTC.

### How labels are kept

ServiceNow has no labels. OpenIAM relies on two of them: `openiam`, which marks every ticket it created, and `openiam-<subject key>`, which ties a ticket to its subject (a request, a user and trigger, …) so a retried create finds the existing ticket instead of opening a second one. The connector keeps them in the Task integration fields:

| Label                   | Stored as                                    |
| ----------------------- | -------------------------------------------- |
| `openiam`               | **Correlation display** = `OpenIAM`          |
| `openiam-<subject key>` | **Correlation ID** = `openiam-<subject key>` |

Any other label a rule sets is not stored. Do not overwrite the two correlation fields from ServiceNow workflows on OpenIAM-created tickets: sync-back and retries find tickets through them.

### Closing and moving tickets

A rule's **Target state** names the state to move the ticket to, by label (`Resolved`) or value (`6`). ServiceNow has no workflow transitions, so the connector sets **State** directly; the states offered are those of the rule's table.

Where the instance requires more fields with a state — a close code and close notes when an incident is resolved, for example — add them after the state, separated by `|`:

{% code overflow="wrap" %}

```
Resolved | close_code=Solution provided | close_notes=Access granted by OpenIAM
```

{% endcode %}

The rule's comment is added as a work note in the same update.

## Reconciliation and synchronization

OpenIAM seeds a synchronization configuration of type **TICKET** for every ticketing managed system; it reads ticket status back for ServiceNow exactly as for Jira. ServiceNow-specific behaviour:

* The connector searches the rule's table, or **Task** when no table is given, for records whose **Correlation display** is `OpenIAM`.
* A search's native query fragment is a ServiceNow **encoded query**, for example `active=true`. It is ANDed to the connector's own conditions; do not use `^NQ` in it.
* A record read through **Task** reports no resolution, because the close code lives on the child table.

## Use cases

* **Service desk fulfilment visibility.** Every approved access request opens a Catalog Task for the team that owns the application, and closes it when OpenIAM finishes provisioning.
* **Leaver follow-up.** A user termination raises an Incident for the asset team to collect hardware, with the manager as caller and the cost center as an additional field.
* **Provisioning failures as incidents.** A failed provisioning operation opens an Incident in the integration team's assignment group, so failures are worked in the same queue as everything else.

## Related

* [Raise a ServiceNow incident from an approval](https://docs.openiam.com/administration-guide/requests/approval-flows/raise-a-servicenow-incident.md) — the older, script-based integration this connector replaces
* [Freshservice ticketing system](https://docs.openiam.com/connector-configuration/freshservice-ticketing.md) — the same connector for Freshservice
* [Connector configuration](https://docs.openiam.com/connector-configuration/connectorconfig.md)
* [Connector troubleshooting](https://docs.openiam.com/connector-configuration/4-troubleshootingconnector.md)


---

# 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.openiam.com/connector-configuration/servicenow-ticketing.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.
