Assembly Order (Parent Item) Sync from ERP to E-commerce Middle Platform: A Practical Strategy on Qeasy
What This Strategy Solves
A retail enterprise had a straightforward requirement: once assembly orders (parent items) are generated in the source ERP system, the downstream e-commerce middle platform needs to receive this inbound data to update available inventory and subsequent fulfillment. It looks like a simple document flow, but because the two sides have completely different organizational structures, warehouse codes, and product coding systems, things go wrong after running for a while. We used the Qeasy (轻易云) data integration platform to bridge this link, with the goal of stably pushing parent assembly order information to the target system at the business cadence, and centralizing the mapping relationships for management.
Data Flow and Field Mapping
The overall flow is source system → Qeasy middle layer → target system, with document semantics transformed in the middle layer. The source side pulls data incrementally by document number through the query interface (executeBillQuery), and the target side writes via the inbound storage order WebAPI. Below are the key field mapping considerations:
| Business Meaning | Source Field | Middle Layer Processing | Target Field |
|---|---|---|---|
| Document number | FBillNo | Pass through | remark/external document number |
| Document status | FDocumentStatus | Filter approved | Only sync valid documents |
| Inventory organization | FStockOrgId.FNumber | Code mapping | warehouseName |
| Date | FDate | Time format normalization | Inbound date |
| Parent item | Body FEntryID, etc. | Split into inbound goods array | goods_list |
Tip: Process header and body in phases. Get the header running stably first, then attach the detail array; this makes troubleshooting much more efficient.
How to Configure on Qeasy
Step one, configure the query interface in the source system connector. Fill in the conditions for organization, document status, date, etc., and reference the source field names directly in the request body (FID, FBillNo, FDocumentStatus, FStockOrgId.FNumber, FDate, etc.). Use the document number FBillNo as the increment key to avoid full scans every time.
Step two, select the inbound storage order WebAPI in the target system connector. The key point is the warehouse name field — the source side provides a financial organization code, while the target side needs a warehouse name. This step must not be hard-coded. Qeasy supports reverse lookup by finance_code to find name through _findCollection in a mapping collection, so adding new warehouses later only requires updating the mapping table without touching the main flow. For fixed values like employee name, just write the constant string directly.
Step three, centralize code mapping management. Put all cross-system organization, warehouse, and product codes in the same mapping table, maintained in Qeasy as collections or dictionaries, with source field values resolved through references. This is a very common pattern among Qeasy customers — it extracts the "translation table" out of the code.
Implementation Steps
- Increment starting point: For the first run, do a historical data backfill to confirm middle layer fields are not lost or drifted; then switch to increment mode, using the document number as the increment key, and trace back a small window (e.g., the most recent 7 days) as a fault tolerance measure.
- Full trigger: When encountering organizational changes or large-scale supplementary orders, schedule an offline full sync, while increment remains the daily mode. The increment-and-full dual-track approach is the safe practice for this type of business document.
- Scheduling frequency: Source-side fetching can be set to every 3 minutes (referencing crontab
2-59/3 2-23 * * *), avoiding peak hours on the hour; target-side writing every 5 minutes (*/5 2-23 * * *) is sufficient, with a slightly slower cadence than the source to give downstream processing time. - Exception handling: Configure failure retry and alerting on the Qeasy side. When the source has no new documents, treat it as a normal completion without false alarms.
Pitfall Retrospective
- Typical mistake: warehouse name hard-coded. The source provides an organization code, the target needs a warehouse name. Hard-coding works once, but three months later when a new warehouse is added, documents start getting dropped. The safe practice is to use a mapping collection lookup.
- Typical mistake: header and body processed together. If even one detail line in the body array errors, the entire document fails, making root cause analysis painful. The safe practice is to get the header running independently first, then attach the details.
- Typical mistake: ignoring document status filtering. Draft-status documents from the source are also pushed downstream, causing duplicate inbound entries. Add status filtering in the middle layer to only push approved documents.
- Typical mistake: centralized scheduling on the hour. All strategies set to
0 * * * *create instantaneous pressure on the source. Distributing strategy triggers across 2–59 minutes significantly improves stability in public cloud environments. - Typical mistake: wrong increment key. Using update time as the increment key easily leads to missed documents (multiple documents in the same second, cross-timezone situations, etc.). A document number + status combination is more reliable.
Applicable and Non-Applicable Scenarios
Applicable: Scenarios where the organization and warehouse systems are stable, and assembly orders drive downstream inventory updates as inbound storage orders; projects that need centralized mapping rule management to avoid hard-coding. Not applicable: Scenarios where source-side document status flow is complex with frequent reversals and reworks; links requiring strong real-time (second-level) feedback — document sync inherently has minute-level latency, so message push would be more suitable.