Syncing Student Master Data from VC Docs to Kingdee Cloud: A Single-Strategy Walkthrough

What This Strategy Solves

Pushing student master data from a source system into Kingdee Cloud looks like a simple "pull a list and write it back." In real customer environments, the pain points are pagination, encoding mapping, and default organization values. After we onboarded this on the Qeasy Data Integration Platform, we collapsed it into a single A→B strategy whose goal is to land the source student list into Kingdee's customer profile so downstream documents can reference it directly and ops no longer have to key records by hand.

Data Flow and Field Mapping

The source side is a standard paginated WebAPI query (/v3/students, GET) that pages with X-Page-Size and X-Page-Number headers, 1000 rows per page. The target side is Kingdee Cloud's batchSave execute API (POST), writing into the customer profile.

The middle layer is Qeasy's strategy engine: pull, cleanse, assemble, write, and log. The key field mapping is:

Business Meaning	Source Field	Target Field	Handling Notes
Business key	`id`	`FNumber` (customer code)	Passed through; used as idempotency key
Given name	`first_name`	`FName` (multilingual)	Concatenated with middle and family
Middle name	`middle_name`	`FName`	Joined with spaces; skipped when empty
Family name	`last_name`	`FName`	Joined with spaces; skipped when empty
Create org	(not on source)	`FCreateOrgId=102`	Constant, not sourced
Use org	(not on source)	`FUseOrgId=102`	Constant, aligned with create org
Family ID	(not on source)	`F_VRKB_Base`	To be filled by a follow-on strategy

FName on Kingdee is a multilingual structure (1033 / 2052, etc.). The template must use a JSON array that puts the name under each language, not a plain string — that is a hard requirement of Kingdee's batchSave.

How to Configure It on Qeasy

On the Qeasy platform, this strategy is just one source endpoint, one target endpoint, and one schedule. No custom code required.

Source setup. API: /v3/students, GET, idCheck=true. number points to first_name only so the metadata has a recognizable business label; the real idempotency key is id. Fix X-Page-Size=1000 and start at X-Page-Number=1; pagination is handled automatically by the platform. Pick id, first_name, middle_name, and last_name out of the response so downstream can reference them.

Target setup. API: batchSave, POST. FNumber={{id}}. Build FName as a multilingual template that joins {{first_name}} {{middle_name}} {{last_name}}. When middle name is empty, fall back to an empty string in the template rather than emitting extra spaces. Set FCreateOrgId and FUseOrgId to the constant 102. Do not skip FUseOrgId — Kingdee will reject the record if it is missing.

Mapping policy. A common Qeasy customer pattern is to centralize encoding mappings into one mapping table that every strategy references. Header and body are also staged separately: this round only writes the student header profile; if you later need to bring in the student-family relation, do it as a second strategy rather than cramming family IDs into the student endpoint.

Implementation Steps

Cold-start full load. On the first run, page through the full source and lay down the baseline customer profile in Kingdee. Schedule this during off-peak hours so batchSave does not crowd out normal traffic.
Incremental anchor. Use source id as the cursor for the incremental anchor. Qeasy's dual-track mode — incremental by cursor, full load on demand — fits this case well.
Schedule frequency. Source crontab is 1 7,12,16,20 * * * (minute 1 of the chosen hours); target crontab is offset by 30 minutes to 30 7,12,16,20 * * *, leaving a window for the network and pagination round-trips.
Go-live observation. Watch three consecutive schedule windows: did pagination complete, did writes succeed, are organization fields populated.
Hand over to ops. Roll the strategy into daily monitoring. Let the platform handle retries; no more human babysitting.

Lessons From the Field

Writing FName as a plain string. Kingdee's batchSave expects a multilingual JSON array. We took the shortcut on the first attempt and got back a 200 with empty names — half a day lost in troubleshooting.
Forgetting FUseOrgId. Many engineers set only FCreateOrgId and assume "use org" is implied. Kingdee does not guess; missing this field is a hard reject.
Empty middle_name produces double spaces. Naive concatenation turns a blank middle name into "John Smith." The safe pattern is to skip empties in the template or use a normalized join helper.
Pagination stops on page one. Hardcoding X-Page-Number=1 silently drops everything past row 1000. Qeasy's paginator walks the total page count automatically — do not override it in the source config.
Wrong idempotency key. Choosing first_name as the idempotency key causes same-named students to overwrite each other. The source unique key is id; map it straight through to FNumber.

When to Use It and When Not To

Use it when the source has a standard paginated query API and the target is Kingdee Cloud, and you need to land external master data as customer or student profiles. Do not use it when source data needs heavy cleansing (for example, family and address merges) or when the target requires an approval workflow instead of a direct write — in that case, prefer a two-stage "draft first, then submit" design.