Cross-Application Data Source API

Yida provides remote API calling capability that allows asynchronous interface calls via HTTP requests (for detailed usage, refer to Remote API Documentation). In addition to this, Yida platform also provides some built-in remote APIs for operating Yida data.

caution

Since calling the Open API provided by Yida requires authentication, remote Open API cannot be directly used on no-login pages. You can call it through FaaS or self-built services as intermediate calls.

API Call Instructions

Request Path

Yida provides various application-level interfaces. Within applications, you can call remote APIs in the following way (cross-application calls are supported). The interface return format is:

# The application code can be viewed in Application Settings => Deployment and O&M page
# Reference the following documentation for interface paths, different APIs provide different interface paths
"/dingtalk/web/${application code}/${interface path}"

tip

When writing interface request code in the Yida platform, please directly use relative paths as shown below, to avoid needing to adjust code due to enterprise subdomain name changes.

/dingtalk/web/APP_X1X2X3X4/v1/form/searchFormDatas.json

Interface Return Structure

The return structure of the remote API provided by the Yida platform is as follows:

interface IResponse {
  success: boolean; // Whether the request was successful
  result?: object | array | string; // Content returned on success
  errorMsg?: string; // Error message
  errorCode?: string; // Error code
  errorLevel?: number; // Error level
}

Form Related APIs

The Yida platform provides form-type pages for collecting form data. Form-related APIs are used to perform corresponding CRUD operations on form data. The form instances mentioned below are essentially individual data records in the form data collection.

Create Form Instance

• Interface path: /v1/form/saveFormData.json
• Request type: POST
• Parameters: (formDataJson needs to be serialized by the JSON.stringify() function)

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB
appType	Application ID	Yes	APP_DR4OK27ZKL5N22B907E8
formDataJson	Form data	Yes	{"textField_jcpm6agt": "Single line", "employeeField_jcos0sar": ["workno"]}	Reference: Appendix 1 Save/Update Form Data Format Description

• Return value example:

{
  "result": "FINST-EF6Y93URN2UZ1SBPLIP9NAV6HR2GEO1Z4ZCHSCJ0",
  "success": true
}

Update Specified Component Values in Form

• Interface: /v1/form/updateFormData.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
formInstId	Form data ID to be updated	Yes	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9
updateFormDataJson	Form component values to be updated, required	Yes	{"employeeField_jcpm5gy2": ["xxxxx", "yyyyy"]}	Reference: Appendix 1 Save/Update Form Data Format Description. Components with parameters will be updated, unchanged components remain as they are. Detailed values can only be updated uniformly, individual component values under subforms cannot be updated separately
useLatestVersion	Use the latest form version for update	No	y	Reference: Appendix 1 Save/Update Form Data Format Description "Special Note"

• Return value example:

{
  "success": true
}

Delete Form Instance

• Interface: /v1/form/deleteFormData.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
formInstId	Form data ID to be deleted	Yes	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9

• Return value example:

{
  "success": true
}

Query Form Instance Details by Form Instance ID

• Interface: /v1/form/getFormDataById.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
formInstId	Form data ID to query	Yes	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9

• Return value example:

{
  "success": "Whether the request is successful",
  "errorMsg": "Error message",
  "errorCode": "Error code",
  "result": "Form instance details 👇🏻👇🏻👇🏻"
}

result Refer to Appendix 5. Form Instance Details Object Format Description

Search Form Instance ID List by Conditions

• Interface: /v1/form/searchFormDataIds.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	Query based on form component values	No		Format see Appendix 2: Conditional Search by Component Values, component value format description
currentPage	Current page	No	1	Must be greater than 0, default 1
pageSize	Records per page	No	10	Must be greater than 0, default 10, cannot exceed 100
originatorId	Query by data submitter's work number	No
createFrom	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format
createTo	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format. Together with createFrom, equivalent to querying data created between 2018-01-01 to 2018-01-31 (including 01 and 31)
modifiedFrom	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period	No	2018-01-01	String format, yyyy-MM-DD format
modifiedTo	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period.	No	2018-02-01	String format, yyyy-MM-DD format. Together with modifiedFrom, equivalent to querying data modified between 2018-01-01 to 2018-01-31 (including 01 and 31)
dynamicOrder	Sorting	No	column: '+'	column: '+'

