跳到主要内容

宜搭平台接口(页面数据源可直接调用)

能力

免费版

轻享版

专业版

专属版

宜搭页面数据源

不支持

不支持

支持

支持

1. 调用说明

1.1 接口地址拼接规则

目前支持应用维度接口,在应用内(支持跨应用)通过以下方式即可访问对应接口,接口访问格式为:

${宜搭域名}/dingtalk/web/${应用编码} + 接口路径。


比如在浏览器端想调用应用编码为 APP_X1X2X3X4 的「流程实例-流程发起」服务接口,则在数据面板里调用请求地址为(使用相对路径即可):

/dingtalk/web/APP_X1X2X3X4/v1/process/startInstance.json

请参考【二、流程实例】下面的【1. 流程发起】里面有详细的实战演示案例


注意,目前版本的 searchFieldJsondynamicOrder 字段需要的是一个字符串类型的值。比如:

const someJson = {
"textField_kkm9o5cd":"123"
}

// 如果直接把 someJson 传给 searchFieldJson 是不会有效果的。我们需要通过 JSON.stringify 方法,把这个对象转成字符串形式。
const fieldJson = JSON.stringify(someJson); // '{"textField_kkm9o5cd":"123"}'

2. 流程实例

2.1 流程发起

  • 接口: /v1/process/startInstance.json 
  • 请求类型: POST 
  • 参数

参数名

描述

是否必填

示例

备注

processCode

流程code

TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4

单独发起页链接上可查

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3

单独发起页链接上可查

formDataJson

表单数据


类型:String

参考:附录1保存/更新 表单数据格式说明

deptId

发起人所在部门号

18295

不填,默认发起人主职部门


  • 返回值:
    • result  : 实例 ID
    • success  : 请求是否成功
    • errorMsg  : 错误信息
    • errorCode  : 错误码
  • 返回值
{
"result": "f30233fb-72e1-4af4-8cb8-c7e0ea9ee530",
"success": true
}


场景演示:

①. 搭建一个简单的流程页面,点击其中的某个需要自定义填充值的组件,获取其唯一标识备用,例如本例中单行文本框的唯一标识为「textField_kkm9o5cd」。


②. 新建一个高级展示页,拖动一个 Button 按钮到页面中,添加一个数据源

名称填写为一个简单易懂的名称,并且保证在该页面下唯一,请求地址根据业务实际需要填写,本例是希望点击按钮可以发起一条流程,因此这里的请求地址填写为:/alibaba/web/APP_D45S78OXJSL51QTQVHT8/v1/process/startInstance.json,其中APP_D45S78OXJSL51QTQVHT8 为应用唯一标识,需要替换为自己的应用的唯一标识,请求方法注意选择为 POST方式。


③. 为按钮添加一个 onClick 事件,点击 <> 图标前往进行远程数据源与按钮方案绑定的实现:

参考:https://developers.aliwork.com/docs/api/about

编写如下的绑定代码,注意这里我们给表单控件单行文本框(唯一标识:textField_kkm9o5cd)填写的是固定值 123 。

formUuid processCode 参数的获取路径为:【应用设置】-【应用数据】-【XX流程】下面的表单 ID 和流程 Code 。


export function onClick(){
const params = {
"processCode":"TPROC--CFYJ5HYUN89NJ1JW3IXBI7A95RXM3652O9MKK3",
"formUuid": "FORM-CFYJ5HYUN89NJ1JW3IXBI7A95RXM3552O9MKK2",
"formDataJson": '{"textField_kkm9o5cd":"123"}'
}

this.dataSourceMap.myDatasource.load(params).then((response) => {
this.utils.dialog({
method: 'alert', // 或confirm
title: '请求成功',
type: 'success', // PC端支持 info/success/error
content: `返回结果为 ${response}`,
})
})
console.log('onClick');
}


④. 代码编写完成之后点击页面右上角的保存按钮。


⑤. 前往运行态页面进行流程发起的测试,点击按钮,可以通过浏览器自带的调试工具下的 Network 看到startInstance 接口发送成功,接口返回的内容 da5ed25c-977b-40e0-acff-4a1c07aa6f41 为流程实例 id ,唯一标识该流程实例。


⑥. 接下来,我们再次前往对应的流程的数据管理页面,找到了我们新发起的那一条流程,并且单行文本中填写的内容就是我们在程序中填写的固定值 123,全部测试验证完成。


  • 视频展示


2.2 根据条件搜索流程实例 ID

  • 接口: /v1/process/getInstanceIds.json 
  • 请求类型: GET 
  • 权限说明:流程需要配置实例可查看权限(管理员除外)
  • 参数

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


searchFieldJson

根据表单内组件值查询


类型:String
格式见附录2:根据组件值进行条件搜索,组件值格式说明

taskId

任务ID

2199132092

一般用不到。

instanceStatus

实例状态

RUNNING

可选值为:RUNNING,TERMINATED,COMPLETED,ERROR。

分别代表:运行中,已终止,已完成,异常。

approvedResult

流程审批结果

agree

可选值为:agree, disagree。

分别表示:同意, 拒绝。

currentPage

当前页

1

必须大于0

默认1

pageSize

每页记录数

10

必须大于0

默认10

不能大于100

originatorId

根据流程发起人工号查询



createFrom

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

yyyy-MM-DD 

