Material Master Data Sync in Practice: A Single-Strategy Implementation from Kingdee KIS Private Cloud to Heihu Workshop

What This Strategy Solves (Scenario & Value)

For one manufacturer, material master data lives in Kingdee KIS Private Cloud while shop-floor work orders run on Heihu Workshop. The two systems used different coding schemes and update cadences, so picking, BOM referencing, and work order creation were constantly breaking. The material master sync strategy does something simple yet critical: push material records from KIS into Heihu incrementally so the shop floor references a single, consistent material dictionary. We built this pipeline on the Qeasy Data Integration Platform, wrapping source query, field mapping, and target write into a single monitorable, re-runnable, traceable sync strategy.

Data Flow and Field Mapping

The flow is unidirectional: source KIS (on-premises) → Qeasy middleware → target Heihu Workshop. The source side uses a paginated query interface that pulls change records within a time window; the target side uses a product creation API keyed by material code.

Key field mapping (core fields only, actual projects may vary):

A common pitfall: source id and number are both set to FNumber, meaning if KIS ever changes a code (rare but possible), the sync chain cannot detect it. Our safe practice is to set source idCheck=false and rely on the business code as the idempotency key, while target idCheck=true so Heihu deduplicates on productCode.

How to Configure in Qeasy

Break the strategy into three segments: source reader, mapping processor, target writer.

Source configuration highlights:

• Endpoint calls KIS's material list query via POST; pagination driven by ItemsOfPage=20 and CurrentPage using Qeasy built-in pagination variables.
• Time window uses StartDate / EndDate placeholders bound to LAST_SYNC_TIME and CURRENT_TIME; replace spaces with T to match KIS's ISO timestamp format.
• AccountDB is passed as input to isolate by organization at the source.

Target configuration highlights:

• Calls the product creation API via POST.
• Field mappings use lightweight expressions like {{FNumber}}, {{FName}}, {{FModel}}—no custom scripts needed for most fields.
• Fixed-value fields (product attribute, unit) are maintained centrally in Qeasy rather than scattered across strategies. This is the "centralized encoding mapping" pattern we often recommend: change a constant in one place.

Scheduling: source cron is 0-59/10 7-20 * * *; target is offset by two minutes at 2-59/10 7-20 * * * so the writer never starts before the reader finishes.

Implementation Steps

We usually roll out in three phases, each with clear deliverables and verification points.

Phase 1: Incremental Starting Point (Full Init + Incremental Anchor)

• Before the first run, manually set LAST_SYNC_TIME to a point well before historical data (e.g., one year back) and do a cold-start full sync.
• After the full sync completes, reset LAST_SYNC_TIME to this completion timestamp as the incremental anchor.
• This avoids the back-and-forth of "run incremental, notice missing data, then patch."

Phase 2: Incremental Sync (Every 10 Minutes)

• Enable cron; pull every 10 minutes during business hours (07:00–20:00).
• Qeasy automatically uses the last successful timestamp as StartDate and current time as EndDate.
• Failed records enter a retry queue without blocking the main flow.

Phase 3: Tune the Schedule

• After two weeks, review Qeasy's runtime reports for average duration and page count.
• If changes are sparse, drop frequency to every 15 or 30 minutes.
• If changes are dense and shop floor needs near-real-time, evaluate shorter intervals—but a common Qeasy customer pattern is the "dual-track" approach: high-frequency incremental for daily use plus a nightly validation full sync.

Lessons Learned

1. Timestamp format mismatch: KIS expects ISO timestamps separated by T. Passing YYYY-MM-DD HH:mm:ss directly returns an empty page. Always use a _function expression to replace the space.
2. Pagination gaps: KIS pagination is driven by CurrentPage, and Qeasy handles it automatically, but ItemsOfPage hardcoded at 20 is slow for large datasets. Load-test and tune to 50–100.
3. Target idempotency failure: Heihu dedupes on productCode, but if historical dirty data already contains the same code, writes fail. Safest practice: reconcile on the target side first, pull the anomaly list, clean manually, then start sync.
4. Hardcoded units and attributes scattered: A typical mistake is putting "unit=个" directly in the strategy. When the customer later asks for "件," you must edit a dozen strategies. We centralize these in Qeasy's constant mapping table so one edit covers all.
5. Account switch forgets sync parameters: AccountDB is an input, not an output. Switching accounts requires more than just updating the source side—you must also confirm the target side writes into the correct organizational context.

Applicable and Non-Applicable Scenarios

Applicable: source is an ERP/KIS-class system, material master data is relatively stable, and a manufacturer needs high-frequency incremental sync to MES/WMS. Not applicable: source cannot query by time window, target cannot dedupe on business code, or material master changes so frequently that near-real-time push is required—the latter should move to a message-queue-triggered real-time architecture.