Configure a WPS Bitable data source
The WPS Bitable data source reads data from WPS Bitable through Offline Sync and writes it to the platform's built-in data warehouse. This article covers application authorization in WPS, data source configuration, sync plan creation, and mounting on a Flow.
Limitations and prerequisites
Before you start, confirm the following limitations and prerequisites:
- WPS Bitable is supported only as a data source. The Data Target is the platform's built-in data warehouse; writing back to WPS Bitable is not supported.
- Prepare a WPS enterprise account. Authorized personnel need to create an enterprise custom application, request API permissions, and submit an application version for review. Ask the enterprise administrator to confirm that the enterprise has the required open platform entitlements.
- Prepare the document link for the target WPS Bitable, confirm that the application has permission to read the file, and identify the Data Table and view to read.
- The platform's runtime environment must be able to access the WPS Open Platform. If the application has an IP allowlist enabled, prepare the actual egress IP addresses of the servers in advance.
- The fields available for reading are determined by the selected Data Table and view. First confirm the fields and content in the data preview.
| Environment configuration | Use cases | Requirements |
|---|---|---|
| not distinguish environment | The development and production environments share one WPS application | Enter one set of App ID, App Key, and API request signing settings |
| Independent setting | The development and production environments use different WPS application configurations | Configure each environment separately; both applications must have access to the document, Data Table, and view selected in the plan |
Configuration validation and data preview use the development environment configuration, while manual execution uses the production environment configuration. With independent settings, check application permissions, document read permissions, API request signing, and server egress IP addresses in both environments.
Complete authorization in the WPS Open Platform
- Prepare an enterprise account. Sign in to WPS 365 and follow the prompts to create an enterprise, or ask the enterprise administrator for an invitation to join an existing enterprise. Then use the same account to sign in to the WPS Developer Console and select the enterprise for this integration. The enterprise administrator needs to confirm the required open platform capabilities and entitlements with WPS.
- Create an enterprise custom application. In the Developer Console, click Create Application, select Enterprise Custom Application, and enter the name, description, and other information. After creation, obtain the App ID and App Key, and provide them to the person responsible for configuring the data source. For details, see Create an enterprise custom application.
- Request read permission and complete the review. In the application's Permission Management, request the permission listed below and select Application authorization (app) as the permission type. Then create an application version and submit it for release. The permission takes effect only after the enterprise administrator approves it. See Configure application capabilities.
| Feature name | Permission scope | Permission type |
|---|---|---|
| Query Bitable | kso.dbsheet.read | Application authorization (app) |
- Prepare document read permissions. Ask the person responsible for the document to check the ownership, access scope, and permission settings of the target Bitable to ensure that the application can read the document. Both API permissions and file permissions must meet the requirements. Being able to open the document in your browser does not mean that the application has read access. For file read permission requirements, see the WPS Bitable read instructions. Copy the document link for later configuration, for example,
https://www.kdocs.cn/l/ExampleID. - Configure security settings. In the application's Security Settings, configure API request signing according to your enterprise security requirements and inform the person responsible for the integration of its status, so that the WPS settings and data source configuration match. If an IP allowlist is required, ask your operations team for the actual egress IP addresses of the servers that access WPS and add all required addresses to the allowlist. Enter server egress IP addresses, not the IP address of the computer running the browser. Configure all addresses if different environments or nodes have different egress addresses. See WPS API request flow and security configuration.
Keep the App Key secure and use a secure method to hand it over. Avoid exposing it in screenshots, logs, or public documentation. Before changing API request signing or the IP allowlist for an application that is already integrated, confirm with the person responsible for the integration to avoid affecting existing sync tasks.
Create a WPS Bitable data source
- Go to DataOps Platform > Integration > Data Source and click + Data Source.
- Select WPS Bitable, click Next step, and enter the data source name and remarks.
- Select not distinguish environment or Independent setting. With independent settings, you need to configure the development and production environments separately.
- Enter the application's App ID and App Key, and configure API request signing to match the security settings of the WPS application.
- In Test Connection, click Test. After confirming that application authentication succeeds, click Complete.
| Configuration Item | Description |
|---|---|
| App ID | The App ID of the WPS enterprise custom application |
| App Key | The App Key of the corresponding application |
| API request signing | Match the API request signing settings of the WPS application and configure them according to enterprise security requirements |
The connectivity test checks application authentication only. Document access and API request signing still need to be verified by loading data or previewing it in the next section. After the test succeeds, continue with source configuration and preview.
When you edit a saved data source, the App Key is masked by default. To replace the credentials, enter the new App Key, test the connection again, and verify document access.
Create an offline sync plan
- Go to DataOps Platform > Integration > Offline Sync and click + Integration plan.
- In Data Source, select WPS Bitable and the data source you created.
- In WPS Bitable URL, enter the document link, for example,
https://www.kdocs.cn/l/ExampleID, and click Check URL. - After the URL check and loading succeed, select the Data Table to read, and then select a View in it.
- Click Data Preview, check the fields and data content, and confirm that the current application can read the selected document.
Enter an HTTPS document link for WPS Bitable. After switching the data source, changing the URL, or switching the Data Table, check the Data Table, view, and Field Mapping again. You need to select a view again after switching the Data Table.
If you cannot find the Data Table or view, or cannot preview the data, first check whether the application's read permission has been approved and taken effect, along with document read permissions, API request signing, and IP allowlist settings. With independent settings, this step uses the development environment configuration. The production environment must also be able to read the same content selected in the plan.
Field mapping and sync verification
After configuring the data source, select the target table in the platform's built-in data warehouse and create field mappings. Source fields display the WPS field names when available.
Supported field types
WPS Bitable supports reading the content of fields visible in the selected view, including text, numbers, Boolean values, and array and object content returned by the API. For date, time, and formula fields, also use the data preview to confirm the actual returned content. Do not judge read results solely by field names or their display in WPS.
Source fields are uniformly displayed as strings (string). This does not limit support to WPS text fields.
Unsupported fields and limitations
If a field is deleted, hidden by the selected view, or inaccessible to the current application, synchronization cannot continue with the original field configuration. Refresh the source configuration and confirm the field scope again.
Configuration and verification
- In Data Target, select or create the target table and set the write mode as your business requires.
- In Field Mapping, map the source fields to the target fields.
- Fill in the plan name, owner, and remarks, then save the plan.
- Click Run Now, confirm in the execution records that the task succeeded, then check the fields and data content in the target table. Manual execution uses the production environment configuration, so check the credentials and permissions of the production application in advance.
The fields in the figure only illustrate the mapping interface. Select the fields to synchronize according to your actual business needs.
After WPS Data Tables, views, or fields change, refresh the source configuration and Field Mapping, and confirm that the selected view and mapped fields are still valid. If fields are deleted or hidden, check the mappings again before saving and running the plan.
| Symptom | What to check |
|---|---|
| Connectivity test fails | Check that the App ID and App Key are correct and the application is in a normal state |
| Connectivity test succeeds, but data cannot be loaded or previewed | Check that kso.dbsheet.read uses application authorization and has been approved and taken effect, that the application has document read permission, and that API request signing and the IP allowlist are configured correctly |
| URL check fails | Use a standard WPS Bitable HTTPS document link, and confirm that the document still exists and the application can read it |
| Data Table or view not found | Confirm that the options have not been deleted, refresh the lists, and select them again; select a view again after switching the Data Table |
| A message indicates that mapped fields have been deleted or hidden | Check the fields and view settings in WPS, refresh Field Mapping, and check it again |
| Development environment preview works, but manual execution fails | Check the production application credentials, document permissions, API request signing, and server egress IP addresses |
| Synchronized field content does not match expectations | Check the source data preview and field correspondences, adjust the configuration, and validate again |
Mount on a Flow
After manual verification succeeds, you can mount the offline sync plan on a Flow so that it runs automatically on a schedule.
- Open the saved offline sync plan and click Mount on task flow.
- Select the target Flow.
- Enter the node name, select the execution mode, and set the owner and remarks as needed. The node type and integration plan are filled in automatically.
- Click Create node and mount on it. After mounting succeeds, click Go to flow page to check the node's position and its upstream and downstream dependencies.
- Save and release the Flow. Production scheduling uses the data source configuration of the production environment.
To change the sync plan or data source, first assess the dependencies of existing Flows, and run the plan again to verify the result after the change.