createTo

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。

和createFrom一起,相当于查询在

2018-01-01到2018-01-31之间(包含01和31号)创建的数据。

modifiedFrom

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

modifiedTo

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。 和modifiedFrom一起,相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。


  • 返回值
    • result : 实例 ID 列表;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
{
"result": {
"data": [
"f30233fb-72e1-4af4-8cb8-c7e0ea9ee530",
"bc0950a3-fe1b-459c-b6ba-282be38523ab",
"f540cbd7-43eb-40de-b915-6716578a2802"
],
"totalCount": 3,
"currentPage": 1
},
"success": true
}



2.3 根据搜索条件获取实例详情列表

  • 接口: /v1/process/getInstances.json 
  • 请求类型: GET 
  • 权限说明:流程需要配置实例可查看权限(管理员除外)
  • 参数

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


searchFieldJson

根据表单内组件值查询


类型:String

格式见附录2:根据组件值进行条件搜索,组件值格式说明

taskId

任务ID

2199132092

一般用不到。

instanceStatus

实例状态

RUNNING

可选值为:RUNNING,TERMINATED,COMPLETED,ERROR。

分别代表:运行中,已终止,已完成,异常。

approvedResult

流程审批结果

agree

可选值为:agree, disagree。

分别表示:同意, 拒绝。

currentPage

当前页

1

必须大于0

默认1

pageSize

每页记录数

10

必须大于0

默认10

不能大于100

originatorId

根据流程发起人工号查询



createFrom

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

createTo

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。

和createFrom一起,相当于查询在

2018-01-01到2018-01-31之间(包含01和31号)创建的数据。

modifiedFrom

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

modifiedTo

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。 和modifiedFrom一起,相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。


  • 返回值
    • errorCode : 错误码;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • result :
      • currentPage : 当前页
      • totalCount : 符合条件的实例总数
      • data : 实例详情列表,实例详情格式 参见 附录3-流程实例详情对象格式说明(注意,出于性能考虑,本接口不会返回实例中的子表数据)



2.4 根据实例 ID 获取流程实例详情

  • 接口:/v1/process/getInstanceById.json
  • 请求类型:GET
  • 参数

参数名

描述

是否必填

示例

备注

processInstanceId

流程实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530



  • 返回值
    • result : 实例详情,参见 附录 3- 流程实例详情对象格式说明
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;




2.5 删除流程实例

  • 接口: /v1/process/deleteInstance.json 
  • 请求类型: POST 
  • 参数

参数名

描述

是否必填

示例

备注

processInstanceId

流程实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530



  • 返回值
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;



2.6 终止流程实例

  • 接口: /v1/process/terminateInstance.json 
  • 请求类型: POST 
  • 参数

参数名

描述

是否必填

示例

备注

processInstanceId

流程实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530



  • 返回值
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;



2.7 实例ID批量获取流程实例详情【暂未开放】

  • 接口: /v1/process/getInstancesByIds.json 
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

processInstanceIds

流程实例ID列表,多个用,分割

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530,d230233fb-72e1-4af4-8cb8-c7e0ea9ee530



  • 返回值
    • result : 实例详情列表,参见 附录 3- 流程实例详情对象格式说明
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;



2.8 执行单个任务接口

  • 接口: /v1/task/executeTask.json 
  • 请求类型: POST 
  • 参数

参数名

描述

是否必填

示例

备注

taskId

任务ID

12002575


procInstId

实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530


outResult

审批结果

AGREE

AGREE(同意)、DISAGREE(不同意)

remark

审批意见

确认同意


formDataJson

更新的表单值


参考:附录1保存/更新 表单数据格式说明。

参数有的组件更新,没有的组件保持不变。

明细的值只能统一更新,无法只更新子表单下某个组件的值

noExecuteExpressions

是否不执行校验&关联操作

y

本任务节点有绑定校验规则或者关联操作时,

y -> 不执行校验规则&关联操作

n -> 执行校验规则&关联操作

不传默认为n,即会执行校验规则&关联操作


  • 返回值
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;

2.9 获取审批记录

  • 接口:/v1/process/getOperationRecords.json
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

processInstanceId

流程实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530



  • 返回值
    • result :
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
  • 返回格式
{
"success": true,
"content": [
{
"operateTime": "2018-06-22 14:35:40",
"remark": "",
"taskHoldTime": 0,
"type": "HISTORY",
"operatorName": "宜小搭",
"operator": "yida",
"activityId": "sid-restartevent",
"action": "提交申请",
"actionExt": "submit",
"id": 2846866118,
"operatorPhotoUrl": "/photo/yida.128x128.jpg",
"processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
"showName": "提交申请",
"operateType": "NEW_PROCESS",
"domains": [],
"operatorStatus": "A",
"operatorAgentIds": [],
"size": 1,
"operatorDisplayName": "宜小搭",
"taskId": "null"
},
{
"taskHoldTime": 531398377,
"type": "TODO",
"operatorName": "宜小搭",
"operator": "yida",
"activityId": "sidJIOB2P2J1JW3RPMDOS28",
"taskType": "COMMON_ALL_AT_ONCE",
"actionExt": "doing",
"operatorPhotoUrl": "/photo/yida.128x128.jpg",
"processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
"showName": "执行人",
"activeTime": "2018-06-22 14:35:41",
"domains": [],
"operatorStatus": "A",
"operatorAgentIds": [],
"size": 1,
"operatorDisplayName": "宜小搭",
"taskId": "2846866145"
}
]
}


