PolarDB:Sync Feishu documents to a knowledge base

Scope of application

Before you start, make sure that the following resources are ready:

• A PolarDBknowledge base is created. For more information about how to create a knowledge base, see Use enterprise knowledge spaces.

• Feishu enterprise administrator or application administrator permissions, which are required to approve application permissions and publish the application.

• Administrator permissions on the folder or wiki to be synchronized, which are required to authorize the resources to the application.

Workflow overview

1. Create a Feishu enterprise self-built application and obtain the App ID and App Secret.

2. Enable the read, download, and export permissions for cloud documents. If you want to synchronize a Feishu wiki, also enable the wiki read permission.

   Note

   • If the target knowledge space was created with Document ACL enabled, also enable the read permissions for users, departments, groups, and wiki members.

   • When you synchronize documents to a permission-aware space that has Document ACL enabled, the source-side access permissions of Feishu documents are inherited by the documents in the knowledge base. Users, user groups, and departments from Feishu are mapped to standardized permission principals and synchronized to the retrieval index for document-level ACL filtering. No additional permission principal configuration is required when you create a Synchronization Link. The permissions mentioned in other steps of this topic refer to the API permissions (scopes) of the Feishu enterprise self-built application, which are different from the document-level ACL of the knowledge space.

3. Authorize the folder or wiki to be synchronized to the application.

4. Create a Feishu synchronization link in PolarDB and specify the application credentials, the Feishu resource link, and the synchronization interval.

5. Wait for the next synchronization cycle and check the files in the target knowledge base.

Step 1: Create a Feishu enterprise self-built application

1. Log on to the Feishu Open Platform and click Developer Console.

2. Click Create Enterprise Self-Built App and enter the application name, description, and icon. We recommend that you use an easy-to-recognize name, for example, PolarDB Document Sync Assistant.

3. Go to the Credentials and Basic Information page of the application, and copy and securely store the following information:

   • App ID

   • App Secret

4. Go to App Capabilities > Add App Capability and add the bot capability so that you can search for the application in Feishu and authorize resources to it later.

Step 2: Enable API permissions

1. In the Feishu application admin console, go to the Permissions page.

2. Enable the app identity permissions listed in the following table.

   Manual

   Permission	Scope	Scenario
   View file metadata in the drive	drive:drive.metadata:readonly	Feishu drive and wiki
   View and download files in the drive	drive:file:readonly	Feishu drive and wiki
   Export cloud documents	docs:document:export	Feishu drive and wiki
   List cloud documents in a drive folder	space:document:retrieve	Feishu drive folder. Used to traverse the target folder and its subfolders.
   View wiki	wiki:wiki:readonly	Required only when you synchronize a Feishu wiki.

   If the target knowledge space was created with Document ACL, enable the following app identity permissions in addition to the permissions in the preceding table:

   Permission	Scope	Purpose
   Get basic enterprise information	tenant:tenant:readonly	Retrieves the Feishu tenant identifier to establish the namespace for ACL user identities.
   View cloud document collaborators	docs:permission.member:retrieve	Reads the collaborators of documents and folders and their access permissions.
   Get basic address book information	contact:contact.base:readonly	Queries the address book users that correspond to document collaborators.
   Get user employee IDs	contact:user.employee_id:readonly	Converts collaborator identities into stable user_id.
   Get group members	im:chat.members:read	Reads group members and synchronizes effective ACL when a document is authorized to a group or group chat.
   Get wiki space members	wiki:member:retrieve	Reads the members of a wiki space when the wiki space is a document permission subject. Required only when you synchronize a Feishu wiki.

   Batch import

   You can go to and import the following content:

   {
     "scopes": {
       "tenant": [
         "docs:document:export",
         "drive:drive.metadata:readonly",
         "drive:file:readonly",
         "space:document:retrieve",
         "wiki:wiki:readonly"
       ]
     }
   }

   If the target knowledge space was created with Document ACL, you can import the following full permission list:

   {
     "scopes": {
       "tenant": [
         "contact:contact.base:readonly",
         "contact:user.employee_id:readonly",
         "docs:document:export",
         "docs:permission.member:retrieve",
         "drive:drive.metadata:readonly",
         "drive:file:readonly",
         "im:chat.members:read",
         "space:document:retrieve",
         "tenant:tenant:readonly",
         "wiki:member:retrieve",
         "wiki:wiki:readonly"
       ]
     }
   }

   Note

   For Get basic address book information (contact:contact.base:readonly) and Get user employee IDs (contact:user.employee_id:readonly), we recommend that you set the accessible data scope of the application to All members of the organization. If the data scope does not include a document collaborator, the system may fail to retrieve the user information, and the Document ACL information of that user is missing.

3. Create an application version, submit it for administrator review, and publish it. New permissions take effect only after the application version is published.

Step 3: Authorize the resources to synchronize

After you enable the API permissions, the application does not automatically gain access to all documents in the tenant. You must authorize the specific resources to be synchronized to the application.

Step 4: Create a Feishu synchronization link

You can create a Feishu synchronization link by using the console or the CreateKBSyncLink operation.

After the synchronization link is created, the system returns a synchronization link ID that starts with pkbl-. Record the ID for later use when you query the link, adjust the synchronization interval, or delete the link.

Step 5: Verify the synchronization result

1. Confirm that the synchronization link has been created and the link status is normal.

2. Wait for at least one synchronization cycle. Feishu documents require additional time for download, ingestion, and indexing. The first synchronization of a large number of documents may take longer.

3. Go to the file list of the target knowledge base and confirm that the files from Feishu have appeared.

4. Modify a synchronized Feishu document, wait for the next synchronization cycle, and then check whether the file in the knowledge base has been updated.

Supported file types

Synchronization links support the following Feishu file types:

Precautions

• Each synchronization link supports only one Feishu folder, one wiki space, or one wiki node. To synchronize multiple directories, create separate synchronization links.

• If a subnode in a folder or wiki has independent access restrictions, the application may not be able to read the node. Make sure that the application has at least read access to the target node.

• The current version synchronizes newly added and updated files, but does not automatically delete the corresponding files in the knowledge base when files are deleted from the Feishu source. To delete files, handle them separately in the knowledge base.

• Document permission changes on the Feishu side, such as adjusting collaborators or changing folder permissions, are incrementally propagated to the knowledge base by the synchronization task. Before the propagation is complete, the system follows a deny-first policy and temporarily excludes documents whose permission status has not yet been updated to avoid returning potentially unauthorized content. After permissions are granted, the affected documents may need to wait for the next synchronization cycle and indexing to complete before they can be retrieved.

FAQ

• Q: Only some files are synchronized.

  A: Common causes include:

  • Some subfolders or subnodes have not granted read access to the application.

  • The target directory contains Feishu file types that are not supported by the current synchronization link.

  • The format of common uploaded files is not within the parseable range of the knowledge base.

• Q: The document is not immediately updated after modification.

  A: The synchronization task runs at the interval specified by theSyncIntervalMinutes parameter. After the source document is downloaded, additional ingestion and indexing are required. Wait for the next synchronization cycle and allow time for document processing.

• Q: After Document ACL is enabled, some users cannot see the synchronized documents in the knowledge base.

  A: Common causes include:

  • The incremental ACL permissions in Step 2 are not enabled for the application.

  • The accessible data scope of the application address book does not include the collaborator.

  • The user does not have read access to the source document in Feishu.

  • The document authorization principal is a group or wiki space, but the application has not enabled the im:chat.members:read or wiki:member:retrieve permission.