事项同步

• 1: V8同步至三方
• 1.1: 三方系统提供写入OpenAPI（推荐）
• 2: 三方同步至V8
• 2.1: COP平台开放写入OpenAPI（推荐）
• 2.2: 消息队列
• 2.3: 第三方同步到V8常见问题

1 - V8同步至三方

集成模式

1.1 - 三方系统提供写入OpenAPI（推荐）

1、概述

三方异构系统提供写入OpenAPI，由COP定时调用接口主动推送，完成事项同步。

三方系统提供事项写入OpenAPI，COP平台封装接口，定时主动推送待办事项，配置字段映射，完成事项同步。

2、优缺点

* 优点

a. 三方系统工作量少，三方无需关注字段映射、同步日志等集成步骤，针对有标准接口的saas产品集成效率更高；

b. 整个集成步骤都是在图形化操作界面中完成，可以大量节约集成工期和研发投入；

c. 主动写入，数据时效性高；

* 缺点

a. 三方系统数据库结构字段要求高，必须满足COP系统事项呈现要求，否则会造成部分功能缺失；

b. 致远实施工作量大，需要了解三方系统数据库字段要求；

3、操作步骤

序号	步骤名称	责任方	使用场景
1	提供单点登录接口规范和文档	三方系统	非必须，如果COP和三方系统未接入统一身份认证系统，则需要通过单点登录方式免登陆打开事项详情页
2	提供事项写入接口规范和文档	三方系统	必须，
3	注册并配置鉴权AppID和秘钥	三方系统	非必须，如果三方系统接口调用时涉及到安全鉴权，则需要提供
4	提供接口调用示例	三方系统	必须，为了集成效率，强烈建议三方系统提供可直接使用的postman接口调用示例，
5	新建三方集成应用	致远	必须，集成应用负责封装三方系统接口和配置单点登录
6	发布三方集成应用	致远	必须，集成应用只有发布后才能正常使用
7	封装安全认证	致远	非必须，如果三方系统接口调用时涉及到安全鉴权，则需要配置安全认证
8	封装签名	致远	非必须，如果三方系统接口调用时涉及到签名参数，则需要配置签名
9	接口封装	致远	必须，三方系统提供的接口只有正常封装后才能供给COP使用
10	在线调试验证	致远	必须，三方系统接口封装完成后，需要在线调试，验证网络通信、接口返回结果是否正确等
11	单点登录	三方系统	必须，参照【三方系统单点登录打开COP】单点登录模式配置
12	新建事项同步	致远	必须，
13	选择同步模式	致远	必须，
14	配置同步周期	致远	必须，根据数据量和服务器消费能力，合理配置同步周期
15	配置字段映射	致远	必须：三方系统接口文档中的字段名，字段释义与COP不一致，需要配置参数映射、层级转换等

4、集成配置说明

4.1. 新建三方集成应用

4.2. 封装安全认证

4.3. 枚举定义

4.4. 接口封装

4.5.在线调试验证

4.6. 新建事项同步【致远】

4.7. 选择同步模式【致远】

4.8. 配置字段映射【致远】

4.9. 发布三方集成应用

5、注意事项

无

2 - 三方同步至V8

集成模式

2.1 - COP平台开放写入OpenAPI（推荐）

1、概述

COP平台开放写入OpenAPI，由三方异构系统定时增量推送，完成事项同步模式。

2、核心字段定义

术语	定义	来源	测试数据
appKey	V8统一认证中心分配给每个接入应用的唯一标识Id，别名应用Id	致远COP	3e4a140e2509477396fa04ddcd70c3d2
AppSecret	V8统一认证中心分配给每个接入应用的加密解密秘钥，别名应用秘钥	致远COP	5bad0b6618934c62bffefe4cc0d8c03d
url前缀	文档中所有接口的请求前缀	致远COP	http://openapi-bpm.CC.com.cn
capabilityId	同步能力编码，针对事项同步场景：新增待办、新增我的已发、已发更新为已办	致远COP	1531486151775358223
capabilityId	同步能力编码，针对消息同步场景	致远COP	1457957992996539915

3. 集成导图

4、接口签名

4.1、请求头（Header）

参数名称	是否必填	参数说明
app-key	true	应用的唯一标识，创建接入应用后生成，可在应用基础信息页面获得。 示例：d43b0b442cf34076a2c4af6bb8928afb
sign-type	true	固定值：MD5
sign	true	签名，字符串“AppSecret+请求体的JSON字符串+AppSecret”的MD5值（MD5值忽略大小写） AppSecret，为应用的秘钥，创建接入应用后生成，可在应用基础信息页面获得。 示例：154fa5bc7e294deda68a15559b07c845请求体的JSON字符串， 需要将请求体中的请求参数转换为JSON字符串。
Accept-Language	false	语种：用以设置开放平台OpenAPI运行时上下文的语种参数。 枚举项可选值列表：zh-CN（简体中文）， zh-TW（繁体中文）， en（英文）， 其他枚举项请参照平台语种列表。

