> 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/overview.md).
# How ticket integration works
How OpenIAM turns an event into a Jira or ServiceNow ticket — rules, triggers, trigger groups, one ticket per subject, delivery states and the status read back from the ticketing system.
## What this is, and when you need it
This page is for every administrator who writes ticket rules or answers "why did this ticket (not) appear?". It explains the moving parts and the rules every ticket obeys, without settings. Read it before your first rule: most rules that "do nothing" break one of the rules in [One ticket per subject](#concept-one-ticket-per-subject).
To connect Jira or ServiceNow, go to [Connect a ticketing system](/administration-guide/ticketing/connect-a-ticketing-system.md). To write a rule, go to [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md).
## The vocabulary
| Term | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ticketing system** | Jira (Cloud or Data Center) or ServiceNow. In OpenIAM it is a [managed system](/administration-guide/lifecycle/connectors-and-managed-systems.md) whose connector is the **Ticket Connector** and whose **Ticketing system** field says which of the two it is |
| **Ticket Connector** | The runtime component (`ticket-connector-rabbitmq`) that calls the Jira or ServiceNow REST (Representational State Transfer) API on OpenIAM's behalf. One connector serves every ticketing managed system |
| **Ticket rule** | A rule on one ticketing managed system: *when* this event happens (**WHEN**), *if* it matches these conditions (**IF**), *then* create, update or close a ticket with this content (**THEN**) |
| **Trigger** | The kind of OpenIAM event a rule reacts to, such as **Request submitted** or **User terminated**. There are 25; see [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md) |
| **Trigger group** | The family a trigger belongs to. All triggers of a group share one ticket per subject; a rule's triggers must all be of one group |
| **Subject** | What a ticket is about: a request, a user, a user on a managed system, or a non-human identity (NHI). The trigger group decides which |
| **Ticket** | OpenIAM's record of one ticket in the ticketing system: its key (such as `ACCESS-142`), its subject, the rule that made it, its delivery state and the status read back from the ticketing system |
| **Delivery** | OpenIAM's own send of a create, update or close to the ticketing system, and whether the ticketing system accepted it: **Pending**, **Delivered** or **Failed** |
| **Ticket status** | The ticketing system's own status and resolution of the ticket (`Done`, `Closed Complete`…). OpenIAM reads it back; it never decides it |
## How a ticket is produced
1. **An event happens and is emitted.** A request is submitted, a user is saved, a provisioning reply arrives, an NHI changes. User, request and NHI events are sent only after the change is committed, so a rolled-back save raises nothing. Each event carries its trigger and the ids of its subject.
2. **The rules are loaded.** OpenIAM takes every *enabled* rule that lists the event's trigger, across all ticketing managed systems, in **Order** (lowest first) and then by name. Rules on a managed system that is inactive, or whose connector is not the Ticket Connector, are skipped.
3. **Every matching rule runs.** There is no "first match wins": each rule whose **IF** conditions match the event is processed, in order. Two rules on the same system and subject therefore act on the same ticket one after the other.
4. **The decision.** For each rule OpenIAM looks up the subject's ticket on that system and decides:
| Rule operation | Subject has no ticket yet | Subject already has a ticket |
| -------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Create** | Create the ticket | **If a ticket already exists for this subject**: update it (**Add a comment instead**) or skip (**Do nothing**) |
| **Update** | **If no ticket exists yet**: create it (**Create a new ticket**) or skip (**Do nothing and log**) | Update it |
| **Close** | **If no ticket exists yet**: create it and then close it, or skip | Close it with the rule's transition |
5. **The content is rendered.** The rule's summary, description, comment and additional fields are templates; their `${…}` [placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md) are filled from the event, the request, the users involved and the managed system. A placeholder with no value renders as nothing.
6. **The TICKET policy map shapes the request.** The ticketing managed system's [TICKET policy map](/administration-guide/ticketing/policy-map-and-sync.md#map-ticket-policy-map) turns the rendered fields into the connector request; extra rows there add a field to every ticket.
7. **The connector delivers it.** The ticket is written as **Pending** and the request goes to the Ticket Connector, which calls Jira or ServiceNow. If the managed system is in [simulation mode](/administration-guide/ticketing/review-before-sending.md) for that operation, the request is captured for review instead.
8. **The reply updates the ticket.** A successful create stores the key, the internal id and the link; the ticket becomes **Delivered**. A refusal makes it **Failed** with the reason, and OpenIAM retries it with a growing delay. See [Operate ticket integration](/administration-guide/ticketing/operate-ticketing.md).
9. **The status comes back.** Every 15 minutes the [ticket synchronization](/administration-guide/ticketing/policy-map-and-sync.md#sync-ticket-sync) reads the status, resolution and assignee of OpenIAM's tickets from the ticketing system. It never creates, closes or deletes anything.
Every step is audited; the [ticket details](/administration-guide/ticketing/tickets.md#tickets-audit-trail) show the trail of one ticket.
## One ticket per subject
OpenIAM keeps its own record of every ticket it created, and an update or close never searches the ticketing system for "a ticket that looks right". It looks the ticket up by three things:
1. **The ticketing managed system** the rule belongs to.
2. **The trigger group** of the event — not the individual trigger, and not the rule.
3. **The subject** of the event, which the trigger group defines:
| Trigger group | Subject — one ticket per | Triggers |
| ------------------ | ------------------------------ | --------------------------------------------------- |
| Request | request | the eight request lifecycle triggers |
| Access revoked | revoke request | **Access revoked** |
| User created | user | **User created** |
| User edited | user | **User edited** |
| User terminated | user | **User terminated** |
| Provisioning | user and target managed system | **Provisioning failed**, **Provisioning succeeded** |
| Fulfilment | — (reserved) | **Provisioning requested** |
| Non-human identity | non-human identity | the ten NHI triggers |
The database enforces it: two tickets for the same system, group and subject cannot exist. Three consequences follow, and most rules that do not do what you expect trace back to one of them:
* **Rules share tickets.** Every rule and every trigger of one group, on one ticketing system, works on the same ticket for a subject. In the running example, **Access request opened** (Request submitted → Create), **Access request decided** (Request step decided → Update) and **Access request finished** (Request completed → Close) all act on `ACCESS-142`.
* **Groups never share tickets.** **User created**, **User edited** and **User terminated** are three separate groups. A **User terminated → Close** rule never finds the ticket that **User created** opened for the same person.
* **Tickets created by hand are never matched.** Only tickets OpenIAM created are in its record. A Jira issue someone opened manually for Sam Patel is invisible to every rule.
A ticket stays the subject's ticket after it is closed in the ticketing system. A later event for the same subject updates the closed ticket rather than opening a new one; it reopens only if a rule's transition moves it back to an open status.
{% hint style="info" %}
The **Subject** column of the Tickets screen shows the subject's name, and the drawer shows the **Trigger group**. Together they tell you which later events will find a ticket.
{% endhint %}
## Trigger groups and subjects
### Request
All eight request lifecycle triggers — submitted, step decided, escalated, delegated, completed, rejected, cancelled, expired — share one ticket per request. This is the group to use for a ticket that follows a request from start to finish: a create rule on **Request submitted**, update rules on the steps, a close rule on the outcomes. The subject key is the OpenIAM request id, the only id that stays the same from submission to completion.
### Access revoked
**Access revoked** is alone in its group. Its subject is the revoke request, so each revoke request gets its own ticket and no other trigger can update or close it. Use it with **Create**.
### User created
**User created** is alone in its group; the subject is the user. A create rule here opens one ticket per new user. Nothing later finds that ticket: user edits and terminations are other groups.
### User edited
**User edited** is alone in its group, and the subject is the user — one ticket per user for all of that user's edits. The first matching edit creates the ticket (with an update rule and **Create a new ticket**, or with a create rule); every later edit updates the same ticket.
### User terminated
**User terminated** is alone in its group; the subject is the user. A create rule opens one ticket per leaver. An update or close rule on this trigger finds that ticket only when the same user is terminated again, for example after being reactivated.
### Provisioning
**Provisioning failed** and **Provisioning succeeded** share one ticket per user *and* target managed system. A failure on Corporate AD for Sam Patel and a later success on Corporate AD for Sam Patel act on one ticket; a failure on another managed system opens another. The operation (save, delete, reset password…) is not part of the subject: it is available as a condition and a placeholder.
For a group provisioning reply the subject is the group and the managed system; such events carry no target user.
### Fulfilment
Reserved for a later release. Its only trigger, **Provisioning requested**, is listed in the rule editor but no event is sent for it, so a rule on it never fires. The editor does not let you combine it with the other provisioning triggers.
### Non-human identity
All ten NHI triggers share one ticket per non-human identity: a create rule on **NHI created** and an update or close rule on any later NHI event act on the same ticket. See [Manage non-human identities](/administration-guide/nhi.md) for the identities themselves.
## How OpenIAM recognizes its own tickets
Every ticket OpenIAM creates carries two markers next to the rule's own labels:
| Marker | Value | Used for |
| ------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Marker label | `openiam` | The ticket synchronization searches the ticketing system for it |
| Subject label | `openiam-`, for example `openiam-` | A retried create first searches for it, so a ticket created by an attempt whose reply was lost is adopted instead of created twice |
In Jira both are ordinary labels. ServiceNow has no labels: the connector stores `OpenIAM` in the record's **Correlation display** field and the subject label in **Correlation ID**, and keeps no other label. Do not remove these markers by hand; a ticket without them is no longer read back by the synchronization.
## Delivery states
A ticket has two independent states. **Ticket status** is what Jira or ServiceNow says about the work. **Delivery** is whether OpenIAM's last change reached the ticketing system. The screens show delivery as three states; the backend keeps nine.
### Pending
| Constant | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `PENDING_CREATE` | The create has been sent, or captured for review in simulation, and the new key has not come back yet |
| `PENDING_UPDATE` | An update has been sent, or is being held because the ticket has not been created yet |
| `PENDING_CLOSE` | The close transition has been sent, or is being held until the ticket exists |
An update or close that arrives while the create is still on its way is held, not lost: OpenIAM checks it again every minute and sends it as soon as the key exists. A held change that waits longer than 15 minutes becomes **Failed**. A pending delivery whose reply never arrives is sent again after the pending timeout (10 minutes by default).
### Delivered
| Constant | Meaning |
| --------- | ------------------------------------------------------------ |
| `CREATED` | The ticketing system created the ticket and returned its key |
| `UPDATED` | The last update reached the ticketing system |
| `CLOSED` | The close transition was accepted |
### Failed
| Constant | Meaning |
| ------------- | ----------------------------------------------------- |
| `FAIL_CREATE` | The create was refused or could not be sent |
| `FAIL_UPDATE` | The last update was refused or could not be sent |
| `FAIL_CLOSE` | The close transition was refused or could not be sent |
A failed delivery keeps its reason in **Last error** and is retried automatically: five times by default, the first time after 10 minutes and then after a delay that doubles each time. After the last retry it stays **Failed** until you **Retry** or **Discard** it on the [Tickets screen](/administration-guide/ticketing/tickets.md#tickets-retry). The SelfService **Ticket** column shows the same three states as a badge when a ticket has no key yet.
## Who can do what
The **Ticket rules** and **Tickets** menu items are seeded for the shipped Super Security Admin role only, and appear only on a managed system whose connector is the Ticket Connector. The screens have no finer rights of their own: whoever can open a ticketing managed system's menu can create, change and delete its rules and retry or discard its deliveries. Rule saves and deletes are audited with the administrator who made them. To give someone else the screens, grant them the two menu items through the usual menu authorization.
Requesters and approvers never see these screens. In SelfService they see only the ticket key, linked to the ticketing system, next to their request.
## Limits
| Limit | Value |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ticketing systems | Jira Cloud, Jira Data Center, ServiceNow |
| Authentication | Basic authentication only: e-mail and API token on Jira Cloud, user name and password on Jira Data Center and ServiceNow. No OAuth 2.0, no Data Center personal access token |
| Tickets per subject | One per ticketing system and trigger group |
| Rules listed on the Ticket rules screen | 200 per ticketing system |
| Rule name | 120 characters, unique within the ticketing system |
| Triggers per rule | Any number, all of one trigger group |
| Ticket status read-back | Every 15 minutes, up to 1000 tickets per run |
| Automatic retries of a failed delivery | 5, the first after 10 minutes, each delay double the one before |
## Related
* [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md) — the rule editor, card by card.
* [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md) — when each trigger fires and what it can do.
* [Track tickets](/administration-guide/ticketing/tickets.md) — the Tickets screen and the SelfService Ticket column.
* [Operate ticket integration](/administration-guide/ticketing/operate-ticketing.md) — retries, properties and audit actions.
* [Glossary](/glossary.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/administration-guide/ticketing/overview.md?ask=&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.