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

# 蓝鲸 ITSM 同步

> 配置蓝鲸网关认证、工单提单及已关联工单的状态回传。

通过蓝鲸 ITSM 集成，将 Flashduty 故障创建为蓝鲸工单，并将已关联工单的节点或完结状态同步回故障。

## 同步范围

| 同步方向 | 从 Flashduty 提单 | 将已关联工单状态回传到 Flashduty |
| - | - | - |
| 双向同步 | 支持手动或自动提单 | 支持 |
| 仅 Flashduty → 蓝鲸 | 支持手动或自动提单 | 不执行故障认领或关闭 |
| 仅蓝鲸 → Flashduty | 不创建蓝鲸工单，需关联已有单号 | 支持 |

状态回传只作用于已关联的故障，不会把蓝鲸中的其他工单导入为新故障。Flashduty 的认领、关闭或字段变更不会代替蓝鲸审批，也不会更新已创建工单的任意字段。

## 接入前准备

1. 确认当前 Flashduty 版本已包含“蓝鲸 ITSM”集成。
2. 在蓝鲸中准备已发布的工单服务，确认提单字段、必填项和流程节点含义。
3. 准备蓝鲸应用的 `app_code`、`app_secret`，以及有目标服务和工单操作权限的蓝鲸用户名。
4. 为应用申请以下 ESB / API 网关资源权限，并确认网关允许当前应用以配置的用户名访问资源。
5. 确认 Flashduty 后端可访问网关；需要回调时，还应确保蓝鲸可访问 Flashduty 的回调地址。

| 方法 | 蓝鲸接口 | 用途 |
| - | - | - |
| GET | `get_services` | 加载可用工单服务 |
| GET | `get_service_detail` | 加载提单字段及校验规则 |
| POST | `create_ticket` | 创建工单；仅入站模式不调用 |
| GET | `get_ticket_info` | 关联已有工单时核对服务 |
| GET | `get_ticket_status` | 查询实际状态及当前节点 |
| POST | `ticket_approval_result` | 配置完结关闭时核对审批结果 |

正式接入使用 ESB / API 网关认证。Flashduty 将应用凭证和操作用户放入 `X-Bkapi-Authorization` 请求头，字段名为 `bk_app_code`、`bk_app_secret` 和 `bk_username`。如果网关要求额外的交互式用户令牌，需要先与蓝鲸管理员确认兼容的资源认证策略；当前页面不提供用户令牌配置。

SaaS 接入的网关需使用后端可访问的公网地址。私有化部署可使用可达的内网地址。独立测试环境的认证适配仅用于联调，不能据此判断正式网关认证已经通过。

## 在 Flashduty 配置集成

进入“集成中心”，找到“蓝鲸 ITSM”并创建集成，填写名称、描述和管理团队。

### 连接认证

| 配置项 | 填写说明 |
| - | - |
| ESB / API 网关接口前缀 | 填写目标 ITSM 资源的公共 URL 前缀，例如 `https://bk.example.com/api/c/compapi/v2/itsm`；网关部署不同时以管理员提供的实际前缀为准 |
| `app_code` | 蓝鲸应用标识 |
| `app_secret` | 对应应用密钥；编辑已有集成时留空会保留原凭证 |
| 蓝鲸操作用户 | 上述授权用户的用户名，不是用户密码 |

接口前缀不要包含 `get_services` 等具体接口名、查询参数或 URL 内嵌凭证。系统会在前缀后追加接口名及尾部 `/`。蓝鲸控制台登录地址和独立部署的原始 OpenAPI 地址不一定是正式网关前缀。

点击“测试连接并加载服务”，成功后选择“工单服务”。此操作只验证服务列表访问，并不证明创建工单、查询状态或回调权限都已验证。

### 同步设置

选择同步方向，以及本集成生效的“协作空间”。一个集成对应一个蓝鲸工单服务；同一故障在同一集成下只保留一个工单关联。需要接入不同服务时，分别创建集成。

