> 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/administration-guide/ticketing/connect-a-ticketing-system.md).

# Connect a ticketing system

Deploy the Ticket Connector, create the managed system that represents Jira or ServiceNow, enter the site and the credential, and prove the connection before any rule fires.

## What this is, and when you need it

Before OpenIAM can raise a ticket it needs two things: the **Ticket Connector** running somewhere it can reach your ticketing system, and a **managed system** that tells the connector which system to talk to, where it is and which account to use. This page sets up both, for Jira (Cloud or Data Center) and for ServiceNow, and ends with a successful **Test connection**.

One managed system is one ticketing system with one account. If you raise tickets in two Jira sites, or in Jira and ServiceNow, create two managed systems; each has its own rules, tickets and policy map. The running example has two: **Service Desk Jira** and **IT Service Desk**.

You do not need this page to write rules on a system that already passes **Test connection** — go to [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md). How each ticket field lands in Jira or ServiceNow is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md).

## At a glance

|                          |                                                                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | An active managed system on the Ticket Connector, its TICKET policy map, its ticket synchronization and batch task, and the **Ticket rules** and **Tickets** menu items |
| **Where**                | **Provisioning → Managed System** (`/webconsole/mngsystem`)                                                                                                             |
| **You need first**       | The `ticket-connector-rabbitmq` service running; a Jira or ServiceNow account for OpenIAM                                                                               |
| **Authentication**       | Basic authentication only: Jira Cloud e-mail and API token, Jira Data Center user name and password, ServiceNow user name and password                                  |
| **Reversible**           | Yes. Delete the managed system; its tickets, rules and ticket synchronization go with it, the tickets in Jira or ServiceNow stay                                        |

## Before you begin

### Run the Ticket Connector

The connector is a separate service, `ticket-connector-rabbitmq`. It listens on the RabbitMQ queue `TICKET_Connector_1_Request` and answers on `TICKET_Connector_1_Response`; the conf seed registers it as the connector **Ticket Connector** (`TICKET_PC`, queue `TICKET_Connector_1`). One running instance serves every ticketing managed system, Jira and ServiceNow alike: the managed system's **Ticketing system** field tells it which client to use on each request.

* **Kubernetes.** The Helm chart `ticket-connector-rabbitmq` deploys a StatefulSet of the same name. It ships with `openiam.replicas: 0`, so nothing runs until you set the replica count to `1` in your values. It takes its environment from `openiam.platform.env` like the other connectors and requests 100m CPU and 384 MiB.
* **Docker.** The image `ticket-connector-rabbitmq` is built on the OpenIAM Spring Boot base image and needs no variable of its own beyond the platform's RabbitMQ settings.

### Tune the connector, if you must

The defaults suit both systems. To change them, put the keys in `${confpath}/conf/properties/ticket-connector-rabbitmq.properties` and restart the connector.

| Property                                | Default  | Meaning                                                               |
| --------------------------------------- | -------- | --------------------------------------------------------------------- |
| `ticket.jira.connect.timeout.ms`        | `10000`  | How long to wait for a TCP connection to Jira                         |
| `ticket.jira.read.timeout.ms`           | `30000`  | How long to wait for Jira to answer                                   |
| `ticket.jira.max.retries`               | `3`      | Retries after the first attempt on a retryable error                  |
| `ticket.jira.retry.base.delay.ms`       | `1000`   | First retry delay; doubles on each retry                              |
| `ticket.jira.retry.max.delay.ms`        | `30000`  | Cap on a retry delay, including a `Retry-After` from Jira             |
| `ticket.jira.field.cache.ttl.ms`        | `600000` | How long the Jira field schemas used for additional fields are cached |
| `ticket.jira.field.cache.max.entries`   | `500`    | How many project and issue type combinations the cache holds          |
| `ticket.servicenow.connect.timeout.ms`  | `10000`  | As for Jira                                                           |
| `ticket.servicenow.read.timeout.ms`     | `30000`  | As for Jira                                                           |
| `ticket.servicenow.max.retries`         | `3`      | As for Jira                                                           |
| `ticket.servicenow.retry.base.delay.ms` | `1000`   | As for Jira                                                           |
| `ticket.servicenow.retry.max.delay.ms`  | `30000`  | As for Jira                                                           |

Which errors are retried, and why a create is never retried on a server error, is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md#system-retries-and-timeouts).

### Prepare the Jira account

