摘要由AI智能服务提供苍穹流程任务集成第三方系统主要有两种方式：通过API接口或集成消息渠道推送待办任务。平台已提供标准接口供调用，并预置六种消息渠道供选择配置。用户可根据需求修改配置，并扩展开发其他消息渠道。集成时需注意人员信息同步和单点登录问题。详细说明了接口调用方法、企业微信配置及扩展开发流程，包括人员信息同步、单点登录、接口复写等关键步骤。同时提醒了网络不稳定可能导致消息推送失败及异常处理机制的重要性。
1 实现方式
目前苍穹流程任务集成第三方系统主要有两种实现方式：
（1）通过提供API接口方式，第三方系统查询获取待办任务信息等；
（2）通过集成第三方消息渠道推送待办任务。
1.API接口
目前平台已经提供了标准的接口，第三方系统只需要调用查询即可。
2.集成消息渠道推送
苍穹系统目前预置了六种消息渠道---电子邮件、短信、云之家、钉钉、企业微信，华为Welink。用户可以根据自身需求修改六种的渠道配置参数信息，开发时在苍穹和第三方系统中完成相应的配置即可以完成集成，目前系统默认启用的是短信与云之家两种渠道。
这几种消息渠道能满足大部分用户的消息推送需求，若用户需要使用其他第三方移动办公软件，比如泛微OA，蓝凌OA等，则需要对消息渠道进行二次扩展开发，以满足个性化需求，与第三方系统集成过程中，开发设计时需关注人员信息同步和单点登录这两个比较关键的问题。
（1）人员信息同步
推送待办任务至第三方渠道，需要以第三方系统的人员为基础，因此第三方系统人员信息如何同步至苍穹系统，并如何存储双方人员映射关系是一个基本问题。
（2）单点登录
第三方系统接收到链接消息以及待办任务后，需要点击链接到苍穹处理页面，为了方便用户使用，需要处理第三方系统的单点登录问题。
2 API获取流程任务信息
2.1接口说明
在客户的第三方系统列表界面调用苍穹工作流提供的API查询某个用户的待办列表，直接格式化融合显示，获取的结果中已经包含了苍穹审批界面的URL，可以直接打开URL进行审批。
工作流中已经提供了标准的获取待办任务等信息的接口，我们可以在开放平台中的API服务管理中的流程服务云，工作流服务中获取详细的接口名称，请求参数等。
1.在集成过程中比较常用的几个接口：
（1）获取待办任务：/app/wf/getToHandleTasksByUserId
（2）获取已办任务：/app/wf/getHandledTasksByUserId
（3）获取任务数量：/app/wf/getTaskCountByType
2.2接口调用测试
1.接口调用：接口调用需要获取accessToken信息，获取accessToken的方式这里不再赘述，有疑问的请参考
https://dev.kingdee.com/index/docsNew/6668c5c0-b547-4f55-8f74-cc6ea2f5c65c
2.结果演示
场景：获取用户ID920332164929707008的待办任务，限制返回10条；
请求地址：
<a href="http://localhost:8080/ierp/kapi/app/wf/getToHandleTasksByUserId?body={\" userid\":920332164929707008,\"start\":0,\"limit\":10}&access_token="1218732684788893696_7rp3jurPNll6XUKb9REHT4FYs4NGcBSQLF6niJA2Nr2H3pNj7aNU87eqLvhQtuKaO698KygXM3ecYKqGgXi2n9iewJaUGAm5ILnZ"" target="_blank">http://localhost:8080/ierp/kapi/app/wf/getToHandleTasksByUserId?body={"userId":920332164929707008,"start":0,"limit":10}&access_token=1218732684788893696_7rp3jurPNll6XUKb9REHT4FYs4NGcBSQLF6niJA2Nr2H3pNj7aNU87eqLvhQtuKaO698KygXM3ecYKqGgXi2n9iewJaUGAm5ILnZ
注意：如果数据量较大时，需要分页拉取，参数start和limit
3集成企业微信
以企业微信为例，讲解流程任务如何集成预置的消息渠道，其他消息渠道也是类似的，开发时通过配置即可实现。
3.1苍穹配置
1.基础配置
配置企业微信参数
a.操作位置：系统服务云-配置工具-系统参数-系统服务云-基础服务
b.配置企业ID和通讯录应用秘钥，以下截图为获取方式：
（2）人员同步（同步企业微信人员信息）
a.操作位置：系统服务云-基础服务-人员-企业微信同步(注：只有在系统参数中启用了企业微信，该按钮才会显示)
b.点击企业微信同步按钮，在企业微信【通讯录】api授权的前提下，系统会将企业微信人员信息映射到苍穹系统中（如想了解同步的实现过程，可调式代码kd.bos.sec.user.utils.UserOperationUtils中synWxqyh方法）。
注：是否同步成功可以通过查询映射表确认（系统库t_bas_immapping）
SELECT * FROM t_bas_immapping t WHERE t.`FUSERID`='xxx' AND t.`FIMTYPEID`='3';
（其中FUSERID为表t_SEC_User的id）
2. 消息中心配置
（1）消息渠道配置和启用：
a.操作位置：系统服务云-系统管理-消息平台-消息渠道
b.配置企业ID，应用ID和应用秘钥（应用ID和应用秘钥的获取需要在企业微信中自建应用，获取方式参考3.2企业微信配置）
c.启用微信渠道
（2）消息类型的配置：任务类型添加企业微信渠道（如果想要将某种消息类型需要推送到对应的消息渠道，对应的消息类型中勾选添加对应的消息渠道即可）
a.操作位置：系统服务云-系统管理-消息平台-消息类型
3. 环境配置
实现待办任务点击之后，免登录进入苍穹的审批界面，客户苍穹环境需要有域名地址，并需要设置环境配置方案相关内容。
（1）单点登录配置:
a. 操作位置：系统服务云-配置工具-单点登录-企业微信号或者进入开发平台，搜索cts_wxqyh基础资料，新增企业微信的信息
3.2企业微信配置
1. 创建应用
（1）输入应用名称、上传应用Logo，应用介绍，并制定应用可见范围，创建应用。
（2）获取应用ID和应用秘钥
2. 设置可信域名
（1）如果客户的苍穹访问地址中包含域名，需要在创建的应用中设置可信域名
（2）可信域名必须和苍穹的域名一致，否则不能正常跳转。填写时注意规则，不需要填写http或者https，如有端口号可以填上端口号
（3）申请校验域名，如果想要实现微信端审批完成后关闭审批页面功能，需要申请校验域名，按照点击申请校验域名后展开的步骤执行。完成后会显示为如图所示已验证
3.3测试结果
1. 前期准备：需要在苍穹中新建一个表单，并设置对应的审批节点和审批人
2. 提交单据
3. 消息中心：进入审批人中的消息中心页面，待办任务中存在待审批的单据
4. 企业微信中的自建应用同步接收到苍穹的待办任务
4消息渠道扩展开发
4.1开发预研
扩展开发其他消息渠道需要关注以下几个问题：
1. 人员信息同步
人员同步的方案，可参考标准产品的第三方渠道的同步方式。目前标准产品的方案：
（1）同步功能的主要逻辑是，通过第三方系统提供的组织人员接口，获取到人员信息，并以两个系统中人员的焦点(比如手机号、邮箱账号等)作为比较条件，建立两个系统的人员映射关系，存储至苍穹系统中。
（2）苍穹与微信、钉钉等第三方系统人员映射关系表t_bas_immapping
字段 | 编码 | 类型 | 描述 |
FID | Bigint(20) | ||
映射类型ID | FIMTYPEID | Bigint(20) | 0~100为原厂预留，扩展渠道第三方需要>100 |
苍穹人员ID | FUSERID | Bigint(20) | t_sec_user表中ID |
第三方系统人员ID | FOPENID | Varchar(80) |
2. 单点登录
目前苍穹单点的方案一般是在链接消息的url上拼接参数苍穹登录模块加装增加处理逻辑，链接由nginx转交之后，由登录模块识别并自动登录到苍穹目标单据，用户执行后续操作。渠道解析类中createtodo() sendMessage()方法中获取todoInfo和messageInfo的链接，并根据登录要求加以改造。
第三方系统单点登录苍穹可参考：
https://vip.kingdee.com/article/89302586737890816
3. 第三方系统API接口
不同第三方系统提供的接口不同，在流程任务集成的过程中，除了人员同步的接口外，应该重点关注以下含义的API:
（1）消息推送接口，推送文本消息或链接消息；
（2）待办任务创建接口；
（3）待办任务状态更新接口，待办变已办任务；
（4）待办任务删除接口，删除待办。
4.2开发过程
（1）人员信息同步
人员信息同步如参考标准方案，具体逻辑开发人员可以参考以下代码实现：
kd.bos.sec.user.utils.UserOperationUtils.synWxqyh，该方法为企业微信同步人员信息实现过程，其中saveIMMapping方法为保存账号映射关系。
注意：需要同步处理人员新增情况，考虑第三方是否提供增量同步接口等。
（2）第三方系统实现类代码开发，实现类需要继承
kd.bos.workflow.engine.msg.handler.AbstractMessageServiceHandler
抽象类，并复写抽象类中若干方法。在该类中实现创建待办、处理待办、删除待办、推送消息等相关逻辑内容，具体逻辑可以参考原厂标准云之家渠道解析类YunzhijiaServiceHandler
以下为复写关键方法说明：
A.createTodo方法：工作流中的待办任务创建之后，会调用此接口
public void createToDo(MessageContext ctx, ToDoInfo info){ 1. 流程节点任务，创建待办； 2. todoInfo&messageContext中包含了绝大部分场景中待办所需参数数据； 3. 在该方法中调用接口，推送待办任务； 4. 标准产品中没有记录待办日志，二开根据需求决定是否将待办日志落库处理,数据库表以及落库方式没有要求； 5. 在方法的逻辑执行过程中，若是出现异常，请向上抛出，系统会根据异常，自动重试再次推送待办； 6. 对于待办链接的改造可以在该方法中进行； } |
B.dealTodo方法：工作流中将待办变成已办的时候，会调用此接口进行待办变已办的处理
public void dealToDo(MessageContext ctx, ToDoInfo info){ 1. 流程处理待办任务； 2. 在该方法中调用泛微接口，推送待办处理请求； } |
C.deleteTodo方法：工作流中撤回，或者多人收到任务，其中一人审批，删除其他人的待办时，调用此接口
public void deleteTodo(MessageContext ctx, ToDoInfo info){ 1. 删除待办任务方法； 2. 转交任务、任务的处理都会调用该方法，删除掉泛微方的待办； 3. 工作流中撤回，或多人收到任务，其中一人审批，删除其他人的待办，会调用该方法 4. 在该方法中调用泛微接口，发起删除泛微待办请求； } |
D.checkTodo方法：
public void checkTodo(MessageContext ctx, ToDoInfo info){ 1.校验第三方待办处理情况，一般不复写该方法； } |
E.sendMessage方法：
public void sendMessage(MessageContext ctx, MessageInfo message) { 1. 工作流的任务类消息，比如传阅、协办消息、节点消息、催办消息等都会推送到该方法中，业务调用消息中心接口推送的消息同理也会推送到该接口中； 2. 发送报警、预警、通知消息，调用该方法； 3. Ctx=null, 对于流程类消息，可以在messageInfo.getParam()方法中获取到ctx数据； 4. 调用推送消息接口，推送消息； 5. 若是调用接口部分请求失败，请向上抛出异常，异常方式可以参考原厂逻辑，系统会自动重试再次推送消息； 6. 对于链接消息中URL的改造可以在该方法中进行 } |
F.deleteProcessInstance方法：
public void deleteProcessInstance(MessageContext ctx, Long proceInstanceId){ 1.若第三方系统中有流程，苍穹删除流程的动作会推送到该方法汇总，若第三方系统中没有流程相关，则无需复写该方法； } |
G.completeProcessInstance方法：
public void completeProcessInstance(MessageContext ctx, Long proceInstanceId){ 1. 若第三方系统中有流程，苍穹流程结束动作会推送到该方法汇总，若第三方系统中没有流程相关，则无需复写该方法; } |
（2）新增消息渠道：移动应用选择”其他“，填写对应的实现类，完成新增消息渠道界面配置
注意：如果是需要将第三方系统的必要参数抽象到配置界面上，也可以通过扩展msg_channel表单，达到元数据二次开发的需求。
4.3说明
(1) 由于苍穹与第三方系统之间，通过网络关联，由于网略不稳定性等因素，可能导致消息推送失败，此时，可以在sendMessage方法中抛出异常，该异常被上游功能捕获，失败消息记录到消息日志列表中，等待重试机制重试；
参考YunzhijiaServiceHandler处理方式：
（2）待办创建、处理、删除若是遇到调用接口失败的情况，请抛出异常给上游逻辑，触发重试机制；参考YunzhijiaServiceHandler处理方式：云之家目前会先重试3次，失败再直接抛出等待定时重试
（3）第三方系统中待办请重视待办ID的唯一性问题，苍穹中多人处理的任务，taskId是一样的，针对有的第三方系统，可以拼接人员Id做唯一性处理
推荐阅读