2.10 流程实例更新


  • 接口: /v1/process/updateInstance.json 
  • 请求类型: POST 
  • 参数


参数名

描述

是否必填

示例

备注

processInstanceId

实例ID



updateFormDataJson

更新的表单数据


参考:附录1保存/更新 表单数据格式说明


  • 返回值:
    • success : 是否成功
    • errorMsg : 错误信息;
    • errorCode : 错误码;
  • 返回值 demo
{
"success":true
}

2.11 获取流程设计节点上的按钮列表[暂未开放]


  • 接口: /v1/process/getActivityButtonVOs.json 
  • 请求类型: GET 
  • 参数


参数名

描述

是否必填

示例

备注

processCode

流程编码

TPROC--X1G***42ZMGA31OYELIWJ1


activityId

节点ID




  • 返回值:
    • success : 是否成功
    • errorMsg : 错误信息;
    • errorCode : 错误码;
  • 返回值 demo:
{
"result": [
{
"aliasEn": "Forward",
"alias": "转交",
},
{
"aliasEn": "Append",
"alias": "加签",
},
{
"aliasEn": "Return",
"alias": "退回",
}
],
"success": true,
"errorCode": null,
"content": null,
"errorMsg": null
}


3. 表单实例

3.1 新增表单实例

  • 接口: /v1/form/saveFormData.json 
  • 请求类型: POST 
  • 参数:

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB


appType

应用ID

APP_DR4OK27ZKL5N22B907E8


formDataJson

表单数据

{"textField_jcpm6agt": "单行","employeeField_jcos0sar": ["workno"]}

类型:String
参考:附录1保存/更新 表单数据格式说明


  • 返回值:
    • success: 请求是否成功
    • result:实例 ID
    • errorMsg: 错误信息
    • errorCode:错误码
  • 返回值 demo:
{
"result":"FINST-EF6Y93URN2UZ1SBPLIP9NAV6HR2GEO1Z4ZCHSCJ0",
"success":true
}


3.2 更新表单中指定组件值

  • 接口: /v1/form/updateFormData.json 
  • 请求类型: POST 
  • 参数:

参数名

描述

是否必填

示例

备注

formInstId

要更新的表单数据ID

FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9


updateFormDataJson

要更新的表单组件值,必填

{"employeeField_jcpm5gy2":

["xxxxx","yyyyy"]}

(以成员组件示例)

类型:String
参考:附录1保存/更新 表单数据格式说明。 参数有的组件更新,没有的组件保持不变。 明细的值只能统一更新,无法只更新子表单下某个组件的值

useLatestVersion

使用最新的表单版本进行更新

y

【特别注意】

默认值为n,建议使用y。


  • 返回值:
    • success: 请求是否成功
    • errorMsg: 错误信息
    • errorCode:错误码
  • 返回值 demo
{
"success":true
}

3.3 删除表单实例

  • 接口: /v1/form/deleteFormData.json 
  • 请求类型: POST 
  • 参数:

参数名

描述

是否必填

示例

备注

formInstId

要删除的表单数据ID

FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9



  • 返回值:
    • success: 请求是否成功
    • errorMsg: 错误信息
    • errorCode:错误码
  • 返回值 demo
{
"success":true
}




3.4 根据表单实例 ID 查询表单实例详情

  • 接口: /v1/form/getFormDataById.json 
  • 请求类型: GET 
  • 参数:

参数名

描述

是否必填

示例

备注

formInstId

要查询的实例的实例ID

FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9



  • 返回值
    • success:请求是否成功
    • errorMsg: 错误信息
    • errorCode:错误码
    • result:表单实例详情。参见附录5. 表单实例详情对象格式说明




3.5 根据条件搜索表单实例 ID 列表

  • 接口: /v1/form/searchFormDataIds.json 
  • 请求类型: GET 
  • 权限控制:该接口会受页面设置的权限控制(管理员除外)。
  • 参数:

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


searchFieldJson

根据表单内组件值查询


类型:String

格式见附录2:根据组件值进行条件搜索,组件值格式说明

currentPage

当前页

1

必须大于0

默认1

pageSize

每页记录数

10

必须大于0

默认10

不能大于100

originatorId

根据数据提交人工号查询



createFrom

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

createTo

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。

和createFrom一起,相当于查询在

2018-01-01到2018-01-31之间(包含01和31号)创建的数据。

modifiedFrom

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

modifiedTo

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。 和modifiedFrom一起,相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。

dynamicOrder

排序

column: '+'

正序 +,倒序 -


  • 返回值
    • success : 请求是否成功;
    • errorCode : 错误码;
    • errorMsg : 错误信息;
    • result :
      • currentPage : 当前页
      • totalCount : 符合条件的实例总数
      • data : 实例 ID 列表
  • 返回值 demo:
{
"result":{
"data":[
"FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0"
],
"totalCount":1,
"currentPage":1
},
"success":true
}


3.6 根据条件搜索表单实例详情列表

  • 接口: /v1/form/searchFormDatas.json 
  • 请求类型: GET 
  • 权限控制:该接口会受页面设置的权限控制(管理员除外)。
  • 参数

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


searchFieldJson

