(高级) 第三方服务回调

一、简介

在宜搭中，凡是涉及到接口服务调用的均称为第三方服务回调，通过对服务调用的支持，使宜搭可以和外部系统进行集成，数据互相流转，避免宜搭应用成为信息孤岛。服务回调的使用场景目前多集中于表单服务回调和审批节点的服务回调，不同场景场景下的服务回调使用方式大致相同，下面就不同场景下的配置和使用分别予以介绍。

服务回调功能完整的使用流程如下：

二、注册服务

首先确认您是否已经在宜搭注册了自己了回调服务，您可以通过“平台管理”→“服务注册”进行查看，如果还没有注册，那么请先注册自己想要调用的服务，注册过程请参考文档《（高级）服务注册》。

三、服务使用场景

3.1 单据第三方服务校验/执行

• 第三方服务校验: 用于在表单提交时，调用业务服务接口校验数据的合法性，同步调用
• 第三方服务执行: 用于在单据提交/编辑/删除成功后，执行第三方服务调用，异步调用.

下面将分别针对新老版本的页面设计器介绍一下上述功能的入口：

在单据页面的设计器中，如果打开的页面风格是黑色主题的老版页面设计器，点击页面空白处，如果需要使用第三方服务校验，则点击”添加校验条件”按钮，如果需要使用第三方服务执行，则点击”添加第三方服务回调”按钮，如下图所示：

在单据页面的设计器中，如果打开的页面风格是白色主题的老版页面设计器，则首先在设计好的表单页面，点击页面空白处，如果需要使用第三方服务校验，则点击”服务校验”下的”添加服务”按钮；如果需要使用第三方服务执行，则点击“服务执行”下的”添加执行”按钮，如下图所示：

此时会弹出一个”函数计算”的页面，在1位置有一个默认的标题可以修改，2，3，4分别为校验或者服务执行的时机，目前提供了三个操作节点，分别是表单提交、表单删除和表单编辑，用户可以根据自己的实际需要选择，可以同时配置一个或者多个，如下图所示：

（1）您可以为即将添加的回调服务设置一个标题
（2）回调执行时机，表示当有数据提交时执行
（3）回调执行时机，表示当数据被删除时执行
（4）回调执行时机，表示当数据被编辑时执行
您可以根据需要在对应的时机配置回调服务，下面以“单据提交”为例说明配置过程：

配置过程大体分为如下几个步骤：
（1）点击【单据提交】下方的输入框，进入服务选择页面。
（2）点击“第三方服务”后方的下拉框，选择已经在宜搭注册的服务，可参考文档《（高级）服务注册》。
（3）选择需要调用的服务，系统为会为您列出该服务所需要的参数。
（4）参数赋值，参数值可以为常量，也可以是宜搭支持的表单变量，变量格式为：#{变量id}，您可以支持输入“#”号，系统会为您列出所有表单变量，选择某一字段后，服务调用时系统会将变量替换为字段值后传递给目标服务。
（5）点击【确定】完成回调服务的添加。

服务的编辑和添加过程类似，不再赘述。

返回格式要求：http的是 {“success”:true}，hsf的是 {“success”:true,”content”:true}

• 作为表单校验时, success为true，表示数据合法可以成功提交。success为false，阻断提交。
• 作为服务回调时，success为true，表示调用成功

3.2 流程节点服务取人

在宜搭流程的【服务】节点中，您可以使用第三方服务动态获取该审批节点的审批人。

注意

• 取人格式必须如下

  [
  "工号1",
  "工号2"
  ]

• 假如是阿里内部使用，工号不足6位，记得前面补0.

• 假如服务想返回空，直接返回null

特别注意：
在使用这一功能时，如果需要取表单中的某个组件的值，需要采用的占位符格式为：#表单组件的id ，例如：

下面的流程中一级审批人是某个具体的个人，二级什么人需要根据表单中的参数值去动态获取：

