Querying VC Grade List and Syncing to Kingdee Grade: A Practical Breakdown of a Master Data Sync Strategy

What This Strategy Solves (Scenario and Value)

In a real project, the client used a North America-oriented student management VC system on the front end, while finance and academic organization master data lived in Kingdee Cloud. Grade levels (grade_level) are small in volume, but if they are wrong, classes, students, fees, and reports all go out of alignment. Early on, they maintained grade data in Kingdee manually via spreadsheets, and within two months it collapsed—additions, deactivations, and merges all depended on human memory.

Querying the grade list from VC and writing it into Kingdee Cloud's organization/basic data as an "automatic, reconcilable, traceable" sync chain solves the problem. On the client site, we used the Qeasy Data Integration Platform to host this strategy, positioned as a small-volume, strongly-consistent master data sync.

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

The overall flow is one-way pull: the A-side (VC document) uses a WebAPI to query the grade list, Qeasy acts as the middle layer for field transformation and code mapping, then calls the B-side (Kingdee Cloud) batchSave to write the data.

The source side uses idCheck=true, meaning the grade code acts as an idempotency key; the target side also verifies on the id dimension, so re-writing the same code is recognized as an update rather than a new insert—this is the key basis for setting up the "incremental starting point" later.

How to Configure on Qeasy

On Qeasy, this strategy is essentially a standard "one source query + one target execute" chain, requiring no complex orchestration. The key is to centralize the mapping rules.

1. Connect the source platform: Create a VC document connection, fill in the tenant credentials, and bind the grade_level API metadata. Set X-Page-Size to 1000 first; adjust later if grades exceed 1000.
2. Connect the target platform: Create a Kingdee Cloud connection, select batchSave, and turn org-dimension fields like FCreateOrgId and FUseOrgId into "platform-level constants" rather than filling them in per strategy—this is one of the common practices among Qeasy clients: centralized management of code mappings.
3. Field mapping: In the mapping canvas, drag grade_level to FNumber, and assemble the name field into the multilingual package structure (1033 for English, 2052 for Simplified Chinese). FName is required by Kingdee; always confirm the template JSON has no syntax errors.
4. Idempotency and write-back: Enable idCheck. Qeasy will trigger the update branch when FNumber matches an existing record, and the insert branch when it does not.
5. Logs and alerts: Enable full source-response logging and target-request parameter snapshots. When issues arise, you can directly diff which grade_level failed.

Implementation Steps (Phased Scheduling)

Grade-level master data has small volume but cannot afford disorder. We generally run it in three phases:

Phase One: Full Initialization Manually trigger once to write all existing VC grades into Kingdee. The crontab field in the materials is "1 1 1 1 1" (indicating no real cycle is enabled by default). During initialization, we temporarily change it to run once a day at dawn, observe for 3 consecutive days to ensure no duplicates or missing records, then move to the next phase.

Phase Two: Incremental Starting Point Once the full sync is stable, immediately switch the recognition rule from "pull all" to "pull incrementally by update time/ID". The incremental starting point is recommended to be the timestamp of the most recent full sync completion, to avoid overlap with Phase One. A common Qeasy client practice is dual-track incremental and full sync: run incremental normally, keep a full sync verification at the start of each month to detect "drift between the two ends".

Phase Three: Steady-State Scheduling Grade-level changes occur at low frequency; scheduling it once a day at dawn is sufficient. If the client's organization changes frequently, it can be compressed to every 6 hours—but no higher frequency. Grades are not orders; over-scheduling only generates redundant logs.

Lessons Learned (Practical Experience)

1. FName multilingual package JSON typo fails the entire batch: Kingdee's FName must follow the [{Key,Value}, ...] structure. Missing a comma or extra newline causes the interface to return a parameter error directly. It is recommended to extract this mapping as a "snippet" in Qeasy; reuse must be validated with a JSON-checking tool first.
2. Ignoring the meaning of idCheck and treating updates as inserts: Some engineers see idCheck=true and enable it on the target side as well. The result is that Kingdee uses FNumber for matching—matched records go through the update branch, unmatched go through the insert branch—but if FNumber is not passed or is empty, it mysteriously creates a batch of "empty-code" organizations. The safe approach: source primary key fields must be non-null validated, and required target fields must never be left empty.
3. X-Page-Size set too large blows up the middle layer: Grades only have a few hundred entries, but some engineers set it to 5000 to save effort, and the response body ends up stuffed with irrelevant fields. It is recommended to set pagination size according to the actual data volume—pulling more pages is better than pulling too much at once.
4. Hardcoded organization dimensions collapse when the org changes: FCreateOrgId and FUseOrgId are hardcoded in each strategy. When the client changes organization, all 4 strategies must be modified. We later used Qeasy's "organization dimension constants" to manage these centrally, so one change propagates across the entire chain.
5. Misreading the crontab expression: "1 1 1 1 1" looks like "every day at 1 o'clock", but its meaning varies across cron parsers, which can cause it to run happily in test environments but stay still in production. The safe approach is to configure cron visually directly in Qeasy's scheduling panel, rather than relying on the string in metadata.

Applicable and Non-Applicable Scenarios

Applicable: "Basic data / master data" with stable codes and low-frequency changes that require cross-system alignment, such as grade levels, departments, product categories, regional dictionaries, etc.; both ends have clear primary keys and support idempotent writes.

Not applicable: Large business documents (orders, inventory transfers) going through batchSave will hit performance bottlenecks; scenarios where the source lacks stable primary keys, performs frequent physical deletes, or the target does not support idempotency—this chain cannot sustain such loads.