4.2、签名示例（sign）

String secret = "154fa5bc7e294deda68a15559b07c845";
String body = "{"name": "张三", "age": 35, "company": {"name": "致远", "address": "北京"}";
String sign = Md5(secret + body + secret); // 结果是 01a8795a7fe6dda23aaec40de3d301b7;

5、集成配置

目的：生成APPKey、APPSecret和同步能力编码三个核心参数

5.1. 新建集成应用

5.2. 配置单点登录

5.3、新建事项同步,获取事项同步能力编码

5.4、发布应用

5.5、启用API

5.6、新建接入应用

5.7、启用接入应用

5.8、分配APPKey和AppSecret

5.9、应用级别API授权

5.10、按需开启IP白名单

5.11、按需开启限流控制

5.12、API调用日志

6、接口清单

请求地址：

【url前缀】/cip-manager/plugin-affair/create-update

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。 如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	PluginAffairBatchDto	请求参数数据
capabilityId	data	true	int64	待办同步能力编号
affairAction	data	true	enum[START:START; OTHER:OTHER; ]	产生事项变更的动作
idType	data	true	enum[OUTER_ID； V8_ID； V8_CODE；  V8_LOGIN_NAME； V8_PHONE；]	发起人/处理人标识类型， 不传递默认OUTER_ID（三方系统ID）。 枚举项可选值列表：OUTER_ID（三方系统ID）， V8_ID（V8内部ID）， V8_CODE（V8系统编号）， V8_LOGIN_NAME（V8登录名）， V8_PHONE（V8手机号）
affairList	data	true	array[PluginAffairDetailDto]	待办详情列表
externalAffairId	affairList	true	string	事项标识
startMemberId	affairList	true	string	发起人标识
startTime	affairList	true	string	发起时间。毫秒时间戳或者yyyy-MM-dd HH:mm:ss格式
ownerId	affairList	true	string	处理人标识
title	affairList	true	string	待办标题
importance	affairList	true	int32	重要程度，0=普通，1=重要
receiveTime	affairList	true	string	接收时间。毫秒时间戳或者yyyy-MM-dd HH:mm:ss格式
todoWebUrl	affairList	true	string	PC端查看地址
todoMobileUrl	affairList	true	string	移动端查看地址
objectId	affairList	true	string	组ID，比如流程id
dealTime	affairList	true	string	处理时间。毫秒时间戳或者yyyy-MM-dd HH:mm:ss格式
newStatus	affairList	true	string	目标状态，仅更新时使用enum[ NONE:默认值：空; READY:待发; SENT:已发; PENDING:待办; DONE:已办; REVOKE:撤销; ]
subStatus	affairList	true	string	目标子状态，仅更新时使用 pending=正常待办 ready=草稿待发 sent=正常已发 done=正常已办 temporary=暂存 backed=被退回 retrieve=取回s top=终止 terminated=被终止 transfer=移交 return=退回 specifyFallback=指定退回 revoke=撤销 revoked=被撤销 beCompetitive=被竞争 abandoned=废弃 sender=回退到开始节点子状态 pause=挂起状态
objectState	affairList	true	int32	-1=空 0=运行中 1=终止 2=完成 4=挂起 5=撤销 6=草稿 7=删除
compareKey	affairList	true	string	数据更新标识。传递时间戳即可
openType	affairList	false	string	详情打开方式：WORKSPACE（工作区）， NEWWINDOW（新窗口，默认值）

请求示例

{
  "data": {
    "affairList": [
      {
        "newStatus": "DONE",/*枚举值*/
        "externalAffairId": "123321128",/*业务系统事项Id，唯一*/
        "importance": 1,/*枚举值*/
        "startMemberId": "MB202305060001",/*根据idType定义，示例中idType=V8_CODE时，传值致远V8用户Code*/
        "ownerId": "MB202305060001",/*根据idType定义，示例中idType=V8_CODE时，传值致远V8用户Code*/
        "title": "待办同步测试123",/*待办事项标题*/
        "todoWebUrl": "PC详情url",/*待办事项PC端待处理页URL地址*/
        "subStatus": "pengding",/*枚举值*/
        "receiveTime": "2023-04-24 19:25:30",/*接受时间*/
        "compareKey": "1688033651186",/*数据更新标识。传递时间戳*/
        "dealTime": "2023-04-24 19:25:30",/*处理时间*/
        "startTime": "2023-04-24 19:25:30",/*发起时间*/
        "todoMobileUrl": "移动端详情url123",/*待办事项移动端待处理页URL地址*/
        "openType":"NEWWINDOW",/*枚举值，详情页打开方式*/
        "objectId": "1008"/*流程Id，与待办objectId参数一致*/
      }
    ],
    "capabilityId": "1531486151775358223",/*固定值，事项同步能力编码*/
    "affairAction": "OTHER",/*固定值*/
    "idType":"V8_CODE"/*枚举值*/
  },
  "requestId": "1395151404498159078",/*请求流水号，每次请求唯一*/
  "timestamp": 1688033651186/*请求时间戳,毫秒级*/
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
details	content	array
externalAffairId	details	string	事项ID
result	details	string	操作结果，ADD=新增，MODIFY=更新
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
    "status": 0,/*成功标识*/
    "code": "BOOT_0000",/*错误码*/
    "message": "SUCCESS",/*返回信息*/
    "data": {
        "content": {
            "details": [
                {
                    "externalAffairId": "1693299012298",
                    "result": "ADD"
                }
            ]
        }
    }
}

