> 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/jira-and-servicenow.md).
# How fields reach Jira and ServiceNow
What each ticket field becomes in Jira and in ServiceNow — projects and tables, issue types and categories, priorities, labels, transitions and target states, additional fields — and what the connecto
## What this is, and when you need it
A ticket rule speaks one vocabulary — project, issue type, summary, description, priority, labels, transition, comment — and the Ticket Connector translates it for the ticketing system of the managed system. This page is that translation, field by field, for Jira (Cloud and Data Center) and ServiceNow. Read it when a ticket arrives with the wrong priority, a transition is refused, an additional field is rejected, or you need to know what a comment-only rule actually writes.
It does not explain how to write a rule; that is [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md). How to connect the system is on [Connect a ticketing system](/administration-guide/ticketing/connect-a-ticketing-system.md).
## The mapping at a glance
| OpenIAM (rule editor) | Jira | ServiceNow |
| --------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| **Project** / **Table** | The project, by key (`ACCESS`) | The table, any table that extends Task (`sc_task`, `incident`) |
| **Issue type** / **Category** | The issue type, by id or name; required on create | The record's `category`; optional |
| **Summary** | `summary`, sent as written | `short_description` |
| **Description** | `description` — Atlassian Document Format on Cloud, wiki markup on Data Center | `description`, plain text |
| **Priority** | The priority, by id or name | `priority`, by value or label; on `incident` also impact and urgency |
| **Labels** | Labels, plus `openiam` and `openiam-` | Not offered; OpenIAM's two labels go to the correlation fields |
| **Transition** / **Target state** | A workflow transition, by id, name or target status | A state, optionally followed by fields set with it |
| **Comment** | An issue comment | A work note (`work_notes`) |
| Additional fields | Any field id, typed from Jira's field schema | Any column name, sent as text |
| Ticket key | The issue key, `ACCESS-142` | The record `number`, `SCTASK0010042` |
| Ticket id | The issue id | The `sys_id` |
| Link | `/browse/ACCESS-142` | `/sc_task.do?sys_id=...` |
| **Ticket status** read back | The status name | The state label |
| **Resolution** read back | The resolution | The `close_code` |
| **Assignee** read back | The assignee | `assigned_to` |
The summary, description, comment and the values of additional fields are rendered from the rule's templates first; see [Template placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md).
## Jira
### Cloud and Data Center
The connector uses REST API v3 on Jira Cloud and REST API v2 on Data Center, chosen from the site address or the `JIRA_DEPLOYMENT_TYPE` attribute (see [Site URL](/administration-guide/ticketing/connect-a-ticketing-system.md#connect-jira-site-url)). On Cloud the issue search uses `/search/jql` with page tokens, on Data Center `/search` with offsets; both read 100 issues a page.
### Description and comment formatting
The templates know two kinds of formatting, and nothing else is interpreted:
| In the template | Jira Cloud (Atlassian Document Format) | Jira Data Center (wiki markup) |
| --------------------------------------------- | --------------------------------------------------- | ---------------------------------- |
| A blank line | Starts a new paragraph | Kept as is |
| A single line break | A hard break inside the paragraph | Kept as is |
| A line starting with `-` | A bullet-list item; consecutive lines form one list | Rewritten to `* item` |
| Anything else, including `*bold*` or `[link]` | Plain text | Interpreted by Jira as wiki markup |
`${request.items}` renders one `- ` line per requested role, group and resource, so it becomes a bullet list on both deployments. The summary is sent exactly as rendered.
### Priority and issue type
A value made only of digits is sent as an id (`{"id":"3"}`), anything else as a name (`{"name":"Medium"}`). The connector does not check the value first: a priority or issue type the project does not use comes back as Jira's own error, for example `Crud Operation Error:Jira rejected the request (HTTP 400): priority: ...`.
### Labels
Every ticket gets the rule's labels plus two of OpenIAM's own:
* `openiam` — marks the issue as OpenIAM's; the ticket synchronization searches for it.
* `openiam-` — ties the issue to its subject, for example `openiam-` for rule 1 of the example. OpenIAM searches for it before it retries a failed create, and adopts an issue it finds instead of creating a second one.
Label values are split on commas, trimmed, inner whitespace becomes `-`, and duplicates are dropped, so `access request, onboarding` is sent as the two labels `access-request` and `onboarding`. On an update labels are only ever **added**; OpenIAM never removes a label, including one you removed from the rule.
### Transitions
A close rule, and an update rule with a transition, move the issue through a workflow **transition**. The connector reads the issue's available transitions and takes the first that matches, in this order:
1. the transition id, exactly;
2. the transition name, ignoring case (`Done`);
3. the name of the status the transition leads to, ignoring case.
If nothing matches, the delivery fails with `Transition 'Done' is not available for issue ACCESS-142; available: Start progress, Resolve`. The transition request carries only the transition: fields on a transition screen, such as **Resolution**, cannot be set. The rule's comment is posted after the transition.
The rule editor lists transitions read from the most recently updated issue of the project, so the list is empty for a project without issues; you can type a name instead.
### Additional fields
Additional fields — on a rule or as extra rows of the TICKET policy map — are sent by field id (`customfield_10050`, `duedate`). The connector looks the field up in Jira's field schema and types the value:
| Field schema | What you enter | What is sent |
| ----------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Select list (option) | The option's value | `{"value": ""}` |
| Multi-select (array of options) | Values separated by commas | A list of `{"value": ...}` |
| Labels-style text list (array of strings) | Values separated by commas | A list of strings |
| User picker | Cloud: the account id. Data Center: the user name | `{"accountId": ...}` or `{"name": ...}` |
| Number | A number | A JSON number; anything else fails with `Jira field expects a number, got ''` |
| Date, date and time | The value in Jira's format, such as `2026-10-31` | The text as given |
| Multi-line text | Text | Atlassian Document Format on Cloud |
| Anything else | Text | The text |
A value that renders empty clears the field (an empty list for list fields) — except on a rule, where an additional field that renders empty is not sent at all. There is no lookup of a user by name or e-mail: give the account id or user name. The schema comes from the create screen of the project and issue type when they are known and is cached for 10 minutes (`ticket.jira.field.cache.ttl.ms`); when it cannot be read, values are sent as text.
## ServiceNow
### Tables and categories
The **Table** of a rule is any table that extends **Task**. The rule editor lists them from `sys_db_object`; if the integration user may not read it, it offers five standard tables: `change_request`, `sc_task`, `incident`, `problem` and `sc_req_item`. You can always type another. **Category** is optional and goes to the record's `category`.
Updates, closes and reads find a record by its number, or its `sys_id`, on `task`, and then work on the record's own table, so a ticket keeps working if you change the rule's table later. A record the user cannot see fails with `ServiceNow has no task record visible to the account`.
### Priority, impact and urgency
A value made only of digits is sent as is. Anything else is matched against the table's priority choices (or those of `task`): by value, then by label ignoring case, then by the text after ` -` , so `High`, `2 - High` and `2` all mean the same choice. No match fails with `Priority '' is not a priority of ; available: ...`.
On the `incident` table ServiceNow computes the priority from impact and urgency, so a priority of 1 to 5 also sets them:
| Priority | Impact | Urgency |
| -------- | ------ | ------- |
| 1 | 1 | 1 |
| 2 | 1 | 2 |
| 3 | 2 | 2 |
| 4 | 2 | 3 |
| 5 | 3 | 3 |
This assumes the out-of-the-box priority lookup. If a rule or the policy map sets `impact` or `urgency` itself as an additional field, the connector sets **neither**, and the values you give are the only ones sent.
### OpenIAM's labels on ServiceNow
ServiceNow records have no labels, and the editor hides **Labels** on a ServiceNow system. OpenIAM's two markers go to the correlation fields instead, on every create and update:
| Marker | Field | Value |
| ----------------------- | --------------------- | ----------------------- |
| `openiam` | `correlation_display` | `OpenIAM` |
| `openiam-` | `correlation_id` | `openiam-` |
Any other label is dropped. Do not let another integration write these two fields on the same records: the ticket synchronization and the duplicate check before a retried create rely on them.
### Target states
**Target state** is a state of the table, optionally followed by fields to set in the same update, separated by `|`:
{% code overflow="wrap" %}
```
Resolved | close_code=Solution provided | close_notes=Closed by OpenIAM
```
{% endcode %}
The state is matched against the table's state choices like a priority (value, label, or the text after ` -` ); unknown states fail with `State '' is not a state of ; available: ...`. A field with an empty value is cleared. Text that does not follow the pattern fails with `ServiceNow transition '' is not ' | = | ...': `. The state, the fields and the rule's comment go to ServiceNow in one update, so a mandatory close code can be set together with the state. On `sc_task` the closing state is `Closed Complete`.
### Work notes and descriptions
The comment of an update or close rule is added as a **work note**, visible to fulfillers, not as a customer-visible comment. The description is sent as plain text, line breaks included; `-` lines stay as written.
### Additional fields
Additional fields are column names of the table, such as `assignment_group` or `u_cost_center`, and their values are sent as text — for a reference field, give the `sys_id` or the display value your instance accepts. The rule editor lists the table's columns (and those of `task`) from `sys_dictionary`, without system columns and without the columns the editor already covers; if the user may not read `sys_dictionary`, the list is empty and you type the column name.
### Custom create endpoint
With the managed-system attribute `TICKET_CREATE_PATH` (see [Instance URL](/administration-guide/ticketing/connect-a-ticketing-system.md#connect-servicenow-instance-url)), a create is one `POST` to that path instead of the Table API. The body holds `short_description`, `description` and the additional fields only — no category, priority or correlation fields — so the record has no OpenIAM markers until the first update writes them. The answer may be a `result` object, a `result` list or a flat object, and must name the record's `number` or `sys_id`; otherwise the create fails with `ServiceNow endpoint answered without a record number or sys_id; a ticket may have been created there`. Check ServiceNow before you retry that ticket.
## What each operation does
| Operation | Jira | ServiceNow | Reply to OpenIAM |
| ----------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------- |
| Create | `POST /issue` with every field | `POST` to the table, or to the custom endpoint | The key, the id and the link |
| Update | `PUT /issue/` with the changed fields and the added labels, then the comment | One `PATCH` with the fields, the correlation fields and the work note | Success only |
| Transition (close, or update with a transition) | Find the transition, `POST` it, then the comment | One `PATCH` with the state, its fields and the work note | The new status |
| Get, search | Read the issue; search by JQL on labels, project and update time | Read the record; search by encoded query on the correlation fields and `sys_updated_on` | The ticket, or the list |
An update without a ticket key fails with `Ticket has no external key yet`; OpenIAM holds such updates until the create has returned the key (see [How ticket integration works](/administration-guide/ticketing/overview.md)).
Even an update that only adds a comment writes a field: on Jira it adds the `openiam` label (so the account needs **Edit issues**), on ServiceNow it writes `correlation_display`.
## Retries and timeouts
The connector retries a call itself before it answers OpenIAM. With the default properties:
| Error | Create | Every other call |
| ---------------------------------- | --------------- | ---------------- |
| HTTP 429 (rate limit) | Retried | Retried |
| HTTP 5xx, connection or read error | **Not retried** | Retried |
| Any other HTTP 4xx, including 401 | Not retried | Not retried |
Up to three retries, after 1, 2 and 4 seconds, or after the `Retry-After` time Jira or ServiceNow asks for, capped at 30 seconds. Connections time out after 10 seconds, answers after 30. A create is never repeated on a server error, because the first attempt may have created the ticket; OpenIAM's own retry later first searches for the ticket's subject label and adopts what it finds. A comment, a Jira transition or a ServiceNow work note retried after a server error can therefore appear twice.
What the connector cannot fix becomes a failed delivery in OpenIAM, which retries it on its own schedule; see [Operate ticket integration](/administration-guide/ticketing/operate-ticketing.md).
## Limitations in this release
* Basic authentication only: no OAuth, no Jira Data Center personal access tokens.
* Jira transitions cannot set transition-screen fields such as **Resolution**.
* Jira labels are added, never removed.
* Jira user fields need an account id (Cloud) or user name (Data Center); there is no lookup.
* ServiceNow additional fields are sent as text, without typing; a numeric ServiceNow priority is not checked against the choices.
* The impact and urgency mapping assumes ServiceNow's default incident priority lookup.
* A ServiceNow record created through a custom endpoint has no correlation fields until its first update.
## Related
* [ServiceNow ticketing system](https://github.com/openiam-platform/gitbook-docs/tree/main/connectorconfig/servicenow-ticketing.md) — the connector page for ServiceNow, with the instance prerequisites.
* [Connect a ticketing system](/administration-guide/ticketing/connect-a-ticketing-system.md) — the fields and attributes these rules read.
* [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md) — where project, issue type, priority, labels, transition and additional fields are set.
* [The TICKET policy map and ticket synchronization](/administration-guide/ticketing/policy-map-and-sync.md) — extra fields on every ticket, and what is read back.
* [Track tickets](/administration-guide/ticketing/tickets.md) — where a refused field shows up as a failed delivery.
---
# 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/jira-and-servicenow.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.