• Return value example:

{
  "result": {
    "data": ["FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0"],
    "totalCount": 1,
    "currentPage": 1
  },
  "success": true
}

Search Form Instance Details List by Conditions

• Interface: /v1/form/searchFormDatas.json
• Request type: GET
• Permission control: This interface will be subject to page-set permission control (except for administrators)
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	Query based on form component values	No		Format see Appendix 2: Conditional Search by Component Values, component value format description
currentPage	Current page	No	1	Must be greater than 0, default 1
pageSize	Records per page	No	10	Must be greater than 0, default 10, cannot exceed 100
originatorId	Query by data submitter's work number	No
createFrom	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format (or precise to seconds yyyy-MM-DD HH:mm:ss)
createTo	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format (or precise to seconds yyyy-MM-DD HH:mm:ss). Together with createFrom, equivalent to querying data created between 2018-01-01 to 2018-01-31 (including 01 and 31)
modifiedFrom	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period	No	2018-01-01	String format, yyyy-MM-DD format (or precise to seconds yyyy-MM-DD HH:mm:ss)
modifiedTo	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period.	No	2018-02-01	String format, yyyy-MM-DD format. (or precise to seconds yyyy-MM-DD HH:mm:ss). Together with modifiedFrom, equivalent to querying data modified between 2018-01-01 to 2018-01-31 (including 01 and 31)
dynamicOrder	Sorting	No	{"numberField_1ac":"+"}	Indicates sorting by field numberField_1ac in ascending order

• Return value example:

{
  "success": true,
  "errorCode": "",
  "errorMsg": "",
  "result": {
    "data": [],
    "totalCount": 1,
    "currentPage": 1
  }
}

Get Form Definition

This interface will be upgraded on December 1, 2024. After the upgrade, the interface will no longer support regular users, only administrators will be able to call it.

• Interface: /v1/form/getFormComponentDefinationList.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB
version	Form version	No	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9	Can pass the version field in formData.
Empty returns the latest version definition

• Return value example:

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

Get Sub-form Data

• Interface: v1/form/listTableDataByFormInstIdAndTableId.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-NJYJZELV8YZRDEI2N5IQ7L6VEDMR1VE9GMPCJB
formInstanceId	Instance ID of the instance to query	Yes	FINST-NJYJZELVVYZRVGJHR7M6FJW3ESJN1P1TCNPCJ9
tableFieldId	Unique identifier of the sub-form component to search	Yes	tableField_ksyaujq1
currentPage	Current page	No	10	Must be greater than 0, default 1
pageSize	Records per page	No	50	Greater than 0 and less than 50, default 10

• Return value example:

{
  "result": {
    "data": [
      {
        "textField_kstqokaa": ""
      },
      {
        "textField_kstqokaa": "1"
      },
      {
        "textField_kstqokaa": "2"
      }
    ],
    "totalCount": 120,
    "currentPage": 1
  },
  "success": true
}

Process Related APIs

Process forms are one of the basic capabilities provided by the Yida platform. Process-related APIs are used for performing related operations on processes.

Start Process

• Interface path: /v1/process/startInstance.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
processCode	Process code	Yes	TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4 ｜ Available on standalone start page link
formUuid	Form ID	Yes	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3 ｜ Available on standalone start page link
formDataJson	Form data	Yes		Reference: Appendix 1 Save/Update Form Data Format Description
deptId	Department number of starter	No	18295	Not required, defaults to starter's main department

• Return value example:

{
  "result": "f30233fb-72e1-4af4-8cb8-c7e0ea9ee530",
  "success": true
}

Search Process Instance ID by Conditions

