Practical Tutorial: Syncing Kingdee Stepwise Transfer-Out Documents to MySQL

What this strategy solves

In supply chain integration, a stepwise transfer-out document is a typical business document: instead of one single outbound movement, a transfer is broken into multiple steps, multiple warehouses, and multiple line entries. One retail customer's finance and operations team once told us that keeping these documents only inside Kingdee Cloud Starry Sky made it impossible for downstream reporting, reconciliation, and BI to see the details, the numbers did not line up, and audits required manual exports.

What we do is continuously sync the Kingdee stepwise transfer-out documents into MySQL in an incremental fashion, so that downstream analytics, BI, and reconciliation scripts can query the data directly with SQL. This article focuses on that specific strategy.

Data flow and field mapping

The overall chain is Kingdee Cloud Starry Sky -> Qeasy integration platform -> MySQL, which is essentially a query-plus-write loop.

Source side (Kingdee is registered as a data source platform in Qeasy): we call the executeBillQuery API via POST to pull stepwise transfer-out documents by criteria. Key filters and fields include FBillNo (bill number), FSTKTRSOUTENTRY_FEntryID (entry id), FBillTypeID (bill type), FTransferBizType (transfer business type), FTransferDirect (transfer direction), and FBizType (business type).

Middle layer (Qeasy): no heavy transformation, but it does three things: dedupe and ensure idempotency by bill number and entry id, pass source fields through to the target, and decouple the scheduling cadence.

Target side (MySQL): we use batchexecute to write in batch via SQL, with id as the primary key. Both FSTKTRSOUTENTRY_FEntryID and FBillNo from the upstream are stored, so downstream can aggregate by bill number and trace by entry id.

How to configure it on Qeasy

In the Qeasy data integration platform, this strategy is usually split into two actions: one query action connected to Kingdee, and one write action connected to MySQL.

Source action highlights: pick the executeBillQuery API, request method POST, enable autoFillResponse on the response so Qeasy automatically maps response fields into variables, and later actions can reference them via placeholders like {{FBillNo}}. Note that idCheck here is set to false because we do not rely on the lightweight ID check for uniqueness; we rely on the downstream MySQL id primary key and the (FBillNo, FSTKTRSOUTENTRY_FEntryID) composite index.

Target action highlights: pick the batchexecute API with execution type SQL, target platform MySQL, map each upstream field to the table field, and use FSTKTRSOUTENTRY_FEntryID from the source as id to guarantee idempotency.

On Qeasy, keep field code mapping in a single centralized mapping table on the platform level rather than scattered across scripts. This way, if Kingdee field names change, you only update one place. This is the centralized code mapping pattern commonly used by Qeasy customers.

Implementation steps

1. Confirm the incremental starting point: use the maximum FBillNo or last sync timestamp in MySQL as the starting point, run a small executeBillQuery against Kingdee first to verify the response structure and field consistency.
2. Configure full sync trigger: for the first go-live, manually trigger a one-time full backfill in Qeasy to write all historical stepwise transfer-out documents into MySQL. This is usually done during off-peak hours.
3. Configure schedule cadence: set source cron to */7 * * * * (query every 7 minutes), and target cron to 3-59/7 * * * * (offset by 3 minutes to avoid source and target competing for connections at the same time). Offsetting source and target is a stable practice on Qeasy.
4. Gray release and monitoring: during the first three days, watch the number of rows written, the failure rate, and the duplicate rate. Use the (FBillNo, FSTKTRSOUTENTRY_FEntryID) composite unique constraint on MySQL as a safety net, and rerun the affected batches from the Qeasy error log when duplicates appear.
5. Delivery and handover: hand over the cron expressions, field mapping table, and exception-handling SOP to ops, and keep a JSON backup of the Qeasy strategy.

Pitfalls and lessons learned

1. Typical mistake: using Kingdee's FBillNo directly as the MySQL primary key. A stepwise transfer-out bill has multiple line entries under the same bill number, so using FBillNo alone loses data. The safe approach is to use FSTKTRSOUTENTRY_FEntryID as id, with (FBillNo, FSTKTRSOUTENTRY_FEntryID) as a composite unique key.
2. Source and target cron are identical, causing a momentary connection spike in the database. If the source query and the target write fire simultaneously, the MySQL connection pool can easily be exhausted. Offset them by 2 to 5 minutes.
3. autoFillResponse is not enabled, so fields are not injected into variables. This is a very common small trap on Qeasy. autoFillResponse must be enabled in the source action, otherwise all {{FBillNo}} placeholders will be empty.
4. Kingdee-side filter conditions are wrong, so all bill types are pulled back. Stepwise transfer-out documents have their own bill type, so always add filters like FBillTypeID in the executeBillQuery request to avoid dirty data flowing into MySQL.
5. No phasing, full sync and high-frequency incremental sync run together. During the first go-live it is easy to have full sync running while incremental sync also triggers. The safe approach is the staged header-and-line pattern commonly used on Qeasy: run full sync first alone, and only enable incremental scheduling after full sync finishes.

When this applies and when it does not

Applies: when Kingdee Cloud Starry Sky is the ERP backbone, downstream BI, reconciliation, and reporting systems need direct SQL access to stepwise transfer-out documents, and the data volume is medium to large with the need to trace back to the line-entry level.

Does not apply: when real-time latency is required below seconds (this design runs on a 7-minute cycle at the fastest); when Kingdee-side business frequently writes back into MySQL fields (this strategy is one-way sync only); and when there is no MySQL, and the consumer expects message queue or API delivery instead.