Practical Tutorial on the "Query-then-Overwrite" Purchase Order Sync Strategy: Pulling Source Bills from Kingdee Cloud and Routing Them Back to Qeasy

What This Strategy Solves

In a typical supply chain integration, once a purchase order has been pushed from the e-commerce front end to the ERP, the business side often asks a very practical question: "Which upstream document did this PO actually come from, and where is it now?" Searching manually inside the ERP is slow, but re-pushing the whole purchase order is risky because it will overwrite fields that operators may have already adjusted by hand.

This strategy is about querying a known purchase order without re-writing it. It uses executeBillQuery on the Kingdee Cloud side to look up the purchase order and pull back the linkage fields (such as the single-number/line-number key and the source bill number), then writes the result back to the integration layer in overwrite mode so downstream consumers can join on it.

Data Flow and Field Mapping

The data flow is unidirectional: Kingdee Cloud → Qeasy Integration Platform (datahub). The target side only receives the query result; it does not push back to Kingdee.

Two fields deserve attention. F_QGWK_Link_FSId is the business-defined "single-number/line-number" key that joins the PO row back to the upstream world. FSourceBillNo is the trace left by another upstream chain (typically the sales order path). Both must be carried back to the integration layer; if either is dropped, downstream traceability silently breaks.

How to Configure It in Qeasy

In Qeasy, this strategy is configured as two independent cards (one source, one target) rather than a single end-to-end orchestration, because the flow is a read-then-sink pattern with no downstream business write.

Source card (read from Kingdee): choose the Kingdee.Cloud platform, pick the executeBillQuery API, bind the business object to F_QGWK_Link_FSId, and turn on autoFillResponse so the Kingdee response fields are projected automatically — no hand-written mapping table needed. Open the request parameters FPOOrderEntry_FEntryId, FID, FBillNo, and FSourceBillNo, and set is_required to false for all of them. This is a query, not a create, so missing optional fields must not be treated as a hard error.

Target card (write to Qeasy): choose the datahub platform (Qeasy itself) and the Write-Null-Op API. The "null operation" is not a no-op in the colloquial sense; it persists the query result into a logging/sink table so the run is observable. Set idCheck to true so the same purchase order cannot be persisted twice by repeated query results.

A pattern we often see on customer sites is centralized code mapping: the FNumber-to-Wangdiantong-product code table lives in Qeasy's mapping center and is shared by every strategy. When a Kingdee material code is updated, the FBillTypeID_FNumber carried back by this query will resolve through the same mapping, instead of each strategy maintaining its own copy.

Implementation Steps

Step 1: Establish the incremental baseline. Before going live, freeze a batch of PO numbers and run one full query to seed the incremental comparison base. In the source card, add a filter F_QGWK_Link_FSId is not null so dirty rows without a linkage key are excluded up front.

Step 2: Trigger the full load. Use Qeasy's "manual run + full mode" to execute a complete query once, and compare the returned row count with the target sink count. Mismatches usually point to pagination behavior or the per-call return limit of Kingdee's executeBillQuery.

Step 3: Switch to scheduled mode. The source crontab is */55 9-21 * * * — every 55 minutes during business hours, silent overnight so it does not collide with Kingdee's backup window. The target crontab is */30 0-8 1 1 1 — a low-frequency tail job that effectively acts as a daily reconciliation sweep, triggered after the source side has finished its sink.

Step 4: Live monitoring. For the first three days, manually verify FSourceBillNo on five randomly picked POs each day. Once correct, hand the query over to the business team for self-service.

Lessons from the Field

1. Forgetting idCheck. In the first release we missed the idCheck flag, and the same purchase order was written twice by successive query runs. Downstream dedup logic then flagged both rows as dirty. The trap here is: a "null operation" API is not risk-free; "null" only means no business-table write, not "no row written at all."
2. Setting every is_required to true. For a query interface, request parameters are really a projection selector. Marking them all mandatory turns a routine lookup into a fault-prone operation. The safe default for query-style interfaces is is_required = false.
3. Mismatched write-back timing. If the target side writes a few minutes after the source side finishes, the source bill number can still be empty in the result. On customer sites we either add a five-minute manual delay or insert a "wait N minutes after source completion" step in Qeasy.
4. Using FBillNo as the dedup key. A typical mistake is to use FBillNo alone for idCheck, which causes different lines of the same purchase order to be treated as different records. POs must be deduplicated by the combination of "document number + line number," which is exactly what F_QGWK_Link_FSId was designed for.
5. Date format drift across years. When the PO creation date crosses a year boundary, Kingdee sometimes returns a mix of YYYY and YY formats. Normalize the string once in Qeasy before any downstream date comparison, or you will see spurious mismatches.

When to Use It — and When Not To

Use it when the PO already exists in Kingdee, the requirement is to enrich linkage fields without rewriting the order, the document volume is steady, and queries are concentrated in business hours.

Do not use it when you need to push Kingdee fields back to Wangdiantong (that is a "write-back strategy," not a query), when the volume is large enough to demand minute-level latency (the query API has its own throughput ceiling), or when the PO has not yet been generated on the source side and there is simply nothing to look up.