根据表单内组件值查询


类型:String

格式见附录2:根据组件值进行条件搜索,组件值格式说明

currentPage

当前页

1

必须大于0,默认1

pageSize

每页记录数

10

必须大于0

默认10

不能大于100

originatorId

根据数据提交人工号查询



createFrom

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式

(或者精确到秒

yyyy-MM-DD HH:mm:ss)

createTo

createFrom和createTo两个时间构造一个时间段。查询在该时间段创建的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式(或者精确到秒

yyyy-MM-DD HH:mm:ss)

和createFrom一起,相当于查询在

2018-01-01到2018-01-31之间(包含01和31号)创建的数据。

modifiedFrom

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表

2018-01-01

字符串格式,且为yyyy-MM-DD格式(或者精确到秒

yyyy-MM-DD HH:mm:ss)

modifiedTo

modifiedFrom和modifiedTo构成一个时间段,查询在该时间段有修改的数据列表。

2018-02-01

字符串格式,且为yyyy-MM-DD格式。 (或者精确到秒

yyyy-MM-DD HH:mm:ss)和modifiedFrom一起,相当于查询在 2018-01-01到2018-01-31之间(包含01和31号)被修改的数据。

dynamicOrder

指定排序字段

{"numberField_1ac":"+"}

表示按照字段numberField_1ac升序排列


  • 返回值
    • success : 请求是否成功;
    • errorCode : 错误码;
    • errorMsg : 错误信息;
    • result :
      • currentPage : 当前页
      • totalCount : 符合条件的实例总数
      • data : 实例详情列表。每个实例详情格式参见 附录 4 作为返回值的表单数据的格式说明



3.7 获取表单定义

  • 接口: /v1/form/getFormComponentDefinationList.json 
  • 请求类型: GET 
  • 参数:

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB


version

表单版本

1

可以传入formData中的version字段。

为空时返回最新的版本定义


  • 返回值:
    • success: 请求是否成功
    • result:[]
    • errorMsg: 错误信息
    • errorCode:错误码


  • 返回格式
{
"success":true,
"content":[
{
"label":"{"en_US":"CheckBox Field","zh_CN":"多选","type":"i18n"}",
"key":"checkboxField_jiwvhkdi"
},
{
"label":"{"en_US":"Textarea Field","zh_CN":"多行输入框","type":"i18n"}",
"key":"textareaField_jiwvhkdh"
},
{
"label":"{"en_US":"Select Field","zh_CN":"下拉单选","type":"i18n"}",
"key":"selectField_jiwvhkdg"
}
]
}

3.8 获取子表单数据

  • 接口:/v1/form/listTableDataByFormInstIdAndTableId.json 
  • 请求类型:GET
  • 参数

参数名

描述

是否必填

示例

备注

formUuid

表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


formInstanceId

要查询的实例的实例ID

FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9


tableFieldId

需要查找的子表单组件的唯一标识

tableField_ksyaujq1


currentPage

当前页

10

必须大于0,默认1

pageSize

每页记录数

50

大于0并且小于50,默认10


  • 返回值
    • success : 请求是否成功;
    • errorCode : 错误码;
    • errorMsg : 错误信息;
    • result :
      • currentPage : 当前页
      • totalCount : 符合条件的实例总数
      • data : 实例详情列表。每个实例详情格式参见 附录 4 作为返回值的表单数据的格式说明
  • 返回格式
{
"result": {
"data": [
{
"textField_kstqokaa": ""
},
{
"textField_kstqokaa": "1"
},
{
"textField_kstqokaa": "2"
}
],
"totalCount": 120,
"currentPage": 1,
},
"success": true,
}

4. 任务中心

4.1 已提交任务

  • 接口: /v1/process/getMySubmitInApp.json 
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

pageSize

每页记录数

10

必须大于0 默认10 最大值:100

currentPage

当前页

1

必须大于0 默认1

keyword

关键词



  • 返回值:
    • content : 返回内容;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
    • errorLevel : 错误级别;
  • 返回格式


成功:

{
"result": {
"data": [
{
"modifiedTime": "2018-04-12 19:44:14",
"formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
"title": "单据",
"instValue": [
{
"componentId": "node_jfwgghbo",
"componentName": "TextField",
"fieldId": "textField_jfwggg8e",
"label": "姓名",
"validation": [],
"fieldData": {
"complexType": "custom",
"dataType": "CHANGED",
"pass": true,
"value": "jack"
},
"errorMsg": null,
"hasError": false
}
],
"processId": 0,
"appType": "APP_R8MYLKYXXXXXX",
"dataMap": {
"textField_jfXXXXXX": "XXXXXX"
},
"originatorId": "XXXXXX",
"formUuid": "FORM-0G7KPV3WZL0U3AHTOA9BFVXXXXXX",
"dataType": "finst",
"originatorAvatar": "http://static.dingtalk.com/media/lADPBbCc1R7VwSHNXXXXXX.jpg",
"version": 0,
"createTime": "2018-04-12 19:44:14"
}
],
"totalCount": 1,
"currentPage": 1
},
"success": true
}

失败:

{
"errorCode": "TIANSHU_000006",
"success": false,
"errorMsg": "没有权限"
}


Tips:instValue 返回的是字符串,内容格式是 Json 数组


示例请求代码:

 @Test
