> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tickets

> Connect Jira, ServiceNow or Meegle, create tickets on incidents or automatically by rule, have them follow the incident with comments and transitions, and sync their status.

A ticket connector syncs incidents to Jira (Cloud, or Data Center / Server), ServiceNow or Meegle (Feishu Project in
China). Create a ticket on an incident, or let new incidents get one by rule; from then on the ticket
follows the incident: acknowledgements, resolutions, and notes become comments, and resolving the incident
moves the ticket to done. The ticket's status is synced back every 5 minutes, and Jira can also push it at
once through a webhook.

Open **Alerts → Tickets**. Viewing requires `alerts.tickets.read`, managing connectors requires `alerts.tickets.manage`,
and creating tickets on incidents requires `alerts.incidents.tickets`.

## Connect Jira

Select **New ticket connector** and choose **Jira**:

| Setting | Notes |
| - | - |
| **Site address** | For example `https://example.atlassian.net`. |
| Deployment | **Jira Cloud** signs in with the **Account email** and an **API token** (created on the security page of the Atlassian account settings); **Jira Data Center / Server** with a **Personal access token**. |
| **Project key**, **Issue type** | For example `OPS` and `Incident`. |
| **Ticket priority by incident priority** | A Jira priority name for each of the organization's incident priorities (P1 to P5 by default), then for each severity, for example `Highest` for P1; an incident without a priority, or a priority left empty, falls back to its severity, and all empty sets no priority. |
| **Labels** | Labels added to tickets; every ticket also gets `molesignal`. |
| **Transition when resolved** | A transition's name or ID; empty takes the first transition to a done status. |
| **Webhook secret** | Jira's webhook is taken only with a secret; see [Status sync](#status-sync). |

The account needs to create issues, add comments, and run transitions in the project. After saving, select
**Test connection**; on success it shows who it is connected as.

## Connect ServiceNow

Click **New ticket connector** and choose **ServiceNow**. It uses the Table API; a ticket is a record in a table.

| Setting | Description |
| - | - |
| **Instance address**, **Table** | Such as `https://example.service-now.com` and `incident`. The table must extend `task`. |
| Authentication | **User name and password**; **OAuth client credentials** (the instance must allow that grant, property `glide.oauth.inbound.client.credential.grant_type.enabled`); **API key** (from the Washington DC release, in the `x-sn-apikey` header). The account must be able to read and write the table. |
| **Assignment group**, **Caller**, **Category** | Fields written on creation. The group and caller are `sys_id`s; empty sets none. Other fields go through `settings.fields` in the API. |
| **Ticket priority by incident** | ServiceNow works out the priority from impact and urgency, so write `impact/urgency` here, like `2/1`; one number means both. The incident's priority is looked up first, then its severity. By default critical is `1/1`, error `2/1`, warning `2/2` and info `3/3`. |
| **State value on resolve**, **Resolution code** | The `state` and `close_code` written when the incident resolves, `6` and `Solution provided` by default. The default data policy requires a resolution code and notes on resolve; the choices of `close_code` differ per instance. The notes say the incident was resolved in MoleSignal, in the workspace's default language. |
| **States that count as done** | Values of `state`, comma separated, `6, 7, 8` by default (Resolved, Closed, Canceled). |

Changes on the incident go to `work_notes`, the internal notes, so they do not disturb the caller. The record's `correlation_id` is the incident ID and `correlation_display` is `MoleSignal`. **Test connection** reads the table once.

## Connect Meegle

Select **New ticket connector** and choose **Meegle**. First create a plugin in Meegle's developer console
to get a plugin ID and plugin secret, and install the plugin in the space where tickets go.

| Setting | Notes |
| - | - |
| **Platform**, **Site address** | **Feishu** (Feishu Project, `https://project.feishu.cn`) or **Lark** (Meegle, `https://meegle.com`). The site address follows the platform and can be copied, not edited. |
| **Plugin ID**, **Plugin secret** | Exchanged for a plugin token. |
| **Acting as (user\_key)** | Tickets are made and comments written as this person. |
| **Space (project\_key)**, **Work item type (work\_item\_type\_key)** | Which kind of work item to make, in which space. |
| **Priority field key**, priority mapping | A priority option value for each of the organization's incident priorities, then for each severity; an incident without a priority, or a priority left empty, falls back to its severity, and all empty sets no priority. |
| **Transition ID when resolved** | For work items with a state flow. |
| **Node finished when resolved** | For work items with a node flow. |
| **States that count as done** | State keys, comma separated; a ticket in one of them is done. |

**Test connection** reads the work item type once, which succeeds when the credentials, space, and type are
all right.

## Following the incident

**Following the incident** on the connector decides how its tickets follow the incident:

| Setting | Effect |
| - | - |
| **Comment when the incident is acknowledged**, **Comment when the incident is resolved** | Adds a comment saying the incident was acknowledged or resolved in MoleSignal. |
| **Write the incident's notes as comments** | New [notes](https://docs.molesignal.com/en-US/alerting/incidents.md#notes) on the incident become ticket comments. |
| **Move the ticket to done when the incident is resolved** | Closes the ticket with the transition set above. |
| **Resolve the incident when the ticket is done** | When the work is done on the ticket's side, the incident is resolved, whether open or acknowledged. Off by default. |
| **Make a ticket when a major incident is declared** | Creates a ticket with this connector when the incident is declared a [major incident](https://docs.molesignal.com/en-US/alerting/major-incidents.md). |

A ticket's title is `[severity] incident summary`, and its body gives the incident's severity and status,
services, labels, triggering query, the summary of its AI root cause, and a link to the incident page;
comments and the body are in the workspace's default language.

## Automatic tickets

With **Make tickets automatically** on, a new incident at or above **Severity at least**, whose service is
among **Services** (empty means any), gets a ticket with this connector on its own. Each connector creates
at most one ticket per incident.

## Create a ticket on an incident

**Tickets** in the incident details lists the incident's tickets: the key (which opens the ticket), the
status, when it was last synced, and any error from syncing or commenting. Select **Create ticket**, or
**Create in …** when there are several connectors. The ticket is recorded on the incident's timeline and
in the audit log.

Action items of a [postmortem](https://docs.molesignal.com/en-US/alerting/major-incidents.md#postmortems) can each get a ticket too; those
tickets get no comments or transitions from the incident and do not resolve it when done.

## Status sync

Tickets that are not done are synced every 5 minutes, and a status change goes on the incident's timeline. What counts as done: for Jira the status category, for Meegle and ServiceNow the states listed on the connector.

Jira can push changes at once instead: set a **Webhook secret** on the connector, and the connector list
shows the Jira webhook address with **Copy address**. In Jira's **System settings → WebHooks**, create a
webhook with that URL and the same secret, for issue updates. MoleSignal checks `X-Hub-Signature` with the
secret and refuses requests that do not match. The webhook address needs no sign-in; see
[Public access](https://docs.molesignal.com/en-US/public-access).

## API

| Operation | Endpoint |
| - | - |
| Manage connectors | [`/api/v1/alerts/tickets/connectors`](https://docs.molesignal.com/en-US/api/alerting/tickets) |
| Create a ticket on an incident | [`POST /api/v1/alerts/incidents/{id}/tickets`](https://docs.molesignal.com/en-US/api/alerting/tickets#create-a-ticket-for-an-incident) |
| Jira webhook | [`POST /api/v1/public/tickets/jira/{connector_id}`](https://docs.molesignal.com/en-US/api/alerting/tickets#status-sync-and-the-jira-webhook) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.