Third-party process and page integration

​

1. Feature overview

As enterprise digitalization deepens, more organizations need to integrate their OA systems with third-party business systems such as ERP, CRM, and finance systems. Third-party process and page integration enables data exchange, process sharing, and a unified operation interface, improving overall office efficiency and management collaboration. This guide walks developers and system administrators through configuring third-party process and page integration on the OA platform, so you can quickly implement system integration.

​

2. Applicable scenarios

Initiate a process from a business system and call DingTalk’s native OA Approval APIs to create a DingTalk OA Approval process. Then, open the business system’s approval detail page inside DingTalk to process the approval.

​

3. Operation flow

The end-to-end interaction between the business system and DingTalk is shown below:

​

4. Result preview

​

1. Open the business system’s approval detail page from the DingTalk OA Approval list

Take a business trip request as an example. From the DingTalk OA Approval list, tap the approval form to open the business system’s detail page directly for processing:

​

2. Open the business system’s approval detail page from DingTalk To-Do

In DingTalk To-Do Center, tap a to-do task to open the business system’s detail page for processing:

​

5. Development flow

The following example uses an Internal app developed by an organization to implement this integration. The business system initiates the approval, and its detail page opens inside DingTalk for processing. The implementation flow is shown below. (Note: in this scenario, approval tasks are synchronized in step 5.)

​

Integration flow overview

This document walks through creating an Internal app and using APIs provided by the OA Approval Process Center to create, update, and delete third-party approval templates; create and update approval instances; create, update, and query approval to-do tasks; and clean up OA Approval data. It shows how the business system initiates the approval and how the business system’s detail page opens inside DingTalk for this integration scenario. Prerequisite: complete the Create app flow. Step 1: Go to the app details page and obtain the Client ID and Client Secret. Step 2: Apply for the API permission, specifically the “OA Approval” permission. Step 3: Obtain the app’s access credential by retrieving the access token for the Internal app. The access token is used to authenticate the caller when invoking the API. Step 4: Call the OA Approval-related APIs:

