Kingdee Cloud Material Sync to Jky Goods: A Single-Strategy Implementation Guide
What This Strategy Solves
Syncing material master data from an ERP (in this case, Kingdee Cloud) to a front-end business system (Jky) looks like a simple "push the code and name" task, but in real projects the trouble rarely comes from the transport itself — it comes from code mapping, unit conversion, and getting the incremental starting point right. Once the material master drifts between the two sides, every downstream purchase, sales, and inventory document will carry the error. We use the Qeasy data integration platform to handle this strategy, and the goals are threefold: maintain the master in one place, share it everywhere, and keep it traceable.
Data Flow and Field Mapping
The flow is one-way: Kingdee Cloud (source) → Qeasy integration platform (middleware) → Jky (target). The source pulls materials in batches via the executeBillQuery API, and the target writes them in batches via erp.goods.skuimportbatch. Below is the core field mapping — in real projects we always walk through this table with the business side on-site before touching anything.
| Business Meaning | Kingdee Cloud (Source) | Jky (Target) | Notes |
|---|---|---|---|
| Entity Primary Key | FMATERIALID | id | Keep it for idempotency |
| Code | FNumber | goodsNo / outSkuCode | Unique on both sides, used as business key |
| Name | FName | goodsName / goodsAlias | Alias can mirror the name |
| Specification | FSpecification | spec | Plain text passthrough |
| Old Material Code | FOldNumber | — | Source-only, for historical tracing |
| Barcode | FBARCODE | skuBarcode | Multiple barcodes require splitting |
| Purchase Unit | FPurchaseUnitId.FName | unitName | Name matching, easy to get wrong |
Configuring It on Qeasy
The whole strategy is a "source query → field mapping → target write" pipeline on the Qeasy data integration platform. A few configuration points worth highlighting:
- Source API: Pick Kingdee Cloud's
executeBillQuery, set the business object to material, useFMATERIALIDas the primary key andFNumberas the business code, and turn onidCheck. - Target API: Pick Jky's
erp.goods.skuimportbatchand configure it in batch-write mode. Note that Jky requiresgoodsNoandoutSkuCodeto appear together — missing either one will fail the call. - Code mapping: This is where things usually go wrong. The source
FNumbertypically follows an internal coding scheme, while the targetgoodsNomay reuse the same scheme or a different one. We recommend centralizing the code mapping rules on Qeasy's mapping layer so that any future change happens in one place. - Unit matching: The source unit is a composite field (
FPurchaseUnitId.FName), but the target only accepts the name (unitName). You need a separate "unit query" strategy to land the unit ID-to-name mapping into an intermediate table first; the material strategy then references that table. Do not hardcode units in the material strategy. - Idempotency and deduplication: Use
FMATERIALIDas the idempotency key. Qeasy's platform uses this key by default to decide insert vs. update, avoiding duplicate writes.
Implementation Steps
We recommend a three-phase rollout — this rhythm has been validated across multiple projects:
Phase 1: Prepare the incremental starting point First, decide with the source side what timestamp marks the beginning of incremental sync. A safe approach is to use the material's last-modified time as the initial cursor, run a one-time full sync to backfill existing materials, then switch to incremental mode. Qeasy supports persisting the cursor value into a scheduling variable, so you don't have to fill it manually each run.
Phase 2: Full sync trigger Manually trigger a full sync and verify that the counts and fields line up on both sides. Focus your checks on three field groups: units, barcodes, and multi-category assignments. The business side usually only looks at code and name, but it's the less obvious fields that determine whether downstream documents actually work.
Phase 3: Enable scheduled frequency
Material master data doesn't change often — two or three runs a day are usually enough. But on-site users typically want "sync immediately after I save." We suggest an incremental + full double-track approach: run incremental at high frequency (e.g., every 5 minutes) and run a verification full sync at low frequency (e.g., daily at dawn). This gives both freshness and a safety net for missed records. Schedule the source to run during business hours (e.g., */5 8-22 * * *) and offset the target by about a minute so both ends don't race for the same material.
Lessons Learned (Pitfalls)
A few pitfalls we keep hitting in real projects — writing them down here saves a lot of debugging later:
- Pitfall 1: Code mapping scattered across scripts. On our first attempt we wrote code conversion logic into each strategy's script, only to find that the same material had to be written five times across five strategies. The safer approach is to centralize code mapping in Qeasy's mapping table so every strategy references the same source of truth.
- Pitfall 2: Unit name matching fails. The source stores units by ID with the name in a separate master. If you run the material sync before the unit sync is stable, you'll get "unit does not exist" errors. The header-then-body phased approach is common among Qeasy customers: get units and categories stable first, then run materials.
- Pitfall 3: Switching between full and incremental at the wrong time. If you turn on incremental before the full sync completes, the same material gets written twice. You must wait for the full sync to return successfully before resetting the cursor in the scheduling variable to the last successful cutoff time.
- Pitfall 4: Ignoring disabled or deleted materials. When a material is disabled on the source side and you don't filter it out, "ghost goods" appear on the target side and break downstream ordering. Add a status filter on the source query, or add a guard in the mapping layer.
- Pitfall 5: Multi-value barcodes not split. Kingdee Cloud allows multiple barcodes per material as a concatenated string, while Jky requires an array. Use Qeasy's "field split" component for this conversion — never pass the raw concatenated string through.
When This Applies — And When It Doesn't
This strategy fits: a single legal entity with a single ledger, where the coding scheme is relatively uniform, and where the ERP is the master-data owner while the front-end system is the consumer. It does not fit: scenarios requiring per-organization code distribution across multiple ledgers, or near-real-time (second-level) bidirectional sync — for the latter, an event-driven architecture is more appropriate than scheduled polling.