> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# ServiceDesk Plus 同步
> 通过 ServiceDesk Plus 同步 Webhook，实现故障与 ServiceDesk Plus request 的关联。
**版本要求**：此功能需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/)
通过 ServiceDesk Plus 同步 Webhook，将 Flashduty 的故障与 ServiceDesk Plus request 进行关联同步，实现 Flashduty 与 ServiceDesk Plus 的联动。
本集成基于 ServiceDesk Plus 官方提供的 v3 API 协议，兼容其接口规范。若您使用私有化部署版本，请确认其 API 是否支持 v3 版本。此外，ServiceDesk Plus 的云版本与私有化版本在授权配置方式上存在差异，具体配置请参考相关文档说明。
* [云版本](#云版本)
* [私有化](#私有化)
在配置此集成时，如果您选择的同步方向是 From\_ServiceDesk\_Plus，您可以直接跳过授权相关配置，直接参考[配置同步](#配置同步)即可。
## 云版本
### 在 ServiceDesk Plus
#### 步骤1 创建授权应用
请根据您的 ServiceDesk Plus 服务区域选择对应的 Developer Console 地址：[Data Centres](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html)
1. 登录 Developer Console，选择 `Self Client` 类型的 Client 并创建。
2. 点击 `Generate Code`，在 `Scope` 中填写：**SDPOnDemand.requests.ALL,SDPOnDemand.setup.READ,SDPOnDemand.custommodule.READ**。权限范围参考[官方文档](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/oauth-2.0.html#scopes)。
3. `Time Duration` 选择最大的 **10 minutes**，`Scope Description` 填写内容可自定义，比如： Flashduty 同步使用，并创建。
4. 将生成的 **Code** 和 **Client ID** 以及 **Client Secret** 复制备用。
###### 注意：Code 的有效期只有 10 分钟且只能使用一次，所以在获取到 Code 后，请在有效期内尽快完成[集成授权](#集成授权)
### 在 Flashduty On-call
#### 步骤2 集成授权
请根据您的 ServiceDesk Plus 服务区域选择对应的 API Endpoint 和 Accounts Server URL：[Data Centres](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html)
1. `平台类型` 选择**云版本**，填写`API Endpoint` 和 `Accounts Server URL`。
2. 将**创建授权应用**步骤中生成的 `Code` 和 `Client ID` 以及 `Client Secret` 填写到对应的编辑框并点击下一步完成[集成配置](#集成配置)（如果报错请重新获取 Code，或联系技术支持排查问题）。
## 私有化版本
### 在 ServiceDesk Plus
#### 步骤1 生成 API 密钥
1. 登录 ServiceDesk Plus 控制台，在个人中心点击 `生成 API 密钥`。
2. `令牌过期时间` 选择 **永不过期**，将生成的 **Token** 复制备用，并完成[集成授权](#私有化版本集成授权)。
###### 注意：生成 API 密钥的用户需要具备相关权限，比如创建/更新请求、获取模版/优先级/自定义字段列表等权限，如果权限不足，会导致无法完成集成配置，建议使用管理员角色生成。
### 在 Flashduty On-call
#### 步骤2 集成授权
1. `平台类型` 选择**私有化版本**，填写`API Endpoint`。
2. 将生成的 **Token** 填写到对应的编辑框并点击下一步完成[集成配置](#集成配置)。
## 通用配置
### 在 Flashduty On-call
#### 步骤1 集成配置
1. **集成名称：** 为当前集成定义一个名称。
2. **管理团队：** 当选择管理团队后，只有该团队成员以及租户管理员可以编辑此集成。
3. **同步方向：**
* To\_ServiceDesk\_Plus：将 Flashduty 的故障同步至 ServiceDesk Plus。
* From\_ServiceDesk\_Plus：将 ServiceDesk Plus 的 Request 同步至 Flashduty。
* Two-way：Flashduty 和 ServiceDesk Plus 互相同步。
4. **触发模式**：
* 自动触发：需要配置相应的条件，Flashduty On-call 会自动将符合条件的故障同步到 ServiceDesk Plus 中。
* 手动触发：需要在故障详情页的更多操作中手动触发 ServiceDesk Plus 同步（该集成配置的名称为触发器名称）。
5. **协作空间**：选择该集成生效的协作空间。
6. **请求模版**：选择创建 request 时使用的模版，为空时使用默认模版创建工单。
7. **严重程度映射**：可以选择使用严重程度、故障标签、自定义字段的值与 ServiceDesk Plus 的优先级字段进行映射，如果为空，在创建工单时不传该字段。
8. **自定义字段映射**：可以将故障中的标签或自定义字段，映射到 ServiceDesk Plus 工单中的对应文本字段，实现信息自动填充。该功能支持将常见上下文信息（如服务名、实例地址、指标名称等）同步至 ServiceDesk Plus，便于后续排查与跟踪。
* 仅支持目标为单行文本或多行文本类型的字段。
* 支持从故障标签（如 service、instance）或自定义属性中提取值。
* 若源字段为空，目标字段也将保持为空，不会覆盖原有内容。
9. **指派对象映射**：当 Flashduty 的故障同步至 ServiceDesk Plus 并需要自动指派到 Technician 或 Group 时，可以获取 Flashduty 故障标签的值作为指派对象（如果对应的指派对象不存在，会导致同步失败，请谨慎选择）。
10. **请求者**：创建工单时指定的 requester，如果工单在创建时该字段是必须，则需要配置。
11. 点击`保存`完成配置。
### 在 ServiceDesk Plus
#### 步骤2 配置同步
要实现 ServiceDesk Plus 的 Request 向 Flashduty 的同步，请参考此配置项。**注意:** 不同版本的路径可能略有不同，但配置方法相同。
##### 创建 Webhook
1. 登录 ServiceDesk Plus 控制台，找到 `Setup` 配置页面。
2. 选择 `Automation` 之后，进入到 `Custom Actions` 页面，并选择 `Webhooks`。
3. 点击 `New Webhook`，在编辑页面中 `Webhook Name` 填写 **to\_Flashduty**。
4. `URL` 填写集成的推送地址。
5. `Applies to` 选择 **Requsts**，`Method` 选择 **POST**，`Headers` 中填写 **Content-Type application/json**。
6. `Message Body` 的 Type 选择 **JSON**，并填写以下内容：
```
# 云版本
{
"subject":"${subject}",
"request_id":"${id}",
"description":"${udf_fields.txt_destination}",
"priority":"${priority.name}",
"status":"${status.name}",
"txt_test_field":"${udf_fields.txt_test_field}"
}
```
```
# 私有化版本
{
"suject":"${{request.subject}}",
"request_id":"${{request.id}}",
"description":"${{request.description}}",
"status":"${{request.status.name}}",
"priority":"${{request.priority.name}}",
"udf_sline_301":"${{request.udf_fields.udf_sline_301}}"
}
```
7. 点击 `Save` 完成配置。
##### 步骤3 创建触发器
1. 登录 ServiceDesk Plus 控制台，找到 `Setup` 配置页面。
2. 选择 `Automation` 之后，进入到 `Triggers` 页面，并选择 `Request`。
3. 点击 `New Trigger`，在编辑页面中 `Name` 填写 **to\_Flashduty**。
4. `Trigger applies to` 选择 **Request**，`Execute when a request is` 勾选 **Create 和 Edited**。
5. `Execute during` 选择 **Any time**，并勾选 **Enable Trigger**。
6. `Conditions` 选择 `Without condition` 或按实际需求配置。
7. 在 `Actions` 中选择 **Webhook** 并勾选 **to\_Flashduty** 通道。
8. 点击 `Save` 完成配置。
## 同步信息映射关系
### 表单字段
| ServiceDesk Plus | Flashduty | 备注 | |
| ---------------- | ------------- | ----- | -- |
| Subject | Title | | 标题 |
| Description | Description | 描述信息 | |
| Status | Progress | 状态 | |
| Priority | Severity | 严重程度 | |
| Others | Custom Fields | 自定义字段 | |
### 状态映射
| ServiceDesk Plus | Flashduty | 备注 |
| -------------------- | ---------- | --------- |
| Open | Triggered | 触发 |
| In Progress | Processing | 待处理 |
| Assigned | Processing | 待处理 |
| Pending Verification | Processing | 待处理 |
| Staging | Processing | 待处理 |
| On Hold | Snoozed | 默认暂缓 2 小时 |
| Resolved | Closed | 关闭 |
| Closed | Closed | 关闭 |
| Canceled | Closed | 关闭 |
| Rejected | Closed | 关闭 |
## 调用历史
ServiceDesk Plus 同步集成提供完整的调用历史记录，方便你排查同步是否成功以及调试接口问题。
### 查看调用历史
进入 ServiceDesk Plus 同步集成详情页，切换到 **调用历史** 页签即可查看。
### 筛选与搜索
| 筛选项 | 说明 |
| :-------- | :----------------------------------------------- |
| **时间范围** | 支持选择最近 30 分钟、6 小时、1 天、2 天、7 天、14 天、30 天，或自定义时间范围 |
| **故障 ID** | 输入故障 ID 进行精确搜索 |
| **协作空间** | 按协作空间筛选记录 |
| **请求状态** | 按成功或失败筛选 |
### 历史记录字段
| 字段 | 说明 |
| :------------- | :---------------------------------------------------- |
| **触发时间** | 事件触发的时间 |
| **故障标题** | 关联的故障标题，可点击跳转到故障详情 |
| **Request ID** | ServiceDesk Plus 工单 ID，可点击跳转到 ServiceDesk Plus 查看工单详情 |
| **协作空间** | 关联的协作空间，可点击跳转 |
| **请求状态** | 成功或失败 |
### 查看调用详情
点击某条记录的 **查看详情**，可查看完整的请求信息：
* **故障 ID**：关联的故障 ID
* **协作空间**：关联的协作空间
* **故障标题**：可点击跳转到故障详情页
* **触发时间**：请求触发的时间
* **请求状态**：成功或失败
* **Error Message**：失败时显示错误信息
## 常见问题
Scope 是否可以更改
不可以，目前所使用的 Scope 已经是最小单元了，Flashduty 在与 ServiceDesc Plus 进行同步 request 时，需要做获取/创建/更新操作，以及在配置集成时，需要获取优先级/自定义字段列表，所以需要相应的权限支持。