Salary Slip Sync from DingTalk to Kingdee Cloud: A Single-Strategy Implementation Guide

What This Strategy Solves

A retail enterprise runs a non-payroll salary slip flow in DingTalk YIDA, where employees submit reimbursements and commissions. Finance accounting lives in Kingdee Cloud. With no integration, finance staff export to Excel and key entries by hand every day — slow and error-prone. This strategy pulls salary slips from DingTalk on a schedule and writes them into the corresponding payable documents in Kingdee Cloud, so business flow and accounting flow converge automatically.

Data Flow and Field Mapping

The overall flow is: DingTalk YIDA (source) → Qeasy Data Integration Platform (middleware handling field mapping, transformation, and write orchestration) → Kingdee Cloud (target).

The source side uses DingTalk's open platform process instance API v1.0/yida/processes/instances to query submitted salary slips, with processInstanceId as the primary key and title as the document number field.

The target side calls Kingdee Cloud's batchSave API to write multiple documents at once. The table below lists key field mappings. In real projects, this usually extends to line items as well.

How to Configure in Qeasy

1. Register source/target connectors. On the DingTalk side, fill in the app ID, app secret, and operating user ID for authentication. On the Kingdee Cloud side, configure tenant and account set credentials per the private deployment environment. Both connectors are available out of the box in Qeasy's connector marketplace.

2. Build the data flow strategy. Create a new sync strategy in Qeasy. Source: DingTalk – Process Instance Query. Target: Kingdee Cloud – batchSave. The key step is to land the field mapping table in the visual mapping canvas; Qeasy handles placeholder substitution and function evaluation automatically.

3. Centralize code mapping. Across customer projects we routinely put mappings like "employee code → contact unit code" and "department → cost center" in Qeasy's centralized mapping tables rather than hard-coding them in the strategy. When the HR system changes, only one place needs updating and every dependent strategy picks it up.

4. Configure request parameters and pagination. The source pulls paginated results via pageNumber / pageSize, with page size tuned against observed API rate limits. The target submits multiple records in one call with idCheck enabled to avoid duplicate writes.

5. Schedule. Source cron is 10 * * * * (10 minutes past the hour), target cron is 20 * * * * (20 minutes past the hour), giving a 10-minute offset so they don't hit the downstream API at the same instant.

Implementation Steps

Phase 1: Align incremental start point. Don't start with a full sync. Pick a historical anchor — for example, "submitted in the last 7 days but not yet written" — as the incremental starting point. If something breaks, blast radius is small and reconciliation is straightforward.

Phase 2: Trigger full backfill. Once incremental logic is verified, manually trigger a full backfill in Qeasy. Break it into batches within the target API's max batch size to avoid throttling.

Phase 3: Switch to scheduled runs. After full backfill completes, switch the strategy to the normal hourly cron. Watch 1–2 scheduling cycles of logs, write counts, and downstream response codes before handing off to business users.

Phase 4: Exception and retry policy. Qeasy retries failed batches a limited number of times by default. Our standard practice is to split retryable errors (network blips, throttling) from non-retryable ones (missing fields, document already audited). The former auto-retries; the latter goes straight to a manual queue.

Lessons from the Field

1. Timestamp unit mismatch. DingTalk YIDA returns date fields in milliseconds, but Kingdee's FDATE expects YYYY-MM-DD. Without a conversion function, the written date ends up in 1970. The safe move is to add FROM_UNIXTIME(.../1000,'%Y-%m-%d') in the mapping.

2. Document number prefix collision. DingTalk's title is a long string. Using it directly as FBillNo easily collides with Kingdee's existing coding rule. We typically append a (FKD) suffix — it preserves traceability and avoids duplicate numbers with manual documents.

3. Matching employees by name instead of code. This is a classic pitfall. DingTalk forms store employee names, but Kingdee's FCONTACTUNIT requires the employee primary key code. Two employees with the same name and the write goes to the wrong person. The reliable approach is to use employee ID as the unique match key in Qeasy's mapping table.

4. No upper bound on source pagination. If DingTalk's process instance pagination parameters are left blank, it may return the full result set in one shot, which can overwhelm the middleware on large datasets. Set an explicit pageSize and enable cursor-based pagination.

5. Both ends scheduled at the same minute. If source and target both run at 0 * * * *, a flood of requests hits the system at the same instant — easy to trigger throttling and hard to diagnose. A 5–15 minute offset is a small but effective habit.

When to Use and When Not to Use

Use when: DingTalk YIDA form-based business documents (reimbursements, salaries, commissions) need to be written into Kingdee Cloud for financial accounting, with hourly-scale volumes and relatively stable document structures. Do not use when: Real-time, second-level sync is required, or when DingTalk form structures change frequently (e.g. weekly iterations). For those cases, lock down the fields on the DingTalk side first, then sync — otherwise maintenance cost will be prohibitively high.