Kingdee Purchase Order Query Sync in Practice: Field Mapping and Pitfalls from Source to Hub

What This Strategy Solves (Scenario & Value)

A manufacturing enterprise needed its MES to look up Kingdee Cloud purchase orders by document number—for example, to display source document numbers, order types, and business types as the "source of truth" on the MES side. Letting MES call Kingdee APIs directly creates permission headaches and forces on-site developers to write duplicate code. We used the Qeasy Data Integration Platform to wrap this lookup into a single strategy, "Query Kingdee Purchase Orders": Kingdee is the source, Qeasy is the hub, and MES consumes standardized data through the platform. This strategy does exactly one thing—fetch purchase orders precisely by FBillNo and land them on the hub for downstream consumers.

Data Flow and Field Mapping (Source → Hub → Target)

The source is Kingdee Cloud, which uses executeBillQuery (POST) to reverse-look up documents by FBillNo. The hub is the Qeasy Data Integration Platform, where the target is a "write empty operation" WebAPI (api: 写入空操作, effect: EXECUTE). This effectively captures the source response into the platform's request/response model without performing any write into a downstream database.

Key field mapping table:

Document type enum (from the source describe, must be preserved verbatim): Standard Purchase Order CGDD01_SYS, Standard Subcontract Order CGDD02_SYS, Direct Ship Purchase Order CGDD03_SYS, Asset Purchase Order CGDD04_SYS, Expense Purchase Order CGDD05_SYS, Replenishment Purchase Order CGDD06_SYS, VMI Purchase Order CGDD07_SYS, Spot Purchase Order CGDD08_SYS, Distribution Purchase Order CGDD09_SYS. A common Qeasy customer pattern is to maintain these enums centrally in a single "code mapping table" rather than re-copying them into every strategy.

How to Configure in Qeasy (Typical Configuration Points)

First, enter the source metadata exactly as defined in the materials: api=executeBillQuery, method=POST, number=FBillNo, id=FPOOrderEntry_FEntryId, idCheck=false (query scenarios do not need primary-key conflict checks), and autoFillResponse=true so that response fields auto-populate, reducing manual mapping effort. Second, the target is the "write empty operation" WebAPI with effect=EXECUTE and idCheck=true, whose purpose is to capture the source response into the platform's request/response structure so it can later be subscribed to or referenced by other strategies. Third, the enum values inside the field describe (especially for document type) must be preserved verbatim—these become the key trace when later investigating "why can't I find this record."

Implementation Steps (Phased Scheduling)

Incremental Starting Point: On the first day of go-live, trigger a one-shot query by document number, pulling all known-order-no records into the hub to establish a baseline. Full-Load Trigger: Temporarily change the crontab to * * * * * for one full-load validation run, confirm field mapping and enums all line up, then switch back to the production frequency. Scheduling Frequency: The source-side crontab is * 7-22 * * *, which means every minute from 07:00 to 22:00 daily—a typical "high-frequency during business hours, quiet overnight" setup that suits MES scenarios needing real-time reverse lookup. The target-side crontab is 1 1 1 1 1 (a one-time trigger), since the empty operation only needs to run once to populate the model. If downstream MES needs continuous subscription, layer on an additional "change push" strategy that fans out the hub data externally.

Pitfalls and Lessons Learned

1. idCheck set wrong caused one outage: If a query strategy mistakenly has idCheck=true, the hub tries to compare against primary keys, resulting in "Kingdee has the record, but the platform cannot find it." The safe rule is idCheck=false for query strategies; only enable it for write-to-target strategies.
2. Enums not centrally managed: All nine document-type codes scattered across different strategies' describe fields. Three months later someone changed a code on the Kingdee side and the troubleshooting chain became very long. Recommendation: maintain a dedicated "Kingdee Enum Mapping Table" on Qeasy and have all purchase-related strategies reference it.
3. Empty FBillNo fails the entire batch: FBillNo is required by executeBillQuery; if the caller passes an empty value, the API errors out and the whole batch fails. The on-site fix is to add a "non-null validation + default placeholder" pre-processing layer in Qeasy so that a single failed record is isolated and does not break the whole run.
4. FSourceBillNo mistakenly assumed required: Many engineers assume every purchase order has a source document number, but for direct-ship and VMI orders FSourceBillNo is legitimately empty. Downstream consumers on the hub must handle null values gracefully.
5. Nighttime scheduling wastes resources: With the crontab * 7-22 * * *, MES does not query at night, so this is fine—but some teams forget to adjust the crontab when cloning a strategy and end up hitting Kingdee's API quota every minute through the night. Always review the schedule after cloning.

Suitable and Unsuitable Scenarios

Suitable: When MES, SRM, or WMS needs to reverse-look up Kingdee purchase orders by document number without being granted direct Kingdee API access. Unsuitable: When you need to "write back" purchase orders to Kingdee (that is a separate save strategy); when you need complex filtering by business date, supplier, or organization for bulk sync—this query strategy serves only single-point reverse lookup. For bulk extraction, use a dedicated list-query strategy.