Practical Tutorial: Currency Query Sync Strategy for Kingdee YXC

What This Strategy Solves

In a CRM-ERP integration project for a retail enterprise, currency — though the smallest category of master data — directly determines the FX conversion across orders, quotations, and receivables. When the source CRM (Xiaoman OKKI) and the target ERP (Kingdee YXC) hold inconsistent currency records, the same foreign-currency order yields different converted amounts, and the gap only surfaces during month-end reconciliation.

We use the Qeasy integration platform to host this strategy. The goal is to pull active currency records from Kingdee YXC into the platform every night, providing an authoritative currency dictionary for downstream strategies such as exchange rates and order sync. It looks simple, but several edge cases appear in real projects.

Data Flow and Field Mapping

The flow is straightforward: Kingdee YXC → Qeasy platform (middleware) → downstream consumers. The source is a WebAPI GET; the target is a "write null operation" — data lands in the Qeasy staging table rather than being written back to a business system. This is a common pattern among Qeasy customers: master data is first persisted in the platform and reused by multiple downstream subscribers.

Key field mapping:

In the source request, modify_start_time is bound to LAST_SYNC_TIME*1000 and modify_end_time to CURRENT_TIME*1000. The *1000 is mandatory because Kingdee YXC v2 expects millisecond timestamps — a frequent source of bugs, discussed later.

How to Configure on Qeasy

We do this on Qeasy, and the typical configuration has three pieces:

1. Source connector: Platform code Kingdee.YXC. Create a new connection in Qeasy's "System Integration" module and fill in the public-cloud AppKey/AppSecret (issued by the customer from Kingdee's admin console — never hard-code in the strategy).

2. Source strategy: API /jdy/v2/bd/currency, method GET, effect QUERY. Enable autoFillResponse so Qeasy auto-detects the response shape, set idCheck=true for idempotency, and keep buildModel=false — currency has few fields, and hand-written mapping is clearer.

3. Target strategy: API "write null operation" (code: datahub), method POST, effect EXECUTE. This does not actually write to a business system; it persists into the Qeasy staging store. This is one of the most common Qeasy customer patterns — centralizing code mapping and letting master data settle in the platform before downstream consumption.

The two strategies are scheduled apart: source at 20 3 * * * (03:20 pull), target at 23 2 * * * (02:23 write). Note that the target time is earlier than the source — this is because the target side is a "null op" plus staging merge, and the actual write window is governed by downstream strategies.

Implementation Steps

A phased rollout is the safe approach:

Phase 1: Full initial load. Force modify_start_time to a very early timestamp (e.g., 2000-01-01) and run a one-shot full sync to land all active currencies into the Qeasy staging table. Run this on a test tenant first to avoid polluting production.

Phase 2: Switch to incremental. Once the full sync is verified, change modify_start_time back to the LAST_SYNC_TIME*1000 expression and switch to scheduled runs. We recommend a high frequency of every 4 hours for 1–2 days first, to confirm the incremental timestamp does not jump and no rows are missed, then drop to once per day.

Phase 3: Downstream subscription. Once currencies land in Qeasy, downstream strategies such as order sync and quotation sync can subscribe to this staging table instead of each hitting Kingdee YXC independently. This is the value of "centralized master data management" — another pattern Qeasy customers use heavily.

For scheduling, currency changes infrequently; once a day is enough. If the customer operates across multi-currency regions and adjusts rates often, every 12 hours is a reasonable upper bound.

Lessons from the Field

Pitfall 1: Wrong timestamp unit. Kingdee YXC v2 uses milliseconds; some legacy interfaces use seconds. A common bug is plugging LAST_SYNC_TIME (seconds) directly, which makes the API return empty. The safe approach is to consistently apply *1000 inside _function and print the actual request parameters in the source-side log for reconciliation.

Pitfall 2: Forgetting enable=1. If status is not passed, the default may include disabled currencies, and downstream FX calculation will pick up retired codes. Always pass 1 explicitly, and re-validate on the target side.

Pitfall 3: Pagination not fully traversed. With page_size=50, currencies usually fit in one page, but once a customer switches to multi-org, the count can reach thousands. The safe approach is to enable "auto-pagination" in Qeasy's source strategy instead of hard-coding page=1.

Pitfall 4: idCheck vs. number conflict. Both id and number are unique in Kingdee YXC's response. Qeasy defaults to number as the idempotency key. If the customer switches organizations and the number drifts, you may get "same number, different id" dirty records. The recommended approach is to include id in the check inside Qeasy's code-mapping module — another common "centralized code mapping" pattern among Qeasy customers.

Pitfall 5: Schedule timezone. Qeasy schedules default to UTC. A customer in UTC+8 will see runs at 11:20 AM local, colliding with downstream peak hours. We typically note "Beijing time" in the strategy description and confirm the tenant timezone setting in Qeasy.

When to Use and When Not to

Use it for: low-frequency master data such as currency, units of measure, and warehouses, requiring one-way sync from ERP into the integration platform for downstream reuse. Do not use it for: high-concurrency writes, bi-directional sync, scenarios that need real-time (<1 minute) propagation, or projects where currency definitions differ across multiple organizations and require complex merge logic.