那么，无论是Http还是HSF的服务调用，这里取表单变量的占位符格式为#表单变量的id，下面的示例是直接配置了一个人员搜索框组件的值作为参数。

如果回调接口为HTTP接口，接口的编写要求如下：

• HTTP Method为POST
• 请求参数放在@RequestBody 里

下面给出一个使用Java编写的简单的示例回调接口：

@RequestMapping(value = "/callback",method = RequestMethod.POST)
@ResponseBody
public List<String> callback(@RequestBody CallbackParam callbackParam) {
  // 返回值格式：["工号1","工号2"]，如果返回空，直接返回null
  List<String> result = new ArrayList<>();
  // do something
  return result;
}

3.3 流程节点配置业务服务校验/回调

分两种场景：

• 校验规则: 流程发起/审批时，会调业务服务接口，根据返回的结果，判断是否能发起流程/审批.该场景是同步调用，会阻断数据提交
• 关联操作: 在节点审批后，或者流程结束后，回调业务系统。这种场景是通知业务用，采用异步调用，不阻断流程。

返回格式必须是:
http的是 {“success”:true}，hsf的是 {“success”:true,”content”:true}

• 作为表单校验时, success为true，表示数据合法可以成功提交。success为false，阻断提交。
• 作为服务回调时，success为true，表示调用成功

3.4 流程数据发起查看权限验证

在流程页面设置的权限设置中，通过【高级】可以添加服务回调，这里的回调和之前的不同，这里不会展示服务参数，宜搭只为服务提供了两个默认参数，分别为

{"success":true,"content":"true"}

3.5 消息通知服务取人

返回格式

{
  "success": true,
  "content": "[\"工号1"\,\"工号2\",\"工号3\"]"
}

四、服务调用支持的变量

4.1 表单支持的系统内置字段

• 表单组件值: 输入#，会默认显示当前表单中的组件。当服务调用时，会自动带上表单中组件的值，赋值给对应的参数。
• 系统内置变量(表单校验是在数据生成前执行，因此表单校验触发的三方回调,”数据创建时间”、”数据实例ID”、”流水号”无效)

注意
第三方服务回调，不同使用场景，对接口返回的格式要求不同。请仔细查看每个场景介绍后面，数据返回格式的说明

4.2 流程支持的系统内置字段

注意：这里的变量只能用于流程节点中需要变量的场景，不能用于其他回调服务中，普通的第三方回调请使用4.1中提供的变量

五、服务回调运维接口

由于宜搭侧的服务回调的运维接口暂时尚未在平台侧透出，因此在本小节以文档的形式给出相关的接口的参数说明以及调用示例。

服务回调的运维能力主要通过暴露如下的两个接口能力

• 服务回调调用记录查询：主要用于新接口配置时的功能调试
• 指定调用记录重试：主要用于失败调用记录的重试

5.1 调用记录查询

该接口主要用于新接口配置时的功能调试。

${yida Domain}/alibaba/web/${appType}/query/invoke/queryRecord.json

参数说明：

下图是使用一个非常流行的HTTP 请求的客户端工具post查询服务回调调用记录的请求示例：

请求返回的内容如下所示：