Create a dedicated account, not a person's. On Jira Cloud, sign in as that account and create an **API token** in the Atlassian account settings; on Data Center you use the account's password. In every project your rules write to, the account needs to browse projects, create issues, edit issues, add comments and transition issues. **Edit** is not optional even for rules that only comment: every update also adds OpenIAM's marker label to the issue.

### Prepare the ServiceNow integration user

Create an integration user, such as `openiam.integration`, and give it:

* read and write on the tables your rules write to — any table that extends **Task**, such as `incident`, `sc_task`, `change_request` or `problem` — including their work notes;
* read on `task`, `sys_choice` (the priority and state lists the connector matches against) and `sys_user` (Test connection reads the user's own record and fails without it);
* optionally, read on `sys_db_object` and `sys_dictionary`, so the rule editor can list every task table and its columns, and on `sys_upgrade_history`, so Test connection can report the instance version. Without the first two the editor falls back to five standard tables and offers no column list.

## Create the managed system

{% stepper %}
{% step %}
**Create it with Active off.** Open **Provisioning → Managed System → New** and choose the connector **Ticket Connector**. The form then shows the ticketing fields described in [The ticketing fields](#the-ticketing-fields). Name the system after the desk it feeds — **Service Desk Jira**, **IT Service Desk** — because the name appears in the ticket synchronization, its batch task and every audit event. The generic fields are explained on [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md).
{% endstep %}

{% step %}
**Choose the ticketing system.** Set **Ticketing system** to **Jira** or **ServiceNow**. The labels of the address and credential fields change with it.
{% endstep %}

{% step %}
**Enter the address and the credential.** For Jira, **Site URL**, **Account email** and **API token**; for ServiceNow, **Instance URL**, **User name** and **Password**. The secret is stored in Vault.
{% endstep %}

{% step %}
**Save.** On the first save OpenIAM creates the objects listed in [What the first save creates](#what-the-first-save-creates). They are created once, when the system is new; saving again does not recreate anything you changed or removed.
{% endstep %}

{% step %}
**Test the connection.** **Test connection** appears once the system is saved. Run it and read the result; see [Test connection](#connect-test-connection).
{% endstep %}

{% step %}
**Activate.** Tick **Active** and save. Rules on an inactive ticketing system are skipped: no event raises a ticket until the system is active. If you want to see the first tickets before they reach the desk, set the simulation operations first — see [Review tickets before they are sent](/administration-guide/ticketing/review-before-sending.md).
{% endstep %}
{% endstepper %}

## The ticketing fields

### Ticketing system <a href="#connect-ticketing-system" id="connect-ticketing-system"></a>

**Ticketing system** is the one field the Ticket Connector's page template adds. It is required and offers two values:

| Value        | Shown as       | What the connector does                                  |
| ------------ | -------------- | -------------------------------------------------------- |
| `JIRA`       | **Jira**       | Uses the Jira REST API, Cloud or Data Center             |
| `SERVICENOW` | **ServiceNow** | Uses the ServiceNow Table API on tables that extend Task |

The value is stored in the managed system's `HANDLER5` column and sent with every request as `TARGET_SYSTEM_TYPE`. Changing it on a system that already has tickets points those tickets' keys at a system that has never heard of them — create a second managed system instead.

On a ServiceNow system the rule editor shows **Table**, **Category** and **Target state** where Jira shows **Project**, **Issue type** and **Transition**, hides **Labels**, and does not require a category.

### Site URL (Jira) <a href="#connect-jira-site-url" id="connect-jira-site-url"></a>

The base address of the Jira site, for example `https://example-corp.atlassian.net`. A trailing `/` is removed. The connector decides the deployment from the host:

| Host                                    | Deployment  | API                                                                 |
| --------------------------------------- | ----------- | ------------------------------------------------------------------- |
| Ends in `.atlassian.net` or `.jira.com` | Cloud       | REST API v3; descriptions and comments in Atlassian Document Format |
| Anything else                           | Data Center | REST API v2; descriptions and comments as wiki markup               |

A Cloud site behind a custom domain is detected as Data Center. Override the guess with the managed-system attribute `JIRA_DEPLOYMENT_TYPE`, value `CLOUD` or `DATA_CENTER`, in the **Attributes** table. Any other value fails every request with `Jira deployment type '<value>' (JIRA_DEPLOYMENT_TYPE) is not supported; supported: CLOUD, DATA_CENTER`.

### Account email and API token (Jira) <a href="#connect-jira-credentials" id="connect-jira-credentials"></a>

| Deployment  | **Account email**                                                    | **API token**                          |
| ----------- | -------------------------------------------------------------------- | -------------------------------------- |
| Cloud       | The account's e-mail address, `openiam-integration@example-corp.com` | An Atlassian API token of that account |
| Data Center | The account's user name                                              | The account's password                 |

Both are required. The connector sends them as HTTP Basic authentication on every call; Data Center personal access tokens and OAuth are not supported in this release. The managed system also carries the attribute `TICKET_AUTH_TYPE = API_TOKEN`, created on the first save and not shown on the form; it is the only value, and the connector assumes it when the attribute is missing.

### Instance URL (ServiceNow) <a href="#connect-servicenow-instance-url" id="connect-servicenow-instance-url"></a>

The base address of the instance, for example `https://example-corp.service-now.com`. The connector calls the Table API below it (`<Instance URL>/api/now/table/<table>`).

If your instance creates records through a scripted REST API instead of the Table API, add the managed-system attribute `TICKET_CREATE_PATH` with the path below the instance URL, for example `/api/x_acme/tickets/create`. The path must start with `/api/`, consist of letters, digits, `_`, `.` and `-` only, contain no `.` or `..` segment and no query string; anything else fails with `...has an invalid TICKET_CREATE_PATH '...': expected a path below the instance URL such as /api/x_acme/tickets/create, without a query string`. Only the create goes there, and it sends the short description, the description and the additional fields; category, priority and OpenIAM's correlation fields are not sent. Updates, closes and reads stay on the Table API. Details: [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md#system-servicenow-custom-create-endpoint).

### User name and password (ServiceNow) <a href="#connect-servicenow-credentials" id="connect-servicenow-credentials"></a>

The integration user's **User name**, `openiam.integration`, and **Password**. Both are required and are sent as HTTP Basic authentication; ServiceNow OAuth is not supported in this release. The user's roles are in [Prepare the ServiceNow integration user](#prepare-the-servicenow-integration-user).

## What the first save creates

When you save a new managed system on the Ticket Connector, OpenIAM adds:

| Object                   | Name                                                                          | What it is for                                                                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Policy map               | **TICKET POLICY**, type TICKET, primary                                       | Carries the eight standard ticket fields to the connector. See [The TICKET policy map](/administration-guide/ticketing/policy-map-and-sync.md#map-ticket-policy-map) |
| Managed-system attribute | `TICKET_AUTH_TYPE = API_TOKEN`                                                | The authentication type; hidden on the form                                                                                                                          |
| Synchronization          | `<system name> ticket sync` (cut to 60 characters), active                    | Reads ticket status back. See [Ticket synchronization](/administration-guide/ticketing/policy-map-and-sync.md#sync-ticket-sync)                                      |
| Batch task               | `Ticket sync <system name>` (cut to 50 characters), enabled, every 15 minutes | Runs that synchronization                                                                                                                                            |
| Menu items               | **Ticket rules**, **Tickets**                                                 | Shown on this managed system's menu; the reconciliation items are hidden on it                                                                                       |

Each part is skipped, with a warning in the ESB log, if its conf seed is missing — a sign that the 2026.10.2 database migrations did not all run. Switching an existing managed system to the Ticket Connector later does not create them either, because they are created only when the system is new: create a new managed system instead.

## Test connection <a href="#connect-test-connection" id="connect-test-connection"></a>

**Test connection** is under the form once the system is saved; it tests the **saved** values, so save before you test a change. It sends the connector a test request with the stored credential and shows the outcome in a message under the button:

* `Connection to the ticketing system succeeded.` on success;
* otherwise the connector's error text, such as `Unable to connect to directory.:Jira rejected the credentials (HTTP 401): ...`, or `Connection test failed.` when there is none.

What the connector checks:

| System                               | Calls                                                                                      | Fails when                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Jira                                 | The current user (`/myself`) and the server information (`/serverInfo`)                    | The site cannot be reached, the credential is rejected, or the account may not use the API                            |
| ServiceNow                           | The integration user's own `sys_user` record and, when readable, the latest upgrade record | The instance cannot be reached, the credential is rejected, or the user may not read `sys_user`                       |
| ServiceNow with `TICKET_CREATE_PATH` | Also one probe of the custom path                                                          | No REST API serves the path (`No ServiceNow REST API serves the create endpoint <path>`), or the user may not call it |

The test does not open a project or a table: a missing permission in the project or table a rule uses shows only when the rule runs, as a failed delivery on [Tickets](/administration-guide/ticketing/tickets.md). The rule editor loading the project list is a second, cheap check that the account can browse.

## Verification

* **Test connection** reports success.
* **Ticket rules** and **Tickets** are on the managed system's menu, and **Ticket rules → New rule** lists your projects, or your ServiceNow tables, under **Project** or **Table**.
* **Policy map** shows **TICKET POLICY** with eight rows defined by the ticket rule.
* **Synchronization** lists `Service Desk Jira ticket sync`, and **Batch Tasks** lists `Ticket sync Service Desk Jira`.

## When it goes wrong

| Symptom                                                                     | Likely cause                                                             | Resolution                                                                |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Ticketing system (HANDLER5) is not set on managed system ...`              | **Ticketing system** is empty                                            | Choose **Jira** or **ServiceNow** and save                                |
| `Ticketing system '...' is not supported by this connector; supported: ...` | The stored value is neither `JIRA` nor `SERVICENOW`                      | Choose a value from the dropdown and save                                 |
| `Managed system ... has no host URL`                                        | **Site URL** or **Instance URL** is empty                                | Enter it and save                                                         |
| `Managed system ... has no login or password (API token) set`               | A credential field is empty                                              | Enter both and save                                                       |
| `Jira rejected the credentials (HTTP 401)`                                  | Wrong e-mail or token; on Cloud, a password used instead of an API token | Create a new API token for the account and save it                        |
| `Jira denied access (HTTP 403)` / `ServiceNow denied access (HTTP 403)`     | The account exists but may not use the API or read the resource          | Give the account the permissions in [Before you begin](#before-you-begin) |
| `Jira resource not found (HTTP 404)`                                        | **Site URL** has a path, or points at the wrong site                     | Enter the bare site address                                               |
| `Jira rate limit exceeded (HTTP 429) after 4 attempts`                      | Jira throttled the account                                               | Wait and retry; lower the volume of rules on this system                  |
| `Jira is unavailable (HTTP 503) after 4 attempts`                           | Jira or a proxy is down                                                  | Retry later; the connector has already retried three times                |
| `Cannot reach Jira at <url> after 4 attempts: ...`                          | DNS, proxy, firewall or TLS between the connector and the site           | Test from the connector host, not your workstation                        |
| `Jira deployment type '...' (JIRA_DEPLOYMENT_TYPE) is not supported; ...`   | A wrong value in the attribute                                           | Use `CLOUD` or `DATA_CENTER`, or remove the attribute                     |
| `Authentication type '...' is not supported; supported: API_TOKEN`          | `TICKET_AUTH_TYPE` was edited                                            | Set it back to `API_TOKEN`                                                |
| The test never answers                                                      | The connector is not running — on Kubernetes, still at `replicas: 0`     | Start the connector, then retry                                           |

## Delete a ticketing managed system <a href="#connect-delete-system" id="connect-delete-system"></a>

When the system has tickets, **Delete** warns: *"{n} ticket(s) are associated with this Managed System. If you delete the Managed System, these tickets are deleted too and can no longer be tracked."* Confirming with **Yes, delete the Managed System and its tickets** deletes, in this order: the link from captured simulation requests to the tickets, the tickets, the ticket rules, and the seeded ticket synchronization with its batch task; then the managed system itself. The tickets in Jira or ServiceNow are not touched, but OpenIAM no longer updates, closes or reads them.

A delete sent without that confirmation, for example from an API client, is refused with the response code `LINKED_TO_TICKETS` and the ticket count. To stop ticketing without losing the history, untick **Active** instead.

## Related

* [ServiceNow ticketing system](https://github.com/openiam-platform/gitbook-docs/tree/main/connectorconfig/servicenow-ticketing.md) — installing and running the Ticket Connector for ServiceNow, its properties and troubleshooting.
* [How ticket integration works](/administration-guide/ticketing/overview.md) — what happens between an event and a ticket.
* [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md) — the next step.
* [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md) — what each field becomes in each system, and what the connector retries.
* [The TICKET policy map and ticket synchronization](/administration-guide/ticketing/policy-map-and-sync.md) — the objects the first save creates.
* [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md) — the generic managed system fields.
* [Operate ticket integration](/administration-guide/ticketing/operate-ticketing.md) — logs, audit actions and properties.


---

# 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/administration-guide/ticketing/connect-a-ticketing-system.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.