Integrate DingTalk Approval Workflow

NineData integrates deeply with the DingTalk approval system, allowing you to initiate, approve, and revoke data-management task workflows in DingTalk to ensure audit compliance and workflow automation.

Prerequisites

• You have already created or joined an organization, and the organization has subscribed to DevOps Enterprise. Please ensure that your annual or monthly subscription is still active. For more information, please refer to Manage Organizations.
• Your current account has been switched to the target organization. For more information, please refer to Switching to an Organization.

• Sign in to the DingTalk Open Platform with an enterprise administrator account.
• Your NineData deployment is the dedicated cluster edition.
• You have system administrator permissions in NineData.
• Your DingTalk enterprise has already configured the organization structure, contact directory, employee mobile numbers, and other basic information.

Step 1: Create a custom app in the DingTalk Open Platform

1. Sign in to the DingTalk Open Platform with an enterprise administrator account.

2. Click Create App in the upper-right corner of the page.

3. Fill in the following information on the creation page, click Save, and the browser automatically jumps to the app details page.

   • App name: for example, NineData-Approval Integration.
   • App description: for example, Used for NineData task approval workflow integration.
   • App icon (optional): upload the corresponding icon.

4. In the left navigation pane, click Basic Information > Credentials & Basic Information, and record the values of Client ID and Client Secret.

   

5. In the left navigation pane, click Development Configuration > Permission Management, locate and select the following permissions, and then click Batch Apply on the right side of the page.

   • Workflow instance write permission
   • Workflow template read permission
   • Workflow instance read permission
   • Employee mobile phone information (permission ID: fieldMobile)
   • Member information read permission (permission ID: qyapi_get_member)
   • Get basic member information by mobile number (permission ID: qyapi_get_member_by_mobile)
   • Approval workflow data management permission
   Note

   In addition to workflow permissions, make sure the contact-related permissions above are also granted, especially Employee mobile phone information, Member information read permission, and Get basic member information by mobile number. If any of these permissions are missing, NineData may fail to obtain approver information when querying DingTalk approval workflow details, and the approver will not be displayed.

   In the DingTalk Open Platform, Member information read permission usually needs to include APIs such as Query user details, Get user ID list by department, and Get administrator list. If the page also shows Get executive mode setting, it is recommended to authorize it as well so the returned user information is complete.

Step 2: Create an approval template in the DingTalk admin console

1. Sign in to the DingTalk admin console with an enterprise administrator account.

2. In the left navigation pane, click Workbench > Application Management.

   tip

   The navigation pane is long. If you cannot find Workbench, scroll down the page.

3. In the Application Name list, find OA Approval, and click Enter in the Operation column on the right.

   

4. In the upper-right corner, click Create Approval Form. In the pop-up dialog box, configure the following parameters, and then click Form Design at the top of the page. For more information, see the official DingTalk documentation.

   

   • Form name: for example, NineData Approval Workflow.
   • Group: select the group where the current workflow belongs. You can create a new group or select an existing one.
   • Who can initiate: select which departments or members can initiate this workflow.
   • Form administrator: specify one or more members as the administrators of the current workflow.

5. On the Form Design page, design the form as needed, and then click Process Design at the top of the page.

   

   • Drag controls on the left, such as text, single choice, and attachment, into the form area.
   • Configure the title, field name, whether the field is required, and prompt information for each control.
   • For detailed NineData task types and subtypes, see Appendix 3.

6. On the Process Design page, design the approval workflow based on your enterprise organization structure.

   

7. Click Publish in the upper-right corner, and then click Done in the pop-up dialog box. The browser automatically jumps to the Form Management page. Find the form you just created and record the generated form ID.

   

Step 3: Bind the DingTalk app in NineData

1. Log in to the NineData Console.

2. In the left navigation pane, click DevOps > Policy & Process.

3. Click the Approval Process tab, and then click External approve channel on the right side of the page.

