> 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/ticket-rules.md). # Write a ticket rule Create, change, duplicate and delete ticket rules — the Ticket rules list and the four cards of the rule editor, from the trigger to the ticket's content and the live preview. ## What this is, and when you need it A ticket rule tells OpenIAM to create, update or close a ticket in Jira or ServiceNow when an OpenIAM event happens. This page walks through the **Ticket rules** list and the rule editor, card by card, using the three request rules of the running example. Read [How ticket integration works](/administration-guide/ticketing/overview.md) first if you have not: which ticket an update or close finds is decided by the trigger group and the subject, not by anything on this page. You are in the wrong place if the ticketing system is not connected yet — start with [Connect a ticketing system](/administration-guide/ticketing/connect-a-ticketing-system.md). For the full list of triggers and conditions go to [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md); for every placeholder, to [Template placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md). ## At a glance | | | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Where** | **Provisioning → Managed System**, open the ticketing system, then **Ticket rules** in its menu (`/webconsole/ticket-rules?id=`) | | **Editor** | A full page (`/webconsole/ticket-rule`) with four cards — **WHEN**, **IF**, **THEN**, **Ticket content & template** — and a **Live ticket preview** | | **Operations** | **Create**, **Update**, **Close** | | **Takes effect** | On the next matching event after **Save rule**; existing tickets are not touched | | **Reversible** | Yes — disable or delete the rule; tickets it already created stay in the ticketing system | ## Before you begin * The ticketing managed system exists, is active and passes **Test connection** ([Connect a ticketing system](/administration-guide/ticketing/connect-a-ticketing-system.md#connect-test-connection)). The editor reads projects, issue types, priorities and transitions from it; without a connection you type them by hand. * You know which project and issue type (Jira) or table (ServiceNow) the tickets belong in, and the transition that closes them. * If the rules should not reach the service desk yet, put the managed system in simulation for **Create**, **Update** and **Close** first ([Review tickets before they are sent](/administration-guide/ticketing/review-before-sending.md)). ## The Ticket rules list The list shows every rule of this ticketing system, up to 200, with **New rule** at the top right. With no rules it says *No ticket rules yet*. | Column | Shows | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | The rule name, with the description below it | | **Trigger** | The trigger section as a coloured chip and the first trigger; **+n** when the rule has more triggers, with the others in its tooltip | | **Applies to** | One line per condition (`Managed systems: Corporate AD`); **All** when the rule has no conditions | | **Operation** | **Create**, **Update** or **Close** | | **Target** | The project and issue type (Jira) or table and category (ServiceNow) of the tickets the rule creates | | **Enabled** | A switch; see below | | **Last fired** | See below | | **Actions** | Edit, duplicate, delete | ### Last fired The last time a ticket of this rule was created or changed, taken from the rule's tickets. **Never** means the rule has not produced a ticket yet — either no matching event happened, or every event was skipped by a **Do nothing** choice. It does not count events the conditions excluded. ### Enabled A disabled rule is saved but skipped for every event. The switch in the list saves at once (*Ticket rule saved.*) and flips back if the save fails; the switch in the editor's header is saved with the rule. Disabling a rule does not change its tickets, and re-enabling it does not replay the events it missed. ### Duplicate Opens the editor on a copy of the rule named ` (copy)`, **disabled**, with every setting of the original. Nothing is saved until you click **Save rule**. Duplicate is the quickest way to make **Access request finished** for the ServiceNow system from the Jira one, but remember the copy keeps the original's project and transition. ### Delete Asks *Delete the rule "Access request opened"? Tickets it created are kept.* and deletes the rule. Its tickets stay in OpenIAM and in the ticketing system and show **No rule** in the **Rule** column from then on; later events for their subjects are still matched by the remaining rules of the same trigger group. ## Create a rule This builds rule 1 of the running example, **Access request opened** on Service Desk Jira. {% stepper %} {% step %} **Open the editor.** On Service Desk Jira, open **Ticket rules** and click **New rule**. A new rule starts as **Create**, enabled, with **Add a comment instead** and **Create a new ticket** preselected and no trigger. {% endstep %} {% step %} **Name it.** Type `Access request opened` in **Rule name**, add a description if you like, and leave **Order** at the proposed value (one more than the highest existing order). {% endstep %} {% step %} **Pick the trigger.** In **WHEN · Event trigger**, choose the **Request lifecycle** tab and select **Request submitted**. {% endstep %} {% step %} **Leave the conditions empty.** **IF · Applies to** offers **Request types**; leave it empty so every request opens a ticket. The card's footer reads *Currently fires for: every event of the trigger*. {% endstep %} {% step %} **Choose the action and the target.** In **THEN**, keep **Create**. Select the project **Access Requests (ACCESS)**, the issue type **Task**, the priority **Medium**, and add the label `access-request`. Keep **Add a comment instead** under **If a ticket already exists for this subject**. {% endstep %} {% step %} **Write the content.** In **Ticket content & template**, set **Summary** to `Access request ${request.name} for ${targetUser.displayName}` and **Description** to: {% code overflow="wrap" %} ``` Requested by ${requester.displayName}. Justification: ${request.justification} Items: ${request.items} ``` {% endcode %} {% endstep %} {% step %} **Check the preview and save.** The **Live ticket preview** shows `ACCESS-#### · Task`, the summary with `[Request name]` and `[Target user display name]` in place of the placeholders, and the label chips. Click **Save rule**. The list opens with *Ticket rule saved.* {% endstep %} {% endstepper %} Rules 2 and 3 follow the same steps: **Access request decided** with **Request step decided** → **Update** and a comment, **Access request finished** with four triggers → **Close**. ## The editor header The header stays at the top while you scroll. **Cancel** returns to the list (with *Leave without saving?* when there are unsaved changes, and the browser's own prompt if you close the tab). **Save rule** is disabled while a required field is empty or a template holds an unknown placeholder; a rejected save lists the server's reasons under the header. ### Rule name Required, at most 120 characters, and unique within the ticketing system (*A rule named Access request opened already exists*). The name appears in the Tickets screen, in the audit trail and in the `${rule.name}` placeholder, so name rules after what they do, not after the trigger. ### Order *Rules are evaluated from the lowest order up.* Order decides the sequence in which matching rules run, not which one wins: every enabled rule whose trigger and conditions match the event runs. It matters when two rules act on the same subject in one event — for example a create rule at order 1 and an update rule at order 2 on the same trigger produce a ticket and then a comment on it. Rules with the same order run by name. ## WHEN · Event trigger Pick a trigger section — **Request lifecycle**, **People**, **Provisioning** or **Non-human identities** — then one or more triggers from its list. The search box filters the list; selected triggers appear on the right under *Selected triggers (n)* and can be removed there. Switching to another section clears the triggers *and* the conditions. When to use each trigger, and whether it can usefully create, update or close a ticket, is on [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md#what-each-trigger-can-do). ### One trigger group per rule All triggers of a rule must belong to one trigger group, because they must work on the same ticket. A trigger that cannot be combined with the ones already selected is greyed out, with the tooltip *This trigger cannot be combined with the selected ones*. In practice: * **Request lifecycle** and **Non-human identities**: combine any triggers of the section. **Access request finished** uses four. * **People**: every trigger is its own group, so a rule takes exactly one of them. * **Provisioning**: **Provisioning failed** and **Provisioning succeeded** combine; **Provisioning requested** stands alone (and never fires; it is reserved). The server enforces the same rule: *All triggers of a rule must belong to one trigger group*. ## IF · Applies to Narrow the events the rule reacts to. The fields depend on the triggers: request types for the request lifecycle, changed attributes for **User edited**, resources for **Access revoked**, managed systems and operations for provisioning, NHI types, environments and risk classifications for non-human identities. **User created** and **User terminated** have none. Every field is a list of values, and the rule matches an event whose value is *any* of them; an empty field does not restrict. Conditions in different fields must all match. There are no other operators. The footer, *Currently fires for: …*, summarises what the rule currently matches; check it before you save. Each field is described under [Conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md#conditions). **Provisioning failure** (rule 4) is the example: **Managed systems** = Corporate AD, nothing else. ## THEN · Ticket action & destination Choose the operation at the top of the card. The fields below it change with the operation. ### Create Opens a ticket for the event's subject in the project and issue type you choose, with the summary and description of the content card, the priority, your labels and the [additional fields](#rule-additional-fields). The project, the issue type (Jira only) and the summary are required. ### If a ticket already exists for this subject A create rule finds an existing ticket when an earlier event of the same trigger group already opened one for the subject — the request was resubmitted in a new approval process, or another create rule of the group ran first. | Choice | What happens | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Add a comment instead** | The existing ticket is updated instead of a second one being created. The update carries this rule's rendered summary, description, priority, labels and additional fields, so those fields of the existing ticket are overwritten; a comment is added only if the rule has a comment template, which the editor does not offer for a create rule | | **Do nothing** | The event is skipped for this rule | The existing ticket's state does not matter: a ticket already closed in Jira is updated all the same. ### Update Adds the rendered **Comment** to the subject's ticket. **Access request decided** (rule 2) comments `Priya Nair decided approved on : ` on `ACCESS-142`. An update rule has no transition field: it does not change the ticket's status; use a close rule for that. ### Also change fields Off by default. When on, an update rule also rewrites the ticket's **Summary**, **Description**, **Priority**, adds **Labels** and sets [additional fields](#rule-additional-fields). Turning it off clears those settings when you save, so the update carries the comment only. ### Close Moves the subject's ticket through the **Transition** (Jira) or to the **Target state** (ServiceNow), which is required. **Access request finished** (rule 3) uses **Done** on four triggers, so the ticket closes however the request ends. A close rule never sets additional fields. The ticket's status after the transition comes back in the reply and shows in **Ticket status**. ### Add a closing comment On by default for a new close rule. Adds the **Comment** template together with the transition — rule 3 writes `Request ${request.status}.` with the request's final status. Turned off, the content card says *No content needed: the ticket is closed without a comment.* and the comment template is cleared on save. ### If no ticket exists yet An update or close rule finds no ticket when no earlier event of its trigger group created one for this subject. | Choice | What happens | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create a new ticket** | A ticket is created first, in the project and issue type shown below the choice (*Project and issue type of the ticket created when none exists yet.*). For an update rule the new ticket carries the rule's content. For a close rule OpenIAM creates the ticket and then closes it as soon as the ticketing system has returned the new key | | **Do nothing and log** | The event is skipped for this rule and the decision is audited | Rule 3 uses **Do nothing and log**: a request submitted before rule 1 existed has no ticket, and there is no point in opening one only to close it. {% hint style="info" %} An update or close that arrives while the ticket is still being created waits until the ticketing system has returned the key, then runs. You do not need to order or delay rules for that. A change that still has no ticket after 15 minutes fails. {% endhint %} ### Project **Project** on Jira, **Table** on ServiceNow. The list shows `Name (KEY)` from the ticketing system; choosing another project clears the issue type. On ServiceNow the list holds the tables built on `task` — `incident`, `sc_task`, `change_request`, `problem`, `sc_req_item` and any custom ones. At most 64 characters. ### Issue type **Issue type** on Jira, required for a create. **Category** on ServiceNow, optional. Disabled until a project is chosen (*Please select a project first.*); it lists that project's issue types or the table's categories. An issue type the new project lacks is cleared. ### Priority Optional. Chosen from the ticketing system's priorities, or typed. A value of digits is sent as a Jira priority id or a ServiceNow priority value, anything else as a name; ServiceNow also accepts the label without its number (`High` for `2 - High`). How each system applies it is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md). ### Labels Jira only — the field is hidden on ServiceNow. Free labels, comma-separated, at most 500 characters together. *The openiam marker label and the subject label are added automatically*; see [How OpenIAM recognizes its own tickets](/administration-guide/ticketing/overview.md#how-openiam-recognizes-its-own-tickets). Labels are only ever added to a ticket, never removed. ### Transition **Transition** on Jira, **Target state** on ServiceNow. Required for a close rule, and shown only for one. The list offers the transitions read from the project's most recently updated issue; you can also type a value. Jira accepts a transition id, a transition name or the name of the status it leads to. ServiceNow takes a state, optionally followed by fields set with it: `Closed Complete | close_notes=Closed by OpenIAM`. Details are on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md). The editor checks that a close rule has a transition; the server checks it only when the rule fires, and a close without one fails with `transition is required to close`. ### When the ticketing system cannot be read The editor reads the lists from the ticketing system when it opens and when you pick a project. If it cannot: | Message | Meaning | What to do | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | *The ticketing system could not be reached. Enter the project, issue type, priority and transition by hand.* | Nothing could be read: the connector is down, the credentials are wrong or the system is unreachable | Type the values; check **Test connection** on the managed system | | *The issue types and transitions of project {0} could not be read. All issue types are offered.* | The project is not readable by the integration account, or has no issue yet to read transitions from | Check the account's project permissions; type the transition | Nothing you type is validated against the ticketing system on save: a wrong key surfaces as a **Failed** delivery the first time the rule fires. ## Ticket content & template The content is written as templates. Each field has **Insert placeholder**, which puts a `${…}` placeholder at the cursor and offers only the placeholders every selected trigger can fill; under the field the placeholders show as chips — blue when fine, amber and struck through when a selected trigger cannot fill them, red when unknown. Both amber and red block **Save rule**. See [Template placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md#ph-insert). | Operation | Fields shown | | ---------- | --------------------------------------------------------------------------------------------- | | **Create** | **Summary**, **Description**, additional fields | | **Update** | **Comment**; with **Also change fields** also **Summary**, **Description**, additional fields | | **Close** | **Comment**, when **Add a closing comment** is on | ### Summary One line, required for a create rule (*Enter a summary.*). It becomes the Jira summary or the ServiceNow short description. Keep it short: Jira limits a summary to 255 characters. ### Description The body of the ticket. Keep descriptions compact; a very long description makes Jira slow to accept the create. ### Comment The comment an update or close rule adds — a Jira comment, a ServiceNow work note. ### Formatting *A blank line starts a paragraph. A line starting with - becomes a bullet.* That is all the formatting there is; everything else is plain text. Jira Cloud receives real paragraphs and bullet lists, Jira Data Center the same as wiki markup (`* item`), ServiceNow the text as written. `${request.items}` renders one `- ` line per requested item, so it becomes a bullet list by itself. ### Additional fields **Additional Jira fields** (or **Additional ServiceNow fields**) set any other field of the ticket — `duedate`, a custom field such as `customfield_10050`, or a ServiceNow column such as `assignment_group` or `u_cost_center` — to a fixed value or a template. Shown for a create rule and for an update rule with **Also change fields**, never for a close rule. * **Add field**, pick the **Field** (searchable by name or id; fields the ticketing system marks required come first as *(required)*), then the **Value**. A field with allowed values offers them as a list; otherwise the value is a template. * When the ticketing system reports required fields for the chosen target, *Jira requires: …* lists the ones the rule does not set yet. * A field that renders empty for an event is not sent. * A field set here wins over an extra row of the same name in the [TICKET policy map](/administration-guide/ticketing/policy-map-and-sync.md#map-extra-rows). The eight standard fields (project, issue type, summary, description, priority, labels, transition, comment) cannot be used here; set them in the rule's own fields. How values are typed for Jira (options, users, numbers, dates) and sent to ServiceNow is on [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md). ## Live ticket preview The panel on the right shows the ticket as the rule would write it: `ACCESS-#### · Task` and the operation, the summary and description (or *Transition → Done* and the *New comment* for an update or close), paragraphs and bullets, priority and label chips, and the additional fields. Placeholders appear as their names in brackets — `[Target user display name]` — not as values from a real event, and unknown or unavailable placeholders are flagged. The footer reads *Fires on Request lifecycle · Request submitted*. To see real values, let the rule fire with the managed system in simulation and open the captured request ([Review tickets before they are sent](/administration-guide/ticketing/review-before-sending.md)). ## Validation messages | Message | Cause | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | *Enter a name.* | **Rule name** is empty | | *A rule named … already exists* | Another rule of this ticketing system has the name | | *Select at least one trigger.* | No trigger selected | | *All triggers of a rule must be events of the same kind.* | Triggers of two trigger groups | | *Select a project.* / *Select an issue type.* | A create rule (or a fallback create) without a project, or without an issue type on Jira | | *Enter a summary.* | A create rule without a summary | | *Select the transition that closes the ticket.* | A close rule without a transition | | *The … can have at most n characters.* | Name 120; description and labels 500; project, issue type, priority and transition 64 | | *Remove or correct the unknown placeholder.* | A `${…}` the catalogue does not know | | *Remove the placeholders the selected triggers cannot fill.* | A placeholder that is not available for every selected trigger | | `'priority' is a standard ticket field; set it in the rule's own setting` | An additional field uses one of the eight standard names | | `Additional field 'x' is not a field id of the ticketing system …` | The field id is not `customfield_`, a system field id or a column name | | `… is set more than once` / `… needs a value` | Two rows for one field, or a row without a value | ## Verification 1. Submit a request that matches the rule. Open **Tickets** on the ticketing system: a row with **Delivery** **Delivered** and a key such as `ACCESS-142` appears within seconds. **Pending** that does not turn **Delivered** means the connector has not replied. 2. Click the key. The ticket opens in Jira or ServiceNow with your summary, description, priority and labels. 3. In the rules list, **Last fired** shows the time of the event. 4. For update and close rules, let the next event of the group happen and check the comment and the status on the same ticket. ## When it goes wrong | Symptom | Likely cause | Resolution | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | No ticket at all, **Last fired** stays **Never** | The rule is disabled, the conditions exclude the event, or the trigger never fires (**Provisioning requested**) | Check **Enabled** and *Currently fires for*; see [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md) | | Every event opens a new ticket although the rule is an update | No earlier ticket of the same trigger group exists for the subject, and **If no ticket exists yet** is **Create a new ticket** | The rule that creates the ticket must use a trigger of the same group | | A close rule never closes the ticket another rule opened | The two rules use triggers of different groups, for example **User created** and **User terminated** | Use triggers of one group, or close the ticket in the ticketing system | | The ticket appears twice in the Tickets screen for one request | It does not: one subject has one ticket per group. Two rows are two groups or two ticketing systems | Filter by **Trigger group** | | **Failed** with `Transition 'Done' is not available for issue ACCESS-142; available: …` | The transition name is wrong, or the issue is in a status from which it is not available | Use one of the listed names; for tickets that may already be closed, accept the failure or **Discard** it | | **Failed** with `transition is required to close` | A close rule saved without a transition through the API | Set the **Transition** | | **Failed** with a Jira `400` on create naming a field | A required field of the issue type is not set | Add it under **Additional Jira fields**; the Jira error names the field | | The existing ticket's summary changed when a second request event arrived | A create rule with **Add a comment instead** found the ticket and updated it with its own content | Use **Do nothing** on the create rule, or an update rule for later events | | Placeholders render empty in the ticket | The placeholder has no value for this event | See [Template placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md#when-it-goes-wrong) | ## Related * [How ticket integration works](/administration-guide/ticketing/overview.md) — one ticket per subject and the delivery states. * [Triggers and conditions](/administration-guide/ticketing/ticket-rules/triggers-and-conditions.md) — every trigger and condition. * [Template placeholders](/administration-guide/ticketing/ticket-rules/placeholders.md) — every `${…}` value. * [How fields reach Jira and ServiceNow](/administration-guide/ticketing/jira-and-servicenow.md) — projects, tables, transitions, priorities and additional fields per system. * [Track tickets](/administration-guide/ticketing/tickets.md) — what the rules produced. --- # 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/ticket-rules.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.