050401. 流程待办、消息推送

1.流程图：

2.启用

系统设置-服务器设置-是否开启数据推送 打开即可

2.2初版功能介绍

消息订阅功能介绍, 消息订阅支持 webservice服务 和 http 协议

基础匹配逻辑

1. 岗位, 人员, 部门匹配 订阅规则 过滤
2. 订阅规则是否启用, 消息类型, 消息事件 过滤
3. 字段映射匹配规则 过滤, 直接抛异常, 会保存一条 SubscribeSendRecord记录

目前功能还在不断 完善中, 各位老板在使用过程中遇到问题和 有一些新的场景未满足, 可以在文档下添加评论

3.配置步骤

1.消息订阅 （现更名为 数据推送管理）在 集成管理→ 数据推送管理

2. 跳转到如下页面

3. 配置页面如下，需要着重配置：

（1）字段映射配置 → 决定发送的消息是否与第三方（如钉钉）需要的消息内容匹配。具体需要什么样的消息内容，请参照第三方消息文档要求的消息体，结合本文档进行配置。

（2）匹配规则/适用范围 → 决定哪些用户的消息能够被“数据推送”功能推送出去。

4.自定义需要发送的字段

如下:

配置字段发送格式说明,  

最外层 关键字 （新版参数如json_v2在下文“实际配置案例”中给出。）

success_response_define

unique_third_key

获取第三方app发送消息需要的字段，一般是获取系统绑定信息的
第三方用户id,用于发消息

5.实际配置案例（系统的数据都可以推送到第三方，不限于消息）：

1.以推送一条待办消息到第三方为例，前置配置如图：

表示只有系统新增一条待办消息时才会使用这条推送规则，通知新增，编辑，待办编辑都不会使用这条规则。

2.配置转换规则：

json, data, params, url_params 内部配置详情,具体配置需要根据第三方文档来确定，下边以json参数来(兼容历史版本，使用公式编辑器的为json_v2属性，其他属性自动会加上‘_v2’,在对应参数配置即可)

公式配置案例（具体配置json,data,param,url_params,看具体情况，以下以json为案例，数据推送必须走单点认证模式才能从第三方点击消息回到人力系统。）：

案例代码:json_v2：

{
    "pcurl": "=CONCAT('http://123.61.11.8:9010/api/auth/login_by_sso?sso=customer_sso&next=http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D',id,'&response_type=code&state=app_single_login&flag=veri&name=',get_value_from_dict(['receiver', 'number']),'&entry=',sub_decrypt())",
    "appurl": "=CONCAT('http://123.61.11.8:9010/api/auth/login_by_sso?sso=customer_sso&next=http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D',id,'&response_type=code&state=app_single_login&flag=veri&name=',get_value_from_dict(['receiver', 'number']),'&entry=',sub_decrypt())",
    "flowid": "=get_value_from_dict(['params', 'wf_assignment_id'])",
    "creator": "=get_value_from_dict(['sender', 'number'])",
    "syscode": "HCM",
    "Filetype": "message_type",
    "isremark": "0",
    "nodename": "=get_value_from_dict(['assignment_info', 'wf_def_name'])",
    "receiver": "=get_value_from_dict(['receiver', 'number'])",
    "viewtype": "0",
    "important": 10,
    "receivets": "=S(get_current_timestamp())",
    "requestname": "=content",
    "workflowname": "=get_value_from_dict(['business_info', 'name'])",
    "createdatetime": "=timestamp_format(\"%Y-%m-%d %H:%M:%S\")",
    "receivedatetime": "=timestamp_format(\"%Y-%m-%d %H:%M:%S\")"
}

生成的数据（前往日志查看）：

具体数据案例：

