Querying Customer Master Data from Kingdee Cloud Sky: A Practical Breakdown of a QUERY_ONLY Strategy

What This Strategy Solves (Scenario and Value)

In one of our actual projects, the customer's situation was very common: Kingdee Cloud Sky held a large amount of customer master data, and front-end business systems (CRM, e-commerce middleware, order systems, etc.) needed to pull customer profiles by code or ID. However, calling the Kingdee API directly each time led to scattered permissions and reconciliation difficulties.

This "Query Kingdee Customer" strategy is essentially a QUERY_ONLY strategy: data flows one-way from Kingdee Cloud Sky into the Qeasy Data Integration Platform, where it is transparently transmitted and stored in the middle layer, without being written back to third-party business systems. Its value lies in consolidating "who can call Kingdee, when to call, and by which fields" onto Qeasy, so the business side only needs to read the middle-layer results, reducing coupling and disturbance to the source system.

Data Flow and Field Mapping (Source → Middle Layer → Target)

The data flow of this strategy is unidirectional: Kingdee Cloud Sky → Qeasy Integration Platform → Business-side consumption. The source-side API is Kingdee Cloud Sky's standard executeBillQuery (WebAPI, POST), used for batch querying by customer document.

Key field mapping table (organized based on source metadata):

The target side is the "Write Null Operation" node inside the Qeasy Integration Platform (effect=EXECUTE, idCheck=true). This step handles the landing action, but the actual strategy semantic is QUERY_ONLY, so the target-side write is closer to "flagging + landing intermediate table".

How to Configure on Qeasy

When we landed this strategy on the Qeasy Data Integration Platform, the typical configuration was divided into four parts:

1. Source Platform Connector: Select Kingdee Cloud Sky, fill in tenant information (already desensitized), and confirm the executeBillQuery API can be reached. There is a common pitfall here: the Kingdee API requires Cookie/Session consistency. If the Qeasy request instance creates a new connection each time, authentication will fail. The stable approach is to configure connection reuse in Qeasy to maintain session stability.

2. Metadata Registration: Enter fields such as FCUSTID / FNumber / FName into the request parameter list, keeping label and field naming consistent, so subsequent mapping doesn't require manual translation.

3. Scheduling Strategy: The source strategy's crontab is */15 8-22 * * *, i.e., every 15 minutes from 8 AM to 10 PM daily — this is a common pattern of "high frequency during working hours, paused during business off-peak" to avoid disturbing the source system at night. The target-side crontab is 23 2 * * *, at 2:23 AM daily, typically used for archiving or verification.

4. Middle-Layer Landing: The target side uses a "Write Null Operation" node, which essentially writes the captured results to an internal intermediate table in Qeasy, facilitating downstream BI or business systems to subscribe on demand.

Implementation Steps

We recommend advancing in three phases:

• Phase 1: Incremental Starting Point. First use the customer code (FNumber) as the incremental cursor, do an initial full pull of a batch (e.g., customers with transactions in the last 3 months) to set up the middle layer. The focus of this step is to verify whether field mapping is complete and whether the organization code mapping table is prepared.

• Phase 2: Full Trigger. After the incremental is stable, manually trigger a full pull and check whether the source-side customer count matches the middle-table row count. A typical mistake is only watching "row count" while ignoring "duplicate codes" — the same FNumber in Kingdee may produce multiple FCUSTID due to historical merging. Idempotent key design must be done here.

• Phase 3: Scheduling Frequency Finalization. After going live, the source strategy maintains the */15 weekday high frequency, and the target strategy runs archiving in the early morning. If the business side reports "customer profile update delays", the source strategy can be tightened to */10, but don't blindly compress it to minute-level, the source system can't handle it.

Pitfall Review

We have reviewed several common pitfalls from customer sites:

1. Hardcoding Organization Codes. Many engineers, on their first attempt, hardcode the value of FCreateOrgId.FNumber directly into the request, causing everything to fail when the organization changes. The stable approach is to put organization codes into a mapping table in Qeasy for centralized maintenance, so future switches only require changing one place.

2. Using FCUSTID as a Business Key. FCUSTID is Kingdee's internal primary key, which carries risk when exposed externally and will change if the source system migrates. The business side should use FNumber as the external primary key, and FCUSTID is only used for idempotency inside Qeasy.

3. Missing Request Fields Causing Entire Batch Failure. If the request fields for Kingdee executeBillQuery are not fully provided, the entire batch returns empty instead of throwing an error. Be sure to run it once with Postman or Qeasy's debugging feature after configuration is complete. Don't just look at the schedule log saying "0 successes" and assume it works.

4. Timezone and Time Field Pitfalls. Time fields returned by Kingdee often carry timezone suffixes. If the middle layer is not standardized, it can cause BI reports to calculate one day more or less when filtering by "today". It is recommended to unify timezone normalization in Qeasy's field conversion node.

5. Nighttime Pause Causing Business Side "Cannot Find Customer". The source strategy only runs between 8 AM and 10 PM. If the order system adds new customers in the early morning, the middle table will be missing data. The stable approach is to overlay an event-driven real-time channel (not within the scope of this strategy), or change the source crontab to 7×24 but at a lower frequency.

Applicable and Non-Applicable Scenarios

Applicable: Only need to synchronize Kingdee customer master data unidirectionally to the middle table, with the business side reading by code or ID; the source system does not allow frequent writes or has restricted APIs; need a unified view of customer profiles. Not Applicable: The business side requires real-time bidirectional write-back or needs to reversely update customer status in Kingdee. Such scenarios require a WRITE_BACK strategy, not QUERY_ONLY.