苍穹消息中心集成
1. 引言
1.1. 编写目的
金蝶云·苍穹消息中心使用说明
预期读者：需求人员，开发人员、测试人员等。
1.2. 系统环境
金蝶云·苍穹V5.0.011版本，向下兼容；
1.3. 外部系统
钉钉、企业微信、云之家、welink等第三方软件。
2. 概述
消息中心隶属于苍穹提供的全员应用，收集各类业务产生的任务及消息数据，集中在消息中心查询、处理。同时支持移动和PC两种客户端，任务在处理的同时也可以进行社交化单点或者建群交流。允许用户根据条件设置任务个性化优先级，收录文件夹，并提供任务自动转交、传阅给他人处理任务等功能。与此同时，消息中心提供丰富api接口，供业务发送、获取、处理不同种类消息数据，并提供消息渠道、消息类型、消息模板功能，实现消息配置化，提升消息使用灵活性。
3. 待办消息如何与第三方APP集成
工作流中的待办任务，可以采取两种方式和第三方系统进行集成。
3.1.第一种：通过API拉取苍穹待办
在客户的第三方列表界面调用苍穹工作流提供的待办/已办API查询某个人的待办列表，直接格式化融合显示，获取的结果中已经包含了苍穹审批界面的URL,可以直接打开URL进行审批。如果是在移动端进行显示，建议URL参数中增加&device=mob，如果是PC段建议增加参数&device=pc.
拉取的方式不在第三方存储数据，数据量较大时，需要分页拉取。此种方式需要做单点登录工作，然后才能调用API拉取数据
以下api方法是openapi1.0版本提供的；openapi2.0版本参考：https://dev.kingdee.com/open/detail/api/1758915742255812608
3.1.1.拉取待办API: getToHandleTasksByUserId
调用方式：https://ierp.kingdee.com:2024/mainbiz/kapi/app/wf/getToHandleTasksByUserId?body={"start":0,"limit":10,"billno":"test","subject":"test","entityName":"test"}&access_token={access_token}
请求头部：
参数名称 | 参数值 | 说明 |
Content-Type | application/json | 内容格式 |
accesstoken | 获取的accesstoken值 | 请求令牌 |
Query参数
参数名称 | 参数类型 | 必填 | 示例 | 说明 |
start | int | 是 | start":0 | 开始数据位置，用于分页查询 |
limit | int | 是 | "limit":10 | 结束数据位置，用于分页查询 |
billno | string | 否 | "billno":"test" | 单据编号，支持模糊查询 |
subject | string | 否 | "subject":"test" | 单据主题，支持模糊查询 |
entityname | string | 否 | "entityName":"test" | 单据名称，支持模糊查询 |
terminalType | string | 否 | "terminalType":"all" | [pc|mobile] |
userId | string | 否 | “userId”:”123456789” | 苍穹用户id，如果不传递值，查询当前用户的待办任务，否则查询指定用户的待办任务 |
sortField | string | 否 | “ sortField”:“billno” | 排序字段，用于返回数据的排序,传入字段参考返回值说明 |
sortType | string | 否 | “sortType”:“desc” | 排序方式 |
返回参数：
参数名称 | 参数类型 | 示例 | 说明 |
data | Array | ||
ACTIVE | int | "ACTIVE": "1" | 冻结/激活状态 0为激活 |
BILLNO | String | "BUSINESSKEY": "1022249808284362752" | 单据ID |
CATEGORY | String | "CATEGORY": "AuditTask" 任务所在节点类型，AuditTask-审批节点 | UserTask人工节点 |
CREATEDATE | Long | "CREATEDATE": "2020-11-11 10:44:03" | 任务创建时间 |
ENTITYNAME | Long | "ENTITYNAME": "测试单据" | 单据名称 |
HANDLESTATE | String | "HANDLESTATE": "willApproval" | 任务处理状态[willApproval-待审批,dismissed-被驳回,willHandled-待处理] |
ID | Long | "ID": 9876543210 | 任务ID |
NAME | String | "NAME": "审批" | 任务所在节点 |
SENDERNAME | String | "SENDERNAME": "张三" | 上一步处理人 |
STARTNAME | String | "STARTNAME": "张三" | 流程发起人 |
SUBJECT | String | "SUBJECT": "0.00/test-20201111-0001" | 任务主题 |
URL | String | 任务处理的连接，支持移动和PC | |
success | Boolean | true | |
status | Boolean | true | |
erroeCode | String | "success" |
返回值为json，拉取的结果如下图：
3.1.2.拉取已办任务API: *getHandledTasksByUserId*
请求头部：
参数名称 | 参数值 | 说明 |
Content-Type | application/json | 内容格式 |
accesstoken | 获取的accesstoken值 | 请求令牌 |
Query参数:
参数名称 | 参数类型 | 必填 | 示例 | 说明 |
start | int | 是 | start:0 | 开始数据位置，用于分页查询 |
limit | int | 是 | limit:10 | 结束数据位置，用于分页查询 |
billno | String | 否 | billno:"test" | 单据编号，用于模糊查询 |
subject | String | 否 | subject:"test" | 单据主题，用于模糊查询 |
entityname | String | 否 | entityName:"test" | 单据名称，用于模糊查询 |
terminalType | String | 否 | terminalType:"all" | pc|mobile |
userId | String | 否 | userId”:”123456789” | 如果不传递值，查询当前用户的待办任务，否则查询指定用户的待办任务 |
sortField | String | 否 | sortField”:”billno” | 排序字段 |
sortType | String | 否 | sortType”:”desc” | 排序方式 |
返回参数：
参数名称 | 参数类型 | 示例 | 说明 |
data | Array | ||
BILLNO | String | "BILLNO": "FYSQ-201109-000001" | 单据编号 |
BUSINESSKEY | Long | "BUSINESSKEY": "1020814244624478208" | 单据ID |
CATEGORY | String | "CATEGORY": "UserTask" | 任务所在节点类型，AuditTask-审批节点 UserTask人工节点 |
CREATEDATE | int | "CREATEDATE": "2020-11-09 10:57:43" | 任务创建时间 |
ENDTIME | int | "ENDTIME": "2020-11-09 10:57:43" | 任务结束时间 |
ENTITYNAME | String | "ENTITYNAME": "费用申请" | 单据名称 |
HANDLESTATE | String | "HANDLESTATE": "handled" | 任务处理状态[handled-已完成] |
ID | Long | "ID": 1234567890 | 任务ID |
NAME | String | "NAME": "费用申请单提交" | 任务所在节点 |
SENDERNAME | String | "SENDERNAME": "张三" | 上一步处理人 |
STARTNAME | String | "STARTNAME": "李四" | 流程发起人 |
SUBJECT | String | "SUBJECT": "单据编号：FYSQ-201109-000001" | 任务主题 |
URL | String | 任务处理的连接，支持移动和PC | |
errorCode | String | "success" | |
success | Boolean | true |
返回值为json，拉取的结果如下图：
3.1.3.获取待办&已办的数量：*getTaskCountByType*
调用方式：https://ierp.kingdee.com:2024/mainbiz/kapi/app/wf/getTaskCountByType?body={"type":"toHandle"}
请求头部：
参数名称 | 参数值 | 说明 |
Content-Type | application/json | 内容格式 |
accesstoken | 获取的accesstoken值 | 请求令牌 |
Query参数：
参数名称 | 参数类型 | 必填 | 示例 | 说明 |
type | String | 是 | 类型。可查询待办任务(toHandle)、已办任务(handled)，在办申请(toApply)，已办申请(applyed) | |
userId | Long | 否 | 苍穹用户id，如果不传递值，查询当前用户的待办任务，否则查询指定用户的待办任务 |
返回值为json，拉取的结果如下图：
更多工作流的openapi看查看：
3.2.第二种：通过扩展苍穹消息渠道推送待办
除了可以按照默认的渠道【云之家、短信、邮件】发送之外，也可以自定义和扩展消息渠道进行发送。自定义消息渠道需要一个实现类，在这个实现类中，处理待办相关内容。实现类需要继承：
kd.bos.workflow.engine.msg.handler.AbstractMessageServiceHandler
此接口中的关键说明：
MessageServiceConfig：为消息渠道中定义的渠道相关信息，包括渠道编码，渠道名称，是否启用，自定义参数等；
createToDo：工作流中的待办任务创建之后，会调用此接口，将待办任务传递给响应的渠道做处理；
dealToDo：工作流中将待办变成已办的时候，会调用此接口进行待办变已办的处理；
deleteToDo：工作流中撤回，或者多人收到任务，其中一人审批，删除其他人的待办时，调用此接口；
sendMessage：发送预警，通知，报警等消息时，调用此接口进行当前渠道处理。
推送过去的待办消息，可以将消息存储到第三方的数据库中，也可以直接发送第三方的消息. 具体可以参考云之家的实现类（kd.bos.workflow.engine.msg.handler.YunzhijiaServiceHandler）。
消息渠道扩展：
所有的消息渠道在工作流引擎中均通过异步消息处理，如果失败，会重试三次，三次也失败会进入异常中心等待人工处理。消息的失败不会影响流程的流转，可以在流转日志中查看对应渠道的消息是否执行成功。
点击某个流转日志进入，可以从相关数据中看到关键信息。state=NEW表示创建待办任务/DEAL表示待办变已办/DELETE表示删除待办。service=email表示当前这个消息是发送的邮件，email为消息渠道的编码。
推送的消息也包含相关的URL信息，在第三方的APP中打开苍穹任务链接，需要先做单点登录，然后点击链接，直接打开苍穹的审批界面，支持打开移动端审批界面，也支持打开PC端审批界面。审批完成后，需要刷新待办列表。
*相关连接：*
4. 通过api发送消息
接口基本信息
用途说明：短信平台发送消息
请求方式：POST
请求URL：/v2/wftask/sendMessage
请求头参数
参数名称 | 参数值 | 说明 |
Content-Type | application/json | 内容格式 |
accesstoken | 获取的accesstoken值 | 请求令牌 |
Idempotency-Key | 唯一的requestId | 非必传参数，防止接口被重复调用 |
请求体参数
参数名称 | 参数类型 | 多值 | 必填 | 说明 | 层级 | 示例 |
messageInfo | MessageInfoModel | 否 | 否 | messageInfo | 1 | - |
-messageTitle | String | 否 | 否 | 消息标题 | 2 | “EBrdg” |
-content | String | 否 | 否 | 消息内容 | 2 | “7yF7C” |
-messageContent | String | 否 | 否 | 消息内容 | 2 | “lxoCC” |
-userIds | List | 是 | 否 | 消息接收人 | 2 | [1658373982647] |
-type | String | 否 | 否 | 消息类型 | 2 | “ImaEM” |
-entityNumber | String | 否 | 否 | 实体编码 | 2 | “bT7QD” |
-tag | String | 否 | 否 | 标签 | 2 | “o50XD” |
-senderId | Long | 否 | 否 | 消息发送人Id | 2 | “1658373982714” |
-senderName | String | 否 | 否 | 消息发送人名称 | 2 | “6MoCC” |
-contentUrl | String | 否 | 否 | 消息Web端 url | 2 | “C5gs1” |
-mobContentUrl | String | 否 | 否 | 消息移动端 url | 2 | “1k91J” |
-operation | String | 否 | 否 | 操作 | 2 | “1Xwoe” |
-bizDataId | Long | 否 | 否 | 业务数据id | 2 | “1658373982639” |
-source |
|
