消息同步

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

1 - V8同步至三方

集成模式

1.1 - 三方系统提供写入OpenAPI

1、概述

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

2、优缺点

a. 优点

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

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

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

b. 缺点

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

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

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	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、集成配置

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、接口清单

6.1. 【批量】 批量同步消息

6.1.1. 请求地址：

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

6.1.2. 请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	PluginMessageBatchDto	请求参数数据
capabilityId	data	true	int64	事项所属基础插件能力。复用插件的用户映射，单点登录等配置。
idType	data	false	enum	发起人/处理人标识类型， 不传递默认OUTER_ID（三方系统ID）。 枚举项可选值列表： OUTER_ID（三方系统ID）， V8_ID（V8内部ID）， V8_CODE（V8系统编号）， V8_LOGIN_NAME（V8登录名）， V8_PHONE（V8手机号）
messageList	data	true	array[PluginMessageDetailDto]	消息列表
senderId	messageList	false	string	消息发起人标识
externalMessageId	messageList	true	string	消息外部编号
messageSourceCode	messageList	false	string	消息来源
title	messageList	true	string	消息标题
createTimeStamp	messageList	false	int64	消息创建时间戳
openType	messageList	false	string	详情打开方式： WORKSPACE（工作区）， NEWWINDOW（新窗口，默认值）
todoWebUrl	messageList	false	string	消息WEB端详情地址
todoMobileUrl	messageList	false	string	消息移动端详情地址
receiverDto	messageList	true	MessageReceiverDto	消息接收人对象
userIdList	receiverDto	false	array[string]	消息接收者标识列表（按人员发送消息）。 和unitCodeList至少填一个
unitCodeList	receiverDto	false	array[string]	接收者V8组织编号列表（按组织发送消息）。 和userIdList至少填一个
extendSign	receiverDto	false	boolean	组织是单位时是否包含下级单位（组织是部门时， 固定包含下级部门）

6.1.3. 请求示例

{
  "data": {
    "messageList": [
      {
        "senderId": "MB202306070002",/*致远OA用户Code*/
        "externalMessageId": "11000102",/*业务系统消息Id，唯一*/
        "createTimeStamp": 1688033651186,/*请求时间戳,毫秒级*/
        "todoMobileUrl": "https://www.baidu.com",/*待办事项移动端详情页URL地址*/
        "title": "测试消息头2023年4月19日14:17:06",/*消息标题*/
        "receiverDto": {
          "userIdList": ["MB202306070002"]/*致远OA用户Code*/
        },
        "todoWebUrl": "https://www.baidu.com",/*消息PC端待处理页URL地址*/
         "openType":"NEWWINDOW"/*枚举值，打开方式*/
      }
    ],
    "capabilityId": "1498469601665614061",/*固定值*/
    "idType":"V8_CODE"/*枚举值*/
  },
  "requestId": "1395143136501500012",/*请求流水号，每次请求唯一*/
  "timestamp":1688033651186/*请求时间戳,毫秒级*/
  }

6.1.4. 返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

6.1.5. 返回示例

{
    "status": 0,/*成功标识*/
    "code": "BOOT_0000",/*错误码*/
    "message": "SUCCESS",/*返回信息*/
    "data": null
}

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

1、概述

第三方数据→openapi→调用消息接口，和待办不同的是，消息没有底表。 第三方id最大长度限制是43位。