Integrate Data Agent with Lark

Overview

Data Agent is an AI assistant built into the DataWorks platform. It provides built-in skills for data integration, data development, data governance, and data security. You can use natural language to create data synchronization tasks, generate and debug SQL statements, troubleshoot data quality issues, and query data lineage. The IM channel feature allows you to connect a Data Agent instance to instant messaging tools such as DingTalk, Lark, and WeCom as a bot. After the connection is established, team members can invoke all capabilities of Data Agent by mentioning the bot in their daily communication tool, without having to log on to the DataWorks console.

Prerequisites

• A Data Agent instance is created and is in the Running state.

• A resource group is bound to the Data Agent instance. This is a prerequisite for testing network connectivity.

• You have enterprise administrator or app administrator permissions on the Lark Open Platform.

Step 1: Create a Lark application and obtain credentials

1. Go to the Lark Open Platform. Click Create Enterprise App. Enter the application name and description, select an application icon, and then click OK.

2. In the left-side navigation pane, click Credentials & Basic Info. Copy the App ID (for example, cli_xxx) and App Secret. You will need them later when you configure the Data Agent channel.

3. In the left-side navigation pane, click Permission Management. Click Batch Import/Export Permissions. Paste the following JSON configuration, click Next, confirm the New Permissions, and then click Apply.

     "scopes": {
       "tenant": [
         "contact:contact.base:readonly",
         "docx:document:readonly",
         "im:chat:readonly",
         "im:chat:update",
         "im:message.group_at_msg:readonly",
         "im:message.p2p_msg:readonly",
         "im:message.pins:read",
         "im:message.pins:write_only",
         "im:message.reactions:read",
         "im:message.reactions:write_only",
         "im:message:readonly",
         "im:message:recall",
         "im:message:send_as_bot",
         "im:message:send_multi_users",
         "im:message:send_sys_msg",
         "im:message:update",
         "im:resource",
         "application:application:self_manage",
         "cardkit:card:write",
         "cardkit:card:read"
       ],
       "user": [
         "contact:user.basic_profile:readonly",
         "contact:user.employee_id:readonly",
         "offline_access",
         "base:app:copy",
         "base:field:create",
         "base:field:delete",
         "base:field:read",
         "base:field:update",
         "base:record:create",
         "base:record:delete",
         "base:record:retrieve",
         "base:record:update",
         "base:table:create",
         "base:table:delete",
         "base:table:read",
         "base:table:update",
         "base:view:read",
         "base:view:write_only",
         "base:app:create",
         "base:app:update",
         "base:app:read",
         "board:whiteboard:node:create",
         "board:whiteboard:node:read",
         "calendar:calendar:read",
         "calendar:calendar.event:create",
         "calendar:calendar.event:delete",
         "calendar:calendar.event:read",
         "calendar:calendar.event:reply",
         "calendar:calendar.event:update",
         "calendar:calendar.free_busy:read",
         "contact:contact.base:readonly",
         "contact:user.base:readonly",
         "contact:user:search",
         "docs:document.comment:create",
         "docs:document.comment:read",
         "docs:document.comment:update",
         "docs:document.media:download",
         "docs:document:copy",
         "docx:document:create",
         "docx:document:readonly",
         "docx:document:write_only",
         "drive:drive.metadata:readonly",
         "drive:file:download",
         "drive:file:upload",
         "im:chat.members:read",
         "im:chat:read",
         "im:message",
         "im:message.group_msg:get_as_user",
         "im:message.p2p_msg:get_as_user",
         "im:message:readonly",
         "search:docs:read",
         "search:message",
         "space:document:delete",
         "space:document:move",
         "space:document:retrieve",
         "task:comment:read",
         "task:comment:write",
         "task:task:read",
         "task:task:write",
         "task:task:writeonly",
         "task:tasklist:read",
         "task:tasklist:write",
         "wiki:node:copy",
         "wiki:node:create",
         "wiki:node:move",
         "wiki:node:read",
         "wiki:node:retrieve",
         "wiki:space:read",
         "wiki:space:retrieve",
         "wiki:space:write_only"
       ]
     }
   

4. In the left-side navigation pane, click Add App Capability. On the Add by Capability tab, find the Bot card and click Add.