1. Sync approval template data to DingTalk: Call the new Server API — Create or update approval template — to obtain the unique template code processCode.
   Note: In this scenario, you do not need to configure the processFeatureConfig Process Center integration settings. By default, approvals are handled by opening the business system’s detail page.
   {
   
       "name": "Integrate DingTalk OA using third-party process and page",
       "description": "DingTalk OA Approval supports pushing approval tasks from external systems (self-developed or third-party systems purchased by the organization) to the DingTalk Approval app, so users can view and process all approvals in one place for a unified approval experience.",
       "formComponents": [
           {
               "componentType": "TextField",
               "props": {
                   "componentId": "TextField-1",
                   "label": "Single-line input",
                   "required": true,
                   "bizAlias": "TextField-bizAlias",
                   "disabled": false
               }
           },
           {
               "componentType": "TextareaField",
               "props": {
                   "placeholder": "Please enter",
                   "label": "Multi-line input"
               }
           },
           {
               "componentType": "NumberField",
               "props": {
                   "placeholder": "Please enter a number",
                   "label": "Number input",
                   "id": "NumberField-1"
               }
           },
           {
               "componentType": "DDSelectField",
               "props": {
                   "options": [ // List of available options
                       {
                           "value": "Option 1", // Display name of the option
                           "key": "option_0" // Unique key within the component. Optional; generated by the system by default
                       },
                       {
                           "value": "Option 2",
                           "key": "option_1"
                       },
                       {
                           "value": "Option 3",
                           "key": "option_2"
                       },
                       {
                           "key": "other", // Special key for the "Other" option
                           "value": "Other"
                       }
                   ],
                   "label": "Single-select",
                   "placeholder": "Please select",
                   "componentId": "DDSelectField_1",
                   "required": false
               }
           },
           {
               "componentType": "DDMultiSelectField",
               "props": {
                   "options": [
                       {
                           "value": "Option 1",
                           "key": "option_0"
                       },
                       {
                           "value": "Option 2",
                           "key": "option_1"
                       },
                       {
                           "value": "Option 3",
                           "key": "option_2"
                       },
                       {
                           "key": "other", // Special key for the "Other" option
                           "value": "Other"
                       }
                   ],
                   "label": "Multiselect",
                   "placeholder": "Please select",
                   "componentId": "DDMultiSelectField_1",
                   "required": false
               }
           },
           {
               "componentType": "DDDateField",
               "props": {
                   "unit": "小时", // Date unit. Enum values: 小时 (Hour), 天 (Day)
                   "format": "yyyy-MM-dd HH:mm", // Date format. Optional. Hour: yyyy-MM-dd HH:mm; Day: yyyy-MM-dd
                   "bizAlias": "",
                   "label": "Date",
                   "placeholder": "Please select",
                   "componentId": "DDDateField_1",
                   "required": false,
                   "defaultValue": "2021-12-21 17:46" // Default value
               }
           },
           {
               "componentType": "DDDateRangeField",
               "props": {
                   "unit": "天",
                   "format": "yyyy-MM-dd",
                   "bizAlias": "",
                   "label": "[\"Start time\",\"End time\"]",
                   "placeholder": "Please select",
                   "componentId": "DDDateRangeField_1",
                   "duration": true, // Whether to automatically calculate the duration
                   "durationLabel": "Duration", // Display text for the calculated duration
                   "required": false
               }
           },
           {
               "componentType": "TextNote",
               "props": {
                   "link": "https://www.dingtalk.io/", // Hyperlink
                   "notPrint": "0",
                   "bizAlias": "",
                   "componentId": "TextNote_1",
                   "content": "This is an explanatory note" // Explanatory text
               }
           },
           {
               "componentType": "DDPhotoField",
               "props": {
                   "label": "Image",
                   "componentId": "DDPhotoField_1",
                   "required": false
               }
           },
           {
               "componentType": "MoneyField",
               "props": {
                   "upper": "0", // Whether to display the amount in uppercase (0: no, 1: yes). Uppercase is enabled by default
                   "label": "Amount (CNY)",
                   "placeholder": "Please enter an amount",
                   "componentId": "MoneyField_1",
                   "required": false
               }
           },
           {
               "children": [
                   {
                       "componentType": "TextField",
                       "props": {
                           "label": "Single-line input",
                           "placeholder": "Please enter",
                           "componentId": "TextField_1UE1ZY1A28AO0",
                           "required": false
                       }
                   },
                   {
                       "componentType": "MoneyField",
                       "props": {
                           "upper": "0",
                           "bizAlias": "",
                           "label": "Amount (CNY)",
                           "placeholder": "Please enter an amount",
                           "componentId": "MoneyField_1S85G0",
                           "required": false
                       }
                   },
                   {
                       "componentType": "NumberField",
                       "props": {
                           "unit": "CNY",
                           "bizAlias": "",
                           "label": "Number input",
                           "placeholder": "Please enter a number",
                           "componentId": "NumberField_1XP6A",
                           "required": false
                       }
                   }
               ],
               "componentType": "TableField",
               "props": {
                   "tableViewMode": "table",
                   "verticalPrint": true,
                   "statField": [
                       {
                           "componentId": "MoneyField_1S85G0",
                           "label": "Amount (CNY)"
                       },
                       {
                           "componentId": "NumberField_1XP6A",
                           "label": "Number input"
                       }
                   ],
                   "bizAlias": "table",
                   "label": "Spreadsheet",
                   "componentId": "TableField_1MLEPEA"
               }
           },
           {
               "componentType": "DDAttachment",
               "props": {
                   "label": "Attachment",
                   "componentId": "DDAttachment_1",
                   "required": false
               }
           },
           {
               "componentType": "InnerContactField",
               "props": {
                   "label": "Contact",
                   "placeholder": "Please select",
                   "componentId": "InnerContactField_1",
                   "choice": "1", // Enum values: 1 = multiselect supported, 0 = single-select. Default: 0
                   "required": false,
                   "bizAlias": ""
               }
           },
           {
               "componentType": "DepartmentField",
               "props": {
                   "multiple": false, // Whether multiselect is supported. true: multiselect, false: single-select
                   "label": "Department",
                   "placeholder": "Please select",
                   "componentId": "DepartmentField_1",
                   "required": false
               }
           },
           {
               "componentType": "RelateField",
               "props": {
                   "label": "Associated approval form",
                   "placeholder": "Please select",
                   "componentId": "RelateField_1",
                   "required": false,
                   "bizAlias": "",
                   "availableTemplates": [ // List of approval templates that can be associated. If empty, instances of all approval templates can be associated
                   ]
               }
           },
           {
               "componentType": "AddressField",
               "props": {
                   "addressModel": "district", // Enum values: city (province and city), district (province, city, and district), street (province, city, district, and street)
                   "bizAlias": "",
                   "label": "Province/City/District",
                   "componentId": "AddressField_1",
                   "required": false
               }
           },
           {
               "componentType": "StarRatingField",
               "props": {
                   "limit": 5, // Enum values: 5-point scale, 10-point scale
                   "label": "Rating",
                   "placeholder": "Please enter",
                   "componentId": "StarRatingField_1",
                   "required": false,
                   "bizAlias": ""
               }
           }
       ],
       "templateConfig": {
           "hiddenProcess": true,
           "createInstanceMobileUrl": "https://www.dingtalk.io",
           "createInstancePcUrl": "https://www.dingtalk.io",
           "templateEditUrl": "https://www.dingtalk.io",
           "disableSendCard": false
       }
   }
   
