跳到主要内容

服务回调

能力

免费版

轻享版

专业版

专属版

自定义服务校验

不支持

不支持

支持

支持

未升级到新版信息架构的组织,请 点此查看 使用手册

1. 概念说明

在宜搭中,凡是涉及到接口服务调用的均称为第三方服务回调,通过对服务调用的支持,使宜搭可以和外部系统进行集成,数据互相流转,避免宜搭应用成为信息孤岛


特别说明

在正式使用之前需要确保已经针对所需接口完成了服务注册,如果还没有,请参考 服务注册 进行相关的配置

2. 常见使用场景

服务回调的使用场景目前多集中于表单服务回调和审批节点的服务回调,不同场景场景下的服务回调使用方式大致相同,下面就不同场景下的配置和使用分别予以介绍

2.1 表单服务校验/服务执行

主要可用于表单使用过程中的可能使用到服务回调的场景,从使用方式上来说可以细分为服务校验和服务执行


  • 服务校验: 用于在表单提交时,调用业务服务接口校验数据的合法性,主要用于从业务侧判断用户提交参数的合法性,例如判断持有某个手机号的用户在本市主城区范围内是否拥有第二套住房,同步调用
  • 服务执行: 用于在表单提交/编辑/删除成功后,执行第三方服务调用,主要用于实时同步用户提交的数据到第三方,多用于二次处理或者数据归档的场景,异步调用


路径:表单 >> 编辑表单

表单页面

在表单的设计器中,点击页面空白处,可以展示服务回调的配置面板,根据需求可以不同的配置入口

  • 如果需要使用第三方服务校验,则选择 表单校验 >> 服务校验 >> 添加服务 进行下一步的配置
  • 如果需要使用第三方服务执行,则选择 表单事件 >> 服务执行 >> 添加服务 进行下一步的配置

表单编辑页面

这里我们选择【表单校验】下的【添加服务】按钮,此时会弹出服务校验的对话框,背景会虚化:

  • 位置1 是服务标题,默认名称为【函数计算】,可以自定义修改;
  • 位置 2、位置 3 和位置 4 为服务回调的触发时机,目前宜搭提供了三个可以触发服务调用的时机:分别是表单提交、表单删除和表单编辑,用户可以根据自己的实际需要选择,可以同时配置一个或者多个。
  • 位置 5 如果勾选,则表示当满足服务回调的接口时(即接口返回为 false)阻断用户的表单数据的提交;如果不勾选,则无论服务回调的接口返回的内容是什么,都不会阻断用户的表单数据的提交;如果不满足服务回调的结果时(即接口返回 true ),则用户可以正常提交表单,不会阻断。
  • 位置 6 表示校验错误提示,只有当接口返回为 false 的时候,才会将该错误提示反馈给用户。

添加服务

接口返回格式示例:

{
"success":true
}

参数含义说明:

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


下面以一个实际的案例介绍完整的配置过程:

(1)您可以为即将添加的回调服务设置一个标题

(2)回调执行时机,表示当有数据提交时执行

(3)回调执行时机,表示当数据被删除时执行

(4)回调执行时机,表示当数据被编辑时执行

您可以根据需要在对应的时机配置回调服务,下面以“表单提交”为例说明配置过程:


配置过程大体分为如下几个步骤:

(1)点击【表单提交】下方的输入框,进入服务选择页面。

(2)点击「第三方服务」后方的下拉框,选择已经在宜搭注册的服务。

(3)选择需要调用的服务,系统为会为您列出该服务所需要的参数。

(4)参数赋值,参数值可以为常量,也可以是宜搭支持的表单变量,变量格式为:#{变量id},您可以支持输入#号,系统会为您列出所有表单变量,选择某一字段后,服务调用时系统会将变量替换为字段值后传递给目标服务。

(5)点击【确定】完成回调服务的添加。

2.2 流程服务校验/服务执行

分两种场景:

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

2.2.1 普通流程设计器

路径:普通流程 >> 编辑流程表单旁倒三角符号 >> 流程设计 >> 全局设置 >> 节点提交规则设置

流程表单

节点提交规则

