Querying Sales Orders from Kingdee Cloud Aerospace Flagship Edition: A Strategy-Level Integration Tutorial
What This Strategy Solves
In a real retail integration project, after sales orders are signed off in the CRM, business and finance teams need to see the document status in the ERP in near real time. We use the Qeasy Data Integration Platform (轻易云数据集成平台) as the backbone and isolate the "query sales orders from the Kingdee Cloud Aerospace Flagship Edition" task into a single strategy. Upstream only pushes, downstream only pulls, and the intermediate layer polls on a schedule, so the two systems eventually reconcile.
Data Flow and Field Mapping
This is a QUERY_ONLY strategy: the source is the Kingdee Cloud Aerospace Flagship Edition, and the landing point is the Qeasy integration platform.
Key Field Mapping Table
| Dimension | Source (Kingdee Cloud Aerospace) | Intermediate Layer (Qeasy) | Notes |
|---|---|---|---|
| API | /kapi/v2/dsg5/sm/sm_salorder/queryadd | Write-empty operation | Source uses RESTful POST; intermediate layer just persists |
| Document No. | number (mapped to billno) | number | Business primary key |
| Primary ID | id | id (idCheck=true) | Strict check on intermediate layer |
| Pagination | pageNo, pageSize | — | Paging controlled at source |
| Request body | data (object) | — | Business filter criteria |
| Auto-fill | autoFillResponse=true | — | Reduces downstream manual mapping |
How to Configure on Qeasy
- Register the source platform: In Qeasy, register the Kingdee Cloud Aerospace Flagship Edition as an external data source and fill in the
platform_idand base connection info. In private deployment, this typically goes through the internal gateway. - Create a new strategy with a QUERY action: Paste in the API metadata, choose POST for method, QUERY for effect, and bind
numbertobillno. - Enable autoFillResponse: This is a common pattern with Kingdee-style APIs. Let the platform auto-fill
id,number, and similar fields into the response structure so engineers don't have to repeatedly declare them in scripts. - idCheck off at source, on at target: Set source
idCheck=falseto avoid being blocked by empty values during the first sync; set targetidCheck=trueto ensure data landing in Qeasy always carriesidfor deduplication. - Configure the target as a write-empty operation: Because this strategy only performs "query → land in intermediate layer," and downstream consumption is handled by subsequent strategies, choosing an EXECUTE empty operation on the target keeps things clean.
Implementation Steps
At the customer site, we usually proceed in three phases:
- Incremental starting point: First use the
datafilter to pull only recently changed orders, verifying connectivity and field alignment. - Full trigger: During initial go-live or data backfill, increase
pageSizeto pull historical documents at once; Qeasy automatically loops through pages internally. - Scheduling frequency: The source strategy's crontab is set to
*/3 7-23 * * *, i.e., polling every 3 minutes during business hours; the target (intermediate layer persistence) runs at23 2 * * *in the early morning, consolidating writes and avoiding conflict with daytime real-time polling.
This "high-frequency polling + low-frequency persistence" pattern spreads the load and makes troubleshooting easier when something goes wrong.
Lessons Learned from Pitfalls
- autoFillResponse not enabled, response body all empty: A typical mistake is building JSON directly from the API doc without letting Qeasy auto-fill
idandnumber, causing dedup keys to all be null. The safe approach is to explicitly enable autoFillResponse. - pageSize left at 10 for full sync, ran overnight: The Kingdee API defaults to
pageSize=10; for full sync it must be raised. Many engineers miss this and go live with the default. - idCheck kept on at the source, first sync gets stuck: For add/initial sync strategies, source
idCheck=falseis the common configuration; the target side should be the opposite,true. - crontab set to
* * * * *, overwhelms the source DB: Polling every minute, combined with unbounded paging, exhausts the target DB connection pool quickly. Every 3 minutes during business hours is an empirical sweet spot. - "Query" and "persistence to intermediate layer" coupled in the same strategy: When downstream consumption breaks, the query is dragged down too. We keep query as its own strategy and run downstream consumption on a separate line, keeping the blast radius small.
When This Applies and When It Doesn't
Applies: Retail or distribution enterprises on private deployment that need to pull sales orders from ERP into an intermediate layer for downstream CRM, BI, or reporting consumption, with minute-level freshness requirements. Does not apply: Scenarios that require strict transactional consistency, sub-second latency, or where the order volume far exceeds the single-API paging capability — in those cases, switch to a message queue or database log subscription.