public void postYidaOutTaskTest() {
String api = "/yida_vpc/process/getMySubmmitInCorp.json";
String corpId = "ding5d17e3add038d44535c2f4657eb63711";
String userId = "141940523222800011";
String corpCode = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";

PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
postClient.addParameter("page", "1");
postClient.addParameter("limit", "10");
postClient.addParameter("corpId", corpId);
// postClient.addParameter("appTypes", "["APP_I3D2FD2ZQB75KLLKL48Y"]");
postClient.addParameter("userId", userId);
String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpCode).getBytes()).toUpperCase();
postClient.addParameter("token", token);

String apiResult = postClient.post();
Assert.notNull(apiResult);
}




4.2 待办任务

  • 接口: /v1/task/getTodoTasksInApp.json 
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

pageSize

每页记录数

10

必须大于0 默认10 最大值:100

currentPage

当前页

1

必须大于0 默认1

keyword

关键词




  • 返回值:
    • content : 返回内容;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
    • errorLevel : 错误级别;
  • 返回格式

成功:

{
"result": {
"data": [
{
"processInstanceId": "XXXXXX",
"originatorName": "XXX",
"title": "XXX发起的流程",
"originatorPhoto": "http://static.dingtalk.com/media/lADPdfafafsAXXXXXX.jpg",
"titleEn": "XXX发起的流程",
"createTime": "2018-04-13 13:35:58",
"appType": "APP_R8MdfadfXXXXXX",
"originatorNameEn": "XXXXXX",
"originatorId": "XXXXXX",
"taskId": "XXXXXX",
"status": "NEW"
}
],
"totalCount": 1,
"currentPage": 1
},
"success": true
}

失败:

{
"errorCode": "TIANSHU_000006",
"success": false,
"errorMsg": "没有权限"
}



示例请求代码:

 @Test
public void postYidaOutTaskTest() {
String api = "/yida_vpc/process/getTodoTasksInCorp.json";
String corpId = "ding5d17e3add038d44535c2f4657eb63711";
String userId = "141940523222800011";
String corpCode = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";

PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
postClient.addParameter("page", "1");
postClient.addParameter("limit", "10");
postClient.addParameter("corpId", corpId);
// postClient.addParameter("appTypes", "["APP_I3D2FD2ZQB75KLLKL48Y"]");
postClient.addParameter("userId", userId);
String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpCode).getBytes()).toUpperCase();
postClient.addParameter("token", token);

String apiResult = postClient.post();
Assert.notNull(apiResult);
}




4.3 已完成任务

  • 接口: /v1/task/getDoneTasksInApp.json 
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

pageSize

每页记录数

10

必须大于0 默认10 最大值:100

currentPage

当前页

1

必须大于0 默认1

keyword

关键词




  • 返回值:
    • content : 返回内容;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
    • errorLevel : 错误级别;
  • 返回格式


成功:

{
"result": {
"data": [
{
"processInstanceId": "abc434rfds23XXXXXX",
"finishTime": "2018-03-28 17:46:14",
"originatorName": "",
"title": "XXX发起的流程页面",
"originatorPhoto": "//img.alicdn.com/tfs/TB1msdfsXXXXXX.jpg",
"titleEn": "XXX发起的流程页面",
"createTime": "2018-03-28 17:45:43",
"appType": "XXXXXX",
"originatorNameEn": "XXXXXX",
"originatorId": "XXXXXX",
"taskId": "XXXXXX",
"status": "COMPLETED"
}
],
"totalCount": 1,
"currentPage": 1
},
"success": true
}

失败:

{
"errorCode": "TIANSHU_000006",
"success": false,
"errorMsg": "没有权限"
}


示例请求代码:

 @Test
public void postYidaOutTaskTest() {
String api = "/yida_vpc/process/getDoneTasksInCorp.json";
String corpId = "ding5d17e3add038d44535c2f4657eb63711";
String userId = "141940523222800011";
String corpCode = "AJ1L4CJVOL0UUQPTQWX8YOTCCS7O1T4CSNJF11";

PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
postClient.addParameter("page", "1");
postClient.addParameter("limit", "10");
postClient.addParameter("corpId", corpId);
// postClient.addParameter("appTypes", "["APP_I3D2FD2ZQB75KLLKL48Y"]");
postClient.addParameter("userId", userId);
String token = DigestUtils.md5DigestAsHex(String.format("%s%s%s", corpId, userId, corpCode).getBytes()).toUpperCase();
postClient.addParameter("token", token);

String apiResult = postClient.post();
Assert.notNull(apiResult);
}





4.4 抄送我的任务(应用纬度)

  • 接口: /v1/task/getNotifyMeTasksInApp.json 
  • 请求类型: GET 
  • 参数

参数名

描述

是否必填

示例

备注

pageSize

每页记录数

10

必须大于0 默认10 最大值:100

currentPage

当前页

1

必须大于0 默认1

keyword

关键词



processCodes

流程code列表

["xx","xxx"]


instanceStatus

实例状态


枚举值


  • 返回值:
    • content : 返回内容;
    • success : 请求是否成功;
    • errorMsg : 错误信息;
    • errorCode : 错误码;
    • errorLevel : 错误级别;
  • 返回格式


成功:

{
"result": {
"data": [
{
"modifiedTime": "2018-04-12 19:44:14",
"formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
"title": "单据",
"instValue": [
{
"componentId": "node_jfwgghbo",
"componentName": "TextField",
"fieldId": "textField_jfwggg8e",
"label": "姓名",
"validation": [],
"fieldData": {
"complexType": "custom",
"dataType": "CHANGED",
"pass": true,
"value": "jack"
},
"errorMsg": null,
"hasError": false
}
],
"processId": 0,
"appType": "APP_R8MYLKYXXXXXX",
"dataMap": {
"textField_jfXXXXXX": "XXXXXX"
},
"originatorId": "XXXXXX",
"formUuid": "FORM-0G7KPV3WZL0U3AHTOA9BFVXXXXXX",
"dataType": "finst",
"originatorAvatar": "http://static.dingtalk.com/media/lADPBbCc1R7VwSHNXXXXXX.jpg",
"version": 0,
"createTime": "2018-04-12 19:44:14"
}
],
"totalCount": 1,
"currentPage": 1
},
"success": true
}

失败:

{
"errorCode": "TIANSHU_000006",
"success": false,
"errorMsg": "没有权限"
}
  • Tips:instValue 返回的是字符串,内容格式是 json 数组


5. 附录

5.1 保存/更新 表单数据格式说明

  • 表单中每个组件都有唯一 ID (在页面设计器组件右侧的高级面板可以查看唯一标识),每个组件中填写的数据都有自己的固定格式。目前支持的表单组件有:单行,多行,数字,单选,下拉单选,多选,下拉多选,日期,日期区间,人员搜索框,地区选择,部门选择,级联选择,子表单组件。
  • 保存/更新 表单数据时,用 Map<String, Object> 的 JsonString 格式来作为参数传递表单中的数据。key 为组件ID,Object 为组件的值。每个组件的值格式如下:

组件类型

数据格式

demo

备注

单行输入框

字符串

"danhang"


多行输入框

字符串

"duohang"


数字输入框

数字

1


单选

字符串

"选项一"


下拉单选

字符串

"选项一"


多选

字符串数组

["选项一","选项二"]


下拉多选

字符串数组

["选项一","选项二"]


日期组件

时间戳

1516204800000


级联日期

字符串数组

["1514736000000","1517328000000"]。

假如只有结束时间,["","1517328000000"]

第一个为开始时间的时间戳字符串,第二给结束时间的时间戳字符串

人员搜索框

字符串数组

["231344123","231344156"]

["xxx"]里面是userId

城市选择

字符串数组

["110000","110100","110101"]

第一个必须为省份ID,第二个为城市ID,第三个为区ID。

部门选择

字符串数组

["1123456"]

["xxx"]里面是部门id

级联选择

字符串数据

["part","part_b"]

必须按照级联顺序,依次放到数组中

附件组件

 字符串数组

[

   {

     "downloadUrl": "文件下载地址",

     "name": "文件名",

     "previewUrl": "文件预览地址",

     "url": "文件下载地址",

     "ext": "docx"

   }

]


图片组件

字符串数组

[

{

"downloadUrl": "文件下载地址",

"name": "文件名",

"previewUrl": "文件预览地址",

"url": "文件下载地址",

}

]

超链接组件

 字符串数组

[

   {

       "link":"http://www.aliwork.com",

       "text":"宜搭"

   }

]


子表单

JSONARRAY

[{"textField_jcr0069m": "danhang1"},{"textField_jcr0069m": "danhang2"}]

(textField_jcr0069m为子表单下单行的组件ID)

由于子表单下有多条记录,所以用JSONARRAY。由于每条记录都是很多组件的值,因此用JSONObject来存每个组件对应的值

手写签名

字符串

"图片地址"



  • 完整的表单数据格式如下:


{
"textField_jcr0069m": "danhang",
"textareaField_jcr0069n": "duohang",
"numberField_jcr0069o": 1,
"radioField_jcr0069p": "选项一",
"selectField_jcr0069q": "选项一",
"checkboxField_jcr0069r": [
"选项二",
"选项三"
],
"multiSelectField_jcr0069s": [
"选项二",
"选项三"
],
"dateField_jcr0069t": 1516636800000,
"cascadeDate_jcr0069u": [
"1514736000000",
"1517328000000"
],
"employeeField_jcr0069x": [
"xxxxx"
],
"citySelectField_jcr0069y": [
"110000",
"110100",
"110101"
],
"departmentField_jcr0069z": 1123456,
"cascadeSelectField_jcr006a0": [
"part",
"part_b"
],
{
"attachmentField_jna1lvyb": [
{
"downloadUrl": "https://www.aliwork.com/fileHandle?appType=default_tianshu_app&fileName=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt&instId=&type=download",
"name": "test.txt",
"previewUrl": "https://www.aliwork.com/inst/preview?appType=default_tianshu_app&fileName=test.txt&fileSize=4&downloadUrl=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt",
"url": "https://www.aliwork.com/fileHandle?appType=default_tianshu_app&fileName=edd07ca9-1d2e-44b5-98fe-c1e16202f90d.txt&instId=&type=download",
"ext": "txt"
}
]
},
"tableField_jcr006a1": [
{
"cascadeDate_jcr006aa": [
"1514736000000",
"1517328000000"
],
"cascadeSelectField_jcr006ae": [
"product",
"product_a"
],
"checkboxField_jcr006a7": [
"选项一",
"选项二",
"选项三"
],
"citySelectField_jcr006ac": [
"120000",
"120100",
"120102"
],
"dateField_jcr006a9": 1517328000000,
"departmentField_jcr006ad": ["1123456"],
"employeeField_jcr006ab": [
"yyyyy",
"xxxxx"
],
"multiSelectField_jcr006a8": [
"选项一",
"选项二",
"选项三"
],
"numberField_jcr006a4": 2,
"radioField_jcr006a5": "选项二",
"selectField_jcr006a6": "选项三",
"textField_jcr006a2": "子表单下单行",
"textareaField_jcr006a3": "子表单下多行"
}
],
"digitalSignatureField_kt3nh972": "https://tianshu-vpc.oss-cn-shanghai.aliyuncs.com/5e03f863-dd39-4f62-ba9b-497af2c9ad9f.png"
}