在节点提交规则面板中点击新建按钮,进入新的节点提交规则的详细配置页面:

  1. 规则名称:可以自定义节点提交规则的名称。
  2. 节点类型:支持开始、结束和审批节点。其中开始和结束是指整个流程的开始和结束,如果需要针对流程中的审批节点进行配置,可以将节点类型选择为审批节点。


如果节点类型选择为审批节点,下方将联动展示出当前流程中的所有审批节点供选择,可以通过勾选的方式选择其中的一个或者多个审批节点

下面两张图分别展示了流程节点的配置以及新建节点提交规则选择节点类型为审批节点时的示意图:

  1. 规则类型:支持校验规则和关联操作。
  2. 关联操作点击空白部门的输入框,会弹出目前支持的所有关联操作的内容,下面会详细介绍。

如果规则类型选择的内容为校验规则,那么在规则配置方式中选择第三方服务时,可以进行接口入参与宜搭系统变量及表单变量之间的关联。此外,还可以额外配置校验不通过时是否阻断用户提交,以及阻断提交的自定义的提示文案,配置面板如下:


如果规则类型选择的内容为关联操作,那么在规则配置方式中选择第三方服务时,可以进行接口入参与宜搭系统变量及表单变量之间的关联,配置面板如下:

下面是一个在普通流程节点上配置第三方服务回调进行关联操作的完整的配置示例:

2.2.2 高级流程设计器专业版及以上专享


点击节点提交规则的设置按钮,弹出节点提交规则的详细配置面板:

  1. 规则名称:可以为当前规则设置一个自定义的规则名称。
  2. 规则类型:可以选择校验规则和关联操作,这里的校验规则主要用于指定表单内容的校验,而关联操作主要用于动作触发之后执行下一步的动作。
  3. 触发方式:当前支持在任务完成后执行以及节点完成后执行。由于一个节点可以设置多个审批人,每个节点上的审批人会触发一个审批任务,因此可以选择针对每个审批人的审批任务完成后进行动作触发或者针对节点上所有审批人完成审批任务后触发。
  4. 节点动作:可以细化审批动作的内容,目前支持的审批动作包括同意、角色、保存以及退回,支持多选。
  5. 关联操作:点击空白部门的输入框,会弹出目前支持的所有关联操作的内容,下面会详细介绍。
  6. 保存:当前规则编辑完成之后,可以单击保存按钮,可用于保存单条规则。
  7. 新增规则:针对同一个审批节点,点击新增规则按钮,可以设置多条规则

下面我们再针对校验规则和关联操作选项下的第三方服务回调的配置进行详细的介绍:


如果规则类型选择的内容为校验规则,那么在规则配置方式中选择第三方服务时,可以进行接口入参与宜搭系统变量及表单变量之间的关联。此外,还可以额外配置校验不通过时是否阻断用户提交,以及阻断提交的自定义的提示文案,配置面板如下:


如果规则类型选择的内容为关联操作,那么在规则配置方式中选择第三方服务时,可以进行接口入参与宜搭系统变量及表单变量之间的关联,配置面板如下:


接口返回格式示例:

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


参数含义说明:

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

2.3 流程节点动态获取审批人

宜搭侧的流程节点的审批人目前已经支持通过多种方式进行配置,包括角色、接口人、指定审批人、表单人员变量等,如果上述方式仍然无法满足对于审批人审批的要求,那么可以通过宜搭侧提供的流程节点动态获取审批人的方式,通过调用客户侧提供的服务接口,来动态的获取流程所需的审批人。并且由于流程在执行过程中,中间的审批人可以修改表单内变量的值,后续的节点可以根据更正后的表单数据动态的获取流程审批人,来满足一些动态的、复杂的业务场景的需求。


由于普通流程和高级流程专业版及以上专享配置的入口和配置的方式不完全一致,因此本小结将分别针对普通流程设计器和高级流程设计器分别进行介绍。

2.3.1 普通流程设计器

路径:普通流程 >> 编辑流程表单旁倒三角符号 >>流程设计 >> 选择一个审批节点


点击 添加审批节点 按钮,节点类型选择为服务,点击确定按钮后退出,之后点击审批人按钮右上角的铅笔图标详细编辑该节点。在弹出的设置窗口中,找到第三方服务,点击选择服务内容按钮,在弹出的第三方服务配置窗口中完成表单变量与具有注册服务之间的绑定,全部配置完成之后点击页面右上角的保存并发布按钮。