5. In the left-side navigation pane, click Events & Callbacks. On the Event Configuration tab, click Subscription Mode and select Receive events via long connection. Click Save.

6. On the Event Configuration page, click Add Event. On the Subscribe as Application tab, search for "message" and select Receive message, Message reacted, and Message reaction removed. Click Confirm.

7. In the left-side navigation pane, click Version Management and Release. Create a version, enter the Version Number and Release Notes, click Save, and then submit the version for review and publish it.

Step 2: Test network connectivity

Before you configure the Lark IM channel, make sure that the network connection between the Data Agent instance and Lark is established.

1. Log on to the DataWorks console. In the left-side navigation pane, click Data Agent. Open the target instance.

2. In the left-side navigation pane, click IM Channels.

   The IM Channels page displays channel cards for DingTalk, Lark, and WeCom. Each card shows the current configuration status, network status, and enablement status.

3. On the Lark channel card, click Test Network Connectivity to verify the network connection between Data Agent and Lark.

   • If the channel card shows Connected, the network is ready. Proceed to the next step to configure the IM channel.

   • If the channel card shows Unreachable, proceed to enable the channel network.

4. (Required only if the connectivity test fails) Click Enable Channel Network.

   Data Agent provides a Minimal Setup (recommended) option: only the unreachable channel domains are configured with PrivateZone and PrivateLink, minimizing the impact scope.

   Note

   Minimal Setup is a VPC-level network change. After the setup is complete, other instances in the same VPC can also access the corresponding channel domains. Before you proceed, make sure that all instances in the VPC can share this network access scope.

5. In the vSwitch Zone drop-down list, select a vSwitch for each availability zone. Click Connect with One Click. The system automatically configures PrivateZone DNS resolution and PrivateLink. The setup takes approximately 1 to 5 minutes.

   To have more granular control over the network configuration, click Manage Network to go to the resource group network configuration page. Click Retest to retest the connectivity of each channel at any time.

6. After the setup is complete, the system automatically retests the connectivity. After you confirm that the channel card shows Connected, proceed to configure the IM channel.

Step 3: Configure the Lark IM channel

After the network connection is established, configure the Lark application credentials to connect Data Agent to Lark.

1. On the Lark channel card, click Configure. In the IM channel configuration dialog box, configure the following parameters:

   Parameter	Description
   App ID	The App ID of the Lark application obtained in Step 1.
   App Secret	The App Secret of the Lark application obtained in Step 1.

2. Click Advanced Settings to expand additional settings. Configure the following parameters as needed:

   Category	Parameter	Description
   Session Management	Session Isolation	Specifies whether conversation contexts are isolated between different users or group chats. Valid values: By User: Each user has an independent conversation context. By Group/Topic: Messages in the same group chat or topic share one conversation. This is suitable for group collaboration scenarios. Shared: All users share the same conversation context.
   Permission Management	User Access	Specifies which users can interact with the bot. Valid values: All Members: All members in the organization can use the bot. Allowlist Only: Only users in the allowlist can use the bot. Pairing: First-time users who message the bot will receive a pairing code, access is granted once an administrator approves it. Users already on the allowlist do not need to pair.
   	Allow Group Chat	When enabled, the bot responds only when mentioned or replied to in group chats. You can further configure the Responsive Group Chats scope: All Group Chats: The bot responds in all group chats. Specified Group Chats: The bot responds only in specified group chats.
   Message Processing	Busy Handling	Specifies how new messages are handled when the bot is processing a message. Valid values: Interrupt and Redirect: Cancels the current task and processes the new message. Collect and Merge: Merges the new message with the current task. Queue: Queues new messages and processes them in order.
   	Group Chat Context Backfill	When set to a positive integer, authorized group messages that do not mention the bot are cached and used as context the next time the bot is triggered. Set to 0 or leave empty to disable this feature.
   	Streaming Response	When enabled, the bot sends multiple short messages paragraph by paragraph during the response process, instead of waiting for the complete response. This is suitable for scenarios that require fast feedback. Disabled by default.

3. Click Save after you complete the configuration.

Step 4: Test the Lark bot

After the configuration is complete, add the bot to Lark and test it.