Practical Cross-System Synchronization of Assembly and Disassembly Documents
What This Strategy Solves
Assembly and disassembly documents affect both finished products and component consumption, making them common inventory transactions in manufacturing, retail, and maintenance operations. In a real project, a business document may already exist in the source system while the target system still needs a corresponding inventory transaction. Synchronizing only the document number and material number can easily reverse assembly and disassembly, or cause target-side rejection because organizations, owners, or identifiers do not match.
This strategy takes assembly and disassembly documents queried from the source system, converts them into documents understood by the target system through the Qeasy data integration platform, and then writes them in batches to the target. We focus on document identity, organization ownership, transaction type, material mapping, and quantity, while using both number and record-identifier checks to reduce duplicate-document risk. In a private deployment, Qeasy manages scheduling, transformation, and exception records, making the inventory boundary between the two systems clearer.
Data Flow and Field Mapping
The data flow is: source assembly and disassembly documents → Qeasy intermediate layer → target assembly and disassembly documents. The intermediate layer is not only a field-copying step; it also performs business-semantic conversion, deduplication, and failure isolation.
| Business meaning | Source field example | Intermediate processing | Target field example | Configuration note |
|---|---|---|---|---|
| Query time range | applyStartDate, applyEndDate | Generate a time window according to the schedule | Used as query criteria | Incremental runs should use a start date through the current time; avoid a permanently fixed date |
| Document number | assNo | Retain as an idempotency key | FBillNo | Do not create a duplicate when the number already exists |
| Record identifier | assId | Associate with the document number | id or batch reference | Use the number as the primary check and the record identifier as a secondary check |
| Inventory organization | companyCode | Centralize organization-code mapping | FStockOrgId | Keep mappings in shared configuration instead of hard-coding scripts |
| Document type | Assembly/disassembly business type | Convert to target business rules | FBillTypeID | Configure a document-type value supported by the target system |
| Transaction type | assembleType | Convert a numeric value to a readable enum | FAffairType | Map assembly to Assembly and disassembly to Dassembly |
| Product information | goodsId, goodsNo, goodsName | Link to material master data | Target material fields | Prefer stable codes; use names only as supporting information |
| Quantity | Assembly-part and component quantity | Preserve business direction and precision | Target quantity fields | Validate positive values, precision, and unit conversion |
How to Configure It in Qeasy
First, create a source query strategy in Qeasy. Use POST, treat assNo as the business-number field, assId as the record identifier, and enable number and identifier validation. The query starts with applyStartDate and ends with applyEndDate. An incremental run can cover a recent window through the current time. A full replay must have an explicitly selected historical range; a fixed date must not silently represent a full history.
Next, configure the target execution strategy with POST and the batchSave action. FBillNo receives the document number, FStockOrgId receives the inventory organization, and FBillTypeID uses the target system’s supported assembly/disassembly document type. Configure FAffairType with a conditional expression: map assembly to Assembly and disassembly to Dassembly according to assembleType. Organization, owner, and material-code mappings should be maintained centrally in Qeasy rather than independently in each strategy.
Then enable response auto-fill so the identifier returned by the target is written back to the intermediate record. This makes retries and tracing possible. If the target rejects an entire batch because of duplicates, validation errors, or missing material codes, preserve the original response and split failures by document. Do not treat partial success as a complete failure.
Implementation Steps
Phase 1: Analyze and verify. Confirm the assembly or disassembly direction, as well as organization, material, warehouse, owner, unit of measure, and quantity precision. Select a small set of approved business documents for whitelist verification, focusing on target transaction type, material mapping, and inventory organization.
Phase 2: Establish the incremental starting point. Do not pull all historical production data on the first launch. Define an explicit starting point, such as the most recent day, and use that point as the beginning of the incremental window, with the current time as the end. For cross-time-zone or backdated-entry scenarios, use the business date rather than server time.
Phase 3: Trigger a full synchronization. Full synchronization should be triggered manually or by a maintenance task with a clear historical range. Pause the same type of incremental write during a full run, or let incremental results enter the intermediate layer first. Merge them after the full run using document-number deduplication so that one document is not processed by both paths simultaneously.
Phase 4: Set the scheduling frequency. The source query can run hourly and the target batch save every thirty minutes. Adjust the actual frequency according to document volume, interface response time, and acceptable business delay. If the target processes slowly, Qeasy should retain intermediate results and limit batch size to avoid repeated pulls.
Phase 5: Launch and retry. Start incremental synchronization with a recent, complete time window. Retry failed records according to the error type. Parameter errors should return to mapping configuration for correction; data-validation failures should be sent to business users for confirmation; only transient exceptions are suitable for automatic retry.
Lessons Learned
Pitfall 1: Deduplicate only by document number. Same-name numbers, changed numbers, or the same number across organizations can cause false matches. A safer approach is to use the number as the primary key and the record identifier as supporting information. If the target already contains the same number, check before writing and obtain business confirmation when necessary.
Pitfall 2: Reverse assembly and disassembly. If assembleType is passed directly as the target enum, the inventory transaction can be written in the wrong business direction. This is a common failure point. Perform an explicit conditional conversion in Qeasy and validate both directions with sample documents.
Pitfall 3: Scatter organization codes across scripts. When the target inventory organization and component owner directly use source values, maintenance becomes difficult after an organization-rule change. A common client response is to centralize code mappings in Qeasy and periodically check mappings that have become invalid.
Pitfall 4: Run full and incremental synchronization at the same time. Duplicate execution is often more difficult to detect than an occasional failure. Use full-trigger and incremental-pending patterns, or an incremental/full dual-track approach, but both paths must pass through the same number validation and merge logic.
Pitfall 5: Treat partial success as complete success. A batch interface can return an error even when only some documents are committed. Split the intermediate status according to the target’s per-record results, and record success, failure, and pending-retry states. Do not finish a task merely because the HTTP request succeeded.
Suitable and Unsuitable Scenarios
This strategy is suitable when assembly and disassembly documents already exist in the source system, the target system must create equivalent inventory transactions, and stable scheduling, traceable failures, and duplicate checks are required. It depends on clear mappings for organizations, materials, units of measure, and document status. It is not suitable for direct use when the two systems have no unified inventory organization, material codes cannot be aligned, or the target requires real-time per-event inventory processing without batch conversion. In those cases, complete material-master and inventory-rule governance first.