> ## 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.

# 工单

> 连接 Jira、ServiceNow 或飞书项目，在事件上建单或按规则自动建单，让工单跟着事件写评论、流转，并同步工单状态。

工单连接器把事件同步到 Jira（Cloud 或 Data Center / Server）、ServiceNow 或飞书项目（海外版是 Meegle）。在事件上建单，或让新事件按规则自动建单；之后工单跟着事件走：确认、解决和备注写成评论，解决事件时工单流转到完结。工单那边的状态每 5 分钟同步回来一次，Jira 还可以用 Webhook 实时推送。

打开 **告警 → 工单**。查看需要 `alerts.tickets.read`，管理连接器需要 `alerts.tickets.manage`，在事件上建单需要 `alerts.incidents.tickets`。

## 连接 Jira

点击 **新建工单连接器**，选 **Jira**：

| 设置 | 说明 |
| - | - |
| **站点地址** | 例如 `https://example.atlassian.net`。 |
| 部署方式 | **Jira Cloud** 用 **账号邮箱** 和 **API Token**（在 Atlassian 账号设置的安全页创建）；**Jira Data Center / Server** 用 **个人访问令牌**。 |
| **项目 Key**、**问题类型** | 例如 `OPS` 和 `Incident`。 |
| **优先级对应的工单优先级** | 先按组织的各档事件优先级（默认 P1 到 P5），再按严重度，各填 Jira 里优先级的名字，例如 P1 填 `Highest`；事件没设优先级或那一项没填时看严重度，都空着时不设优先级。 |
| **标签** | 加到工单上的标签，另外每张单都带 `molesignal`。 |
| **解决事件时的流转** | 流转的名字或 ID；空着时走第一个通往完结类状态的流转。 |
| **Webhook 密钥** | 设了才接收 Jira 的 Webhook，见[状态同步](#状态同步)。 |

建单用的账号要能在这个项目里建问题、写评论和执行流转。保存后点击 **测试连接**，成功时显示登录的人。

## 连接 ServiceNow

点击 **新建工单连接器**，选 **ServiceNow**。用的是 Table API，工单是表里的一条记录。

| 设置 | 说明 |
| - | - |
| **实例地址**、**表** | 例如 `https://example.service-now.com` 和 `incident`。表要继承 `task`。 |
| 认证方式 | **用户名和密码**；**OAuth 客户端凭证**（实例要打开客户端凭证授权，属性 `glide.oauth.inbound.client.credential.grant_type.enabled`）；**API Key**（Washington DC 版本起，放在 `x-sn-apikey` 头里）。账号要能读写这张表。 |
| **分派组**、**提单人**、**类别** | 建单时写的字段，分派组和提单人写 `sys_id`；空着不设。别的字段可以经 API 的 `settings.fields` 写。 |
| **优先级对应的工单优先级** | ServiceNow 按 impact 和 urgency 算优先级，这里写 `impact/urgency`，例如 `2/1`；只写一个数字时两个都用它。先按事件的优先级，再按严重度，默认严重写 `1/1`，错误 `2/1`，警告 `2/2`，信息 `3/3`。 |
| **解决时的状态值**、**解决代码** | 解决事件时写的 `state` 和 `close_code`，默认 `6` 和 `Solution provided`。默认的数据策略要求解决时带解决代码和解决说明；`close_code` 的选项各实例不同，按实例改。解决说明是「事件已在 MoleSignal 解决」，用工作区的默认语言。 |
| **算完结的状态** | `state` 的值，逗号分隔，默认 `6, 7, 8`（已解决、已关闭、已取消）。 |

事件上的变化写进 `work_notes`（内部备注），不打扰提单人。记录的 `correlation_id` 是事件 ID，`correlation_display` 是 `MoleSignal`。**测试连接** 读一次这张表。

## 连接飞书项目

点击 **新建工单连接器**，选 **飞书项目**。先在飞书项目的开发者后台创建插件，取得插件 ID 和插件密钥，并把插件安装到要建单的空间。

| 设置 | 说明 |
| - | - |
| **平台**、**站点地址** | 选 **飞书**（飞书项目，`https://project.feishu.cn`）或 **Lark**（Meegle，`https://meegle.com`）。站点地址随平台定，只能复制，不能改。 |
| **插件 ID**、**插件密钥** | 用来换插件 Token。 |
| **以谁的身份（user\_key）** | 工单由这个人建，评论也以这个人的名义写。 |
| **空间（project\_key）**、**工作项类型（work\_item\_type\_key）** | 在哪个空间建哪种工作项。 |
| **优先级字段 key**、优先级对应 | 按组织的各档事件优先级、再按严重度填优先级选项的值；事件没设优先级或那一项没填时看严重度，都空着时不设优先级。 |
| **解决事件时的流转 ID** | 状态流的工作项用。 |
| **解决事件时完成的节点 ID** | 节点流的工作项用。 |
| **算完结的状态** | 状态 key，逗号分隔；工单到了这些状态算完结。 |

**测试连接** 读一次工作项类型，凭证、空间和类型都对时成功。

## 跟着事件走

连接器的 **跟着事件走** 决定工单怎样跟着事件：

| 设置 | 效果 |
| - | - |
| **事件被确认时写评论**、**事件被解决时写评论** | 在工单上写一条评论，说明事件已在 MoleSignal 确认或解决。 |
| **事件上的备注写成评论** | 事件上新加的[备注](https://docs.molesignal.com/zh-Hans/alerting/incidents.md#备注)同步成工单评论。 |
| **解决事件时把工单流转到完结** | 按上面设置的流转把工单关掉。 |
| **工单完结时解决事件** | 工单那边做完了，事件随之解决，开着的和已确认的都解决。默认关闭。 |
| **宣布重大事件时建单** | 事件被宣布为[重大事件](https://docs.molesignal.com/zh-Hans/alerting/major-incidents.md)时在这个连接器上建一张单。 |

工单的标题是 `[严重度] 事件摘要`，正文写事件的严重度与状态、服务、标签、触发查询、AI 根因的摘要和事件页的链接；评论和正文用工作区的默认语言。

## 自动建单

打开 **自动建单** 后，新开的事件严重度不低于 **严重度不低于**、服务在 **服务** 里（空着不限）时，自动在这个连接器上建一张单。每个连接器对同一个事件只建一张。

## 在事件上建单

事件详情的 **工单** 列出事件的工单：单号（点开就是工单）、状态、上次同步的时间，以及同步或写评论出的错。点击 **建单**，有几个连接器时选 **在 … 建单**。建单记在事件的时间线上，并记进审计日志。

[复盘](https://docs.molesignal.com/zh-Hans/alerting/major-incidents.md#复盘)里的改进项也能一项建一张单；这种单不跟着事件写评论、流转，完结时也不会解决事件。

## 状态同步

没完结的工单每 5 分钟同步一次状态；状态变了记在事件的时间线上。完结怎么判断：Jira 看状态类别，飞书项目和 ServiceNow 看连接器上列的状态。

Jira 可以改成实时推送：在连接器里设 **Webhook 密钥**，连接器列表会显示 Jira Webhook 地址，点 **复制地址**。然后在 Jira 的**系统设置 → WebHooks** 里新建一个 Webhook，URL 填这个地址，密钥填同一个 Webhook 密钥，事件勾选问题的更新。MoleSignal 用密钥验证 `X-Hub-Signature`，对不上的请求不收。Webhook 地址不用登录，见[公开访问](https://docs.molesignal.com/zh-Hans/public-access)。

## API

| 操作 | 端点 |
| - | - |
| 管理连接器 | [`/api/v1/alerts/tickets/connectors`](https://docs.molesignal.com/zh-Hans/api/alerting/tickets) |
| 在事件上建单 | [`POST /api/v1/alerts/incidents/{id}/tickets`](https://docs.molesignal.com/zh-Hans/api/alerting/tickets#在事件上建单) |
| Jira Webhook | [`POST /api/v1/public/tickets/jira/{connector_id}`](https://docs.molesignal.com/zh-Hans/api/alerting/tickets#状态同步与-jira-webhook) |


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