Payment Terms Master Data Sync: Kingdee Cloud Cosmos → MySQL on Qeasy
What This Strategy Solves
Payment terms are not just dry fields—they directly drive downstream PO aging calculations, AP posting timing, and AR discount conventions on the sales side. In supply-chain integration projects for retail or manufacturing companies, we keep seeing the same issue: someone changes "Net 30" to "Net 45" in Kingdee Cloud Cosmos, the business MySQL does not follow, downstream documents post with the old terms, and three months later finance cannot reconcile.
The strategy we ship here is tightly scoped: push payment-terms master data from Kingdee Cloud Cosmos into the business-side MySQL, orchestrated by the Qeasy data integration platform. Get code mapping, the incremental watermark, schedule cadence, and field semantics nailed down in one pass, and the "master-data-first" foundation stays solid when transactional sync is added later.
Data Flow and Field Mapping
The chain is unidirectional: Kingdee Cloud Cosmos → Qeasy → MySQL. Qeasy plays the role of an intermediate layer rather than a dumb pipe—it owns code mapping, null handling, and field trimming.
Key field correspondence (typical shape):
| Business meaning | Kingdee Cosmos (source) | Qeasy intermediate | MySQL (target) |
|---|---|---|---|
| Payment term code | FNUMBER | payment_term_code | payment_term_code (PK) |
| Payment term name | FNAME | payment_term_name | payment_term_name |
| Term type | FCREDITPERIODTYPE | Enum normalization (Net / EOM / month-end) | term_type |
| Net days | Derived from FEXPECTEDRECEIVEDATE | Integer days | net_days |
| System preset flag | FISINTERNAL | Boolean | is_system |
| Last modified time | FMODIFYDATE | ISO8601 | updated_at (incremental watermark) |
A note on semantics: the term type in Kingdee is an enum value set; it must be normalized before reaching MySQL or downstream parsing will fall apart. "Last modified time" must serve as the incremental watermark—relying on code-based dedup alone is unreliable under concurrency.
How to Configure on Qeasy
Configuration follows Qeasy's three-stage pattern: source → mapping → target. We focus on three places:
- Source connector: Use the standard Kingdee Cloud Cosmos connector, enable "by-modified-time incremental", and bind the watermark field to
FMODIFYDATE. - Mapping layer: Maintain a single centralized code-mapping table in Qeasy. All "enum → business code" relationships live here, not scattered across strategies. New strategies reference this table directly.
- Target connector: Write to MySQL via upsert (INSERT … ON DUPLICATE KEY UPDATE), with the payment-term code as the primary key.
One Qeasy design detail is worth calling out: staged header/body configuration. Payment terms have no body, so only the header stage runs. But when you later add "vendor master," split header (code, name) from body (contacts, bank accounts) into two stages—otherwise a single failure blows up the whole document.
Implementation Steps
We rolled out this strategy in three paced steps:
- Step 1: Full sync trigger. One-shot push all payment terms from Kingdee Cloud Cosmos to MySQL to establish the baseline. Trigger manually, then validate row counts and sample 20 records of key fields on both sides.
- Step 2: Align the incremental start. After full sync completes, use "current system time − N minutes" as the incremental start point (do NOT use the exact full-sync end timestamp; leave a buffer to avoid boundary misses). Hard-code this as the initial value of the incremental watermark in Qeasy.
- Step 3: Schedule cadence. Payment terms change infrequently—every 30 minutes for incremental is enough. If the business insists on shorter, 15 minutes is fine, but never below 5 minutes—master-data sync values stability over speed.
A common pattern among Qeasy customers is dual-track incremental + full: incremental during the week, full sync weekly as a safety net. This way you never suffer long-term watermark drift, and you have a recovery path when something breaks.
Pitfalls and Lessons Learned
Here are the typical mistakes we have seen across projects:
- Dedup by code instead of modified time. Under concurrency, two writes on the same code overwrite each other and lose updates. Safe approach: watermark + primary key, double insurance.
- Term-type enum not normalized. Kingdee uses Chinese enums (
月结,票到); MySQL expects English or custom codes. The mapping layer must translate; do not pass through directly. - Boundary loss at the full/incremental seam. If the incremental start uses the exact full-sync end timestamp, boundary records are lost. This is a classic trap. Safe approach: roll back a few minutes.
- Deletion/deactivation status not transmitted. When a payment term is disabled and downstream does not know, it keeps posting with the old term. Explicitly carry
FISINTERNAL/ enable flag in the mapping, and keep the status field on the MySQL side. - Schedule cadence chosen by gut feeling. Setting it to once per minute looks "real-time" but the Kingdee API has rate limits, and you will get throttled. Master-data sync frequency should be reverse-engineered from "business tolerance for delay," not from "technical capability."
When to Use and When Not to Use
Use when: Kingdee Cloud Cosmos and business-side MySQL coexist, payment terms / currencies / tax rates need one-way sync, and the source system is the single source of truth. Do not use when: payment terms need to be maintained on both sides, the source is not the sole source of truth, or the business needs second-level real-time freshness for term calculations—the latter should be event-driven, not scheduled.