5.2 根据组件值进行条件搜索,组件值格式说明

  • 表单中每个组件都有唯一 ID (在页面设计器组件右侧的高级面板可以查看唯一标识),每个组件的搜索格式不一样。目前支持搜索的表单组件有:单行,多行,数字,单选,下拉单选,多选,下拉多选,日期,日期区间,人员搜索框,地区选择,部门选择,级联选择,子表单组件。
  • 搜索时,用 Map<String, Object> 格式来表示每个组件的搜索条件。key 为组件 ID,Object 为组件的搜索值。各个组件的搜索类型和值格式如下

组件类型

数据格式

demo

备注

单行输入框

字符串

"danhang"

模糊搜索

多行输入框

字符串

"duohang"

模糊搜索

数字输入框

字符串数组

["1","10"]

范围搜索。第一个为最小值,第二个为最大值

单选

字符串

"选项二"

精确搜索

下拉单选

字符串

"选项二"

精确搜索

多选

字符串数组

["选项二"]

数组搜索。

搜索值必须是多选值的子集

下拉多选

字符串数组

["选项二"]

数组搜索。 搜索值必须是多选值的子集

日期组件

字符串数组

["1514736000000","1517414399000"]

范围搜索。第一个为日期开始的时间戳,第二个为日期结束的时间戳。

日期区间

数组

[["1514736000000","1517414399000"],["1514736000000","1517414399000"]]

范围搜索。第一个数组是日期区间开始的搜索范围。第二个数组是日期区间结束的搜索范围。

人员搜索框

字符串数组

["xxxxx","yyyyyy"]

精确匹配。值必须完全匹配,工号顺序也需要一致。

城市选择

字符串数组

[500000, 500100, 500104, 500104003]

数组搜索。

搜索值必须是城市值的子集。

另外,有市ID,就必须有省ID。有区ID,就必须有省ID和市ID。

部门选择

数字

1123456

精确匹配

级联选择

字符串数组

["part","part_b"]

数组搜索。和城市选择限制条件一致。

子表单组件

字符串

danhang

模糊搜索。

子表单下的值为一个大text,搜索用模糊搜索。


  • 完整例子


{
"textField_jcr0069m": "danhang",
"textareaField_jcr0069n": "duohang",
"numberField_jcr0069o": [
"1",
"10"
],
"radioField_jcr0069p": "选项一",
"selectField_jcr0069q": "选项一",
"checkboxField_jcr0069r": [
"选项二"
],
"multiSelectField_jcr0069s": [
"选项二",
"选项三"
],
"dateField_jcr0069t": [
1514736000000,
1517414399000
],
"cascadeDate_jcr0069u": [
[
1514736000000,
1517414399000
],
[
1514736000000,
1517414399000
]
],
"employeeField_jcr0069x": [
"xxxxx"
],
"citySelectField_jcr0069y": [
"110000",
"110100",
"110101"
],
"departmentField_jcr0069z": ["1123456"],
"cascadeSelectField_jcr006a0": [
"part",
"part_b"
],
"tableField_jcr006a1": "子表单数据"
}


5.3 流程实例详情对象格式说明

字段

描述

示例

备注

actioners

流程实例当前任务执行人

[

{

"name": {

"en_US": "user_en_name",

"zh_CN": "user_zh_name",

"type": "i18n"

},

"userId": "workno"

}

]


如果流程已完成,没有执行人时,该字段为空

processInstanceId

实例ID

f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

唯一

formUuid

流程表单ID

FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3


processCode

流程Code

TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4


title

实例标题

xxxx 发起的流程

根据你的语言环境,返回对应的标题

instanceStatus

实例状态

RUNNING


approvedResult

流程结束时的审批结论

agree

agree -> 通过

disagree -> 拒绝

originator

发起人信息

[ { "name": { "en_US": "user_en_name", "zh_CN": "user_zh_name", "type": "i18n" }, "userId": "workno" } ]


data

表单数据


参加附录4- 作为返回值的表单数据的格式说明


  • 完整的数据格式 demo


