Practical Tutorial: Syncing Employee Master Data from Kingdee Cosmos to MySQL via Qeasy

What This Strategy Solves (Scenario & Value)

In supply chain integration at a retail enterprise, employee master data is the "base vocabulary" of every business document — stores, warehouse keepers, buyers, reviewers, approvers all carry an employee code. Once personnel changes in Kingdee Cosmos are not propagated in time to the MySQL business tables downstream, subsequent sales orders, inventory transfers, and document approvals will mismatch.

The goal of this strategy is very singular: push employee records from Kingdee Cosmos to MySQL incrementally by modification time, ensuring that the employee number, name, department, and job status seen by downstream business systems are always fresh. It does not handle salary, attendance, or performance — only "master data distribution."

Data Flow & Field Mapping (Source → Middleware → Target)

The overall flow is: Kingdee Cosmos (source) → Qeasy Data Integration Platform (middleware) → MySQL (target). Kingdee Cosmos serves as the source of truth for personnel, Qeasy handles extraction, transformation, and idempotent writes, while the MySQL business database acts as the downstream consumer.

Key field mapping (source: Kingdee Cosmos employee records; target: an employee master table in MySQL):

A key design choice here: the incremental cursor uses the source system's last modification time, not the creation time. Employee records go through repeated adjustments in job status, department, and position — tracking creation time alone will miss updates.

How to Configure on Qeasy

On Qeasy, a complete strategy configuration consists of five parts: data source, source retrieval, transformation, target write, and scheduling.

1. Register data sources. Register both the Kingdee Cosmos and MySQL connectors in Qeasy's connection management. Authentication information goes into the platform key vault and never appears in plain text within the strategy.

2. Source retrieval. At the source end, select Kingdee Cosmos's "Employee" business object and pull it through the query interface. Set the filter condition to FModifyTime > {last_sync_time}. For the initial full sync, set the cursor to 1970-01-01.

3. Transformation layer. Build field mappings in Qeasy's transformation canvas. For code mappings, we recommend centralized management: place the mapping table from Kingdee department codes to MySQL department codes into Qeasy's "Mapping Table" component so other strategies can reuse the same table — avoiding the tragedy of "the same rule edited in 5 strategies 5 times."

4. Target write. On the MySQL side, use upsert semantics, with emp_code as the primary key for "update if exists, insert if not." Qeasy defaults to deduplication by primary key, which aligns well with the idempotency requirement for master data distribution.

5. Scheduling. See the next section.

Implementation Steps

We recommend splitting this strategy into three phases:

Phase 1: Incremental start point confirmation. Take the maximum value of FModifyTime from Kingdee Cosmos as the initial cursor. When Qeasy runs for the first time, it writes this value into the scheduling state table, and subsequent runs continue forward from there.

Phase 2: Full sync trigger. Before going live, run a one-time full sync in the test environment to push all historical active employees to MySQL at once. Confirm the row counts match (in a real project we cross-checked twice: SELECT COUNT(*) on Kingdee vs. SELECT COUNT(*) WHERE job_status='Active' on MySQL).

Phase 3: Scheduling frequency and cutover. After the production environment is verified, change the strategy to a scheduled task. Since personnel records change frequently during the day, we generally configure incremental sync every 15 minutes, with a daily validation run during off-peak hours. Qeasy's dual-track mode (incremental + periodic validation) is very useful here: incremental ensures timeliness, while full validation catches anything missed.

During cutover, we recommend running in parallel for one week. During this period, the downstream business system reads from both Kingdee and MySQL, with manual sampling to verify no discrepancies, before switching to a single data source.

Lessons Learned (Pitfalls)

Pitfall 1: Using creation time as the incremental cursor. This is a classic mistake. Employee records go through multiple status changes, and tracking FCreateTime alone will miss every "Active → Left" or "department transfer." The safe approach is to use FModifyTime, with "delete/void" handled through a separate flag.

Pitfall 2: Hardcoding enum values in transformation scripts. In early versions we hardcoded the "Active/Left" enum mapping into the transformer. Later, when the HR system added a "Retain" status, we had to edit 8 strategies. The safe approach is centralized maintenance in Qeasy's mapping table — adding a new status only requires changing one place.

Pitfall 3: Cursor not persisted, lost on restart. Early on, we placed last_sync_time in memory. Each platform restart required re-running the full sync. The safe approach is to have Qeasy persist the cursor in the scheduling state table, so failed retries automatically continue from the last timestamp.

Pitfall 4: No unique key on the target table. If emp_code has no unique index in MySQL, Qeasy's upsert will degrade into delete-then-insert, during which downstream reads see empty records. The safe approach is to add unique keys at the DDL stage.

Pitfall 5: Overwriting with empty values. When an employee's department is cleared in Kingdee Cosmos, if the transformation layer writes NULL directly, it will overwrite the originally correct department in MySQL. The safe approach is "empty values do not overwrite; only non-empty values trigger an update."

Applicable & Non-applicable Scenarios

Applicable: A single system serves as the source of truth for master data, with downstream MySQL only consuming, not writing back; change frequency is moderate (minutes to hours); the team needs traceable incremental logs.

Not applicable: Bidirectional sync or multi-system coexistence with mutual sources; sub-second real-time response required (this solution operates at minute-level granularity); or where the HR system itself is downstream (in which case reverse sync should be used).