宜搭 Open API (旧)

目前，宜搭已经将 OpenAPI 全部上架到了钉钉开放平台, 但是仍然会保留宜搭OpenAPI调用(旧) （后续会逐步移除epaas宜搭OpenAPI说明文档，注意: 仅仅是移除说明文档）。通过钉钉开放平台调用宜搭 OpenAPI 是更好的选择。

当前文档是 epaas 宜搭 OpenAPI，不再建议通过 epaas 访问宜搭 OpenAPI。

通过钉钉开放平台调用宜搭 OpenAPI 请参考宜搭Open API开放接口

手把手教程：

宜搭调用外部接口后将数据回传到宜搭中

1. 准备工作

第一步：申请秘钥授权

目前宜搭已接入钉钉开放平台，优先走钉钉开放平台接口，无需申请秘钥授权。如因钉钉平台无法调用或其他特别原因，可以钉钉联系技术支持-康健（钉钉号：kangjianoops）给予帮助和指引。

第二步：参考案例完成请求调用

demo 参考：下载样例项目 📎call-yidaapi-demo.7z 获取的应用 accessKey 和 secretKey 填入gateway.properties 配置文件中。样例项目是独立的 Spring boot 项目，用户根据需求做取舍。

1.1 Java调用方式

(1)引入依赖

手动JAR包依赖

📎xxpt.gateway.shared.client.zip

其他依赖

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.2</version>
</dependency>
<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.9.4</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.4</version>
</dependency>

说明：

上述需要引入的 maven 配置是网关调用的依赖项，如果和您本地的 jar 包版本冲突，请进行排包处理

(2)参数配置

例自定义配置文件：aecpgateway.properties

xxpt.gateway.protocal=https

xxpt.gateway.domainName=s-api.alibaba-inc.com

xxpt.gateway.accessKey=自己的 accessKey

xxpt.gateway.secretKey=自己的 secretKey

通过 XML 定义 bean

<?xml version="1.0" encoding="UTF-8" ?><beans xmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:context="http://www.springframework.org/schema/context"xmlns:tx="http://www.springframework.org/schema/tx"xmlns:util="http://www.springframework.org/schema/util"xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsdhttp://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsdhttp://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsdhttp://www.springframework.org/schema/util http://localhost:8080/schema/www.springframework.org/schema/util/spring-util-2.0.xsd "default-autowire="byName">
<bean id="propertyConfigurer" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
  <property name="locations">
    <list>
      <value>classpath:aecpgateway.properties</value>
    </list>
  </property> 
</bean>

<bean id="executableClient" class="com.alibaba.xxpt.gateway.shared.client.http.ExecutableClient" factory-method="getInstance" init-method="init" destroy-method="destroy">
  <property name="protocal" value="${xxpt.gateway.protocal}"/>
  <property name="domainName" value="${xxpt.gateway.domainName}"/>
  <property name="accessKey" value="${xxpt.gateway.accessKey}"/>
  <property name="secretKey" value="${xxpt.gateway.secretKey}"/>
</bean>
</beans>

出于安全性考虑，上文中的 ${accessKey} 和 ${secretKey} 请联系宜搭开发人员获取。

说明：

上述需要配置的 XML 需要自行通过 spring 进行加载，文件名没有要求，sdk 中不会自动加载
配置 bean 后，通过 ExecutableClient.getInstance() 获取的对象是单例，请知晓
如果项目框架不是 spring，可以自行通过 new ExecutableClient() 的方式创建对象，对象有设置上述属性的set 方法，属性设置完成后，请务必调用该对象的 init 方法初始化对象内部的其他属性

(3)调用示例

简单的单元测试：