• Interface path: /v1/process/getInstanceIds.json
• Request type: GET
• Permission description: Process needs to configure instance viewable permissions (except for administrators)
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	Query based on form component values	No		Format see Appendix 2: Conditional Search by Component Values, component value format description
taskId	Task ID	No	2199132092	Generally not used
instanceStatus	Instance status	No	RUNNING	Possible values: RUNNING, TERMINATED, COMPLETED, ERROR. Respectively represent: Running, Terminated, Completed, Error.
approvedResult	Process approval result	No	agree	Possible values: agree, disagree. Respectively represent: Approve, Reject.
currentPage	Current page	No	1	Must be greater than 0, default 1
pageSize	Records per page	No	10	Must be greater than 0, default 10, cannot exceed 100
originatorId	Query by process starter's work number	No
createFrom	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format yyyy-MM-DD
createTo	createFrom and createTo construct a time period. Query data list in that period.	No	2018-01-01	String format, yyyy-MM-DD format. Together with createFrom, equivalent to querying data created between 2018-01-01 to 2018-01-31 (including 01 and 31)
modifiedFrom	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period	No	2018-01-01	String format, yyyy-MM-DD format
modifiedTo	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period.	No	2018-01-01	String format, yyyy-MM-DD format. Together with modifiedFrom, equivalent to querying data modified between 2018-01-01 to 2018-01-31 (including 01 and 31)

• Return value example:

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

Get Instance Details List by Search Conditions

• Interface path: /v1/process/getInstances.json
• Request type: GET
• Permission description: Process needs to configure instance viewable permissions (except for administrators)
• Parameters:

Parameter	Description	Required	Example	Notes
formUuid	Form ID	Yes	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
searchFieldJson	Query based on form component values	No		Format see Appendix 2: Conditional Search by Component Values, component value format description
taskId	Task ID	No	2199132092	Generally not used
instanceStatus	Instance status	No	RUNNING	Possible values: RUNNING, TERMINATED, COMPLETED, ERROR.
Respectively represent: Running, Terminated, Completed, Error.
approvedResult	Process approval result	No	agree	Possible values: agree, disagree. Respectively represent: Approve, Reject.
currentPage	Current page	No	1	Must be greater than 0, default 1
pageSize	Records per page	No	10	Must be greater than 0, default 10, cannot exceed 100
originatorId	Query by process starter's work number	No
createFrom	createFrom and createTo construct a time period. Query data list in that period	No	2018-01-01	String format, yyyy-MM-DD format yyyy-MM-DD
createTo	createFrom and createTo construct a time period. Query data list in that period.	No	2018-01-01	String format, yyyy-MM-DD format. Together with createFrom, equivalent to querying data created between 2018-01-01 to 2018-01-31 (including 01 and 31)
modifiedFrom	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period	No	2018-01-01	String format, yyyy-MM-DD format
modifiedTo	modifiedFrom and modifiedTo construct a time period. Query data list modified in that period.	No	2018-01-01	String format, yyyy-MM-DD format. Together with modifiedFrom, equivalent to querying data modified between 2018-01-01 to 2018-01-31 (including 01 and 31)

• Return value example:

{
  "success": true,
  "errorCode": "",
  "errorMsg": "",
  "result": {
    "data": [],
    "totalCount": 1,
    "currentPage": 1
  }
}

Get Process Instance Details by Instance ID

• Interface path: /v1/process/getInstanceById.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
processInstanceId	Process instance ID	Yes	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

• Return value example:

{
  "success": true,
  "errorCode": "",
  "errorMsg": "",
  "result": "Instance details, see [Appendix 3- Process Instance Details Object Format Description](#process-instance-details-object-format-description)"
}

Delete Process Instance

• Interface path: /v1/process/deleteInstance.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
processInstanceId	Process instance ID	Yes	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

• Return value example:

{
  "success": true,
  "errorCode": "",
  "errorMsg": ""
}

Terminate Process Instance

• Interface path: /v1/process/terminateInstance.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
processInstanceId	Process instance ID	Yes	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

