PolarDB:Synchronize SharePoint documents to a knowledge base

Scope of application

Before you begin, make sure that you have prepared the following resources:

• A PolarDB knowledge base that has been created. For more information, see Use enterprise knowledge spaces.

• A SharePoint Online organization tenant and the document library to be synchronized.

• Permissions to register applications in Microsoft Entra, and access to a Microsoft Entra administrator who can grant admin consent.

• Access permissions to the SharePoint site and document library to be synchronized. You must be able to open the target directory and copy its address. To verify the synchronization of file updates, you also need edit permissions on the synchronized files. The following SharePoint Online environments are supported:

  Environment	Example SharePoint domain
  Global Microsoft 365	contoso.sharepoint.com
  Microsoft 365 operated by 21Vianet	contoso.sharepoint.cn

  Note

  On-premises SharePoint Server is not supported. Personal OneDrive addresses (whose domain contains -my.sharepoint.) are not supported either.

Workflow

1. Register a Microsoft Entra application and obtain the directory (tenant) ID and the application (client) ID.

2. Create a client secret for the application.

3. Grant Microsoft Graph SharePoint site read permissions to the application and grant admin consent.

4. Copy the full address of the SharePoint document library or folder to be synchronized.

5. Create a SharePoint synchronization link in PolarDB. Enter the application credentials, SharePoint address, and synchronization interval.

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

   Note

   Synchronized files are saved in their original format without conversion. Whether a file can be parsed by the knowledge base depends on the file formats currently supported by the knowledge base. For more information, see Synchronization behavior and file formats.

Step 1: Register a Microsoft Entra application

1. Log on to the Microsoft Entra admin center for the tenant to which your SharePoint site belongs.

2. Go to Microsoft Entra ID > App registrations and click New registration.

3. Enter an application name, for example, PolarDB SharePoint Document Sync.

4. Under Supported account types, select Accounts in this organizational directory only (Single tenant) and complete the registration. You do not need to configure a redirect URI.

5. On the Overview page of the application, copy and securely store the following information:

   • Directory (tenant) ID: enter this value in TenantId when you create the synchronization link.

   • Application (client) ID: enter this value in ClientId when you create the synchronization link.

   Important

   Do not use the Object ID as ClientId. Otherwise, the synchronization link creation will fail.

Step 2: Create a client secret

1. On the application page, go to Certificates & secrets > Client secrets.

2. Click New client secret, enter a description, and select an expiration period.

3. Immediately copy the value in the Value column after the secret is created. Enter this value in ClientSecret when you create the synchronization link.

   Important

   The value of a client secret is displayed only once after it is created. Do not use the Secret ID, and do not transmit the client secret in plain text by email, instant messaging, or screenshots. If you did not copy the value in time, create a new client secret and use the new value to create the synchronization link.

Step 3: Grant Microsoft Graph permissions

1. On the application page, go to API permissions > Add a permission.

2. Select Microsoft Graph > Application permissions.

3. Search for and add the following permission:

   API	Permission type	Permission	Purpose
   Microsoft Graph	Application	Sites.Read.All	Read the content of SharePoint sites, document libraries, folders, and files.

4. Click Grant admin consent for your organization.

5. Confirm that the permission status shows that consent has been granted for the current organization.

Step 4: Get the SharePoint document library or folder address

1. Open the SharePoint site to be synchronized in a browser.

2. Go to the target document library:

   • To synchronize the entire document library, stay in the root directory of the document library.

   • To synchronize a single folder, open that folder.

3. Copy the full address from the browser address bar.

   Note

   Copy the document library view address directly from the browser address bar. Do not enter a sharing link or short link of a single file or a personal OneDrive address. You do not need to manually obtain the site ID, document library ID, or folder ID.

   Format requirements:

   • Use HTTPS.

   • The domain ends with .sharepoint.com or .sharepoint.cn.

   • The path ends with /Forms/AllItems.aspx.

   • To synchronize a subfolder, the address contains the id query parameter that points to that folder.

   Examples:

   1. Example address for synchronizing an entire document library:

      https://contoso.sharepoint.com/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx

   2. Example address for synchronizing a specified folder in a document library:

      https://contoso.sharepoint.com/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FKnowledge%2FShared%20Documents%2FProductDocs

   3. Example address for the 21Vianet environment:

      https://contoso.sharepoint.cn/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx

Step 5: Create a SharePoint synchronization link

You can create a SharePoint synchronization link in the console or by calling the CreateKBSyncLink OpenAPI operation.

When you create the link, PolarDB uses the application credentials that you entered to access Microsoft Graph and verifies that the target site, document library, and folder are readable. After the link is created, the system returns a synchronization link ID that starts with pkbl-. Keep a record of this ID. It is required when you query the link, adjust the synchronization interval, or delete the link.

Step 6: Verify the synchronization result

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

2. Wait for at least one synchronization cycle. The first synchronization needs to recursively scan directories, download files, and complete ingestion and indexing. It may take longer if there are many files.

3. Open the file list of the target knowledge base and confirm that files from SharePoint have appeared.

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

Synchronization behavior and file formats

• The system recursively scans the subfolders in the selected document library or folder.

• SharePoint files are downloaded and synchronized in their original format and are not converted to other formats.

• Whether a file can be parsed by the knowledge base depends on the file formats currently supported by the knowledge base.

• SharePoint list items, web pages, and folders that are used only as directories are not synchronized as files.

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

• TenantId, ClientId, and ClientSecret must belong to the target SharePoint organization tenant. The cloud environment of the application must match the cloud environment of the SharePoint address: a global Microsoft 365 tenant uses .sharepoint.com addresses, and a Microsoft 365 tenant operated by 21Vianet uses .sharepoint.cn addresses.

FAQ

• Q: The synchronization link fails to be created.

  A: Check the following items in order:

  • Whether TenantId is the directory (tenant) ID.

  • Whether ClientId is the application (client) ID rather than the Object ID.

  • Whether ClientSecret is the value of the client secret, whether it is complete, and whether it is still valid.

  • Whether Sites.Read.All is added as an application permission and admin consent has been granted.

  • Whether SourceDir is the full document library view address from the browser address bar and ends with /Forms/AllItems.aspx.

  • Whether the application tenant and the SharePoint address belong to the same organization and use the same environment (global Microsoft 365 or Microsoft 365 operated by 21Vianet).

• Q: Only some files are synchronized.

  A: Common causes include:

  • SourceDir points to a subfolder in the document library rather than the root directory of the document library.

  • The formats of some files are not within the parsable scope of the knowledge base.

  • The ingestion or indexing of the files has not been completed.

• Q: Modified files are not updated immediately.

  A: The synchronization task runs at the interval specified by SyncIntervalMinutes. After the source files are downloaded, ingestion and indexing are still required. Wait for the next synchronization cycle and allow time for file processing.