4. Click Add External Approval Channel, enter the following parameters in the pop-up dialog box, and click OK to finish binding the app.

   Parameter	Description
   Channel Name	Custom name of the approval channel, used to distinguish different external approval systems in NineData. Example: DingTalk Approval Workflow.
   Channel Type	Select the type of the external approval channel. Choose DingDing here. NineData calls the corresponding API logic based on this type.
   AppID	The unique identifier of the app in the DingTalk Open Platform. It corresponds to the Client ID obtained in Step 1.
   AppSecret	The secret of the app, used to verify the legitimacy of the communication between NineData and the DingTalk Open Platform. It corresponds to the Client Secret obtained in Step 1.
   Signed Token	Leave this empty for now. It will be generated later when you configure event subscription in the DingTalk Open Platform.
   AesKey	Leave this empty for now. It will be generated later when you configure event subscription in the DingTalk Open Platform.

5. Click the newly bound app ID and record Callback url at the bottom of the page. You will use it later when configuring event subscription on the DingTalk side. The URL must be publicly accessible.

6. Click the Approval Workflow Mapping Definition tab, and then click Add approval progress definition. Configure the parameters according to the following table.

   Parameter	Description
   Associated Applications	Select the app you just bound.
   Name	Custom name of the approval workflow mapping.
   Approval Definition ID	The ID of the approval template created in the DingTalk admin console. It corresponds to the form ID obtained in Step 2.
   Approval Workflow Configuration	This configuration allows you to define each node in the approval workflow in detail based on actual business needs, and to verify whether the workflow can run through by using the test function. For examples of each workflow configuration, see Appendix 1.

7. Click OK to complete the configuration.

Step 4 (Optional): Configure event subscription in the DingTalk Open Platform

1. Return to the DingTalk Open Platform and open the app you created earlier.

2. In the left navigation pane, click Development Configuration > Event Subscription, and configure the parameters according to the following table.

   Parameter	Description
   Push method	Select HTTP Push.
   Encrypted aes_key	Click the icon on the right to generate an encrypted aes_key. Paste the generated aes_key into the aes_key of the app bound in NineData.
   Signature token	Click the icon on the right to generate a signature token. Paste the generated token into Signed Token of the app bound in NineData.
   Request URL	Enter the callback URL provided by NineData.

3. Click Save, and then turn on Approval Event under Event Subscription below. Event subscription is now configured.

Step 5: Bind the approval workflow

1. Log in to the NineData Console.

2. In the left navigation pane, click DevOps > Policy & Process.

3. Click the Approval Process tab, find the target approval workflow that needs DingTalk approval enabled, click the workflow name, and go to the Details page.

4. Click the tab of the task type to be configured, and then click Edit on the right side of the target workflow. Select Launch External Approval Workflow at the bottom of the Edit Process page, choose the DingTalk app in the selector on the left, then choose the corresponding DingTalk workflow ID on the right, and click OK.

   

Appendix 1: Example script for NineData approval workflow configuration

