Pulling Customer Master Data from QiQiao: An Incremental Strategy with Qeasy Integration

What This Strategy Solves

In retail and distribution scenarios, customer master data often lives in multiple systems: one copy in CRM, a set of records in an OA form, another in the e-commerce platform. In a recent project, a retail client kept their store customer records in a low-code form on QiQiao, while downstream modules for orders, membership, and marketing all needed that same record. Letting every downstream system call QiQiao's API directly not only pressured the interface but also fragmented field definitions.

Our approach was to introduce a query-only strategy: pull customer master data from QiQiao into an intermediate layer on the Qeasy Integration Platform on a time-window schedule, so downstream consumers only read from the intermediate layer. This guarantees a single source of truth and makes encoding mapping and staged header/body delivery much easier. This article focuses only on the configuration and pitfalls of that single query strategy.

Data Flow and Field Mapping

The flow is unidirectional: QiQiao (source) → Qeasy Integration Platform (target). The source is flagged as system B, the target is the platform's intermediate layer, marked INTERNAL. The strategy type is QUERY_ONLY, responsible only for retrieving data, not for writing back into business systems.

The table below shows the key fields on the source side (desensitized):

The target-side metadata is a "write no-op": the response lands directly in the Qeasy intermediate table, without a second business-API call. This is a common pattern: the intermediate layer absorbs all raw fields, and downstream consumers pick what they need.

Configuring the Strategy on Qeasy

In Qeasy Integration Platform, the typical configuration points are:

1. Source API: type WebAPI, effect QUERY, method GET, path /plus/cgi-bin/open/applications/{applicationId}/forms/{formModelId}. Enable idCheck and autoFillResponse, keep buildModel off. The platform then auto-generates intermediate-table fields from the response shape.
2. Business identifier: use 客户名称 (Customer Name) as both number and id — the business primary key for deduplication and update in the intermediate layer.
3. Target side: choose Qeasy Integration Platform (datahub), effect EXECUTE, method POST, attach a "write no-op" that lands the data directly into the intermediate layer.
4. Time-window variables: startTime uses {{LAST_SYNC_TIME}}000, endTime uses {{CURRENT_TIME}}000. This is the standard Qeasy expression for "incremental start point" — the platform injects the last successful time and current time at each run.
5. Platform registration: register QiQiao as Do1QQ and Qeasy as datahub. All subsequent strategies reference these two codes.

After configuration, Qeasy runs this flow automatically: fetch variables → build URL → call QiQiao → parse response → land in the intermediate layer → write LAST_SYNC_TIME.

Implementation Steps

In practice we roll out this query strategy in three steps:

Step 1: confirm the incremental start point. Before go-live, run a one-shot "full pull": set startTime to a very early date and endTime to the current time, then verify that the intermediate-layer customer count matches the QiQiao form's row count. We trigger this manually rather than relying on a built-in full-pull, so that LAST_SYNC_TIME is not polluted.

Step 2: switch to incremental scheduling. The cron we use for the incremental run is 1-59/4 8-23 * * *: every 4 minutes between 08:00 and 23:59, offset by 1 second to avoid the top-of-hour stampede. This is exactly the value in the source material. Tighten it to 1–2 minutes for large data volumes; loosen it to 10 minutes for smaller ones.

Step 3: connect upstream and downstream. This strategy is sequence: A, meaning it runs first as a query strategy. Downstream strategies like the sales-order sync (type: SYNC, sequence: B) rely on depends_on or direct upstream/downstream wiring in Qeasy, so the order is: order arrives → look up the customer record in the intermediate layer → push to the downstream system. This staged delivery — master data first, transactional data after — must not be reversed.

Pitfalls from the Field

Here are the typical problems we have hit at client sites:

1. Wrong applicationId or formModelId. QiQiao's API uses these as path parameters; a typo yields a direct 404. The safe practice on Qeasy is to expose them as environment variables, with separate values for test and production, so a missed edit never reaches production.
2. Timestamp precision mismatch. QiQiao's createDate is typically millisecond-precision, while {{LAST_SYNC_TIME}}000 is a second-level timestamp multiplied by 1000 to fake milliseconds. Sending raw seconds produces year 1970. The safe move is to debug the variables in Qeasy and print the actual value to the log before going live.
3. LAST_SYNC_TIME overwritten by full pulls. Running a full pull directly will overwrite the last successful incremental time, causing subsequent incremental runs to miss data. That is why we use manual full pulls plus a separately tracked incremental start point.
4. 客户名称 is unstable as the business key. We have seen clients rename 客户名称 in QiQiao, which turned an "update" into an "insert" in the intermediate layer. If the business allows, prefer a system field as the id; if not, add a secondary check inside Qeasy.
5. Schedule frequency clashes with QiQiao rate limits. QiQiao's open API has QPS limits. A 1–2 minute interval is usually fine; 30 seconds will quickly trip throttling. Configure failure retries with backoff in Qeasy so that throttled runs automatically stretch their interval.

When to Use and When Not

Use it when: you need to pull QiQiao's customer/store/product master data into an intermediate layer for multiple downstream consumers; you want incremental sync by createDate/updateDate; you need to prepare master data for downstream transactional strategies.

Do not use it when: sub-second real-time freshness is required (the cron has its own interval); or when you need a write-back strategy. This strategy is QUERY_ONLY — the landing step relies on the target-side "write no-op". Real business write-back requires a separate SYNC strategy.