下面通过一个动态图进行一次完整配置的演示:

特别说明:

在使用这一功能时,如果需要取表单中的某个组件的值,需要采用的占位符格式为:#表单组件的 id  ,宜搭前端默认提示的 #{表单组件的 id} 需要手动修改为表单组件的 id

流程内置参数的说明请参考本章的服务调用支持的变量的第 2 点

2.3.2 高级流程设计器专业版及以上专享

路径:流程表单 >> 编辑流程表单旁边倒三角符号 >> 流程设计

从左侧的节点中选择人工节点拖入到设计图中,与既有节点完成连接,点击该人工节点,可以选择性的修改节点名称,之后点击审批人规则后的小螺丝按钮进行审批人的具体设置。

具体的设置选项介绍如下:

  1. 规则类型:通过下拉选择的方式选择其他规则
  2. 类型:选择第三方服务
  3. 选择服务:下拉或者搜索选择已经注册的服务
  4. 参数配置:参数名称为服务注册时定义的接口入参,参数值可以选择系统变量(例如:发起人、表单UUID等,具体参考2.1小节)或者表单变量(表单内的自定义的控件),通过下拉选择的方式完成接口入参变量与宜搭侧提供的变量(包括系统变量与表单变量)之间的绑定
  5. 配置完成后点击保存按钮

2.4 接口格式要求

2.4.1 接口入参格式要求

如果回调接口为 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;
}

2.4.2 接口返回值格式要求:

示例1:成功调用的接口返回值示例:

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


示例2:没有符合条件的审批人

null

2.5 流程发起/查看权限动态验证

该使用场景主要针对宜搭平台侧提供的提供的静态的权限组人员配置(包括:部门、个人、角色)都无法满足,但是企业服务中可以提供相关的根据人员 id 判断指定流程是否有用发起和查询权限接口,以便将宜搭的流程权限配置以企业既有的统一权限系统进行打通,那么就可以使用该方式完成消流程实例的发起人以及流程实例查看人的动态配置。

路径:普通流程 >> 设置 >> 权限设置 >> 实例发起人/实例查看人 >> 高级 >> 服务配置 (功能即将下线)


详细的配置过程可以参考下面的动态图:

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


参数名

字段类型

参数说明

formUuid

String

表单ID

loginUserId

String

当前登录人工号


对于所使用到的接口返回值至少包含 success 和 content 两个字段,详细的接口返回参数格式要求如下:

参数名

字段类型

参数说明

是否必填

备注

success

Boolean

接口调用成功与否。

可选值:

  • true:接口调用成功
  • false:接口调用失败

content

String

描述信息


接口返回值示例:

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

2.6 消息通知服务动态选择接收人

该使用场景主要针对宜搭平台侧提供的既有人员通知类型(包括:按参与人通知、按角色通知、按指定人员通知、按表单页面内的人员变量通知、指定邮箱、指定钉钉群)都无法满足时,但是企业服务中可以提供相关的人员查询接口,那么就可以使用该方式完成消息通知服务动态选择接收人的配置。详细的配置说明如下:


路径:编辑表单/普通流程旁倒三角符号 >> 页面设置 >> 消息通知 >> 新建通知

新建消息通知

触发条件可以根据自己的业务场景进行选择,通知人员类型勾选 通过第三方服务,点击选择服务内容按钮,在弹窗中完成表单参数与既有服务注册接口的绑定,完成绑定之后再选择关联的消息通知模板,最后选择确定按钮,即可完成全部设置

设置第三方服务通知


对于所使用到的接口返回值至少包含 success 和 content 两个字段,详细的接口返回参数格式要求如下:

参数名

字段类型

参数说明

是否必填

备注

success

Boolean

接口调用成功与否。

可选值:

  • true:接口调用成功
  • false:接口调用失败

content

Array

人员工号列表

可选值:

  • 如果存在合适的人员,请以数组的形式返回,例如:"["人员工号1","人员工号2"]"
  • 如果不存在合适的人员列表,请返回null

接口返回结果示例:

{
"success": true,
"content": "["123","456","789"]"
}

3. 服务调用支持的变量

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

通用格式为:#{变量名}

特别注意:该占位符格式适用于所有除了流程节点动态获取审批人之外的使用场景

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