{
        "pcurl": "http://123.61.11.8:9010/api/auth/login_by_sso?sso=customer_sso&next=http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D4103763&response_type=code&state=app_single_login&flag=veri&name=zhx&entry=553c80a1-13cf-5cc8-9b81-ce2be618fd64",
        "appurl": "http://123.61.11.8:9010/api/auth/login_by_sso?sso=customer_sso&next=http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D4103763&response_type=code&state=app_single_login&flag=veri&name=zhx&entry=553c80a1-13cf-5cc8-9b81-ce2be618fd64",
        "flowid": "7078077",
        "creator": "zhx",
        "syscode": "HCM",
        "Filetype": "message_type",
        "isremark": "0",
        "nodename": "测试节点",
        "receiver": "zhx",
        "viewtype": "0",
        "important": 10,
        "receivets": "1688378522011",
        "requestname": "来自 zhx 的 外勤打卡测试 申请, 请审批",
        "workflowname": "外勤打卡(导入)",
        "createdatetime": "2023-07-03 18:02:02",
        "receivedatetime": "2023-07-03 18:02:02"
    }

特殊数据描述：字段pcurl，appurl 都是构造单点登录链接，其他应用叫法可能不一样，但是一般都会有一个用于跳转的字段，为了保证系统安全，这个字段对应的链接必须携带加密后的密钥。

链接详解：

http://123.61.11.8:9010/api/auth/login_by_sso?sso=customer_sso&next=http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D4103763&response_type=code&state=app_single_login&flag=veri&name=zhx&entry=553c80a1-13cf-5cc8-9b81-ce2be618fd64

单点路径：域名+/api/auth/login_by_sso 也可以使用 域名+/login

sso类型：sso=customer_sso, customer_sso是一类sso,也可以是work_inner,mobile_sso,ding

next:单点登录成功后跳转的地址，比如原来是：http://123.61.11.8:9010/messagerouter?message_id=4103763，需要进行一次编码（前往编码工具）编码后：http%3A%2F%2F123.61.11.8%3A9010%2Fmessagerouter%3Fmessage_id%3D4103763，
这条链接的含义是 ，‘http://123.61.11.8:9010/messagerouter?message_id=’ 表示消息跳转地址，4103763表示消息ID，这个地址在已登录的浏览器打开，就会跳转到对应的消息

response_type=code&state=app_single_login&flag=veri：这些是一些额外的参数，依据情况可能有用处，在这里不是主要字段

name=zhx ：系统的人员编号，用作单点标识(如果没有签名字段，意味着只要修改这个编号，就可以登录别人账号)

entry=553c80a1-13cf-5cc8-9b81-ce2be618fd64：安全密钥，使用加密方法，根据消息生成时间动态生成的，安全等级高。生成规则可以根据具体情况来判断
密钥生成过程，可以使用公式来构造，这里是用了aes 加密，用到的参数包括：
固定的密钥：hcmshenhuoabcbac，长度必须是16的倍数，自定义一个，请勿直接拷贝案例
加密数据：CONCAT(get_value_from_dict(['receiver', 'number']),S(send_date),'oa') 构造的加密数据包括：人员编码，消息生成时间和随意的字符串
偏移量：hcmshenhuocbacba  长度必须是16的倍数，自定义一个，请勿直接拷贝案例

因为加密后的数据中有-,+这种敏感字符（案例：'PHNjcmlwdD5hbGVydCgxKTs8L3Njcml+wdD4='），这里使用uuid_sec再加密一次，确保得到一个标准的字符串（案例：553c80a1-13cf-5cc8-9b81-ce2be618fd64），其他加密方法可以根据实际情况处理
加密认证会在单点登录云函数中处理，下边有对应的单点云函数处理过程。
加密字段配置如图：

信息安全很重要，要牢记，凡事涉及到数据推送和单点的，链接上最好能携带一个加密字段，不允许使用简单 编号，手机号直接查人员后完成登录，如果拥有完整的

oauth2过程，则不需要使用加密字段

单点云函数案例：个性化登录（查看 2.非标准单点模式）

3.认证信息配置详情（看情况配置）

案例：

{
    "url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
    "method": "GET",
    "params": {
        "corpid": "ww5dse3asebcab462a",
        "corpsecret": "rBZrTHww5debc5sd917bAvD2dP_Qa5k4JgsnM(脱敏处理)"
    },
    "headers": {},
    "auth_key": "access_token",
    "location": "params",
    "expire_time": 1500,
    "get_token_field": ["access_token"]
}

4.请求结果处理

案例：

请求返回数据：

 {"result":{"priority":"20","id":"3214521","message":"推送成功","action":"new"}}