7、注意事项

7.1、待办批量更新为已办接口和批量新增待办接口请求地址一致，入参有差异，核心差异字段为请求示例中标记了【差异】的参数newStatus、subStatus、compareKey；

7.2、返回结果中code=BOOT_0000，且externalAffairId不为空时，才表示同步成功。

7.3、当前模式下，不会同步生成消息。

7.4、新增待办时：newStatus=PENDING&subStatus=pending；待办更新已办时：newStatus=DONE&subStatus=done，且事项ID一致、

2.2 - 消息队列

1、概述

COP平台将组织数据写入MQ，三方异构系统消费MQ，实现事项同步模式。

三方系统将事项数据写入MQ，COP监听MQ获取事项数据，实现事项同步。

COP平台还提供同步补偿。

2、优缺点

a. 优点

i. 三方系统集成压力小；

ii. 数据时效性高；

b. 缺点

i. 实施团队需要熟悉三方系统接口规范、定义；

ii. 实施团队需要熟悉COP平台事项维度和数据定义；

3、操作步骤

序号	步骤名称	责任方	使用场景
1	提供事项新增、变更增量更新MQ消息体定义	三方系统	必须
2	提供MQ连接信息	三方系统	必须，
3	新建MQ数据源	致远	必须，封装MQ数据连接
4	新建三方集成应用	致远	必须，三方集成应用负责封装三方系统接口和配置数据映射
5	发布启用三方集成应用	致远	必须，三方集成应用只有发布后才能正常使用
6	新建消息队列	致远	非必须，根据三方系统提供的消息体定义
7	启用事项同步	致远	必须，字段映射、同步周期需要在事项同步中配置
8	选择同步模式	致远	必须，本场景下固定选择模式为：从三方系统获取
9	配置字段映射	致远	必须：三方系统接口文档中的字段名，字段释义与COP不一致，需要配置参数映射、层级转换等
10	使用日志	致远	必须，配置完成并启用后，查看使用日志

4、集成配置说明

4.1. 新建数据源

4.2. 新建三方集成应用

4.3. 队列封装

4.4. 配置单点登录

4.5. 新建事项同步

4.6. 选择同步模式

4.7. 配置字段映射

4.8. 发布三方集成应用

4.9. 三方系统创建事项【三方系统】

配置完成后，三方系统创建事项。

4.10. 等待拉取间隔时间

等待同步周期间隔时间后，登录门户查看已经同步后的待办事项。

4.11. 门户待办栏目查看数据【致远】

4.12. 点击待办数据并处理【致远】

4.13. 等待拉取间隔时间

等待同步周期间隔时间后，登录门户查看已经同步后的已办事项。

待办处理之后变为已办，数据展示在已办栏目。

4.14. 刷新门户首页查看待办、已办数据【致远】

5、 注意事项

无

2.3 - 第三方同步到V8常见问题

1、拉取

一般作为初始化使用，运行中不推荐使用，量大而且实时性差。

2、事件订阅、消息队列

异步的，第三方调用后，会甩出mq，然后订阅执行。第三方不能感知是否最后形成事项，需人工检查。

3、关联开放openapi

第三方数据→cip-connector底表（用于判断更新/新增）→调用affair接口。

1、如何通过第三方id查到对应的事项： cip-connector：select id from cip_p_sync_affair where outer_id=’{第三方id}’ ctp-affair：select * from affair where sub_object_id={cip_p_sync_affair的id}

2、capabilityId获取方式：

3、数据内容一个节点多个人，需要节点id+人的id作为第三方的标识。

4、如果相关人员是第三方信息，那么需要提前建立好用户映射

5、待办更新时，目前需要报文中含有所有字段。如果更新时只给id和状态，那么还需要第三方建立底表存储新建时的报文信息。

6、接口成功都会返回第三方标识。接口错误的一种标志如下