{
  "errorLevel": "",
  "errorMsg": "",
  "errorCode": "",
  "throwable": "",
  "success": true,
  "content": {
    "totalCount": 4,
    "currentPage": 0,
    "limit": 10,
    "values": [
      {
        "invokeResult": "error message : error on submit request on future invoke:",
        "sourceUuid": "",
        "formUuid": "FORM-5Q566O71FX5ETEQRWETFNAFSU2OX1UV50IU7K0",
        "formInstId": "FINST-FFYJVE4VHX5ETTX6Z68TR0LQ8UWD27AB3IU7K0",
        "hookType": "HSF",
        "invokeStatus": "ERROR",
        "invokeUrl": "com.alibaba.work.tianshu.api.form.FormDataService:1.0.0~getFormDataById",
        "invokeSuccess": "n",
        "invokeParams": "{\"param0\":\"1234567890\"}",
        "hookUuid": "INVOKE-FFYJVE4VHX5ETTX6Z68TR0LQ8UWD2FPB3IU7K1",
        "serviceContent": "{\"interfaceName\":\"com.alibaba.work.tianshu.api.form.FormDataService\",\"version\":\"1.0.0\",\"functionName\":\"getFormDataById\",\"signature\":\"\",\"hmacSecret\":\"\",\"params\":[{\"field\":\"app_type\",\"value\":\"app_type\",\"label\":{\"zh_CN\":\"应用类型\",\"en_US\":\"app type\",\"type\":\"i18n\"},\"type\":\"java.lang.String\"}],\"id\":\"HSF_SV_-5Q566O71EX5E6A0LXH8BS0EH2A2J3MFVYHU7K0\"}",
        "serviceParams": "{\"app_type\":\"1234567890\"}",
        "serviceName": "xxHSF服务",
        "shardKey": "",
        "creator": "11111",
        "systemType": "default_tianshu_system",
        "appType": "APP_C5ZN2YS4E11GCT1Q0JC9",
        "corpId": "",
        "gmtCreate": 1584365132000,
        "modifier": "1111",
        "gmtModified": 1584365132000,
        "groupId": "",
        "isDeleted": "n",
        "id": 4,
        "namespace": ""
      },
      {
        "invokeResult": "61\nerror message : [HSF-Provider-11.10.180.111] Error log: [HSF-Provider] execute [com.alibaba.work.tianshu.api.form.FormDataService:1.0.0#getFormDataById_java.lang.String] got NoSuchMethodException, clientIp: 11.10.180.111",
        "sourceUuid": "",
        "formUuid": "FORM-5Q566O71FX5ETEQRWETFNAFSU2OX1UV50IU7K0",
        "formInstId": "FINST-5Q566O71FX5EG3VT2DBW37BIP5KG34K01IU7K0",
        "hookType": "HSF",
        "invokeStatus": "ERROR",
        "invokeUrl": "com.alibaba.work.tianshu.api.form.FormDataService:1.0.0~getFormDataById",
        "invokeSuccess": "n",
        "invokeParams": "{\"param0\":\"12345678\"}",
        "hookUuid": "INVOKE-5Q566O71FX5EG3VT2DBW37BIP5KG38311IU7K1",
        "serviceContent": "{\"interfaceName\":\"com.alibaba.work.tianshu.api.form.FormDataService\",\"version\":\"1.0.0\",\"functionName\":\"getFormDataById\",\"signature\":\"\",\"hmacSecret\":\"\",\"params\":[{\"field\":\"app_type\",\"value\":\"app_type\",\"label\":{\"zh_CN\":\"应用类型\",\"en_US\":\"app type\",\"type\":\"i18n\"},\"type\":\"java.lang.String\"}],\"id\":\"HSF_SV_-5Q566O71EX5E6A0LXH8BS0EH2A2J3MFVYHU7K0\"}",
        "serviceParams": "{\"app_type\":\"12345678\"}",
        "serviceName": "xxxHSF服务",
        "shardKey": "",
        "creator": "11111",
        "systemType": "default_tianshu_system",
        "appType": "APP_C5ZN2YS4E11GCT1Q0JC9",
        "corpId": "",
        "gmtCreate": 1584365025000,
        "modifier": "1111",
        "gmtModified": 1584365025000,
        "groupId": "",
        "isDeleted": "n",
        "id": 3,
        "namespace": ""
      },
      {
        "invokeResult": "response status is 302",
        "sourceUuid": "INVOKE-5Q566O71WQ5E6HII22N3760OT21U29TVU8U7K1",
        "formUuid": "FORM-5Q566O71VQ5ENW7Q2IKVAC6AQPVZ2U0IT8U7K0",
        "formInstId": "FINST-5Q566O71WQ5E6HII22N3760OT21U28IVU8U7K0",
        "hookType": "HTTP",
        "invokeStatus": "ERROR",
        "invokeUrl": "http://www.baidu.com/s",
        "invokeSuccess": "n",
        "invokeParams": "{\"wd\":\"xx\"}",
        "hookUuid": "INVOKE-5Q566O71YQ5EDO8L2SKJO8ZYHDRQ3X0PX8U7K0",
        "serviceContent": "{\"url\":\"http://www.baidu.com/s\",\"isMd5\":null,\"signature\":\"\",\"isSHA\":null,\"hmacSecret\":\"\",\"type\":\"HttpExt\",\"params\":[{\"field\":\"wd\",\"value\":\"wd\",\"label\":{\"zh_CN\":\"单词\",\"en_US\":\"word\",\"type\":\"i18n\"},\"type\":\"java.lang.String\"}]}",
        "serviceParams": "{\"wd\":\"xx\"}",
        "serviceName": "xxHTTP服务",
        "shardKey": "",
        "creator": "11111",
        "systemType": "default_tianshu_system",
        "appType": "APP_C5ZN2YS4E11GCT1Q0JC9",
        "corpId": "",
        "gmtCreate": 1584349753000,
        "modifier": "1111",
        "gmtModified": 1584349753000,
        "groupId": "",
        "isDeleted": "n",
        "id": 2,
        "namespace": ""
      },
      {
        "invokeResult": "response status is 302",
        "sourceUuid": "",
        "formUuid": "FORM-5Q566O71VQ5ENW7Q2IKVAC6AQPVZ2U0IT8U7K0",
        "formInstId": "FINST-5Q566O71WQ5E6HII22N3760OT21U28IVU8U7K0",
        "hookType": "HTTP",
        "invokeStatus": "ERROR",
        "invokeUrl": "http://www.baidu.com/s",
        "invokeSuccess": "n",
        "invokeParams": "{\"wd\":\"xx\"}",
        "hookUuid": "INVOKE-5Q566O71WQ5E6HII22N3760OT21U29TVU8U7K1",
        "serviceContent": "{\"url\":\"http://www.baidu.com/s\",\"isMd5\":null,\"signature\":\"\",\"isSHA\":null,\"hmacSecret\":\"\",\"type\":\"HttpExt\",\"params\":[{\"field\":\"wd\",\"value\":\"wd\",\"label\":{\"zh_CN\":\"单词\",\"en_US\":\"word\",\"type\":\"i18n\"},\"type\":\"java.lang.String\"}]}",
        "serviceParams": "{\"wd\":\"xxx\"}",
        "serviceName": "xx HTTP服务",
        "shardKey": "",
        "creator": "1111",
        "systemType": "default_tianshu_system",
        "appType": "APP_C5ZN2YS4E11GCT1Q0JC9",
        "corpId": "",
        "gmtCreate": 1584349621000,
        "modifier": "1111",
        "gmtModified": 1584349621000,
        "groupId": "",
        "isDeleted": "n",
        "id": 1,
        "namespace": ""
      }
    ],
    "start": 0
  }
}

5.2 调用重试

该接口主要用于对于接口失败调用记录的重试，主要用于错误补偿机制。

${yida domain}/alibaba/web/${appType}/query/invoke/retryInvoke.json

参数说明：

TODO：待补充调用结果示例

5.3 其他说明

注意: 流程上配置的服务节点和自动节点不支持查询

目前支持服务回调查询与重试两种接口。
注意：该接口只有应用管理员或者数据管理员有权限调用。

5.4 实践案例

某一次调用记录如下，可以根据invokeStatus字段发现这次服务回调调用失败了，失败的具体原因可以看invokeResult字段，内容为：“jsgl.zjdyit.com: Name or service not konwn”，标识的含义是在宜搭部署的服务器上解析用户部署服务的域名jsgl.zjdyit.com失败了，可能的原因有很多，例如：

• jsgl.zjdyit.com 不存在
• jsgl.zjdyit.com DNS 没有扩展到全网

具体原因需要联系网络管理员进行确认后修复。