允许向蓝鲸提单时，选择触发模式：

* **手动触发**：在故障详情的 BlueKing ITSM 区域点击“创建或关联蓝鲸工单”，选择集成，工单号留空后点击“创建工单”。
* **自动触发**：配置匹配条件。符合协作空间范围和条件的故障，在新建、认领、关闭或字段更新事件触发处理时可提单。保存集成不会回溯扫描已有故障；已经关联工单时不会重复提单。

只向蓝鲸同步时不需要配置回调和状态映射。仅入站时隐藏提单触发模式，使用“关联工单”建立已有单号与故障的关系。

## 提单字段映射

先选择工单服务，再点击“添加映射”。蓝鲸字段列表来自服务定义；每个目标字段只能配置一次。

| 故障字段来源 | “取值”如何填写 |
| - | - |
| 标题、描述、严重程度、解决信息、故障 ID | 留空，系统读取对应故障属性 |
| 固定值 | 填写要写入蓝鲸字段的内容 |
| 标签 | 填写标签名，例如 `service`，读取故障的该标签值 |
| 自定义字段 | 填写自定义字段的 Key，不是显示名称 |

未显式映射 `title` 时，系统默认使用故障标题。其他蓝鲸必填字段需配置映射，并在实际提单时有值；标签或自定义字段不存在、值为空，也可能导致提单失败。仅入站同步不要求配置提单必填映射。

字段按蓝鲸服务类型转换：整数和数值字段需填写可转换的数字；多选、复选框或自定义表格的字符串值需为有效 JSON，例如多选值 `["a","b"]`。枚举字段使用实际选项 Key，不能直接使用显示名称。严重程度读取故障原值，不会自动转换为蓝鲸优先级。

例如，将蓝鲸的服务名称字段映射为“标签 / `service`”，将环境字段映射为“固定值 / `production`”。目标字段必须确实存在于所选服务中。

映射仅在创建时写入。服务字段或流程重新发布后，应重新加载字段、核对映射，再用测试故障验证。

## 蓝鲸状态回传

### 节点映射

点击“添加节点映射”，填写已发布流程的节点 ID，并选择“认领故障”或“关闭故障”。节点 ID 对应状态接口 `current_steps[].state_id`，不是工单 ID、工单号或节点名称。

| 配置 | 触发条件 | 故障操作 |
| - | - | - |
| 节点 ID → 认领故障 | 工单为 `RUNNING`，该节点也为 `RUNNING` | 认领故障 |
| 节点 ID → 关闭故障 | 工单为 `RUNNING`，该节点也为 `RUNNING` | 关闭故障 |
| 正常完结时的动作 → 关闭故障 | 工单为 `FINISHED`，重新查询到审批通过 | 关闭故障 |

**节点映射在进入节点时生效，不是节点完成后生效。** 只有当“进入该节点”本身表示已经解决时，才配置为关闭故障。不要把待审批或处理中节点映射为关闭。并行节点应避免配置互相冲突的动作。

“正常完结时的动作”可留空；留空时，单据完结本身不会关闭故障。终止（`TERMINATED`）、撤回（`REVOKED`）或完结审批未通过不会执行完结关闭。运行中仍以节点映射为准，需保证流程的拒绝分支不会经过配置为关闭的节点。

已关闭的故障不会被回传重新打开，也不会退回处理中。Flashduty 不会自动审批、转单或撤回蓝鲸工单。

### 回调配置