2. If you did not save the processCode, call the Get template code API to retrieve it.
3. After the approval template is created, go to the DingTalk OA Approval Admin Console to view third-party approval form templates, view or search template data, and export or delete template data.
4. Sync approval instance data to DingTalk: using the template code processCode, call the new Server API — Create instance — to initiate an approval instance and obtain the approval instance processInstanceId.
   {
       "formComponentValueList": [
           {
               "name": "Single-line input",
               "value": "DingTalk"
           },
           {
               "name": "Multi-line input",
               "value": "Please enter multi-line text. Use a line break when needed.\r\nPlease enter multi-line text. Use a line break when needed.\r\n"
           },
           {
               "name": "Number input",
               "value": "100"
           },
           {
               "name": "Single-select",
               "value": "Option 1"
           },
           {
               "name": "Multiselect",
               "value": "[\"Option 1\",\"Option 2\"]"
           },
           {
               "name": "Date",
               "value": "2021-08-17 11:11"
           },
           {
               "name": "[\"Start time\",\"End time\"]",
               "value": "[\"2019-02-19 11:11\",\"2019-02-25 11:11\"]"
           },
           {
               "name": "Image",
               "value": "[\"https://img.alicdn.com/imgextra/i3/O1CN01TDKbCW28HuskT5vnR_!!6000000007908-2-tps-2724-650.png\",\"https://img.alicdn.com/imgextra/i3/O1CN01TDKbCW28HuskT5vnR_!!6000000007908-2-tps-2724-650.png\",\"http://url3\"]"
           },
           {
               "name": "Spreadsheet",
               "value": "[{\"name\":\"Single-line input\",\"value\":\"[DingTalk\"},{\"name\":\"Number input\",\"value\":\"100\"}]]"
           },
           {
               "name": "Amount (CNY)",
               "value": "100"
           },
           {
               "name": "Attachment",
               "value": "[{\"spaceId\": \"163xxxx658\", \"fileName\": \"2644.JPG\", \"fileSize\": \"333\", \"fileType\": \"jpg\", \"fileId\": \"643xxxx140\"}]"
           },
           {
               "name": "Contact",
               "value": "[\"0135185610551036178639\"]"
           },
           {
               "name": "Associated approval form",
               "value": "[\"9XCLWKxNTom6W_u88iKbug09641720074458\", \"9XCLWKxNTom6W_u88iKbug09641720074458\"]"
           },
           {
               "name": "Phone",
               "value": "18015586666"
           },
           {
               "name": "Province/City/District",
               "value": "Beijing,Beijing,Hedong District"
           },
           {
               "name": "Rating",
               "value": "5"
           },
           {
               "name": "Department",
               "value": "714738614"
           }
       ],
       "title": "Integrate DingTalk OA using third-party process and page",
       "processCode": "PROC-39B555F8-FFC6-4CCC-AC5F-xxx",
       "originatorUserId": "manager9814",
       "url": "http://www.dingtalk.io",
       "notifiers": [
           {
               "userid": "manager9814",
               "position": "start"
           }
       ],
       "bizData": "{\"apiKey\":\"apiKey\",\"appUuid\":\"appUuid\",\"version\":\"1\"}"
   }
   
5. After the approval instance is created, go to the DingTalk Approval Center to view the four approval lists (Pending, Processed, Initiated, Received), search approval instance data, and perform approval actions.
6. Sync approval task data to DingTalk: using the approval instance processInstanceId and the tasks to-do list, call the Create Process Center pending task API to sync approval node information from the third-party system to DingTalk OA Approval, obtain the taskId of each to-do item, and generate the corresponding DingTalk to-do tasks. Note: In this scenario, synced approval tasks are handled by opening the business system’s detail page.
   {
       "processInstanceId": "zG1X1zwFTEiwzI0JB5w38A0964172381_xxxx",
       "activityId": "activityId_xxx",
       "tasks": [
           {
               "userId": "manager9814",
               "url": "https://www.dingtalk.io"
           }
       ]
   }
   
7. After the pending task is created, call the Query OA approval tasks integrated via Process Center API to query the user’s running approval tasks.
8. Sync approval task status to DingTalk: using the approval instance processInstanceId and the approval to-do taskId, call the Update Process Center task status API to sync status updates for your own approval to-dos. In scenarios such as parallel approval (OR-sign), call the Batch cancel OA Approval pending tasks API to set all running to-do items under an approval instance to CANCELED in bulk.
9. Sync approval instance status to DingTalk: using the approval instance processInstanceId, instance status, and instance result, call the Update instance status or Batch update instance status API to update the instance status.
10. Finally, to clean up approval template data, call the Delete template API to delete the approval template created for the organization. Instances and to-do tasks created under that template are deleted as well.

​

6. APIs used

​

1. Approval form

​

2. Approval instance

​

3. Process Center tasks

​

7. Related documents