• Token Acquisition (Required): Use the authentication information of the app created in DingTalk to obtain the accessToken. You only need to replace reqBody.put("appKey",APP_ID) and reqBody.put("appSecret",APP_SECRET) with the actual DingTalk Open Platform credentials, where appKey corresponds to Client ID and appSecret corresponds to Client Secret.

  

  Example:

  reqBody.put("appKey","dingxxxxxxxxxxxxxxx")
  reqBody.put("appSecret","In4cWXZedWRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

• Create Approval Workflow (Required): NineData uses this API to submit task data to DingTalk. DingTalk then creates an instance on the specified approval template and starts the approval workflow. You only need to define the form format in the script and map NineData internal platform task fields such as task name, database name, and approval reason to the external approval template fields in the DingTalk approval form created earlier.

  

  Note

  • Field mapping: The name in fluentPut must strictly match the field name in the DingTalk template form.

  • Variable parameters: For the value in fluentPut, see Appendix 2.

  • Keep the InstanceID: After the test of the current workflow succeeds, you can keep the returned approvalInstanceId to continue testing Revoke Approval Workflow.

    

  Example:

  fromField.add(new JSONObject().fluentPut("name","Task ID").fluentPut("value",TASK_ID))
  fromField.add(new JSONObject().fluentPut("name","Task Name").fluentPut("value",TASK_NAME))
  fromField.add(new JSONObject().fluentPut("name","Task Type").fluentPut("value",TASK_TYPE))
  fromField.add(new JSONObject().fluentPut("name","Subtype").fluentPut("value",TASK_SUBTYPE))
  fromField.add(new JSONObject().fluentPut("name","Data Source Name").fluentPut("value",DATASOURCE_NAME))
  fromField.add(new JSONObject().fluentPut("name","Database").fluentPut("value",DATABASE))
  fromField.add(new JSONObject().fluentPut("name","Environment").fluentPut("value",ENV_NAME))
  fromField.add(new JSONObject().fluentPut("name","Reason").fluentPut("value",REASON))
  fromField.add(new JSONObject().fluentPut("name","Permission Request Type").fluentPut("value",AUTH_APPLY_TYPE))
  fromField.add(new JSONObject().fluentPut("name","SQL Text").fluentPut("value",SQL_CONTENT))
  String multiValue = String.format("%s, %s, %s",TASK_URL,AUTH_SENSITIVE,EXPORT_OBJECT)
  fromField.add(new JSONObject().fluentPut("name","Summary").fluentPut("value",multiValue))
  fromField.add(new JSONObject().fluentPut("name","Remarks").fluentPut("value",COMMENT))

• "Revoke Approval Workflow" (Required): Before the approval ends, you can revoke an initiated approval instance by the approval workflow instance ID, approvalInstanceId.

  You do not need to modify the script for this workflow. For testing, only accessToken and the target workflow approvalInstanceId are required.

  

• Callback Approval Workflow Notification (Optional): When key status changes occur in the DingTalk approval workflow, such as approved, rejected, terminated, transferred, or copied, DingTalk actively sends event notifications to the callback URL provided by NineData. NineData then parses the message and maps it back to the internal task status.

  You do not need to modify or test this workflow. Keep the default configuration.

• Synchronize Approval Workflow Status (Required): Use this workflow when you need to actively confirm approval progress or obtain more detailed information, such as the form, operation records, or approvers.

  You do not need to modify the script for this workflow. For testing, only accessToken and the target workflow approvalInstanceId are required.

  

Appendix 2: Form field parameter list

Variable Code	Meaning
TASK_NAME	Task name
TASK_ID	Task ID
TASK_TYPE	Task type
TASK_SUBTYPE	Subtype
COMMENT	Remarks
ENV_NAME	Environment
DATASOURCE_NAME	Data source name
DATASOURCE_URL	Data source URL
DATABASE	Database name
EXPORT_METHOD	Export method
EXPORT_CONTENT	Export content
REASON	Reason
AUTH_TYPE	Request type
SUBMITTER	Submitter
SQL_CONTENT	SQL text (summary, first 200 characters)
SQL_FULL_CONTENT	SQL text (full text, up to 5000 characters)
TASK_URL	Task request URL
FILE_TYPE	Export/import file type
AUTH_SENSITIVE	Sensitive column
AUTH_EXPIRATION_TIME	Permission validity period
AUTH_APPLY_TYPE	Permission type
CREATE_TIME	Submission time
EST_AFFECTED_ROWS	Estimated affected rows
AUTH_APPLY_OBJECT_DB	Requested database
AUTH_APPLY_OBJECT_TB	Requested table
DATASOURCE_ID	Data source ID
EXECUTOR	Executor
EXPORT_OBJECT	Export object, including database or table information, or SQL statements
TASK_DETAILS	Task details
SUBMITER_PHONE	Submitter mobile number
APPROVAL_CODE	External approval template code

Appendix 3: NineData task types and subtypes

Task Type	Subtype
SQL task (including schema design and release)	Must improve
	Suggested improvement
	Compliant
Permission request	Data source
	Database
	Table permission
	Apply for Sensitive Column - S1
	Apply for Sensitive Column - S2
	Apply for Sensitive Column - S3
	Apply for Sensitive Column - S4
	Apply for Sensitive Column - S5
Data export	SQL export
	Export database
	Export table
Data import	Fast mode
Data generation	Data generation
Data tracking and rollback	Data tracking and rollback
Data archiving and cleanup	Cleanup
	Archive
	Cleanup + Archive
SQL code review	SQL review - Recommended index
	SQL review - Must improve
	SQL review - Suggested improvement
	SQL review - Compliant