Practical Tutorial on Querying Product Master Data from OKKICRM to Kingdee Cloud

What This Strategy Solves

When integrating CRM and ERP systems, product master data is often the first hurdle. In a retail company, sales teams maintain product records in OKKICRM while supply chain, inventory, and finance live in Kingdee Cloud. If the two sides disagree on product coding, every downstream order and reconciliation becomes a nightmare. We use the Qeasy data integration platform to handle this: OKKICRM is treated as the authoritative source, and we incrementally pull product data on a schedule into Kingdee Cloud. The "Query OKKI Products" strategy described in the reference material is the starting point of this chain — it only pulls data from the source within a time window, without writing anywhere. It looks simple but is the "heart" of the entire sync chain, because later customer and order sync strategies all depend on the fresh product view it produces.

Data Flow and Field Mapping

The overall flow is OKKICRM → Qeasy Middle Layer → Kingdee Cloud. The source of this strategy is the OKKICRM endpoint /v1/product/list (GET, type QUERY), and the target is registered in the reference as a "Write Empty Operation" node on the Qeasy platform (WebAPI, POST, effect EXECUTE, idCheck true). This is a common pattern in Qeasy: first land data into a dataset in the middle layer via a placeholder, so downstream strategies consume by ID without polling the source repeatedly.

Key request parameters:

On the response side, the source system returns product_no as the unique ID and name as the number field. The target "Write Empty Operation" node maps no fields, but idCheck=true means Qeasy will use the source product_no for idempotent deduplication — this is the lifeline of later reconciliation.

How to Configure in Qeasy

Step 1: Connect both systems in the Qeasy platform. For OKKICRM, use a custom API connector pointing to /v1/product/list and configure authentication with the AppId/Secret provided by the tenant. For Kingdee Cloud, use the official connector and log in to the public cloud tenant.

Step 2: Create a new strategy and select the "Query OKKI Products" template. Fill in the source side according to the table above. Pay attention to two points: first, start_time must use the Qeasy built-in LAST_SYNC_TIME variable, not a hardcoded date; second, pagination parameters start_index and count should be placed in the strategy's visual pagination config. Qeasy will automatically loop based on total or has_more in the response until no pages remain.

Step 3: On the target side, choose "Qeasy Integration Platform" + WebAPI, name the API "Write Empty Operation", method = POST. Enable idCheck, leave buildModel empty. Qeasy will automatically generate a dataset table with product_no as the primary key.

Step 4: Add a simple field mapping script that does only three things: dump the source product_no, name, and other fields into the dataset; perform light cleaning (trim whitespace, unify case); and store updated_at in a dedicated column for downstream time-window filtering. This is a common pattern among Qeasy customers — "centralized encoding mapping management": all caliber conversions live in one strategy's script, avoiding scattered implementations across multiple strategies.

Implementation Steps

1. Full Initialization: Before going live, manually set start_time to a very early date (e.g., three years ago) and end_time to the current moment, and trigger a full pull to bulk-load historical product records into the dataset. After the full pull completes, switch start_time back to the LAST_SYNC_TIME variable to enter incremental mode.
2. Establish Incremental Baseline: When first entering incremental mode, observe for two to three days to confirm that LAST_SYNC_TIME advances in step with the source system's update time, to avoid missed records.
3. Schedule Frequency: The crontab in the reference material is 34 3 * * * (3:34 AM), which is the off-peak window Qeasy recommends to avoid business hours. In production, we usually run between 2 AM and 4 AM, with minutes deliberately scattered to prevent multiple strategies from hitting the database at the same moment.
4. Downstream Handoff: After this strategy runs, the actual landing into Kingdee Cloud is handled by a subsequent "Product Sync" strategy that consumes the dataset produced here based on updated_at. This two-step decoupling embodies the typical "header-body phased" approach in Qeasy: the query strategy only pulls, the write strategy only lands, and neither blocks the other.

Lessons Learned

1. Time Window Misses: In an early project, someone set start_time to "the end_time of the last successful run," and a timezone or source-system drift caused the early-morning batch of updates to be skipped. The reliable approach is to use the Qeasy variable for start_time, use CURRENT_TIME for end_time, and additionally compare the source system's daily record count, immediately re-running on anomalies.
2. Pagination Omission: If the total field is missing from OKKICRM's response, the default pagination plugin assumes only one page exists and only pulls 20 records. A typical mistake is to disable pagination altogether; the correct approach is to manually specify the pagination-stop field (such as has_more or total > start_index + count).
3. idCheck Disabled: Some people think "Write Empty Operation" doesn't write business tables, so they disable idCheck. The result is the same product_no being inserted multiple times, bloating the dataset and slowing downstream consumption. idCheck=true is the free idempotency the platform provides — never disable it.
4. Scattered Encoding Mapping: Different strategies each carried their own product-code conversion script. One day the caliber changed but only one place was updated, causing the two sides to disagree on numbers, and troubleshooting took two weeks. This is where "centralized encoding mapping management" pays off — all caliber lives in the query strategy's script.
5. Confusing Full and Incremental: Running incremental mode directly without a full initialization left historical product records entirely missing from the dataset; Kingdee Cloud was blank, and the business team thought sync was broken.

When to Use and When Not to Use

Use when: CRM is the authoritative source of product master data and ERP is the consumer; product count is under hundreds of thousands and updates are mostly time-based; you need a unified product view for multiple downstream strategies (orders, inventory, customers). Do not use when: product data needs bidirectional sync with edits allowed on both sides; product volume is in the millions and the source does not support time-window increments (only full dumps); the business requires real-time (second-level) rather than near-real-time (day-level) freshness.