• Return value example:

{
  "success": true,
  "errorCode": "",
  "errorMsg": ""
}

Execute Single Task Interface

• Interface path: /v1/task/executeTask.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
taskId	Task ID	Yes	12002575
procInstId	Instance ID	Yes	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530
outResult	Approval result	Yes	AGREE	AGREE(Approve)、DISAGREE(Reject)
remark	Approval comment	Yes	Confirm approval
formDataJson	Approval comment	No	Confirm approval	Reference: Appendix 1 Save/Update Form Data Format Description.
Components with parameters will be updated, unchanged components remain as they are. Detailed values can only be updated uniformly, individual component values under subforms cannot be updated.
noExecuteExpressions	Whether to not execute validation & association operations	No	y	When this task node has validation rules or association operations bound,
y -> Don't execute validation rules & association operations n -> Execute validation rules & association operations. Not passing defaults to n, which means validation rules & association operations will be executed

• Return value example:

{
  "success": "Whether the request is successful",
  "errorCode": "Error message",
  "errorMsg": "Error code"
}

Get Approval Records

• Interface path: /v1/process/getOperationRecords.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
processInstanceId	Process instance ID	Yes	f30233fb-72e1-4af4-8cb8-c7e0ea9ee530

• Return value example:

{
  "success": true,
  "content": [
    {
      "operateTime": "2018-06-22 14:35:40",
      "remark": "",
      "taskHoldTime": 0,
      "type": "HISTORY",
      "operatorName": "Yi Xiaoda",
      "operator": "yida",
      "activityId": "sid-restartevent",
      "action": "Submit Application",
      "actionExt": "submit",
      "id": 2846866118,
      "operatorPhotoUrl": "/photo/yida.128x128.jpg",
      "processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
      "showName": "Submit Application",
      "operateType": "NEW_PROCESS",
      "domains": [],
      "operatorStatus": "A",
      "operatorAgentIds": [],
      "size": 1,
      "operatorDisplayName": "Yi Xiaoda",
      "taskId": "null"
    },
    {
      "taskHoldTime": 531398377,
      "type": "TODO",
      "operatorName": "Yi Xiaoda",
      "operator": "yida",
      "activityId": "sidJIOB2P2J1JW3RPMDOS28",
      "taskType": "COMMON_ALL_AT_ONCE",
      "actionExt": "doing",
      "operatorPhotoUrl": "/photo/yida.128x128.jpg",
      "processInstanceId": "8c124808-82e7-473b-9a7a-43c29b310837",
      "showName": "Executor",
      "activeTime": "2018-06-22 14:35:41",
      "domains": [],
      "operatorStatus": "A",
      "operatorAgentIds": [],
      "size": 1,
      "operatorDisplayName": "Yi Xiaoda",
      "taskId": "2846866145"
    }
  ]
}

Process Instance Update

• Interface path: /v1/process/updateInstance.json
• Request type: POST
• Parameters:

Parameter	Description	Required	Example	Notes
processInstanceId	Instance ID	Yes
updateFormDataJson	Updated form data	Yes		Reference: Appendix 1 Save/Update Form Data Format Description

• Return value example:

{
  "success": true
}

Task Center Related APIs

The Yida platform provides a task center to view the task list and status of all applications in the current organization. The task center related APIs are used to perform query operations on the task list in the task center.

Submitted Tasks

• Interface path: /v1/process/getMySubmitInApp.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
pageSize	Records per page	Yes	10	Must be greater than 0, default 10, maximum value: 100
currentPage	Current page	Yes	1	Must be greater than 0, default 1

• Return value example:
  • Success