1. 完成连接与同步配置，先保存集成。新建阶段尚未生成该集成的回调地址。
2. 重新进入该集成的编辑页，在右侧文档的“本集成回调地址”处复制完整地址，保留 `integration_key` 参数。不要手动拼接地址，也不要复用示例或其他集成的 key。
3. 如需在提单时注册完结回调，将复制的地址填入“蓝鲸回调地址”，再次保存后再创建工单。创建请求会将其作为 `meta.callback_url` 传给蓝鲸。
4. 如需节点变化时及时回传，在蓝鲸中为相应流程事件配置 HTTP 触发器，向同一地址发送 `POST` 请求，设置 `Content-Type: application/json`。
5. 请求体将实际工单号放在顶层 `sn` 字段。蓝鲸不同版本的触发器变量语法可能不同，请选择该版本实际提供的工单号变量，不要固定写入一个测试单号。

```json theme={null}
{
  "sn": "REQ20261022000001"
}
```

Flashduty 使用 `integration_key` 确定集成，再向蓝鲸查询该单号的实际状态。请求体中的状态或审批结果不会直接用于认领、关闭故障。回调不会创建关联；已有工单必须先关联到故障，HTTP 200 也不能单独证明故障状态已更新。

可对**测试故障及其已关联单号**发送回调以验证链路：

```sh theme={null}
curl --request POST '<完整的蓝鲸回调地址>' \
  --header 'Content-Type: application/json' \
  --data '{"sn":"<已关联的测试单号>"}'
```

系统还会定期核对未进入结束状态的已关联工单，补偿回调丢失。定期核对不保证实时；需要确认结果时，可在故障详情点击“刷新状态”。

## 关联已有工单与失败重试

在故障详情点击“创建或关联蓝鲸工单”，选择集成并填写已有工单号，再点击“关联工单”。工单必须属于该集成配置的蓝鲸服务，故障也必须属于所选协作空间。

创建失败或返回结果未知时，先在蓝鲸按故障标题和提单时间核对：

1. 上一次创建仍可能进行中：等待至少 60 秒再核对，系统会拒绝过早重试。
2. 已存在对应工单：关联已有单号，不再创建。
3. 确认不存在：使用“核对后重试”，阅读确认提示后再提交。

不要把修改集成的工单服务作为重试方式；已有工单的关联需要保持原服务一致。

## 联调检查与常见问题

用测试故障完成以下检查后再接入业务流程：手动提单、关联已有单号、进入认领节点、正常审批完结、拒绝或撤回、回调暂停后的定期核对，以及仅入站和仅出站的方向限制。

| 现象 | 优先检查 |
| - | - |
| 连接失败、401 或 403 | 接口前缀、应用凭证、应用资源授权、用户名访问策略和网络可达性 |
| 连接成功但服务不可选 | 目标服务是否发布，以及配置用户是否有服务权限 |
| 提单提示必填、类型或选项错误 | 对照最新服务定义检查字段 Key、实际源值、数字或 JSON 格式及枚举 Key |
| 已有单号无法关联 | 单号是否正确、是否属于所选服务，故障是否在集成协作空间内 |
| 回调成功但状态不变 | 单号是否已关联、同步方向是否允许入站、实际当前节点 ID 是否匹配，以及节点是否正在运行 |
| 完结后没有关闭故障 | 是否配置完结关闭、审批结果是否可查询且为通过；不采信回调自行声明的结果 |
| 创建结果待核对 | 先查询蓝鲸是否已落单，再关联或核对后重试，避免重复工单 |

当前不支持工单普通留言、创建后的任意字段更新、蓝鲸审批自动化或从蓝鲸批量导入新故障。蓝鲸的 `comment` 接口表示完结评价，不等同于普通留言。

## 公开资料

蓝鲸官方提供[创建工单接口说明](https://github.com/TencentBlueKing/bk-itsm/blob/develop/docs/itsm_bkapi/apidocs/en/create_ticket.md)和[工单状态接口说明](https://github.com/TencentBlueKing/bk-itsm/blob/develop/docs/itsm_bkapi/apidocs/en/get_ticket_status.md)。正式认证策略和资源路径以所用蓝鲸版本及管理员配置为准；本页描述的是当前 Flashduty 集成已实现的能力。


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