@Test
public void postYidaOutTest() {
    String api = "/yida_vpc/form/searchFormDatas.json";
    PostClient postClient = ExecutableClient.getInstance().newPostClient(api);
    postClient.addParameter("appType", "APP_XXX");
    postClient.addParameter("systemToken", "XXX");
    postClient.addParameter("formUuid", "XXX");
    postClient.addParameter("userId", "yida_pub_account");

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

工程中实际使用：

import com.alibaba.fastjson.JSON;
import com.alibaba.xxpt.gateway.shared.client.http.ExecutableClient;
import com.alibaba.xxpt.gateway.shared.client.http.PostClient;
import org.springframework.util.CollectionUtils;
import java.util.HashMap;
import java.util.Map;

/*
* aecp网关服务请求工具
* @Author: weimeng(shanyu)
* @Date: 2019/2/28 下午2:50
*/

public class AecpGatewayRequestUtil {
 /**    
* 请求aecp网关    
* @param param 请求参数    
* @param url 网关地址, 在aecp网关服务（https://epaas.alibaba-inc.com）查看    
* @return 请求结果    

*/    
public static AecpGatewayResult baseRequest(Map<String, String> param, String url) {

        try {
            PostClient postClient = ExecutableClient.getInstance().newPostClient(url);
            if (!CollectionUtils.isEmpty(param)) {
                for (Map.Entry<String, String> entry : param.entrySet()) {
                    postClient.addParameter(entry.getKey(), entry.getValue());
                }
            }
            String result = postClient.post();
            return JSON.parseObject(result, AecpGatewayResult.class);

        }catch(Throwable e){
            AecpGatewayResult result= new AecpGatewayResult();
            result.setSuccess(false);
            result.setResult("false");
            return result;

        }

    }

}

/**
* aecp网关服务请求的返回结果类
* @Author: weimeng(shanyu)
* @Date: 2019/2/28 下午2:52
*/

public class AecpGatewayResult {

    private boolean success;

    private String content;

    private String result;

    private String errorCode;

    private String errorMsg;

    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }

    public String getResult() {
        if (result == null) {
            return content;
        } else {
            return result;
        }
    }

    public void setResult(String result) {
        this.result = result;
    }

    public String getErrorCode() {
        return errorCode;
    }

    public void setErrorCode(String errorCode) {
        this.errorCode = errorCode;
    }

    public String getErrorMsg() {
        return errorMsg;
    }

    public void setErrorMsg(String errorMsg) {
        this.errorMsg = errorMsg;
    }

    public String getContent() {
        if (content == null) {
            return result;
        } else {
            return content;
        }
    }

    public void setContent(String content) {
        this.content = content;
    }

    @Override
    public String toString() {
        return "AecpGatewayResult{" +
            "success=" + success +
            ", result='" + getResult() + ''' +
            ", errorCode='" + errorCode + ''' +
            ", errorMsg='" + errorMsg + ''' +
            '}';
    }

}

/**    
* 获取授权用户账号列表    
*/    
public static final String GET_USER_LIST = "/yida_vpc/corp/getAliyunAuthInfo.json";

try {
    Map<String, String> param = new HashMap<String, String>();
    param.put(AecpHsfConstants.CURRENT_PAGE, request.getCurrentPage()+"");
    param.put(AecpHsfConstants.PAGE_SIZE, request.getPageSize()+"");
    param.put(AecpHsfConstants.ACCOUNT_NAME, request.getAccountName());
    // 调用注册在aecp网关服务上的宜搭接口    
	AecpGatewayResult result = AecpGatewayRequestUtil.baseRequest(param, GET_USER_LIST);
    // 请求成功    
	if(result.isSuccess()){
	 // 解析数据，用户列表        
	response = JSON.parseObject(result.getResult(), ConsoleUserListResponse.class);
        if(response.getEmployee() != null && response.getEmployee().getTotalCount() != null){
            response.setTotal(response.getEmployee().getTotalCount().longValue());
        }
        return response;
    }
} catch (Exception e) {
	// TODO
}

2. 表单接口

2.1 新增表单实例

接口：/yida_vpc/form/saveFormData.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB
formDataJson	表单数据	是	{"textField_jcpm6agt": "单行","employeeField_jcos0sar": ["workno"]}	参考：附录1保存/更新表单数据格式说明

返回值：

success: 请求是否成功
result：实例 ID
errorMsg: 错误信息
errorCode：错误码

返回值demo：{"result":"FINST-EF6Y93URN2UZ1SBPLIP9NAV6HR2GEO1Z4ZCHSCJ0","success":true}

2.2 更新表单中指定组件值

接口：/yida_vpc/form/updateFormData.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	helxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formInstId	要更新的表单数据ID	是	33f6d221-17f8-42b7-836a-682b95a046c2
useLatestVersion	使用最新的表单版本进行更新	否	false	默认为false
updateFormDataJson	要更新的表单组件值，必填	是	{"employeeField_jcpm5gy2": ["workno"]}	参考：附录1保存/更新表单数据格式说明。参数有的组件更新，没有的组件保持不变。明细的值只能统一更新，无法只更新明细下某个组件的值

返回值：

success: 请求是否成功
errorMsg: 错误信息
errorCode：错误码

返回值 demo：{"success":true}

2.3 删除表单实例

接口：/yida_vpc/form/deleteFormData.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	helxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formInstId	要删除的表单数据ID	是	33f6d221-17f8-42b7-836a-682b95a046c2

返回值：

success: 请求是否成功
errorMsg: 错误信息
errorCode：错误码

返回值 demo：{"success":true}

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

接口：/yida_vpc/form/getFormDataById.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	helxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formInstId	要查询的实例的实例ID	是	33f6d221-17f8-42b7-836a-682b95a046c2

返回值

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

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

接口：/yida_vpc/form/searchFormDataIds.json
说明：只有应用管理员才能使用这个接口
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录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号)被修改的数据。

返回值

success : 请求是否成功;
errorCode : 错误码;
errorMsg : 错误信息;
result :

currentPage : 当前页
totalCount : 符合条件的实例总数
data : 实例ID列表

返回值 demo：{"result":{"data":["FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0"],"totalCount":1,"currentPage":1},"success":true}

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

接口：/yida_vpc/form/searchFormDatas.json
说明：只有应用管理员才能使用这个接口
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hellxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录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升序排列

解决方案：如何使用上表中dynamicOrder参数实现对一个或多个字段进行自定义排序?以JAVA为例，详见下方代码。

Map dynamicOrdern = new HashMap();
dynamicOrdern.put("textField_ky1av3w7","+");
SearchFormDatasRequest searchFormDatasRequest = new SearchFormDatasRequest()
.setDynamicOrder(JSON.toJSONString(dynamicOrdern));

返回值

success : 请求是否成功;
errorCode : 错误码;
errorMsg : 错误信息;
result :

currentPage : 当前页
totalCount : 符合条件的实例总数
data : 实例详情列表。每个实例详情格式参见附录 4 作为返回值的表单数据的格式说明

2.7 获取表单定义

接口：/yida_vpc/formDesign/getFormComponentDefinationList.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
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"
        }
    ]
}

2.8 获取子表单数据

接口：/yida_vpc/form/listTableDataByFormInstIdAndTableId.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
formInstanceId	要查询的实例的实例ID	是	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9
tableFieldId	需要查找的子表单组件的唯一标识	是	tableField_ksyaujq1
currentPage	当前页	否	10	必须大于0，默认1
pageSize	每页记录数	否	50	大于0并且小于50，默认10
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是

3. 流程接口

3.1 发起新的流程实例

接口: /yida_vpc/process/startInstance.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processCode	流程code	是	TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4	单独发起页链接上可查
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3	单独发起页链接上可查
formDataJson	表单数据	是		参考：附录1保存/更新表单数据格式说明
deptId	发起人所在部门号	否	18295	不填，默认发起人主职部门

返回值：

result : 实例 ID;

success : 请求是否成功;

errorMsg : 错误信息;

errorCode : 错误码;

返回值 demo： {"result":"f30233fb-72e1-4af4-8cb8-c7e0ea9ee530","success":true}

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

接口：/yida_vpc/process/getInstanceIds.json

说明：只有应用管理员才能使用这个接口

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录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 : 错误码;

返回值 demo： {"result":{"data":["f30233fb-72e1-4af4-8cb8-c7e0ea9ee530","bc0950a3-fe1b-459c-b6ba-282be38523ab","f540cbd7-43eb-40de-b915-6716578a2802"],"totalCount":3,"currentPage":1},"success":true}

3.3 根据搜索条件获取实例详情

接口： /yida_vpc/process/getInstances.json

说明：只有应用管理员才能使用这个接口

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	helxxxy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formUuid	表单ID	是	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	根据表单内组件值查询	否		格式见附录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- 流程实例详情对象格式说明

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

接口：/yida_vpc/process/getInstanceById.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530	不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。

返回值

result : 实例详情，参见附录 3- 流程实例详情对象格式说明

success : 请求是否成功;

errorMsg : 错误信息;

errorCode : 错误码;

3.5 根据实例 ID 列表批量获取流程实例详情

接口：/yida_vpc/process/getInstancesByIds.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceIds	流程实例ID列表，多个用,分割	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530,d230233fb-72e1-4af4-8cb8-c7e0ea9ee530	不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。

返回值

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

3.6 更新流程实例

接口: /yida_vpc/process/updateInstance.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hello1234	在应用数据中获取。
userId	钉钉的userId	是		会校验userId是否有流程发起权限
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processInstanceId	实例ID	是		不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。
updateFormDataJson	更新的表单数据	是		参考：附录1保存/更新表单数据格式说明

返回值：

success : 是否成功
errorMsg : 错误信息;
errorCode : 错误码;

返回值 demo： {"success":true}

3.7 删除流程实例

接口：/yida_vpc/process/deleteInstance.json

说明：只有应用管理员才能使用这个接口

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530	不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。

返回值

success : 请求是否成功;

errorMsg : 错误信息;

errorCode : 错误码;

3.8 终止流程实例

接口：/yida_vpc/process/terminateInstance.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530	不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。

返回值

success : 请求是否成功;

errorMsg : 错误信息;

errorCode : 错误码;

3.9 执行审批任务

接口：/yida_vpc/task/executeTask.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是		需要传任务实际处理人的 userId
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
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 : 错误码;

3.10 执行转交任务

接口: /yida_vpc/task/redirectTask.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	验权token	是		在应用数据中获取。
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
processInstanceId	实例ID	是		不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。
byManager	是否应用管理员进行转交	否	y	可选项 : y/n y,则userId必须传应用管理员工号，或者yida_pub_account n, userId必须传任务的当前执行人
userId	钉钉的userId	是
nowActionerId	新的任务处理人工号	是
remark	转交备注	是
taskId	任务ID	是

返回值：

success : 请求是否成功;
errorMsg : 错误信息;
errorCode : 错误码;
errorLevel : 错误级别;

返回格式

成功：

{
  "success":true
}

3.11 执行宜搭平台的审批任务

接口: /yida_vpc/process/executePlatformTask.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyyddd	在应用数据中获取。
userId	钉钉的userId	是	yida_pub_account	写死 yida_pub_account
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
procInstId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530
outResult	审批结果	是	agree disagree
formDataJson	更新的表单数据	否		参考：附录1保存/更新表单数据格式说明。
remark	审批意见	是	确认同意
noExecuteExpressions	是否不执行校验&关联操作	否	y	本任务节点有绑定校验规则或者关联操作时， y -> 不执行校验规则&关联操作 n -> 执行校验规则&关联操作不传默认为n，即会执行校验规则&关联操作

下面举一个具体的使用示例：

新建一个流程

前置审批人根据用户需求设置，需要程序回调执行的审批人需要选择使用角色中的虚拟角色「宜搭平台」，选择完成之后点击「保存」按钮，保存当前最新添加的流程节点。

回到流程设置的最外层，点击「保存并发布」按钮，将整个流程发布

发起流程之后，一路处理，直到审批流到达「宜搭平台」，此时整个流程会卡主，等待这一虚拟角色的审批

可以调用宜搭暴露的「执行虚拟节点任务」的接口 /yida/process/executePlatformTask.json 来更新该审批节点的处理结果。

3.12 获取审批记录

接口：/yida_vpc/process/getOperationRecords.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxyy	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
processInstanceId	流程实例ID	是	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530	不限制字符串长度，但processInstanceIds 包含的流程实例 ID 数不能超过100个。

返回值

result :

success : 请求是否成功;

errorMsg : 错误信息;

errorCode : 错误码;

返回格式

{
  "success": true,
  "content": [
    {
      "operateTime": "2018-06-22 14:35:40",
      "remark": "",
      "taskHoldTime": 0,
      "type": "HISTORY",
      "operatorName": "王许川",
      "operator": "WB260752",
      "activityId": "sid-restartevent",
      "action": "提交申请",
      "actionExt": "submit",
      "id": 2846866118,
      "operatorPhotoUrl": "//work.alibaba-inc.com/photo/WB260752.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": "WB260752",
      "activityId": "sidJIOB2P2J1JW3RPMDOS28",
      "taskType": "COMMON_ALL_AT_ONCE",
      "actionExt": "doing",
      "operatorPhotoUrl": "//work.alibaba-inc.com/photo/WB260752.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"
    }
  ]
}

3.13 获取流程实例可操作功能列表

接口: /yida_vpc/process/getActivityButtonVOs.json
参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hello1234	在应用数据中获取。
userId	钉钉的userId	是		会校验userId是否有流程发起权限
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
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
}

4. 任务中心

4.1 查询已提交任务列表

接口: /yida_vpc/process/getMySubmmitInCorp.json

参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	["APP_xxx","APP_xxx"]
processCodes	流程code列表	否	["xx","xxx"]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：

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 corpToken = "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, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);

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

4.2 查询待办任务列表

接口: /yida_vpc/process/getTodoTasksInCorp.json

参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	["APP_xxx","APP_xxx"]
processCodes	流程code列表	否	["xx","xxx"]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：

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 corpToken = "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, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);

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

4.3 查询已完成任务列表

接口: /yida_vpc/process/getDoneTasksInCorp.json

参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
appTypes	应用标识列表	否	["APP_xxx","APP_xxx"]
processCodes	流程code列表	否	["xx","xxx"]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
userId	钉钉的userId	是
token	验权token	是		md5(corpId + userId + corpToken)，每个企业有自己的唯一code md5取32位大写值 corpId和corpToken参数获取参考本文附录6，如果还是找到请联系宜搭值班。

返回值：

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 corpToken = "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, corpToken).getBytes()).toUpperCase();
        postClient.addParameter("token", token);

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

4.4 查询抄送我的任务列表（应用维度）

接口: /yida_vpc/process/getNotifyMeTasksInApp.json

参数

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	验权token	是
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
page	当前页	是	1	必须大于0 默认1
keyword	关键词	否
userId	钉钉的userId	是
processCodes	流程code列表	否	["xx","xxx"]
createFrom	创建时间开始	否		时间戳
createTo	创建时间结束	否		时间戳
instStatus	实例状态	否		枚举值

返回值：

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 数组

4.5 查询抄送我的任务列表（企业维度）

接口:/yida_vpc/process/getNotifyMeInCorp.json

参数

参数名	描述	是否必填	示例	备注
corpId	企业ID	是
token	验权token	是		md5(corpId + userId + code)，每个企业有自己的唯一code md5取32位大写值
userId	钉钉的userId	是
page	当前页	是	1	必须大于0 默认1
limit	每页记录数	是	10	必须大于0 默认10 最大值：100
language	语言环境	否	zh_CN	可选值：zh_CN/en_US
keyword	表单中组件数据模糊搜	否
appTypes	应用标识列表	否	["APP_xxx","APP_xxx"]
processCodes	流程code列表	否	["xx","xxx"]
instanceCreateFrom	数据提交时间开始	否		时间戳
instanceCreateTo	数据提交时间结束	否		时间戳
createFrom	抄送到达时间开始	否		时间戳
createTo	抄送到达时间结束	否		时间戳

返回结果

{
  "result": {
    "data": [
      {
        "gmtModified": "2019-01-24 19:25:23",
        "creator": "manager55",
        "corpId": "ding5d17e3add038d44535c2f4657eb6378f",
        "title": "小蔡发起的流程",
        "gmtCreate": "2019-01-24 19:25:23",
        "url": "https://www.aliwork.com/alibaba/web/APP_VN7I6HVKUTXES7XX4OI8/inst/carbonDetail.html?formInstId=33f6d221-17f8-42b7-836a-682b95a046c2&activityId=sidJRAJ56IZ2JOFOOPZ2MI7",
        "activityId": "sidJRAJ56IZ2JOFOOPZ2MI7",
        "titleEn": "小蔡（小蔡）发起的流程",
        "processCode": "TPROC--S5VKBWKVB4UVLG1BT5NS6229RVSD2MACIA4IJ7",
        "appType": "APP_VN7I6HVKUTXES7XX4OI8",
        "formInstId": "33f6d221-17f8-42b7-836a-682b95a046c2",
        "mobileUrl": "https://www.aliwork.com/alibaba/mobile/APP_VN7I6HVKUTXES7XX4OI8/inst/detail/carbonDetail?formInstId=33f6d221-17f8-42b7-836a-682b95a046c2&activityId=sidJRAJ56IZ2JOFOOPZ2MI7"
      }
    ],
    "currentPage": 1,
    "totalCount": 1
  },
  "success": true
}

5. 其他接口

5.1 附件地址转临时免登地址

接口：/yida_vpc/file/getOpenUrl.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
fileUrl	宜搭附件地址	是	https://www.aliwork.com/fileHandle?appType=APP_VN7I6HVKUTXES7XX4OI8&fileName=2a4103a6-44d5-4114-990d-4147a2d53811.xlsx&instId=&type=download
timeout	临时地址多久失效,单位毫秒	是	60000	60000表示一分钟后临时地址失效

返回值：

success: 请求是否成功
result：[]
errorMsg: 错误信息
errorCode：错误码

返回格式

{
  "result": "免登的附件地址",
  "success": true
}

5.2 提交表单/流程实例下的评论

接口：/yida_vpc/remark/save.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	评论人钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formInstId	实例ID	是	33f6d221-17f8-42b7-836a-682b95a046c2
replyId	对评论进行回复	否	12
atUserId	将评论内容通过钉钉发给指定用户	否	多个工号,用英文逗号分隔
content	评论内容	是

返回值：

success: 请求是否成功
result：评论 ID
errorMsg: 错误信息
errorCode：错误码

返回格式

{"result":14,"success":true}

5.3 获取应用下的页面列表

接口：/yida_vpc/app/listNavigationByFormType.json
参数：

参数名	描述	是否必填	示例	备注
appType	应用ID	是	APP_PBKT0MFBEBTDO8T7SLVP
systemToken	应用秘钥	是	hexxxx	在应用数据中获取。
userId	评论人钉钉的userId	是
language	语言	否	zh_CN	可选值：zh_CN/en_US 默认：zh_CN
formType	页面类型	是		receipt,单据页面process,流程页面 report，报表页面

返回值：

success: 请求是否成功
result：页面列表
errorMsg: 错误信息
errorCode：错误码

返回格式

{
  "result": [
    {
      "formUuid": "FORM-92GKRGIVZ5xxJZ6XB7WU3G4XNHV1YXYNELXJ0",
      "processCode": "TPROC--92GKRGIxx5V6LJZ6XB7WU3G4XNHV15YYNELXJ1",
      "title": {
        "pureEn_US": "普通流程01",
        "en_US": "普通流程01",
        "zh_CN": "普通流程01",
        "type": "i18n"
      },
    },
    {
      "formUuid": "FORM-92GKRGIV63X6K8X8ZH432CWBEGFN1DZ9V3OXJ0",
      "processCode": "TPROC--92GKRGIV63X6K8X8ZH432CWBEGFN1G3AV3OXJ1",
      "title": {
        "pureEn_US": "普通流程01(carbon)",
        "en_US": "普通流程01(carbon)",
        "zh_CN": "普通流程01-01-抄送人",
        "type": "i18n"
      }
    }
  ],
  "success": true,
  "errorCode": null,
  "content": null,
  "errorMsg": null
}

附录

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

表单中每个组件都有唯一 ID，每个组件中填写的数据都有自己的固定格式。目前支持全部标准组件。

保存/更新表单数据时，用 Map<String, Object> 的 jsonString 格式来作为参数传递表单中的数据。key 为组件 ID，Object 为组件的值。每个组件的值格式如下：

组件类型	数据格式	demo	备注
单行输入框	字符串	"danhang"
多行输入框	字符串	"duohang"
数字输入框	数字	1
单选	字符串	"选项一"
下拉单选	字符串	"选项一"
多选	字符串数组	["选项一","选项二"]
下拉多选	字符串数组	["选项一","选项二"]
日期组件	时间戳	1516204800000
级联日期	字符串数组	["1514736000000","1517328000000"]。假如只有结束时间，["","1517328000000"]	第一个为开始时间的时间戳字符串，第二给结束时间的时间戳字符串
人员搜索框	字符串数组	["xxxxx","yyyyy"]	传人员的userid信息，精确匹配。值必须完全匹配，工号顺序也需要一致。
城市选择	字符串数组	["110000","110100","110101"]	第一个必须为省份ID，第二个为城市ID，第三个为区ID。
部门选择	字符串数组	["xxxxx"]
级联选择	字符串数据	["part","part_b"]	必须按照级联顺序，依次放到数组中
附件组件	JSONArray	[ { "downloadUrl": "文件下载地址", "name": "文件名", "previewUrl": "文件预览地址", "url": "文件下载地址", "ext": "docx" } ]
图片上传组件	JSONArray	[ { "previewUrl": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=open&process=image/resize,m_fill,w_200,h_200,limit_0/quality,q_80", "size": 2610734, "name": "Bts2Z0e6oxA.jpg", "downloadUrl": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=download", "url": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=download" } ]
评分组件	整数	97
富文本组件	字符串	<div><strong>你好，这是测试</strong></div> <div><span style="font-family: kaiti;background-color: #ff0000;color: #ffff00;"><em><strong>测试</strong></em></span></div> <div> </div>
国家选择组件	JSONArray	[ { "value": "PG" } ]
地址组件	JSONObject	{ "address": "111", "regionIds": [ 460000, 469027, 469023401 ], "regionText": [ { "en_US": "hai+nan+sheng", "zh_CN": "海南省" }, { "en_US": "cheng+mai+xian", "zh_CN": "澄迈县" }, { "en_US": "guo+ying+hong+gang+nong+chang", "zh_CN": "国营红岗农场" } ] }
超链接组件	JSONArray	[ { "link":"http://www.aliwork.com", "text":"宜搭" } ]
子表单组件(原名称是明细组件)	JSONArray	[ { "textField_jcr0069m": "danhang1" //(textField_jcr0069m为子表单里的单行文本组件的组件ID) }, { "textField_jcr0069m": "danhang2" } ]	由于子表单组件下有多条记录，所以用JSONARRAY。由于每条记录都是很多组件的值，因此用JSONObject来存每个组件对应的值
关联表单组件	JSONArray	[ { "appType": "APP_XXXX", "formUuid": "被关联页面的表单编码", "formType": "receipt", "instanceId": "被关联的表单实例ID", "title": "标题", "subTitle": "" } ]

完整的表单数据格式如下：

{
  "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": [
    "xxxxx"
  ],
  "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"
    }
  ],  
  "associationFormField_kwx6cmhn":[
    {
      "appType":"APP_TCGTOH1VQGXUX5YLB6QZ",
      "formUuid":"FORM-N4A66IB1K61UUOVNWCPSQGQWL8SV14UXMB6UK4C",
      "formType":"receipt",
      "instanceId":"FINST-3S566KA1830URB9U0MT2JBSAW8LX2U1JOB6UK4RM",
      "title":"选项",
      "subTitle":""
    }
  ],
  "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": "明细下多行"
    }
  ],
  "imageField_l0c1cwit": [
    {
      "previewUrl": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=open&process=image/resize,m_fill,w_200,h_200,limit_0/quality,q_80",
      "size": 2610734,
      "name": "Bts2Z0e6oxA.jpg",
      "downloadUrl": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=download",
      "url": "/ossFileHandle?appType=APP_K6IGJJ6PFAARLPDSWKXQ&fileName=APP_K6IGJJ6PFAARLPDSWKXQ_MTczMjU1NjYyMzg3MzI0NF8wUDk2NlQ2MVIzR1lHV1RaMjMxQ1A5U1Y1NU1NM1lMWVY1QzBMMQ$$.jpg&instId=&type=download"
    }
  ],
  "editorField_l0c1cwiz": "<div><strong>你好，这是测试</strong></div>\n<div><span style=\"font-family: kaiti;background-color: #ff0000;color: #ffff00;\"><em><strong>测试</strong></em></span></div>\n<div> </div>",
  "rateField_l0c1cwis": 3,
  "countrySelectField_l0c1cwiu": [
    {
      "value": "PG"
    }
  ],
  "addressField_l0c1cwiy": {
    "address": "111",
    "regionIds": [
      460000,
      469027,
      469023401
    ],
    "regionText": [
      {
        "en_US": "hai+nan+sheng",
        "zh_CN": "海南省"
      },
      {
        "en_US": "cheng+mai+xian",
        "zh_CN": "澄迈县"
      },
      {
        "en_US": "guo+ying+hong+gang+nong+chang",
        "zh_CN": "国营红岗农场"
      }
    ]
  }
}

2. 条件搜索传参格式说明

2.1 根据组件值进行条件搜索，组件值格式说明

表单中每个组件都有唯一ID，每个组件的搜索格式不一样。目前支持搜索的表单组件有：单行，多行，数字，单选，下拉单选，多选，下拉多选，日期，日期区间，人员搜索框，地区选择，部门选择，级联选择，明细组件。

搜索时，用 Map<String, Object> 格式来表示每个组件的搜索条件。key 为组件 ID，Object 为组件的搜索值。各个组件的搜索类型和值格式如下

组件类型	数据格式	demo	备注
单行输入框	字符串	"danhang"	模糊搜索
多行输入框	字符串	"duohang"	模糊搜索
数字输入框	字符串数组	["1","10"]	范围搜索。第一个为最小值，第二个为最大值
单选	字符串	"选项二"	精确搜索
下拉单选	字符串	"选项二"	精确搜索
多选	字符串数组	["选项二"]	数组搜索。搜索值必须是多选值的子集
下拉多选	字符串数组	["选项二"]	数组搜索。搜索值必须是多选值的子集
日期组件	字符串数组	["1514736000000","1517414399000"]	范围搜索。第一个为日期开始的时间戳，第二个为日期结束的时间戳。
日期区间	数组	[["1514736000000","1517414399000"],["1514736000000","1517414399000"]]	范围搜索。第一个数组是日期区间开始的搜索范围。第二个数组是日期区间结束的搜索范围。
人员搜索框	字符串数组	["xxxxx","yyyyyy"]	传人员的userid信息，精确匹配。值必须完全匹配，工号顺序也需要一致。
城市选择	字符串数组	["110000","110100","110101"]	数组搜索。搜索值必须是城市值的子集。另外，有市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": "明细数据"
}

2.2 采用表单“数据管理”的过滤条件进行条件搜索，格式说明

表单中每个组件都有唯一ID，不同类型的组件的搜索格式不一样，不同类型的组件支持的操作符(例如大于、等于、小于、包含、不等于......)也不一样。
目前支持搜索的表单组件有：单行文本、多行文本、数值、评分、单选、下拉单选、多选、下拉多选、日期、日期区间、成员、级联选择、图片上传、附件、明细组件(子表单组件)、国家/地区选择、部门选择、地址。详情见下表。
除了表单组件可参与搜索，也预置了一些可参与搜索的预置字段，例如表单提交人、表单提交时间、当前审批节点名称、流程审批结果。详情见下表
过滤条件参数是字符串，是JSONArray字符串化的值，具体形式为 [{"key":左操作数,"value":右操作数,"type":"组件值类型","operator":操作符,"componentName":组件名称}]。
综合示例: 提交人等于步凡且流程审批结果为同意，则入参可以填 [{"key":"originator","value":"1732556623873244","type":"STRING","operator":"eq","componentName":"EmployeeField"},{"key":"processApprovedResult","value":["agree"],"type":"ARRAY","operator":"in","componentName":"SelectField"}]。
您可以参考下面2个表格构造您的搜索条件，也可以直接使用表单“数据管理”页面请求宜搭服务端使用的搜索条件，实际上下面2个表格的数据整理自“数据管理”页面的网络请求。

2.2.1 表单组件字段：

	组件名称	操作符	单独的检索条件示例
普通组件	单行文本	等于 (eq) 匹配（like）	[{"key":"textField_kwod1oy2","value":"A","type":"TEXT","operator":"like","componentName":"TextField"}]
	多行文本	等于 (eq) 匹配（like）	[{"key":"textareaField_kwod1oy4","value":"A","type":"TEXT","operator":"like","componentName":"TextareaField"}]
	数值	大于(gt)/小于(lt)/介于(between)/大于等于(ge)/小于等于(le)	[{"key":"numberField_kwod1oy6","value":2,"type":"DOUBLE","operator":"gt","componentName":"NumberField"}] [{"key":"numberField_kwod1oy6","value":2,"type":"DOUBLE","operator":"lt","componentName":"NumberField"}] [{"key":"numberField_kwod1oy6","value":[1,2],"type":"DOUBLE","operator":"between","componentName":"NumberField"}]
	评分	大于(gt)/小于(lt)/介于(between)/大于等于(ge)/小于等于(le)	[{"key":"rateField_kwod1oy8","value":2,"type":"DOUBLE","operator":"gt","componentName":"RateField"}] [{"key":"rateField_kwod1oy8","value":[2,4],"type":"DOUBLE","operator":"between","componentName":"RateField"}]
	单选	等于(eq)/包含(contains)	操作符为“等于”时只能选择单个值 [{"key":"radioField_kwod1oya","value":"选项一","type":"ARRAY","operator":"eq","componentName":"RadioField"}] 操作符为”包含“时可选择多个值 [{"key":"radioField_kwod1oya","value":["选项一","选项二"],"type":"ARRAY","operator":"contains","componentName":"RadioField"}]
	下拉单选	等于(eq)/包含(contains)
	复选	等于(eq)/包含(contains)	[{"key":"checkboxField_kwod1oyc","value":["选项一","选项二"],"type":"ARRAY","operator":"eq","componentName":"CheckboxField"}] [{"key":"checkboxField_kwod1oyc","value":["选项一","选项三"],"type":"ARRAY","operator":"contains","componentName":"CheckboxField"}]
	下拉复选	等于(eq)/包含(contains)	[{"key":"multiSelectField_kwod1oyg","value":["选项一","选项二"],"type":"ARRAY","operator":"eq","componentName":"MultiSelectField"}] [{"key":"multiSelectField_kwod1oyg","value":["选项一","选项二"],"type":"ARRAY","operator":"contains","componentName":"MultiSelectField"}]
	级联选择	等于(eq)/包含(contains)	[{"key":"cascadeSelectField_kwod1oyo","value":["product","product_a"],"type":"STRING","operator":"eq","componentName":"CascadeSelectField"}] [{"key":"cascadeSelectField_kwod1oyo","value":["part","part_b"],"type":"STRING","operator":"contains","componentName":"CascadeSelectField"}]
	日期	大于(gt)/小于(lt)/介于(between)/大于等于(ge)/小于等于(le)	[{"key":"dateField_kwod1oyi","value":1649174400000,"type":"DOUBLE","operator":"gt","componentName":"DateField"}] [{"key":"dateField_kwod1oyi","value":[1649088000000,1652198399000],"type":"DOUBLE","operator":"between","componentName":"DateField"}]
	日期区间	无需传操作符(采用默认操作符)	日期区间在数据管理里自动生成日期区间开始和日期区间结束这个2个组件，各自的操作符为介于，也即日期区间的开始时间介于和日期区间的结束时间介于 [{"key":"cascadeDateField_kwod1oyk","value":[[1649433600000,1651593599000],[1649260800000,1652198399000]],"type":"DOUBLE","componentName":"CascadeDateField"}]
	图片上传	匹配（like）	[{"key":"imageField_kwod1oyq","value":"fileUpload/","type":"TEXT","operator":"like","componentName":"ImageField"}]
	附件	匹配（like）	[{"key":"attachmentField_kwod1oys","value":"APP_ANNSASAS","type":"TEXT","operator":"like","componentName":"AttachmentField"}]
	成员	等于(eq)/包含(contains)	[{"key":"employeeField_kwod1oym","value":"钉钉userId","type":"STRING","operator":"eq","componentName":"EmployeeField"}] [{"key":"employeeField_kwod1oym","value":"["17325566238732445","1163103157219057185"]","type":"STRING","operator":"contains","componentName":"EmployeeField"}]
	成员(多选模式)	等于(eq)/包含(contains)	[{"key":"employeeField_kwod1oym","value":"0124151667379678541","type":"STRING","operator":"eq","componentName":"EmployeeField"}] [{"key":"employeeField_kwod1oym","value":"["0124151667379678541","1163103157219057181","0928242534266035951"]","type":"STRING","operator":"contains","componentName":"EmployeeField"}]
	子表单	包含(contains)	[{"key":"tableField_kwod1oyu","value":"关键词","type":"TEXT","operator":"contains","componentName":"TableField"}]
	子表单内部的组件	和主表单里的组件支持的操作符一致，区别是条件里带有parentId(值为子表单组件的id)	[{"key":"textField_kwod1ozm","value":"ad","type":"TEXT","operator":"like","componentName":"TextField","parentId":"tableField_kwod1oyu"}]
	部门	等于(eq)/包含(contains)	[{"key":"departmentSelectField_kwod1oz8","value":"483524872","type":"ARRAY","operator":"eq","componentName":"DepartmentSelectField"}] [{"key":"departmentSelectField_kwod1oz8","value":["483524872"],"type":"ARRAY","operator":"contains","componentName":"DepartmentSelectField"}]
高级控件	部门(多选模式)	等于(eq)/包含(contains)	[{"key":"departmentSelectField_kwod1oz8","value":"483524872","type":"ARRAY","operator":"eq","componentName":"DepartmentSelectField"}] [{"key":"departmentSelectField_kwod1oz8","value":["483524872"],"type":"ARRAY","operator":"contains","componentName":"DepartmentSelectField"}]
	国家/地区	等于(eq)/包含(contains)	[{"key":"countrySelectField_kwod1oz6","value":"PG","type":"ARRAY","operator":"eq","componentName":"CountrySelectField"}] [{"key":"countrySelectField_kwod1oz6","value":["MO","HK","TW"],"type":"ARRAY","operator":"contains","componentName":"CountrySelectField"}]
	地址	地址：等于(eq) 详细地址：等于(eq)/匹配（like）	地址组件在数据管理里自动生成地址和详细地址，其中地址部分仅支持eq，详细地址部分支持eq和like [{"key":"addressField_kwod1oza","value":{"regionIds":["820000","820200","820007"],"address":"未来park"},"operator":"like","type":"TEXT","componentName":"AddressField"}] [{"key":"addressField_kwod1oza","value":{"regionIds":["820000","820200","820007"],"address":"仓前街道"},"operator":"eq","type":"TEXT","componentName":"AddressField"}]
	富文本	筛选域无透出此字段
	布局容器
	分组
	关联表单
	定位
	手写签名

2.2.2 预置字段：

表单类型	字段名称	对应的组件类型	操作符	单独的检索条件示例
普通表单	实例标题	无	无	无
	提交人	成员/下拉单选	等于(eq)	[{"key":"originator","value":"012415166737967854","type":"STRING","operator":"eq","componentName":"EmployeeField"}]
	提交人组织；仅支持一级，与提交人部门无关	成员/下拉单选	等于(eq)	[{"key":"originatorCorp","value":"ding5d17e3add038d44535c2f4657eb6378f","type":"ARRAY","operator":"eq","componentName":"SelectField"}]
	创建时间	日期	大于(gt)/小于(lt)/介于(between)/大于等于(ge)/小于等于(le)	[{"key":"createTime","value":1649260800000,"type":"DOUBLE","operator":"gt","componentName":"DateField"}] [{"key":"createTime","value":[1649952000000,1652198400000],"type":"DOUBLE","operator":"between","componentName":"DateField"}]
	修改时间	日期	大于(gt)/小于(lt)/介于(between)/大于等于(ge)/小于等于(le)	[{"key":"modifiedTime","value":1649260800000,"type":"DOUBLE","operator":"gt","componentName":"DateField"}] [{"key":"modifiedTime","value":[1649952000000,1652198400000],"type":"DOUBLE","operator":"between","componentName":"DateField"}]
	流水号	文本	等于(eq)	[{"key":"serialNo","value":"TKASNJASFF","type":"TEXT","operator":"eq","componentName":"TextField"}]
流程表单 (流程表单也支持普通表单的预置字段)	当前节点名称	文本	等于(eq) /匹配（like）	[{"key":"currentNodeName","value":"主管","type":"TEXT","operator":"like","componentName":"TextField"}] [{"key":"currentNodeName","value":"主管审批","type":"TEXT","operator":"eq","componentName":"TextField"}]
	流程审批结果	下拉	包含(in)	[{"key":"processApprovedResult","value":["agree"],"type":"ARRAY","operator":"in","componentName":"SelectField"}]
	流程实例状态	下拉复选	包含（in） value枚举: "RUNNING" "NEW" "PAUSED" "TERMINATED" "COMPLETED" "ERROR" "CANCELED"	[{"key":"processInstanceStatus","value":["RUNNING","NEW","PAUSED","TERMINATED","COMPLETED","ERROR","CANCELED"],"type":"ARRAY","operator":"in","componentName":"SelectField"}]
	任务ID	文本	等于(eq)/匹配（like）	[{"key":"taskId","value":"123","type":"TEXT","operator":"eq","componentName":"TextField"}]

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
}

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

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

录入时，地区组件值为["省份ID", "市ID", "区ID"]。作为返回值时，是["省名称","城市名称","地区名称"]。

单选，下拉单选，多选，下拉多选是有国际化的。返回值时，会根据传的 language 参数，返回对应的数据值。

5. 单据实例详情对象格式说明

字段	描述	示例	备注
gmtModified	最后修改时间	2018-01-24 11:22:01
formUuid	表单ID	FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1
formInstId	实例ID	33f6d221-17f8-42b7-836a-682b95a046c2
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": "33f6d221-17f8-42b7-836a-682b95a046c2",
    "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
}

6. Corp ID 和 Corp Token 如何获取？

点击首页右上角的小螺丝的图标，进入平台管理配置页面

有侧边栏点击企业基本信息，在展示页面的租户信息中可以分别查询到 Corp ID 和 Corp Token 的数据，分别对应常用参数里面的 Corp ID 和 Corp Token

7. 可参与搜索结果排序的内置字段

搜索表单实例和流程表单实例时可以对结果进行排序, 除了按照表单组件值进行排序外，一些内置字段也可以参与排序，如下表所示。

示例：按照创建时间降序再按照数字组件numberField_adfeadffad的值降序排序，那么排序规则可以填: {"gmt_create":"-","numberField_adfeadffad":"-"}

字段含义	字段名
流水号	serial_no （旧版元数据为 yida_serial_no）
数据id(表单实例ID)	pid （旧版元数据为 guid）
流程实例状态	process_status
提交人	creator
流程当前节点名称	current_node_name
流程审批结果	approved_result
提交人组织	yida_originator_corp_id
提交时间	gmt_create
修改时间	gmt_modified
流程实例标题	title

8. 宜搭OpenAPI返回的表单实例FormData结构说明

OpenAPI返回的表单实例数据formData(Map数据结构)数据包含组件值(例如表单下拉单选组件的自定义选项配置的选项值、例如部门组件的部门ID)、组件显示值（例如表单下拉单选组件的自定义选项配置的显示值、例如部门组件的部门名称）。
组件值对应带“_value”，“_id”后缀的Map键，组件显示值对应组件id。

例如departmentSelectField_kwod1oz8_id的值是部门的唯一标识，而departmentSelectField_kwod1oz8的值是部门名称
例如radioField_kwod1oya对应单选组件radioField_kwod1oya的自定义选项的显示值（例如“选项二”），而radioField_kwod1oya_id对应单选组件radioField_kwod1oya的自定义选项的选项值（例如“two”）
例如countrySelectField_kwod1oz6对应国家的名称（例如“中国澳门特别行政区”），而countrySelectField_kwod1oz6_id对应国家的唯一编码（例如“MO”）。以下JSON是参考示例。
对于地址组件，addressField_xxxxx的值是地址组件的全值(包含regionIds、regionText、address)，而addressField_xxxxx_id的值是地址完整显示值(例如 “广东省/深圳市/罗湖区/翠竹街道/1号”)。

示例值如下：

{
  "addressField_kwod1oza": "{\"address\":\"1号\",\"regionIds\":[440000,440300,440303,440303004],\"regionText\":[{\"en_US\":\"guang dong sheng\",\"zh_CN\":\"广东省\"},{\"en_US\":\"shen zhen shi\",\"zh_CN\":\"深圳市\"},{\"en_US\":\"luo hu qu\",\"zh_CN\":\"罗湖区\"},{\"en_US\":\"cui zhu jie dao\",\"zh_CN\":\"翠竹街道\"}]}",
  "addressField_kwod1oza_id": "\"广东省/深圳市/罗湖区/翠竹街道/1号\"",
  "departmentSelectField_kwod1oz8": [
    "产品1部"
  ],
  "departmentSelectField_kwod1oz8_id": [
    "483524872"
  ],
  "checkboxField_kwod1oyc": [
    "选项二",
    "选项三"
  ],
  "checkboxField_kwod1oyc_id": [
    "three",
    "two"
  ],
  "multiSelectField_kwod1oyg": [
    "选项二",
    "选项三"
  ],
  "multiSelectField_kwod1oyg_id": [
    "three",
    "two"
  ],
  "numberField_kwod1oy6": 123,
  "numberField_kwod1oy6_value": "123",
  "cascadeSelectField_kwod1oyo": [
    "产品",
    "b产品"
  ],
  "cascadeSelectField_kwod1oyo_id": [
    "product",
    "product_b"
  ],
  "countrySelectField_kwod1oz6": [
    "中国澳门特别行政区"
  ],
  "countrySelectField_kwod1oz6_id": [
    "MO"
  ],
  "employeeField_kwod1oym": [
    "步凡"
  ],
  "employeeField_kwod1oym_id": [
    "1732556623873244"
  ],
  "selectField_kwod1oye": "选项一",
  "selectField_kwod1oye_id": "one",
  "rateField_kwod1oy8": 3,
  "rateField_kwod1oy8_value": "3",
  "radioField_kwod1oya": "选项二",
  "radioField_kwod1oya_id": "two",
  
  "digitalSignatureField_kwod1ozk": "https://tianshu-vpc.oss-cn-shanghai.aliyuncs.com/0e354301-f2ac-4b57-ae52-6aae20bfef03.png",
  "dateField_kwod1oyi": 1649088000000,
  "cascadeDateField_kwod1oyk": [
    "1649088000000",
    "1652112000000"
  ],
  "imageField_kwod1oyq": "[{\"previewUrl\":\"/ossFileHandle?appType=APP_JH8NR06DWA47077A7131&fileName=APP_JH8NR06DWA47077A7131_MTczMjU1NjYyMzg3MzI0NF9VTzk2NkE3MTY1SVpYSUJZMVNVR0FEQjBHRkNCM04xSkRNVTFMSzI$.jpg&instId=&type=open&process=image/resize,m_fill,w_200,h_200,limit_0/quality,q_80\",\"size\":2610734,\"name\":\"Bts2Z0e6oxA.jpg\",\"downloadUrl\":\"/ossFileHandle?appType=APP_JH8NR06DWA47077A7131&fileName=APP_JH8NR06DWA47077A7131_MTczMjU1NjYyMzg3MzI0NF9VTzk2NkE3MTY1SVpYSUJZMVNVR0FEQjBHRkNCM04xSkRNVTFMSzI$.jpg&instId=&type=download\",\"url\":\"/ossFileHandle?appType=APP_JH8NR06DWA47077A7131&fileName=APP_JH8NR06DWA47077A7131_MTczMjU1NjYyMzg3MzI0NF9VTzk2NkE3MTY1SVpYSUJZMVNVR0FEQjBHRkNCM04xSkRNVTFMSzI$.jpg&instId=&type=download\"}]",
  "editorField_kwod1oze": "["root",{},["p",{},["span",{"data-type":"text"},["span",{"highlight":"#FDBE3D","data-type":"leaf"},"文本编辑"]]]]",
  "textField_kwod1oy2": "单行",
  "textareaField_kwod1oy4": "多行\n多行",
  "associationFormField_kwod1ozi_id": "\"[]\"",
  "tableField_kwod1oyu": [
    {
      "cascadeSelectField_kwod1ozw": [
        "部门",
        "B部门"
      ],
      "cascadeSelectField_kwod1ozw_id": [
        "part",
        "part_b"
      ],
      "textField_kwod1ozm": ""
    }
  ]
}

6. 常见问题

6.1 除了文档中提及的 JAVA SDK，是否支持其他语言调用？

回答：支持，除了 Java 语言之外，还支持 go/php 等语言，具体内容可以参考开放接口 SDK 使用说明。

6.2 接口调用产生如下的报错

sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

【原因分析】

网关服务的 https 证书配置存在问题。

【解决方案】

一方面可以将 xxpt.gateway.protocal=https 修改为 xxpt.gateway.protocal=http 临时解决这个问题，

另一方面，向官方值班人员报错，建议官方尽快修复这个 https 证书的问题。

6.3 已经订阅服务了，在进行接口调用时还是产生了如下的报错：

User not authorized to operate on the specified resource

【解决方案】

订阅未生效，联系技术支持同学重新进行接口订阅。

6.4 接口返回："The Api Key 'test_201xxx1-LxQQO1xxxZBNn22' is invalid" ？

【解决方案】

请检查参 domainName 是否正确，正确值应该为：s-api.alibaba-inc.com

6.5 表单排序规则优先级说明

用户自定义排序规则 > 数据管理页或表单内置的排序规则 > 表单设置里的默认排序规则

本文档对您是否有帮助？

有用

没用

1. 准备工作​

第一步：申请秘钥授权​

第二步：参考案例完成请求调用​

1.1 Java调用方式​

(1)引入依赖​

手动JAR包依赖​

其他依赖​

(2)参数配置​

(3)调用示例​

2. 表单接口​

2.1 新增表单实例​

2.2 更新表单中指定组件值​

2.3 删除表单实例​

2.4 根据表单 ID 查询实例详情​

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

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

2.7 获取表单定义​

2.8 获取子表单数据​

3. 流程接口​

3.1 发起新的流程实例​

3.2 根据条件搜索流程实例 ID​

3.3 根据搜索条件获取实例详情​

3.4 根据实例 ID 获取流程实例详情​

3.5 根据实例 ID 列表批量获取流程实例详情​

3.6 更新流程实例​

3.7 删除流程实例​

3.8 终止流程实例​

3.9 执行审批任务​

3.10 执行转交任务​

3.11 执行宜搭平台的审批任务​

3.12 获取审批记录​

3.13 获取流程实例可操作功能列表​

4. 任务中心​

4.1 查询已提交任务列表​

4.2 查询待办任务列表​

4.3 查询已完成任务列表​

4.4 查询抄送我的任务列表（应用维度）​

4.5 查询抄送我的任务列表（企业维度）​

5. 其他接口​

5.1 附件地址转临时免登地址​

5.2 提交表单/流程实例下的评论​

5.3 获取应用下的页面列表​

附录​

1. 保存/更新 表单数据格式说明​

2. 条件搜索传参格式说明​

2.1 根据组件值进行条件搜索，组件值格式说明​

2.2 采用表单“数据管理”的过滤条件进行条件搜索，格式说明​

2.2.1 表单组件字段：​

2.2.2 预置字段：​

3. 流程实例详情对象格式说明​

4. 作为返回值的表单数据的格式说明​

5. 单据实例详情对象格式说明​

6. Corp ID 和 Corp Token 如何获取 ？​

7. 可参与搜索结果排序的内置字段​

8. 宜搭OpenAPI返回的表单实例FormData结构说明​

6. 常见问题​

6.1 除了文档中提及的 JAVA SDK，是否支持其他语言调用？​

6.2 接口调用产生如下的报错​

6.3 已经订阅服务了，在进行接口调用时还是产生了如下的报错：​

6.4 接口返回："The Api Key 'test_201xxx1-LxQQO1xxxZBNn22' is invalid" ？​

6.5 表单排序规则优先级说明​

1. 准备工作

第一步：申请秘钥授权

第二步：参考案例完成请求调用

1.1 Java调用方式

(1)引入依赖

手动JAR包依赖

其他依赖

(2)参数配置

(3)调用示例

2. 表单接口

2.1 新增表单实例

2.2 更新表单中指定组件值

2.3 删除表单实例

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

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

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

2.7 获取表单定义

2.8 获取子表单数据

3. 流程接口

3.1 发起新的流程实例

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

3.3 根据搜索条件获取实例详情

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

3.5 根据实例 ID 列表批量获取流程实例详情

3.6 更新流程实例

3.7 删除流程实例

3.8 终止流程实例

3.9 执行审批任务

3.10 执行转交任务

3.11 执行宜搭平台的审批任务

3.12 获取审批记录

3.13 获取流程实例可操作功能列表

4. 任务中心

4.1 查询已提交任务列表

4.2 查询待办任务列表

4.3 查询已完成任务列表

4.4 查询抄送我的任务列表（应用维度）

4.5 查询抄送我的任务列表（企业维度）

5. 其他接口

5.1 附件地址转临时免登地址

5.2 提交表单/流程实例下的评论

5.3 获取应用下的页面列表

附录

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

2. 条件搜索传参格式说明

2.1 根据组件值进行条件搜索，组件值格式说明

2.2 采用表单“数据管理”的过滤条件进行条件搜索，格式说明

2.2.1 表单组件字段：

2.2.2 预置字段：

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

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

5. 单据实例详情对象格式说明

6. Corp ID 和 Corp Token 如何获取？

7. 可参与搜索结果排序的内置字段

8. 宜搭OpenAPI返回的表单实例FormData结构说明

6. 常见问题

6.1 除了文档中提及的 JAVA SDK，是否支持其他语言调用？

6.2 接口调用产生如下的报错

6.3 已经订阅服务了，在进行接口调用时还是产生了如下的报错：

6.4 接口返回："The Api Key 'test_201xxx1-LxQQO1xxxZBNn22' is invalid" ？

6.5 表单排序规则优先级说明