> 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/policy-map-and-sync.md). # The TICKET policy map and ticket synchronization The TICKET policy map that carries ticket fields to the connector — its eight read-only standard rows and the extra fields you can add to every ticket — and the ticket synchronization that reads statu ## What this is, and when you need it Two objects are created with every ticketing managed system and work in the background of every rule: * the **TICKET policy map**, which carries a ticket's fields from OpenIAM to the Ticket Connector, and to which you can add a field that every ticket of the system must carry; * the **ticket synchronization**, which reads each ticket's status, resolution and assignee back from Jira or ServiceNow every 15 minutes, so the **Tickets** screen and SelfService show where the work stands. Come here to add a field to every ticket — a Jira **Team** or **Due date**, a ServiceNow `assignment_group` — to see why a standard row cannot be edited, or to change how often status is read back. A field that only some rules need belongs on those rules instead, as an [additional field](/administration-guide/ticketing/ticket-rules.md#rule-additional-fields). ## At a glance | | | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Where** | The managed system's menu → **Policy map**, policy **TICKET POLICY** (`/webconsole/policyMap?id=`); **Provisioning → Synchronization** and **Administration → Batch Tasks** for the synchronization | | **Created** | On the first save of the ticketing managed system — see [What the first save creates](/administration-guide/ticketing/connect-a-ticketing-system.md#what-the-first-save-creates) | | **Standard rows** | Eight, read-only, filled from each ticket rule | | **Extra rows** | Any number; each one is sent on every ticket of the system | | **Read back** | Status, resolution, assignee; every 15 minutes; never creates or deletes a ticket | ## The TICKET policy map ### What the policy map does Every ticketing managed system has one policy map named **TICKET POLICY**, of the object type **TICKET**, marked primary. Like the policy map of any managed system it lists what is sent to the connector — but for tickets the values come from the ticket rule that fired, not from a user's attributes. When a rule creates, updates or closes a ticket, OpenIAM builds the request from the map's rows: the eight standard rows take the rule's settings and rendered templates, and each extra row adds its own field. Every row is sent on every operation. The screen shows an information banner instead of the usual policy-map help: *"Ticket fields are defined on each ticket rule. Extra Jira fields can be added below; they are sent on every ticket of this system."*, with a link **Open ticket rules**. The banner says Jira on a ServiceNow system as well; the extra rows work the same there, with column names instead of Jira field ids. The policy map itself cannot be removed and its type cannot be changed (`The TICKET policy map cannot be removed or change its type`), and a row cannot be moved into or out of it (`A row cannot be moved into or out of the TICKET policy map`). Without it, every delivery of the system fails with `no TICKET policy map on `. ### The standard rows The eight standard rows map an attribute the connector understands to the rule setting that fills it. The **Defined by** column says *"Defined by the ticket rule — …"* and the rows have no delete action. | Attribute | **Defined by the ticket rule —** | Jira | ServiceNow | | ------------- | -------------------------------- | ----------- | ------------------- | | `project` | **Project** | Project key | Table | | `issuetype` | **Issue type** | Issue type | Category | | `summary` | **Summary template** | Summary | `short_description` | | `description` | **Description template** | Description | `description` | | `priority` | **Priority** | Priority | Priority | | `labels` | **Labels** | Labels | Correlation fields | | `transition` | **Transition** | Transition | Target state | | `comment` | **Comment template** | Comment | Work note | You can save the map with these rows unchanged, but not edit, deactivate, rename or remove one: the save is refused with `Standard ticket fields of the TICKET policy map cannot be changed or removed: `. To change what a ticket says, change the rule. What each attribute becomes in the ticketing system is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md#system-mapping). ### Add a field to every ticket An extra row sends one more field with every ticket of the system, whatever the rule. Typical uses are a Jira component, team or custom field every issue of the project needs, or a ServiceNow `assignment_group`. {% stepper %} {% step %} **Open the map.** On the managed system's menu choose **Policy map** and open **TICKET POLICY**. {% endstep %} {% step %} **Add a row.** The object type is fixed to **TICKET**, and the new row starts with the policy type `STATIC_VALUE`; `DEFAULT_IDM`, which takes its value from the rule, is reserved for the standard rows. {% endstep %} {% step %} **Pick the field.** **Jira field** searches the fields of the ticketing system by name or id and hides the standard fields and the fields other rows already use. If the fields cannot be read the picker becomes a text box — *"Jira fields could not be read. Type the field id, e.g. customfield\_10050."* — and you type the id: on Jira `customfield_` or a system field id such as `duedate`, on ServiceNow a column name such as `u_cost_center`. {% endstep %} {% step %} **Enter the value and save.** The value is sent as written; how Jira types it (option, user, number, date) is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md#system-jira-additional-fields). {% endstep %} {% endstepper %} A rule that sets the same field as an [additional field](/administration-guide/ticketing/ticket-rules.md#rule-additional-fields) wins over the policy map for its tickets; names are compared ignoring case. A rule can never override a standard row that way. The save checks every extra row, in this order, and refuses the whole map on the first problem: | Check | Message | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The name is empty | `The ticket field name is not a field id of the ticketing system (...)` | | The name is a standard attribute, ignoring case | `The ticket field name is a standard ticket field; only the standard row may use it` | | The name is `query` or `maxResults`, ignoring case | `... reserved by the ticket connector (query, maxResults)` | | The name is not a field id, or longer than 50 characters | `The ticket field name is not a field id of the ticketing system (Jira: customfield_ or a system field id such as duedate; ServiceNow: a column name such as u_cost_center; at most 50 characters)` | | Another row has the same name | `The TICKET policy map already has a row with this name` | ## Ticket synchronization ### How status gets back to OpenIAM Each ticketing managed system gets one synchronization, named ` ticket sync` — for the example, `Service Desk Jira ticket sync` — with these settings: | Setting | Value | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | **Process rule** | **Ticket** | | Source | The managed system, through the Ticket Connector (asynchronous) | | Type | Incremental, query `updated >= ?` on the field `updated` | | **Match** | **Ticket key** (`EXTERNAL_KEY`) against the ticket's key | | Records per batch | 1000 | | Orphan detection, provisioning | Off; the screen hides both for the **Ticket** process rule | | Scripts | `/sync/ticket/TicketSyncValidationScript.groovy` (drops rows without a key) and `/sync/ticket/TicketSyncTransformationScript.groovy` | It runs from the batch task `Ticket sync ` (here `Ticket sync Service Desk Jira`), which is created enabled with the schedule `0 0/15 * * * ?` — every 15 minutes — and the synchronization as its parameter. On each run OpenIAM asks the connector for the tickets carrying the label `openiam` — the correlation field `correlation_display = OpenIAM` on ServiceNow — that changed since the last run; the first run reads them all. At most `org.openiam.sync.ticket.max.results` tickets (default 1000) are read per run. For each ticket whose key matches one of OpenIAM's tickets it writes back: * **Ticket status** — the Jira status or the ServiceNow state; * **Resolution** — the Jira resolution or the ServiceNow close code; * **Assignee**; * **Last synced** and **Sync status** `OK`. The synchronization never creates, deletes or provisions anything, and it does not change a ticket's delivery state: a ticket closed by hand in Jira shows the Jira status while its delivery stays **Delivered**. A ticket created by hand in the ticketing system never matches. Each run writes one `TICKET_SYNC` audit event with the counts `received=`, `matched=` and `unknown=` and up to 50 of the unknown keys — keys carrying OpenIAM's label that OpenIAM has no ticket for, for example tickets of a deleted managed system. ### Change the schedule, or pause it The schedule lives on the batch task, not on the synchronization. In **Administration → Batch Tasks** open `Ticket sync ` and change its cron expression, or untick **Is Active** to pause read-back; tickets are still created, updated and closed. See [Create a batch task](/administration-guide/automation/batch-tasks.md). Running the synchronization by hand from **Provisioning → Synchronization** reads the same changes. Do not change the process rule, the match field or the query of the synchronization: the **Tickets** screen and the retry of failed creates rely on the label and the key. ## When it goes wrong | Symptom | Likely cause | Resolution | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `Standard ticket fields of the TICKET policy map cannot be changed or removed: ` | You edited or deleted a standard row | Cancel the change; set the value on the ticket rule | | `The ticket field name is a standard ticket field; only the standard row may use it` | An extra row uses `summary`, `priority` or another standard name | Use the rule setting instead | | An extra field never reaches the ticket for one rule | The rule sets the same field as an additional field, which wins | Remove it from the rule, or set the value there | | Every delivery fails with `no TICKET policy map on ...` | The map was not created, because its seed was missing on the first save | Run the 2026.10.2 migrations and create the managed system again | | **Ticket status** stays empty | The batch task is disabled or not running, or the connector cannot search | Check the batch task's last run and the `TICKET_SYNC` audit event | | `TICKET_SYNC` shows `matched=0` with many `unknown=` | The tickets belong to another managed system on the same site, or to a deleted one | Expected; only this system's tickets are updated | | Status is old after a burst of changes | More than 1000 tickets changed since the last run | Raise `org.openiam.sync.ticket.max.results`, or run the synchronization again | ## Related * [Write a ticket rule](/administration-guide/ticketing/ticket-rules.md) — where the standard rows get their values. * [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md) — what each row becomes in each system. * [Track tickets](/administration-guide/ticketing/tickets.md) — where the read-back status appears. * [Build a policy map](/administration-guide/lifecycle/policy-map.md) — policy maps in general. * [Set up a synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md) — synchronizations in general. * [Create a batch task](/administration-guide/automation/batch-tasks.md) — the scheduler that runs it. --- # 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/policy-map-and-sync.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.