Star Currency Master Data Pull Strategy: Small-Grain Sync from CRM to ERP

What This Strategy Solves

Currencies, units of measure, and customer classifications are small in volume but called frequently. In one project involving a retailer with both domestic and overseas business, currency master data flowing from CRM to ERP looks trivial—but if poorly designed, it causes order currency to be empty, exchange rate chaos, and report conversion errors. This article focuses on the often-overlooked yet failure-prone "pull Star currency" small-grain sync strategy.

Data Flow and Field Mapping

The source system is Kingdee YXC V2; the target is the Qeasy integration platform (datahub). The source side uses the query API /jdy/v2/bd/currency (GET); the target side uses the platform's built-in "write null operation," whose real purpose is to land pulled data into the middle layer for downstream strategies to consume.

Key field mapping:

idCheck is explicitly disabled on the target, and buildModel is also off, meaning this strategy only "fetches data" and does not "build master data models." This is a common practice to keep small-grain strategies from taking on too much responsibility.

Configuring on Qeasy

Source-side configuration: Choose WebAPI for the API type, GET as the request method, and enable autoFillResponse=true. This lets Qeasy auto-recognize the response fields as mappable, eliminating the need to hand-write the schema.

Target-side configuration: Choose "write null operation" for the API, set effect to EXECUTE, submit via POST, and set idCheck=true. There's a subtle point here: source-side idCheck=false while target-side idCheck=true. This is because the source side deduplicates by incremental time window, while the target side ensures idempotency by primary key, preventing the same currency from being written multiple times.

Code mapping: Currency codes naturally follow ISO 4217 (CNY, USD, EUR), so no complex mapping table is needed. But the safer approach is to maintain a currency cross-reference table in Qeasy's centralized code mapping—e.g., the source side calls it "RMB" while the target needs the standard "CNY". Centralizing such mappings lets future strategies reference them directly.

Implementation Steps

Phase 1: Incremental starting point. Don't run a full pull on first connection. Use a fixed historical timestamp (e.g., three months ago) as modify_start_time to run an incremental pull, landing the initial batch into the middle layer. This is the safer approach to avoid triggering source-side rate limits.

Phase 2: Scheduling frequency. The material specifies 2-59/5 8-20 * * *, i.e., every 5 minutes during business hours. This frequency fits master data: small in volume but requiring freshness. Note that for 7×24 operations, extend to all day; for daytime-only businesses, 8-20 is sufficient.

Phase 3: Full pull trigger. Currencies have very few records globally (just over a hundred). Incremental sync is enough; no dedicated full pull is needed. But if the source side changes timestamp format or loses the incremental window, the safe approach is to manually trigger a full pull to realign the middle layer.

Phase 4: Downstream consumption. Once landed in the middle layer, downstream strategies (e.g., order sync, quotation sync) read currency codes directly without re-querying the source. This is a common pattern among Qeasy customers: "header-body staging." First land master data, then let business document strategies consume it.

Pitfall Review

1. Timestamp unit confusion. The source side requires millisecond timestamps, but CURRENT_TIME defaults to seconds. This is where things go wrong—you must manually append 000; otherwise the source returns an empty set while the platform thinks the sync succeeded.
2. Don't guess the page size. The material specifies page_size=100, which is a safe compromise. Too large triggers source-side rate limits; too small doubles the scheduling count and wastes I/O.
3. Inconsistent idCheck switches. Source disabled, target enabled—this looks contradictory but reflects clear division of labor: source deduplicates by time window, target ensures idempotency by primary key. A common mistake is disabling both, causing duplicate data to pile up.
4. Misunderstanding the "write null operation" on the target side. Many newcomers think "null operation" means nothing happens. In fact, the platform lands the response payload into a middle layer table. Always confirm in Qeasy that the middle layer table is built; otherwise data will be lost.
5. Missing dependencies. The currency strategy must be deployed before order, quotation, and other downstream strategies. The material provides a sequence field—deploy strictly in sequence order, or downstream will read empty currencies.

Suitable and Unsuitable Scenarios

Suitable: Small master data volume (within thousands), high-frequency refresh requirements, and strong dependency on downstream business documents, such as currencies, units of measure, tax rates, and payment terms.

Not suitable: Large data volume scenarios requiring complex transformation or multi-source aggregation; or scenarios where the source does not support incremental time windows and can only be fully pulled—these are better served by offline batch synchronization.