名称

变量

当前用户的工号

#{LOGINUSER}

数据创建人工号

#{creator}

数据创建时间

#{createTime}

数据实例ID

#{formInstId}

表单ID

#{formUuid}

流水号专业版及以上专享

#{serialNo}

3.2 动态获取审批人支持的系统内置字段(审批里用以下的变量)

通用格式为 #变量名


特别注意:该占位符格式仅适用于动态获取审批人这一种使用场景


名称

变量

发起人工号,json数组格式

#originator

数据实例ID,等于上面的formInstId

#procInstId

实例标题中文

#procInstTitle

实例标题英文

#procInstTitleEn

流程编码

#processCode


4. 服务注册运维平台

为了便于开发者们了解服务回调成功与否的结果,目前我们提供了两个运维接口:

  • 查询服务调用记录
  • 重试失败的服务回调


特别说明:

  1. 该接口只有应用管理员或者数据管理员有权限调用,调用时需要登录态
  2. 动态服务取人的使用场景暂不支持调用记录的查询

4.1 接口一:查询服务调用记录

服务调用目前只存30天的记录

https://www.aliwork.com/alibaba/web/${appType}/query/invoke/queryRecord.json?pageNo=1&pageSize=10

参数名

是否必填

参数说明

备注

formUuid

指定表单 ID

例如. FORM-FFYJQU6VD6LL265B0ZDMN5IT2VOP32EV8W9IK2

hookType

请求的类别

可选值:HTTP、GATEWAY

requestUrl

请求地址

来自于服务注册页面填写的请求地址

pageNo

指定页数,

从1 开始,默认1

pageSize

指定每页数量,

default value:  10

instId

限定实例 ID


hookUuid

限定单次调用


sourceUuid

限定原始调用 ID,意味着查到的都是某次调用重试执行


isSuccess

限定成功或者失败的结果


invokeFrom

查询的开始时间

eg. 2020-05-25 00:00:00

invokeTo

查询的结束时间

eg. 2020-05-25 23:59:59


接口返回内容字段说明:

参数名

是否必填

参数说明

备注

invokeResult

调用的错误描述信息


hookType

调用的类型

可选值:

  • HTTP
  • GATEWAY

invokeStatus

调用的结果

可选值:

  • SUCCESS
  • ERROR

invokeUrl

请求的第三方服务的地址

例如:https://www.aliwork.com/test

invokeParams

宜搭侧调用第三方服务时实际调用所传递的参数

例如:{"param0":"1234567890"}

hookUuid

某一次服务回调的唯一标识,可用于接口二的重试功能

例如:INVOKE-FFYJVE4VHX5ETTX6Z68TR0LQ8UWD2FPB3IU7K1

下面是一次成功调用结果的返回示例:

{
"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
}
}

4.2 接口二:重试失败的服务回调

https://www.aliwork.com/alibaba/web/${appType}/query/invoke/retryInvoke.json?hookUuid=INVOKE-FFYJVE4VHX5ETTX6Z68TR0LQ8UWD2FPB3IU7K1

参数名

是否必填

参数说明

备注

appType

应用的唯一表示

例如:APP_C6DTYDDXIKDDHVM7ID4Y

hookUuid

接口一中查询获取得到的 hookUuid

例如:INVOKE-FFYJVE4VHX5ETTX6Z68TR0LQ8UWD2FPB3IU7K1

4.3 服务注册运维平台

上述接口已经通过应用模板的形式提供:

宜搭服务注册运维平台

更多详细的关于该运维应用的使用说明可以参考模板应用的操作手册

5. 常见问题

5.1 实例修改未触发服务回调

若同一事件下绑定多个服务,其中一个服务报错,会影响后续服务调用。

5.2 调用服务注册修改三方系统数据时,出现超时?

宜搭侧服务回调有两种时长限制:

  • ReadTimeout 指的是建立连接后从服务器读取到可用资源所用的时间,时长限制为3秒。
  • ConnectTimeout 指的是建立连接所用的时间,适用于网络状况正常的情况下,两端连接所用的时间,时长限制为3秒。


--------------------欢迎关注我们--------------------


Copyright © 2024钉钉(中国)信息技术有限公司和/或其关联公司浙ICP备18037475号-4