{
"result": {
"data": {
"actioners": [
{
"name": {
"pureEn_US": "xxx",
"en_US": "xxx",
"zh_CN": "xxx",
"type": "i18n"
},
"userId": "xxx"
}
],
"processInstanceId": "f30233fb-72e1-4af4-8cb8-c7e0ea9ee530",
"formUuid": "FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3",
"data": {
"numberField_jcr0069o": 1,
"multiSelectField_jcr0069s": [
"选项三",
"选项二"
],
"textareaField_jcr0069n": "duohang",
"employeeField_jcr0069x": [
"xxxx"
],
"departmentField_jcr0069z": "信息xxx平台",
"cascadeDate_jcr0069u": [
"1514736000000",
"1517328000000"
],
"cascadeSelectField_jcr006a0": [
"part",
"part_b"
],
"tableField_jcr006a1": [
{
"departmentField_jcr006ad": "信息xxx",
"cascadeDate_jcr006aa": [
"1514736000000",
"1517328000000"
],
"selectField_jcr006a6": "选项三",
"citySelectField_jcr006ac": [
"天津",
"天津市",
"河东区"
],
"radioField_jcr006a5": "选项二",
"employeeField_jcr006ab": [
"yyyyy",
"xxxxxx"
],
"dateField_jcr006a9": 1517328000000,
"textField_jcr006a2": "子表单下单行",
"textareaField_jcr006a3": "子表单下多行",
"cascadeSelectField_jcr006ae": [
"product",
"product_a"
],
"numberField_jcr006a4": 2,
"checkboxField_jcr006a7": [
"选项一",
"选项三",
"选项二"
],
"multiSelectField_jcr006a8": [
"选项一",
"选项三",
"选项二"
]
}
],
"selectField_jcr0069q": "选项一",
"citySelectField_jcr0069y": [
"北京",
"北京市",
"东城区"
],
"checkboxField_jcr0069r": [
"选项三",
"选项二"
],
"textField_jcr0069m": "danhang",
"radioField_jcr0069p": "选项一",
"dateField_jcr0069t": 1516636800000
},
"processCode": "TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4",
"originator": {
"name": {
"pureEn_US": "xxx",
"en_US": "xxxx",
"zh_CN": "xxx",
"type": "i18n"
},
"userId": "xxxx"
},
"title": "xxx发起的流程",
"instanceStatus": "RUNNING"
},
"totalCount": 1,
"currentPage": 1
},
"success": true
}


5.4 作为返回值的表单数据的格式说明

作为返回值的表单数据格式和 “附录 1- 保存/更新 表单数据格式说明”基本一致。区别在于:

  • 录入时,地区组件值为["省份 ID ", "市 ID ", "区 ID "]。作为返回值时,是["省名称","城市名称","地区名称"]。
  • 单选,下拉单选,多选,下拉多选是有国际化的。返回值时,会根据传的 language 参数,返回对应的数据值。


5.5 表单实例详情对象格式说明

字段

描述

示例

备注

gmtModified

最后修改时间

2018-01-24 11:22:01


formUuid

表单ID

FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1


formInstId

实例ID

FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0


originator

发起人详情

[{"name": {"en_US": "user_en_name","zh_CN": "user_zh_name","type": "i18n"},"userId": "workno"}]


formData

表单数据详情


参加附录4- 作为返回值的表单数据的格式说明


完整的 demo 如下

{
"result": {
"gmtModified": "2018-01-24 11:22:01",
"formUuid": "FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1",
"formInstId": "FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0",
"formData": {
"numberField_jcr0069o": 1,
"multiSelectField_jcr0069s": [
"选项三",
"选项二"
],
"textareaField_jcr0069n": "duohang",
"employeeField_jcr0069x": [
"xxxx"
],
"departmentField_jcr0069z": "xxxx",
"cascadeDate_jcr0069u": [
"1514736000000",
"1517328000000"
],
"cascadeSelectField_jcr006a0": [
"part",
"part_b"
],
"tableField_jcr006a1": [
{
"departmentField_jcr006ad": "xxxx",
"cascadeDate_jcr006aa": [
"1514736000000",
"1517328000000"
],
"selectField_jcr006a6": "选项三",
"citySelectField_jcr006ac": [
"天津",
"天津市",
"河东区"
],
"radioField_jcr006a5": "选项二",
"employeeField_jcr006ab": [
"xxxxxx",
"yyyyyy"
],
"dateField_jcr006a9": 1517328000000,
"textField_jcr006a2": "子表单下单行",
"textareaField_jcr006a3": "子表单下多行",
"cascadeSelectField_jcr006ae": [
"product",
"product_a"
],
"numberField_jcr006a4": 2,
"checkboxField_jcr006a7": [
"选项一",
"选项三",
"选项二"
],
"multiSelectField_jcr006a8": [
"选项一",
"选项三",
"选项二"
]
}
],
"selectField_jcr0069q": "选项一",
"citySelectField_jcr0069y": [
"北京",
"北京市",
"东城区"
],
"checkboxField_jcr0069r": [
"选项三",
"选项二"
],
"textField_jcr0069m": "danhang",
"radioField_jcr0069p": "选项一",
"dateField_jcr0069t": 1516636800000
},
"originator": {
"name": {
"pureEn_US": "userEnglishName",
"en_US": "userEnglishName",
"zh_CN": "userName",
"type": "i18n"
},
"userId": "xxxx"
}
},
"success": true
}



宜搭为了更好的优化宜搭使用手册内容和质量,占用您3-5分钟时间,辛苦填写一下文档反馈问卷。文档反馈问卷是匿名提交,同时问卷信息仅用于宜搭文档体验反馈收集,感谢您对宜搭的支持!

点此填写调研问卷


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

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