From Production Task Order to Work Order: A Single-Strategy Deep Dive on Syncing KIS Private Cloud to Heihu Workshop
What This Strategy Solves (Scenario and Value)
On the shop floor of a discrete manufacturing enterprise, the production task order issued by the ERP is the planning perspective, while the work order on the MES side is the execution perspective. Once the two sides go out of sync, the workshop ends up in the awkward state of "work orders without tasks, tasks without work orders." A common situation we encountered on a customer site: a manufacturer's KIS private cloud issues dozens to hundreds of production task orders every day. These documents need to land in Heihu Workshop as work orders keyed by planned start time, serving as the entry point for material requisition, job reporting, and kit-shortage analysis. This strategy solves the "task order → work order" link. The key value is to carry the planned time, planned quantity, and product code over in one pass, so the workshop does not have to re-enter anything.
Data Flow and Field Mapping (Source → Middle Layer → Target)
The overall link is one-way A → B. The source system is KIS private cloud, which pulls the production task order list through a RESTful interface. The middle layer is the Qeasy Data Integration Platform, which handles field mapping, code conversion, and time formatting. The target system is Heihu Workshop, which writes the work order master data through a WebAPI.
Key field mapping table:
| Business meaning | Source (KIS private cloud) | Target (Heihu Workshop) | Mapping notes |
|---|---|---|---|
| Document number | FBillNo | projectCode | Passed through directly as the idempotency key |
| Product code | FItemID | productCode | Lookup table converts to FNumber via the material strategy |
| Planned quantity | Fauxqty | plannedNum | Passed through directly, string type |
| Planned start time | FPlanCommitDate | planStartTime | DATE_FORMAT normalized to yyyy-MM-dd HH:mm:ss |
| Planned end time | FPlanFinishDate | planEndTime | Same as above, time formatting applied |
| Incremental cursor | KIS-Timestamp | — | Controlled by {{LAST_SYNC_TIME}} |
The source interface has a paging parameter CurrentPage, while the target is a single-record creation interface that needs to loop through each order.
How to Configure It on Qeasy
On the Qeasy Data Integration Platform, the core of this strategy's configuration is the "source query + target execution" combination:
- Source side: Choose the KIS private cloud adapter, select API
/manufacturingorder/list, method POST, paging field CurrentPage; bind the incremental field to{{LAST_SYNC_TIME}}as the request value for KIS-Timestamp. - Target side: Choose the Heihu Workshop adapter, select API
/api/dytin/external/project/create, method POST, write one record at a time. - Field mapping: For productCode, use
_findCollectionto look up FNumber by FItemID from the result set of the material sync strategy. This is a common pattern among Qeasy customers — "centralized code mapping management." Product codes are maintained in a single strategy, and business document strategies only reference them, avoiding duplicate maintenance on both sides. - Function processing: Time fields are uniformly handled with
_function DATE_FORMAT(..., '%Y-%m-%d %H:%i:%s')as a fallback, to prevent target-side errors when the source returns empty or non-standard formats.
Implementation Steps (Phased Scheduling)
Production task order sync emphasizes "incremental starting point + full-volume fallback + high-frequency scheduling":
- Incremental starting point: At first launch, initialize
{{LAST_SYNC_TIME}}to a recent historical timestamp (for example, the day before launch) to avoid missing records. - Full-volume trigger: On the first day of launch, manually trigger a full backfill to catch up on historical task orders; afterward, only run incremental.
- Scheduling cadence: The source crontab is set to
30 7,9,11,13,15,17,19,21 * * *(query triggered every two hours at the half-hour mark), and the target crontab is set to3-59/15 7-22 * * *(write execution every 15 minutes). This "staggered query and execution" is the dual-track rhythm common among Qeasy customers — queries pull data, execution digests data, neither blocks the other. - Dependencies: This strategy depends on the material strategy, ensuring that product codes are in place before the work order's productCode can be resolved.
Pitfalls and Lessons Learned
- Code mapping not centrally managed: In the early days, some customers wrote the FItemID → FNumber conversion directly into the work order strategy. As soon as the material side changed a code, every work order broke. The safe approach is to use
_findCollectionto reference the material strategy's result set — change once, take effect everywhere. - Time field null crashes: The source occasionally returns FPlanCommitDate as empty, while the target's datetime field is required, resulting in a direct 422. The recommendation is to add a default value in the mapping layer (for example, current time + 24 hours), or use an IFNULL fallback in the function.
- No idempotency key designed: projectCode passes FBillNo directly, which looks naturally idempotent, but if the source document number is duplicated or resent, the target will create duplicate work orders. This is a common place to crash. The safe approach is to enable idCheck=true in the target adapter, and take an update branch on failure rather than inserting another record.
- Header and body mixed together: A production task order usually has a header plus multiple lines (BOM components), but this strategy only syncs the header dimension, leaving the lines for a later stage. If you stuff the body into the same projectCode all at once, Heihu will split it into multiple work orders by "finished product + component," which only makes things messier. The recommendation is to phase it: first get the header working, then add the body.
- Incremental cursor rolled back: KIS-Timestamp uses the last sync time. If the server clock drifts, you can get "incremental range rolling backward," causing missed records. From an operations standpoint, monitor the time difference between the source and the Qeasy platform, and alert when it exceeds the threshold.
Applicable and Non-Applicable Scenarios
Applicable: scenarios where the ERP issues production task orders, the shop-floor MES needs to generate work orders keyed by planned start time, planned quantities are relatively stable, and there is no need to write back job-reporting data. Not applicable: bidirectional sync that needs to write back actual completed quantity and scrap quantity from work orders to the ERP; and scenarios where the source document structure differs greatly from the target and requires a custom intermediate table for conversion — for the latter, it is better to split it into multiple strategies rather than stuffing everything into one.