Practical Tutorial on Kingdee Cloud Organization Data Query Synchronization
What This Strategy Solves
In the master data synchronization chain between CRM and ERP, "organization" is usually the first domino. When a CRM like OKKI needs to push customers, orders, and quotations into an ERP like Kingdee Cloud, both sides must share the same understanding of organization/department/business unit codes. We have seen this go wrong too many times in real projects: when organization is not synchronized first, every downstream entity—items, customers, sales orders—ends up misaligned. The essence of the "Query Kingdee Organization" strategy is therefore to pull organization records nightly from Kingdee Cloud via scheduled jobs, using FNumber as the unique key, and land them into the Qeasy data integration platform as the baseline reference for all downstream document synchronizations.
Data Flow and Field Mapping
The chain is unidirectional: Kingdee Cloud → Qeasy Data Integration Platform. The source uses Kingdee's standard executeBillQuery WebAPI, while the target on the Qeasy side is a write no-op node (which actually persists the pulled data into the platform's intermediate store). The key field mapping is as follows:
| Field | Source (Kingdee Cloud) | Middle Layer (Qeasy) | Purpose |
|---|---|---|---|
| FNumber | Organization code | Primary key | Globally unique identifier, used by downstream items and customers |
| FName | Organization name | Name | Display and auxiliary identification |
| Limit / StartRow / TopRowCount | Pagination parameters | Injected by scheduler | Controls rows per page, default 2000 |
In the source metadata, both number and id point to FNumber. This is a common pattern for Kingdee master data—the business code itself acts as the primary key, so there is no need to fabricate an additional ID.
How to Configure It on Qeasy
Configuring this strategy on the Qeasy data integration platform typically involves four pieces:
- Register the Kingdee Cloud connector: Fill in the access address, account set, and authentication mode for the private deployment. In private environments, we recommend creating a dedicated read-only account instead of mixing it with high-frequency write accounts.
- Configure the source metadata: Select
executeBillQueryas the API, set the method to POST, putFNameandFNumberinto the request fields, and placeLimit,StartRow,TopRowCountinto otherRequest. Use placeholders such as{{PAGINATION_PAGE_SIZE}}and{{PAGINATION_START_ROW}}so the Qeasy scheduler can inject pagination values automatically. - Configure the target node: Set the target's
apito "Write No-op", because this strategy only lands organization data into the platform's intermediate database; the real distribution is left to downstream strategies (items, customers, etc.). This "land first, distribute on demand" pattern is a common approach among Qeasy customers—when you later need to add transformations, validations, or change target systems, you do not need to modify the source. - Enable centralized code mapping management: Use Qeasy's "Mapping Management" to maintain the FNumber → internal organization code mapping in one place. When a new business system is onboarded, simply add mapping rules here, and all downstream strategies that depend on organizations can automatically reuse them.
Implementation Steps
For scheduling design, we typically break it into three phases:
- Initial run: Perform a full pull to bring all current Kingdee organization records in one shot. This is usually placed during the early-morning low-peak hours, with the source crontab set to
3 2 * * *(02:03 daily) and the target at23 2 * * *(02:23). The window ensures the source finishes writing before the target consumes, preventing resource contention. - Steady-state incremental: After the full run completes, switch to incremental. The incremental starting point can use either a "last max update time" marker or a cursor sorted by FNumber, ensuring both new and modified organizations are captured.
- Scheduling frequency: Organization master data changes infrequently, so a daily run is sufficient. However, we recommend keeping a "full pull trigger" switch as a quarterly reconciliation safety net—incremental runs inevitably miss edge cases over time, and a manual full pull can realign both sides within half an hour.
Lessons Learned from the Field
- Do not hardcode pagination parameters. If Kingdee's
Limitis hardcoded to 2000, anything beyond that is silently dropped. The safe approach is to use Qeasy's pagination placeholders so the platform loops page by page automatically. - Watch for clock drift in private deployments. Kingdee servers, the Qeasy scheduler, and database servers may drift by several minutes, causing scheduling windows to misalign. We recommend enforcing NTP on all nodes and adding a "source time window" filter within the strategy.
- Do not ignore FNumber duplicates. If an organization is disabled and re-enabled in Kingdee, two records with the same FNumber may exist. Leaving idCheck at false will carry dirty data downstream. The safe approach is to add a deduplication step on the target side, keeping the most recently modified record.
- The "no-op" target is not really empty. Although the metadata calls the API "Write No-op", it actually persists into Qeasy's intermediate database, and downstream queries and joins all rely on this table. Make sure operations staff clearly understand it is the organization baseline table and avoid cleaning it up.
- Do not hardcode organization codes in downstream strategies. After organization data is pulled, downstream strategies (items, customers, sales orders) should look up codes through the centralized mapping management rather than embedding values like "01 = East China" in scripts.
Applicable and Non-Applicable Scenarios
Applicable: Private deployments integrating ERP and CRM, where downstream business documents need a shared organization baseline; low-frequency changes but strict global consistency required. Not applicable: Scenarios with high-frequency organization changes requiring real-time push (minute-level), or environments without executeBillQuery permission that must rely on direct database access—the latter requires a different pipeline and cannot reuse this strategy.