配置案例：

表示：根据success_response_key，success_response_value判断是否请求成功，成功的话调用API：private.test_api_i，API可以拿到的参数为：{"action":"new","message_id":"3214521"}

{
    "callback_api": "private.test_api_i",
    "callback_param": [{
        "map": "action",
        "field": ["result", "action"],
        "default": "new"
    },  {
        "map": "message_id",
        "field": ["result", "id"],
        "default": "111"
    }],
    "success_response_key": ["result","priority"],
    "success_response_value": "20"
}

5.失败重试机制

handler: 消息类别，mobile_handler表示发短信提醒,mail_handler表示邮件提醒，可以为空，不配置

to:mobile_handler表示配置手机号，mail_handler表示配置邮箱，可以为空，不配置

time:表示失败后多久再推送一次，默认20秒，最小5秒最大3600秒

message:消息内容，可以替换数据ID

配置案例：

案例功能描述：以下配置表示如果数据推送失败了，20秒后执行再次推送，如果还是失败，20秒后再次重新推送，然后发短信给两个手机号，如果再次失败，40秒后再次推送，发邮件给邮箱。

[{
    "to": "",
    "time": 20,
    "handler": "",
    "message": "失败消息数:{msg_id}"
}，{
    "to": ["18845191220", "18845191521"],
    "time": 20,
    "handler": "mobile_handler",
    "message": "失败消息数:{msg_id}"
}, {
    "to": ["223014282@qq.com", "223212282@qq.com"],
    "time": 40,
    "handler": "mail_handler",
    "message": "失败消息数"
}]

6.内部接口调用配置

如图，包括接口参数定义：

6.消息体格式说明

原始发送消息体参考

普通通知

{
    "id": 289289, 消息ID
    "date": 1630048695583,消息生成时间戳
    "type": "message",
    "level": 0,消息级别
    "title": { 消息标题信息
        "id": 2,
        "name": "待办",
        "number": "task-001",
        "company_id": 169,
        "description": "待办消息"
    },
    "to_id": 1507563, 消息接收人ID
    "action": "new", 推送类别
    "go_url": "/messagerouter?message_id=2314532",跳转链接
    "params": { 跳转参数
        "type": "wf",
        "business_id": "15785",
        "wf_assignment_id": "7054794"
    },
    "sender": { 发送人名称，编号，手机号等
        "id": 1507563,
        "name": "张三",
        "mobile": "18682315095",
        "number": "SHHR001",
        "identity_card": "370403198005132215"
    },
    "unread": true, 是否已读
    "content": "来自 张三 的 测试(导入) 申请, 请审批", 消息内容
    "from_id": 1507563,发送人ID
    "is_read": false,
    "go_param": "{\"wf_assignment_id\": \"7054794\", \"business_id\": \"15785\", \"type\": \"wf\"}",
    "go_state": "workflow_bill_v3",跳转state
    "receiver": { 接收人名称，编号，手机号等
        "id": 1507563,
        "name": "张三",
        "mobile": "18682315095",
        "number": "SHHR001",
        "identity_card": "370403198005132215"
    },
    "title_id": 2,消息标题
    "send_date": 1630048695583,
    "article_id": null,
    "company_id": 169,公司ID
    "is_task_done": 1,消息类别，0:通知，1:待办，2已办
    "message_type": "message",消息类别
    "from_object_id": null,
    "from_object_class": null
}

在公式编辑器页面，已经添加了对应的中文描述：

其他消息数据发送结构体可以在初始配置时, 如何明确流程消息结构体

1. 不配置字段发送格式,
2. 触发这条消息订阅规则
3. 在SubscribeSendRecord, 找到触发的消息推送记录, 查看发送数据, 如下
4. 

由于人员相关字段太多, sender 和 receiver只会展示部分字段, 实际人员字段参照 hcm.model.get 接口返回的数据格式

7.查看推送记录

/common_model_list?model=SubscribeSendRecord

支持手动同步, 打开浏览器控制台, F12, 选中一条同步记录, 点击手动同步,  查看接口如下图

返回值为同步记录id: 失败信息的字典映射