Syncing Store/Shop Master Data from a Source ERP to Qeasy: A Field-Proven Walkthrough
What This Strategy Solves (Scenario & Value)
In supply-chain integration projects at retail clients, we often face a deceptively simple requirement: pull store/shop master data from a source system into the Qeasy integration platform so it can serve as the shared reference for downstream processes (orders, inventory, reconciliation). It looks like "just moving some basic data," but if code mappings are misaligned or branch open/close status isn't transmitted correctly, within three months downstream reports will show mismatched store counts or list closed stores as available. This strategy gets that right with minimal overhead.
Data Flow & Field Mapping (Source → Middle Layer → Target)
The overall flow is one-way: source ERP → Qeasy integration platform → downstream consumers (such as the finance/ERP system). This strategy covers only the first two segments—source to Qeasy.
| Source Field | Qeasy Middle Layer | Downstream Consumer | Notes |
|---|---|---|---|
| store_code | store_code | store_code | Primary key, globally unique |
| store_name | store_name | store_name | Name changes should update, not insert |
| status | status | status | Open/closed status needs explicit enum |
| contact info | contact_info | contact_info | Sensitive—desensitize before distributing |
| org_id | org_id | org_id | Org changes affect downstream permissions |
In practice we centralize all code mappings in Qeasy's mapping table rather than scattering them across each strategy's scripts, so cross-system changes only require one edit.
How to Configure in Qeasy
In the Qeasy console, this strategy is defined as an INTERNAL-direction SYNC task, marked with sequence A, indicating it's the first leg of the upstream master-data sync chain.
Typical configuration points:
- Source connection: points to the source ERP's open API. Fill in authentication per the Qeasy connector spec; always use a dedicated application account in production.
- Extraction mode: store master data isn't huge but changes often. We usually adopt a dual-track approach—"incremental by update time + daily early-morning full validation"—with separate crontabs in Qeasy's scheduler.
- Target write: the target is Qeasy's own data model (PLATFORM), no need to write back to the source.
- Field mapping: configured visually in Qeasy's field-mapping page—source field, target field, transform function in three aligned columns.
- Exception policy: retry 3 times on failure, then route to a "manual handling" queue rather than silently dropping the record.
Implementation Steps
At the client site we generally proceed in three steps:
Step 1 — Set the incremental checkpoint. The first time this goes live, Qeasy needs a clear "time anchor" and will only pull stores changed after that point. Set it too early and you waste API quota re-pulling everything; too late and you'll miss stores that opened on launch day. We recommend anchoring at 23:59 the day before go-live.
Step 2 — Trigger a full validation pass. Once incremental runs are stable, manually trigger a full reconciliation to confirm no historical stores are missed and statuses are correct, then switch the schedule from manual to automated.
Step 3 — Set the schedule. Store master data doesn't change very frequently, so most clients opt for every-15-minute increments plus a daily full validation, all managed centrally in Qeasy's scheduler.
The whole loop usually closes in 2–3 working days.
Pitfalls from the Field
- Scattered code mappings: in v1 we let each strategy maintain its own store-code translation. When the source later switched its encoding scheme, we had to touch seven places to find them all. The safer approach is to centralize everything in the Qeasy mapping table.
- Treating "closed" as "deleted": the source flagged closed stores with a "closed" marker, but downstream interpreted it as deletion, breaking the link from historical orders to stores. Recommend explicitly distinguishing "closed" from "deleted" in Qeasy's field transforms—closed is an update, only deletion does a physical remove.
- Misaligned initial checkpoint: anchoring at 00:00 on launch day caused two stores opening that day to be missed. Safer to anchor right after closing time the day before, leaving enough buffer.
- Unsanitized sensitive fields: contact phone numbers were pushed as-is to multiple downstream systems, and an audit later required remediation. Just add a desensitization function in Qeasy's field-processing node—preferably at platform entry, not duplicated downstream.
- Undeclared dependencies: this strategy is sequence A; downstream product, customer, and inventory strategies all depend on it. If the dependency isn't explicitly marked in Qeasy's dependency graph, on-call engineers running manual replays can trigger out-of-order execution, causing downstream empty runs or duplicate writes.
When to Use and When Not To
Use it for: multi-store retail, franchised chains, cross-system shared master data platforms, and any scenario where the store is a dimension on subsequent business documents.
Don't use it for: single-store businesses, scenarios with no downstream consumers, or when the source system is already the sole master-data source (adding another sync layer only introduces consistency risk).