{
  "result": {
    "data": [
      {
        "modifiedTime": "2018-04-12 19:44:14",
        "formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
        "title": "Bill",
        "instValue": [
          {
            "componentId": "node_jfwgghbo",
            "componentName": "TextField",
            "fieldId": "textField_jfwggg8e",
            "label": "Name",
            "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
}

• Failure

{
  "errorCode": "TIANSHU_000006",
  "success": false,
  "errorMsg": "No permission"
}

Pending Tasks

• Interface path: /v1/task/getTodoTasksInApp.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
pageSize	Records per page	Yes	10	Must be greater than 0, default 10, maximum value: 100
currentPage	Current page	Yes	1	Must be greater than 0, default 1

• Return value example:
  • Success

{
  "result": {
    "data": [
      {
        "processInstanceId": "XXXXXX",
        "originatorName": "XXX",
        "title": "Process initiated by XXX",
        "originatorPhoto": "http://static.dingtalk.com/media/lADPdfafafsAXXXXXX.jpg",
        "titleEn": "Process initiated by 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
}

• Failure

{
  "errorCode": "TIANSHU_000006",
  "success": false,
  "errorMsg": "No permission"
}

Completed Tasks

• Interface path: /v1/task/getDoneTasksInApp.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
pageSize	Records per page	Yes	10	Must be greater than 0, default 10, maximum value: 100
currentPage	Current page	Yes	1	Must be greater than 0, default 1

• Return value example:
  • Success

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

• Failure

{
  "errorCode": "TIANSHU_000006",
  "success": false,
  "errorMsg": "No permission"
}

Tasks copied to me (Application dimension)

• Interface path: /v1/task/getNotifyMeTasksInApp.json
• Request type: GET
• Parameters:

Parameter	Description	Required	Example	Notes
pageSize	Records per page	Yes	10	Must be greater than 0, default 10, maximum value: 100
currentPage	Current page	Yes	1	Must be greater than 0, default 1
processCodes	processCodes	No	["xx", "xxx"]
instanceStatus	Instance status	No		Enum values

• Return value example:
  • Success

{
  "result": {
    "data": [
      {
        "modifiedTime": "2018-04-12 19:44:14",
        "formInstanceId": "FINST-AJ1L4CJVXL0UIAIPR06ZA52U9HKUXXXXXX",
        "title": "Bill",
        "instValue": [
          {
            "componentId": "node_jfwgghbo",
            "componentName": "TextField",
            "fieldId": "textField_jfwggg8e",
            "label": "Name",
            "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
}

• Failure

{
  "errorCode": "TIANSHU_000006",
  "success": false,
  "errorMsg": "No permission"
}

Appendices

Save/Update Form Data Format Description

• Each component in the form has a unique ID (which can be viewed in the Advanced panel on the right side of the component in the page designer). Each component's entered data has its own fixed format. Currently supported form components include: single-line, multi-line, number, single-select, dropdown single-select, multi-select, dropdown multi-select, date, date range, personnel search box, region selection, department selection, cascade selection, sub-form components.
• When saving/updating form data, use Map<String, Object> JsonString format as the parameter to pass form data. key is the component ID, Object is the component's value. Each component's value format is as follows:

Component Type	Data Format	Data Format	Notes
Single-line Input Box	String	"single line"
Multi-line Input Box	String	"multi line"
Number Input Box	Number	1
Single Select	String	"Option 1"
Dropdown Single Select	String	"Option 1"
Multi Select	String Array	["Option 1", "Option 2"]
Dropdown Multi Select	String Array	["Option 1", "Option 2"]
Date Component	Timestamp	Date Component
Cascade Date	String Array	["1514736000000", "1517328000000"]. If only end time exists, ["", "1517328000000"]	First is start time timestamp string, second is end time timestamp string
Personnel Search Box	String Array	["xxxxx", "yyyyy"]
City Selection	String Array	["110000", "110100", "110101"]	First must be province ID, second is city ID, third is district ID.
Department Selection	String Array	["1123456"]	["xxx"] contains department IDs
Cascade Selection	String Array	["part", "part_b"]	Must follow cascade order, place sequentially in the array
Image Upload	String Array	[{"downloadUrl":"file download address", "name": "filename"}]
Attachment Component	String Array	[{"downloadUrl":"file download address", "name": "filename"}]
Hyperlink Component	String Array	[{"link":"http://www.aliwork.com", "text":"Yida"}]
Sub-form	JSONARRAY	[{"textField_jcr0069m": "singleline1"}, {"textField_jcr0069m": "singleline2"}] (textField_jcr0069m is the component ID of the single-line in the sub-form)	Since sub-forms have multiple records, JSONARRAY is used. Since each record contains many component values, JSONObject is used to store the value for each component
Handwritten Signature	String	"Image URL"

• Complete form data format example:

{
  "textField_jcr0069m": "singleline",
  "textareaField_jcr0069n": "multiline",
  "numberField_jcr0069o": 1,
  "radioField_jcr0069p": "Option 1",
  "selectField_jcr0069q": "Option 1",
  "checkboxField_jcr0069r": [
    "Option 2",
    "Option 3"
  ],
  "multiSelectField_jcr0069s": [
    "Option 2",
    "Option 3"
  ],
  "dateField_jcr0069t": 1516636800000,
  "cascadeDate_jcr0069u": [
    "1514736000000",
    "1517328000000"
  ],
  "employeeField_jcr0069x": [
    "xxxxx"
  ],
  "citySelectField_jcr0069y": [
    "110000",
    "110100",
    "110101"
  ],
  "departmentField_jcr0069z": 1123456,
  "cascadeSelectField_jcr006a0": [
    "part",
    "part_b"
  ],
  "imageField_l096bb9l": [
    {
      "name": "crazy xiao xin.jpg",
      "previewUrl": "https://img.alicdn.com/imgextra/i4/O1CN01DD8OQA1Lnay0fZRs3_!!6000000001344-0-tps-640-452.jpg",
      "downloadUrl": "https://img.alicdn.com/imgextra/i4/O1CN01DD8OQA1Lnay0fZRs3_!!6000000001344-0-tps-640-452.jpg",
      "size": 19039,
      "url": "https://img.alicdn.com/imgextra/i4/O1CN01DD8OQA1Lnay0fZRs3_!!6000000001344-0-tps-640-452.jpg"
    }
  ],
  "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": [
        "Option 1",
        "Option 2",
        "Option 3"
      ],
      "citySelectField_jcr006ac": [
        "120000",
        "120100",
        "120102"
      ],
      "dateField_jcr006a9": 1517328000000,
      "departmentField_jcr006ad": ["1123456"],
      "employeeField_jcr006ab": [
        "yyyyy",
        "xxxxx"
      ],
      "multiSelectField_jcr006a8": [
        "Option 1",
        "Option 2",
        "Option 3"
      ],
      "numberField_jcr006a4": 2,
      "radioField_jcr006a5": "Option 2",
      "selectField_jcr006a6": "Option 3",
      "textField_jcr006a2": "Single line in sub-form",
      "textareaField_jcr006a3": "Multi line in sub-form"
    }
  ],
  "digitalSignatureField_kt3nh972": "https://tianshu-vpc.oss-cn-shanghai.aliyuncs.com/5e03f863-dd39-4f62-ba9b-497af2c9ad9f.png"
}

Conditional search by component value, component value format description

• Each component in the form has a unique ID (which can be viewed in the Advanced panel on the right side of the component in the page designer). Each component has a different search format. Currently supported searchable form components include: single-line, multi-line, number, single-select, dropdown single-select, multi-select, dropdown multi-select, date, date range, personnel search box, region selection, department selection, cascade selection, sub-form components.
• When searching, use Map<String, Object> format to represent each component's search criteria. key is the component ID, Object is the component's search value. Search types and value formats for various components are as follows

Component Type	Data Format	Data Format	Notes
Single-line Input Box	String	"singleline"	Fuzzy search
Multi-line Input Box	String	"multiline"	Fuzzy search
Number Input Box	String Array	["1", "10"]	Range search. First is minimum value, second is maximum value
Single Select	String	"Option 1"	Exact search
Dropdown Single Select	String	"Option 1"
Multi Select	String Array	["Option 2"]	Array search. Search value must be a subset of multi-select values
Dropdown Multi Select	String Array	["Option 2"]	Array search. Search value must be a subset of multi-select values
Date Component	String Array	["1514736000000", "1517414399000"]	Range search. First is start date timestamp, second is end date timestamp.
Date Range	Array	[["1514736000000", "1517414399000"], ["1514736000000", "1517414399000"]]	Range search. First array is date range start search range. Second array is date range end search range.
Personnel Search Box	String Array	["xxxxx", "yyyyy"]	["xxxxx", "yyyyyy"] Exact match. Values must match completely, work number order must be the same.
City Selection	String Array	["110000", "110100", "110101"]	["110000", "110100", "110101"] Array search. Search value must be a subset of city values. Also, if city ID exists, province ID is required. If district ID exists, province and city IDs are required.
Department Selection	Number	1123456	Exact match
Cascade Selection	String Array	["part", "part_b"]	Array search. Same limitations as city selection.
Sub-form Component	String	"singleline"	Fuzzy search. Sub-form values form one large text, search uses fuzzy search

• Complete Example

{
  "textField_jcr0069m": "singleline",
  "textareaField_jcr0069n": "multiline",
  "numberField_jcr0069o": ["1", "10"],
  "radioField_jcr0069p": "Option 1",
  "selectField_jcr0069q": "Option 1",
  "checkboxField_jcr0069r": ["Option 2"],
  "multiSelectField_jcr0069s": ["Option 2", "Option 3"],
  "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": "Sub-form data"
}

Process Instance Details Object Format Description

• Each component in the form has a unique ID (which can be viewed in the Advanced panel on the right side of the component in the page designer). Each component has a different search format. Currently supported searchable form components include: single-line, multi-line, number, single-select, dropdown single-select, multi-select, dropdown multi-select, date, date range, personnel search box, region selection, department selection, cascade selection, sub-form components.
• When searching, use Map<String, Object> format to represent each component's search criteria. key is the component ID, Object is the component's search value. Search types and value formats for various components are as follows

Field	Description	Example	Notes
actioners	Current process instance task executors	[{"userId": "workno", "name":{"zh_CN": "user_zh_name", "type": "i18n"}}]	If the process is completed and there are no executors, this field is empty
processInstanceId	Instance ID	"f30233fb-72e1-4af4-8cb8-c7e0ea9ee530"	Unique
formUuid	Process form ID	FORM-EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ3
processCode	Process Code	TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4
title	Instance title	Process initiated by xxxx	Returns corresponding title according to your language environment
instanceStatus	Instance status	RUNNING
approvedResult	Approval conclusion when process ends	agree	agree -> Approve disagree -> Reject
originator	String array	[{"name":{"zh_CN": "user_zh_name", "type": "i18n"}, "userId": "workno"}]
data	Form data		Reference Appendix 4- Form Data Format Description as Return Value

• Complete data format 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": ["Option 3", "Option 2"],
        "textareaField_jcr0069n": "multiline",
        "employeeField_jcr0069x": ["xxxx"],
        "departmentField_jcr0069z": "Information xxx Platform",
        "cascadeDate_jcr0069u": ["1514736000000", "1517328000000"],
        "cascadeSelectField_jcr006a0": ["part", "part_b"],
        "tableField_jcr006a1": [
          {
            "departmentField_jcr006ad": "Information xxx",
            "cascadeDate_jcr006aa": ["1514736000000", "1517328000000"],
            "selectField_jcr006a6": "Option 3",
            "citySelectField_jcr006ac": ["Tianjin", "Tianjin City", "Hedong District"],
            "radioField_jcr006a5": "Option 2",
            "employeeField_jcr006ab": ["yyyyy", "xxxxxx"],
            "dateField_jcr006a9": 1517328000000,
            "textField_jcr006a2": "Single line in sub-form",
            "textareaField_jcr006a3": "Multi line in sub-form",
            "cascadeSelectField_jcr006ae": ["product", "product_a"],
            "numberField_jcr006a4": 2,
            "checkboxField_jcr006a7": ["Option 1", "Option 3", "Option 2"],
            "multiSelectField_jcr006a8": ["Option 1", "Option 3", "Option 2"]
          }
        ],
        "selectField_jcr0069q": "Option 1",
        "citySelectField_jcr0069y": ["Beijing", "Beijing City", "Dongcheng District"],
        "checkboxField_jcr0069r": ["Option 3", "Option 2"],
        "textField_jcr0069m": "singleline",
        "radioField_jcr0069p": "Option 1",
        "dateField_jcr0069t": 1516636800000
      },
      "processCode": "TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4",
      "originator": {
        "name": {
          "pureEn_US": "xxx",
          "en_US": "xxxx",
          "zh_CN": "xxx",
          "type": "i18n"
        },
        "userId": "xxxx"
      },
      "title": "Process initiated by xxx",
      "instanceStatus": "RUNNING"
    },
    "totalCount": 1,
    "currentPage": 1
  },
  "success": true
}

Form Data Format Description as Return Value

As a return value, the form data format is basically consistent with Appendix 1 Save/Update Form Data Format Description. The difference is:

• When entering, the region component value is ["Province ID", "City ID", "District ID"]. When returned as a value, it is ["Province Name", "City Name", "Region Name"].
• Single select, dropdown single select, multi select, and dropdown multi select are internationalized. When returning values, it will return corresponding data values based on the language parameter passed.

Form Instance Details Object Format Description

Field	Description	Example	Notes
gmtModified	Last modified time	2018-01-24 11:22:01
formUuid	Form ID	FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1
originator	Originator details	[{"name":{"zh_CN": "user_zh_name", "type": "i18n"}, "userId": "workno"}]
formData	Form data details	TPROC--EF6Y4G8WO2FN0SUB43TDQ3CGC3FMFQ1G9400RCJ4	Reference Appendix 4- Form Data Format Description as Return Value

• Complete data format demo

{
  "result": {
    "gmtModified": "2018-01-24 11:22:01",
    "formUuid": "FORM-EF6Y93URN24F1SCX15VA2P918LPEIJ2H3UFORCJ1",
    "formInstId": "FINST-EF6Y93URN2F02S745LTMW2D2G4WVDS16O17ISCJ0",
    "formData": {
      "numberField_jcr0069o": 1,
      "multiSelectField_jcr0069s": ["Option 3", "Option 2"],
      "textareaField_jcr0069n": "multiline",
      "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": "Option 3",
          "citySelectField_jcr006ac": ["Tianjin", "Tianjin City", "Hedong District"],
          "radioField_jcr006a5": "Option 2",
          "employeeField_jcr006ab": ["xxxxxx", "yyyyyy"],
          "dateField_jcr006a9": 1517328000000,
          "textField_jcr006a2": "Single line in sub-form",
          "textareaField_jcr006a3": "Multi line in sub-form",
          "cascadeSelectField_jcr006ae": ["product", "product_a"],
          "numberField_jcr006a4": 2,
          "checkboxField_jcr006a7": ["Option 1", "Option 3", "Option 2"],
          "multiSelectField_jcr006a8": ["Option 1", "Option 3", "Option 2"]
        }
      ],
      "selectField_jcr0069q": "Option 1",
      "citySelectField_jcr0069y": ["Beijing", "Beijing City", "Dongcheng District"],
      "checkboxField_jcr0069r": ["Option 3", "Option 2"],
      "textField_jcr0069m": "singleline",
      "radioField_jcr0069p": "Option 1",
      "dateField_jcr0069t": 1516636800000
    },
    "originator": {
      "name": {
        "pureEn_US": "userEnglishName",
        "en_US": "userEnglishName",
        "zh_CN": "userName",
        "type": "i18n"
      },
      "userId": "xxxx"
    }
  },
  "success": true
}