Querying Jushuitan Categories: A Practical Guide to a Read-Only Sync Strategy

What This Strategy Solves

For a retail enterprise whose product master data lives in both Jushuitan and Kingdee Cloud, the very first step before syncing goods is to align the category trees on both sides. Push products before categories are reconciled and you get two predictable failures: empty coding mappings and incompatible naming rules, both expensive to fix later. What we did with Qeasy was simple — schedule a read-only pull of Jushuitan categories into the platform middle layer, indexed by modification time, as a reconnaissance pass.

Data Flow and Field Mapping

The source is Jushuitan's /open/category/query endpoint; the target is an internal no-op write on the Qeasy integration platform itself, used to fire the schedule and persist into the staging table.

Purpose	Source Field (Jushuitan)	Target (Middle Layer)	Notes
Unique ID	`c_id`	`category_id`	Category primary key, used later to join goods sync
Window start	`modified_begin`	`{{LAST_SYNC_TIME}}`	Last successful sync time
Window end	`modified_end`	`{{CURRENT_TIME}}`	Current time
Pagination	`page_index` / `page_size`	Pass-through	Max 50 rows per page

Note that Jushuitan requires the time window and the product code to not be empty together. Using the time window alone is sufficient — do not pass a product code.

How to Configure It in Qeasy

Open the Qeasy Data Integration Platform strategy editor, create a QUERY_ONLY strategy, pick Jushuitan as the source and datahub (the platform itself) as the target.

There are three configuration essentials:

Metadata import. Reference the source/target metadata JSON from the source files; confirm effect=QUERY, method=POST, autoFillResponse=true. Keep idCheck as false because this is a first-time inventory and does not depend on pre-existing records.
Request template. Default page_index to 1, hard-code page_size at 50, and use Qeasy's built-in time macros for the time window: {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}. A common pattern we use on customer sites is to isolate these two macros on their own lines, not mixed into business fields, so timezone drift is easy to spot during troubleshooting.
Response persistence. With autoFillResponse enabled, fields returned by Jushuitan (c_id, c_name, modified, etc.) are written into the staging table by name match — no custom parsing script is needed.

Implementation Steps

We suggest a phased rollout: prove the link first, then schedule, then add safety nets.

Phase 1: Manual trigger, prove the link. On the Qeasy strategy detail page, click "Run Once" with a known-busy window (e.g., last 24 hours) and compare the response count against the staging table row count. The most common pitfall here is time format — Jushuitan expects yyyy-MM-dd HH:mm:ss; an ISO timestamp is silently dropped.
Phase 2: Set the incremental baseline. For the first full pull, set LAST_SYNC_TIME to a value slightly earlier than the earliest category modification time so nothing is missed. After the first run, Qeasy records CURRENT_TIME automatically as the next run's start.
Phase 3: Attach a schedule. The reference crontab is */5 8-20 * * *, meaning every 5 minutes from 08:00 to 20:00 daily. On customer sites we often see this strategy relaxed to 30 minutes, since categories change far less frequently than products. The conservative approach is to run dense for one week, confirm no drops, then loosen.
Phase 4: Idempotency and retry. Jushuitan's window cannot exceed 7 days, and network blips occasionally return 502. Qeasy's retry mechanism handles transient failures automatically, but confirm that idCheck is set to true on the no-op target to avoid duplicate write firings.

Lessons From the Trenches

Window exceeding 7 days fails hard. Jushuitan enforces this; the documentation says it clearly, but on customer sites, after a server timezone change the start time ended up 8 days back. Lock the macro timezone to Asia/Shanghai inside Qeasy.
page_size over 50 is silently truncated. The metadata notes "max 50", but a few engineers read that as "recommended 50" and passed 200. The API returned 50, and subsequent pagination logic broke. The safe move is hard-coding 50 and leaving no opening.
Mixing first-run full pull with incremental. If LAST_SYNC_TIME is not reset on the first run, Qeasy starts from the incremental baseline and old data is lost forever. Our delivery checklist requires the first run to explicitly specify a start time.
Special characters in category names. Jushuitan allows &, /, （）, and the staging table handles them fine with UTF-8mb4, but the downstream Kingdee Cloud side historically only accepts ASCII. The fix is to pull raw into the middle layer and centralize the character conversion in the write strategy — a common pattern among Qeasy customers.
Strategy ordering via dependencies. This sequence-A strategy is upstream. The downstream sequence-B strategy "Query Kingdee Product Categories" must wait for it to complete before comparison. We explicitly declare the dependency via Qeasy's depends_on field to prevent both category sets running concurrently and overwriting the staging table.

When This Fits and When It Doesn't

This pattern fits integration projects where both sides need a product master but first need to verify that category trees align. It does not fit scenarios that demand second-level real-time category changes with strict downstream dependency — the 5-minute polling cadence is too coarse for those. For that, switch to event-driven or streaming interfaces.