Kingdee Cloud Sales Delivery Order Query Strategy: Bridging Jushuitan to Qeasy Datahub

What This Strategy Solves

In a real retail supply-chain integration project, Jushuitan handled front-end e-commerce transactions while Kingdee Cloud managed back-end finance and inventory. Both sides generated sales delivery orders every day, yet each maintained its own encoding scheme, organizational dimensions, and document statuses. The question finance kept asking was: "Which system is the source of truth for this order?"

The sales delivery order query strategy pulls delivery orders already created in Kingdee Cloud back toward the Jushuitan side for reconciliation, aligning both systems on bill number, date, customer, and sales organization. It writes no business data itself—its sole role is "matching what can be matched, finding what can be found." A lightweight yet indispensable bridge in the broader supply-chain sync chain.

Data Flow and Field Mapping

The flow is one-way: Kingdee Cloud → Qeasy Datahub → Jushuitan-side reconciliation view. The source is Kingdee Cloud's executeBillQuery WebAPI; the target on Qeasy is a "write-noop" node that lands pulled data into a staging store for downstream consumption.

Key field mapping (only reconciliation-critical fields shown; real projects extend from this skeleton):

How to Configure on Qeasy Datahub

For the source, attach Kingdee Cloud's executeBillQuery as a query-type data source. Expose document type, date range, and sales organization as parameters in the request body. We usually use {{start_date}} and {{end_date}} placeholders, injected by the scheduling context.

For the target on Qeasy, configure a RESTful write node using POST with the "write-noop" interface. This looks like a meaningless empty run, but it actually does three things: lands the pulled data into Qeasy's staging table, creates a combined bill_no + bill_date index in that table, and provides a stable data source for downstream reconciliation views.

The most worthwhile time investment in the mapping layer is centralized encoding management. Kingdee's FNumber doesn't map one-to-one with Jushuitan's shop or SKU codes. We typically maintain a mapping table in Qeasy's data dictionary or transformation scripts—when the customer adds a new organization, only that one table is updated, and every strategy referencing it picks up the change automatically. This centralized management pattern is common among Qeasy customers and eliminates the duplication of writing conversions in every strategy.

Implementation Steps

We split this strategy's rollout into three phases.

Phase 1: Set the incremental anchor. The anchor isn't the go-live date—it's the cutoff of the customer's historical data. The usual approach is to first run a full sync to backfill all historical documents while recording the "maximum bill date" as the incremental starting point. Full syncs are triggered manually on Qeasy using parameterized date ranges, not relying on schedulers.

Phase 2: Schedule frequency and staggering. The source cron is 12 3 * * * (3:12 AM); the target cron is 23 2 * * * (2:23 AM). The two timestamps are deliberately staggered so Kingdee's query finishes before Qeasy's staging write starts, avoiding concurrent fetches of the same batch. The stagger depends on chain length—this customer's chain has over 40 strategies including material sync and sales order sync. Staggering each by 5–10 minutes prevents everyone from hitting the same second.

Phase 3: Dual-track incremental and full sync. During the first week after go-live, incremental runs daily while a manual full sync triggers every Monday morning as a safety net. Once incremental data stabilizes for a week, full sync drops to monthly and stays in the emergency channel. This dual-track pattern—incremental for timeliness, full sync for completeness—is common among Qeasy customers.

Lessons from the Trenches

Pitfall 1: Wrong timezone on bill date. Kingdee's FDate is a timestamp with time; Jushuitan only stores the day. Without normalizing via DATE_FORMAT in Qeasy, cross-midnight orders land in the next day's incremental window and get refetched the next day. The safe approach is to truncate to day at the source, storing as yyyy-MM-dd.

Pitfall 2: Missing sales organization triggers a full table scan. FSaleOrgId_FNumber is marked optional, but omitting it makes Kingdee return delivery orders for every organization. One full sync pulled hundreds of thousands of rows, instantly flooding Qeasy's staging table. That was the very first symptom on-site—adding the organization filter cut volume by two orders of magnitude.

Pitfall 3: Document type code drift. Different Kingdee books use different FNumbers for document types. The test environment might use XSD01, production XSD02. Hardcoding the value into Qeasy's request body means production returns nothing. Promote it to a Qeasy environment variable or strategy parameter, each environment reading its own value.

Pitfall 4: Write-noop mistaken for a bug. The target's "write-noop" node looks idle in logs, but it has already landed data in the staging table. New engineers often suspect misconfiguration and keep adding logs, which only complicates the chain. Explaining the node's semantics upfront saves many unnecessary tickets.

Pitfall 5: Wrong idempotency key. We initially used FEntity_FENTRYID as the idempotency key, but Kingdee regenerates the entry ID after unapprove-reapprove cycles, causing duplicates in Qeasy's staging table. Switching to a composite key of FBillNo + FEntity_FENTRYID eliminated the duplicates entirely.

When to Use and When Not to Use

Use this strategy when Jushuitan and Kingdee Cloud need sales delivery order reconciliation, cross-system document traceability, or cross-organization data validation, and master data sync (items, customers, organizations) is already running. Do not use it when Kingdee is the origin of delivery business (use sales order sync instead), when you need to write back to modify Kingdee itself (that's an execute-type strategy), or when the source system isn't Kingdee Cloud.