Practical Guide: Query-Only Currency Sync Strategy from Kingdee YXC to the Middle Layer

What This Strategy Solves (Scenario and Value)

In multi-system supply-chain integration, the currency master is a typical "small but critical" base-data record. In one retail enterprise project, the source system is Kingdee's cloud accounting platform (a v2 web API exposed by the back-end service), and the target side is an ERP platform. Settlement, exchange rates, and purchase pricing all depend on the currency dictionary. If the source system adds or disables a currency and the target side does not pick it up in time, subsequent documents will produce incorrect exchange calculations and unbalanced reports.

This query-only currency strategy has a very clear positioning: it does not actively write into the target business system. Instead, it consolidates the currency records into the middle layer hosted by the Qeasy data integration platform, serving as the "currency baseline table" referenced on demand by other strategies. This pattern of "middle-layer consolidation plus reference decoupling" is very common among Qeasy customers.

Data Flow and Field Mapping (Source → Middle Layer → Target)

The data flow is straightforward: source system → Qeasy middle layer → business strategies reference on demand. This strategy only handles the first two segments; it does not write back to the ERP side directly.

Key field mapping table (simplified per the actual scenario):

Business Meaning	Source Field	Middle-Layer Field	Notes
Currency internal ID	id	currency_id	Primary key
Currency code	number	currency_code	e.g. CNY, USD
Currency name	name	currency_name	For display
Status	status	is_active	Enabled / Disabled

The source API calls /jdy/v2/bd/currency, GET method, effect is QUERY. The target side is configured with Qeasy's internal "write empty operation," which lands the data in the middle layer (the actual persistence is handled by Qeasy's internal mechanism), with no business response fields required.

How to Configure on Qeasy

In the Qeasy data integration platform's strategy configuration page, create a new strategy and fill in the following key points:

Strategy name: Follow a naming convention that includes the "query-only" marker, for example 【仅查询】Currency-ok, so that future maintenance can identify it at a glance.
Source platform: Select the Kingdee v2 WebAPI adapter. API path: /jdy/v2/bd/currency. Request method: GET.
Request parameters: Leave the fuzzy search search blank; set pagesize to a fixed 100; let page auto-increment through the pagination loop.
Pagination and cursor: The source API is a paginated query; Qeasy pulls page by page by default. Here, set idCheck to true and use id as the idempotency key to avoid duplicate landing.
Target platform: Select Qeasy's own WebAPI adapter (datahub), choose the "write empty operation" API, effect EXECUTE, POST method, with request/response fields empty. This is not a misconfiguration; it is the typical pattern for this kind of consolidation strategy.
Metadata modeling: Set buildModel to false and autoFillResponse to true, so the platform lays out fields automatically based on the source response structure and saves manual modeling effort.

Implementation Steps

Phase 1: Establish the incremental baseline

Before going live, perform a manual inventory of currency records in the source system and confirm the total count and enabled statuses as the baseline. The first run is a full sync that lands the entire baseline into the middle layer. This step may look redundant, but almost every Qeasy customer has stumbled here: without a baseline, when the middle layer is found missing a few currencies one day, it is impossible to tell whether the source system failed to push or the middle layer dropped them.

Phase 2: Trigger the full sync

Manually trigger a full sync once and confirm the page size and filter conditions are correct. Currency records are generally small in volume (tens to hundreds), so a full sync finishes in a few minutes. Once the full sync passes, switch the strategy from manual to scheduled.

Phase 3: Schedule frequency

This strategy's crontab is 59 2 * * * (runs at 02:59 every day). There is a trick here: avoid the peak at the top of the hour and pick a "minute offset" when the source system is relatively idle. A common pattern among Qeasy customers is "dual-track incremental and full": this strategy performs a daily full sync as a safety net, and for enterprises with frequent currency enable/disable changes, an additional change-time-based incremental strategy is layered on top. This material only demonstrates the full-sync strategy.

Phase 4: Monitoring and alerting

In Qeasy's runtime monitoring, watch two indicators: whether the record count per pull matches the source system's daily currency total, and the consecutive failure count. Currency sync failures do not blow up business immediately, but they will explode inside a nightly report job.

Pitfalls Recap

A typical mistake is hard-coding the pagination parameter in the request. If the page field is configured as a fixed value of 1, the next day's sync will always return the same page. The safe approach is to leave it to Qeasy's pagination loop mechanism so the platform flips pages automatically.
Never turn off idCheck. Currency records can be re-pushed by the source system and create duplicates. Once the idempotency check is off, the middle layer will have "multiple rows for the same code," and downstream reference strategies will hit random rows, making troubleshooting extremely painful.
Do not mistake the target-side "write empty operation" for a misconfiguration. When first seeing this setup, new engineers will suspect they forgot to fill in fields. In fact, this is Qeasy's standard pattern for "middle-layer consolidation": the target adapter itself does not map business fields, and the data is persisted into the platform's own intermediate tables.
Avoid scheduling time colliding with the source system's backup window. In one customer engagement, the currency sync stalled at 3 a.m. because the source system was doing a data backup. Moving the cron to 02:59 made the issue disappear.
Align the currency-code naming convention at the source. ERP target systems such as the one used in this project have strict character validation on currency codes (usually requiring uppercase letters). If the source system has lowercase codes like cny, add a conversion step in Qeasy's field mapping rather than expecting the target system to convert automatically.

Suitable and Unsuitable Scenarios

Suitable: Scenarios where the currency record volume is small (within hundreds), the change frequency is low, and multiple downstream strategies need to reference a unified source; also multi-system integration architectures that wish to decouple "base data" from "business documents."

Not suitable: Scenarios where the source system adds currencies frequently and requires real-time sync to the target business system; nor scenarios where the source currency fields differ greatly from the target and require per-field customized mapping — the latter is better served by centralized encoding-mapping management at the material level.