Sales Delivery Notice Sync Tutorial: From Kingdee Cloud to Jiandaoyun
What This Strategy Solves
An IT engineer at a retail company recently ran into this problem: after the sales team issued a delivery notice in Kingdee Cloud, the warehouse staff on Jiandaoyun mobile forms could not see the document. They had to manually re-enter the bill number before printing and shipping, which was slow and error-prone.
The sales delivery notice sync strategy solves exactly this: push delivery notices from the upstream ERP to the downstream business form in business-time order, so logistics, finance, and customer service can collaborate on the same bill number.
Data Flow and Field Mapping
Data flows from Kingdee Cloud (source) to Jiandaoyun (target), passing through the Qeasy data integration platform pipeline, which performs light cleaning and mapping before writing to the target form.
Key field mapping (source → target):
| Meaning | Source (Kingdee Cloud) | Target (Jiandaoyun field) | Notes |
|---|---|---|---|
| Bill number | FBillNo | Delivery notice number | Business key, basis for idempotency |
| Sales order number | FOrderNo | Sales order number | Linked to upstream sales order |
| Document status | FDocumentStatus | Document status | Only approved statuses synced |
| Sales organization | FSaleOrgId.FNumber | Sales organization | Required for multi-org |
| Date | FDate | Delivery date | Used as incremental anchor |
| Customer | FCustomerID | Customer | Requires code mapping |
| Entity primary key | FID | (not written back) | Used only for deduplication |
The source side uses Kingdee Cloud's executeBillQuery (POST) to fetch data incrementally by bill number and date; the target side uses Jiandaoyun's data_create endpoint. The header primary keys like _widget_1688112112673 are managed by Jiandaoyun's own field naming—our pipeline does not depend on those names, only on the values.
How to Configure on Qeasy
Configuration falls into source fetch, target write, and scheduling.
In the source metadata, set the API to executeBillQuery, effect to QUERY, turn on idCheck, and bind the number field to FBillNo so Qeasy can deduplicate by bill number. Pick out fields including FID, FBillNo, FDocumentStatus, FSaleOrgId.FNumber, FDate, FCustomerID. Use FDocumentStatus as a pre-filter so only approved documents are pulled.
In the target metadata, set the API to data_create, effect to EXUTE, and turn on idCheck. Map each field using {{source field}} placeholders, e.g., {{FBillNo}} → delivery notice number. A common pitfall is in the otherRequest block: is_start_workflow and is_start_trigger. The recommended defaults are is_start_workflow=true and is_start_trigger=false, to prevent one delivery notice from kicking off the approval flow multiple times.
Two patterns commonly used by Qeasy customers are worth noting:
- Centralized code mapping: keep customer, warehouse, and material code mapping tables in a Qeasy dataset, not duplicated in each strategy. When a customer's code changes, you only update one place.
- Phased header/body delivery: this strategy only syncs the header and necessary line items. Larger fields (attachments, remarks) go in a later phase to limit blast radius on failure.
Implementation Steps
A phased rollout is the safe path.
Phase 1—Incremental start point. Define the incremental start date. Qeasy will use the FDate >= start condition as the first full pull, then automatically switch to incremental mode. On the go-live day for one retail customer, we used the business end-of-last-month as the start point, which avoids missing history while not pulling three years of data.
Phase 2—Full trigger. Beyond the schedule, Qeasy supports a manual full trigger to backfill historical data on go-live day. Once the full run completes, the schedule enters normal mode.
Phase 3—Schedule frequency. crontab is set to */10 8-22 * * *, i.e., every 10 minutes during business hours. Delivery notices are time-sensitive but do not need second-level latency, so 10 minutes is a cost-effective interval. Non-business hours stop the schedule to reduce no-op requests and upstream query pressure.
Phase 4—Status filter. Add FDocumentStatus = approved on the source side to prevent drafts from being pushed downstream.
Pitfalls Recap
- No status filter. The first run pushed drafts downstream, producing empty bill numbers in the target form. The safe approach is to treat FDocumentStatus as a query pre-condition in source metadata, not to filter after data enters the pipeline.
- No idempotency key design. Kingdee bill numbers can change on re-approval. If you use an auto-increment ID for idempotency, duplicates will appear. The safe approach is to use FBillNo as the business key and turn on idCheck in Qeasy.
- Customer codes patched on both sides. The target form needs the customer code, but when Kingdee renames a customer, Jiandaoyun still recognizes the old name. A typical mistake is hard-coding mappings inside each strategy; maintenance collapses later. The safe approach is centralized code mapping in a single dataset.
- Downstream flow triggered repeatedly. is_start_trigger is on by default, so each sync runs the Jiandaoyun trigger, which writes back to Kingdee, forming a loop. The safe approach is to explicitly pass is_start_trigger=false in the target's otherRequest.
- 24-hour schedule. Nobody approves documents at night; tasks run empty and consume upstream quota. The safe approach is to constrain crontab to business hours—Qeasy scheduling supports hour-level precision.
Applicable and Non-applicable Scenarios
Applicable: delivery notices, sales outbound, cross-system shipping collaboration with 5–15 minute latency tolerance and scheduled pull. Not applicable: second-level inventory deduction, bidirectional real-time sync, or reconciliation-grade data—those should use event-driven or dedicated middleware.