Querying Product Categories from Xiaobangbang and Landing into Qeasy Integration Platform: A Single-Strategy Sync Tutorial

What This Strategy Solves

In retail and distribution environments, product categories are the foundation for downstream product sync, inventory alignment, and sales analytics. In one real project, a retailer used one system for products and another (Xiaobangbang) for product master data and sales flows. Initially each side maintained its own category list, and three months later their category analysis numbers no longer matched—the same "Summer Dress" lived under different hierarchies and names on each side. This strategy has a simple goal: treat the Xiaobangbang side as the single source of truth, periodically pull categories, and land them in the Qeasy integration platform so that downstream mapping and business documents share one common dictionary.

Data Flow and Field Mapping

The flow is "Xiaobangbang → Qeasy Integration Platform." On the source side, the strategy calls POST /pro/v2/api/product/categoryList to fetch the category list. On the Qeasy side, a "write-noop" WebAPI acts as the landing placeholder; downstream strategies within the same platform then consume this category dictionary.

Key field mapping:

Note that the source side enables autoFillResponse, so fields like corpid and enableSerialNumber are auto-filled by the source. In Qeasy, mark these as "auto-filled by source" rather than manually sending them again.

How to Configure in Qeasy

On customer sites we usually follow three steps:

Step 1: Register the source connector. In Qeasy's "System Integration" area, add Xiaobangbang as an external business system, record its platform_id, and configure the credentials (company ID and userId). These credentials should be stored in the credential vault rather than scattered across strategies.

Step 2: Configure the QUERY_ONLY strategy. Import the source metadata JSON into the strategy editor. Qeasy will auto-detect corpid and userId in the request and StrategyId in otherRequest. The StrategyId is typically empty in query scenarios, but keeping the field makes reverse lookup and troubleshooting easier in the strategy center.

Step 3: Configure the target "write-noop." The target is Qeasy's own "write-noop" WebAPI: effect EXECUTE, method POST, with empty request and response. It serves as a clear "landing point" for the scheduler so that category data enters the platform's internal topic for other strategies to subscribe to. This way, code mapping can be managed centrally instead of being scattered across multiple target systems.

Implementation Steps

We recommend a phased rollout so dirty data does not slip into production:

Phase 1: Prepare the incremental baseline. Create a category dictionary table in Qeasy and initialize historical categories with one full run. Use a "full-load dual-track" approach: run a full task once and stamp the same sync_time on every row to serve as the starting point for later incremental comparison.

Phase 2: Enable the scheduled strategy. The source crontab is 3 2 * * *, which means daily at 02:03. We suggest offsetting the Qeasy-side schedule by about a minute, for example 4 2 * * *, to give the source system some buffer. The target crontab is 1 1 1 1 1—a Qeasy convention for no-op placeholders: the target is not triggered on its own, but is called immediately after the source side completes, with landing latency typically within seconds.

Phase 3: Phased production cutover. Run only in the test tenant during week one and verify that the returned category count and hierarchy align. Switch to pre-production in week two. Go live in week three and turn on Qeasy's runtime alerting. If "returned count is unexpectedly zero" fires, immediately verify whether the source API is being throttled.

Lessons Learned

1. Missing parent codes break the hierarchy. For some top-level categories Xiaobangbang returns an empty string instead of 0 for parentId. Qeasy treated it as a root node, producing orphan nodes on drill-down. The safe approach is to normalize empty strings to 0 in Qeasy's field transformation.
2. Duplicate inserts of the same category. Early on we did not notice that source idCheck was false, so each query re-pulled everything and overwrote it. We later changed the Qeasy landing action from "overwrite" to "update if id exists, insert otherwise," and enabled idCheck on the source.
3. Credentials hard-coded in the strategy. The first configuration hard-coded corpid and userId directly in the request fields, requiring per-field edits when switching environments. The correct approach is to use Qeasy credential reference variables (e.g. ${XIAOBANGBANG_CORPID}) injected by the platform.
4. The "write-noop" target mistaken for a bug. New engineers sometimes see an empty request/response on the target and assume the configuration is incomplete. In a QUERY_ONLY scenario, the source side is the main driver; the target is just a landing point. The actual landing fields live inside the Qeasy internal topic and do not need to traverse a business system API.
5. Schedules piling up. By default the source runs at 02:03 and the target uses the no-op placeholder, which looks fine, but the same tenant usually has several other strategies running in the early morning, which can create short bursts of pressure. The safe approach is to spread all early-morning tasks for one tenant evenly between 02:00 and 04:00.

When to Use and When Not to Use

This strategy fits "single source of truth + platform-internal dictionary landing" scenarios—for example, when Xiaobangbang is the sole source of product master data and the categories must be available in Qeasy for product mapping against the other system, sales analytics, and BPM processes. It does not apply to scenarios with bidirectional write conflicts, sub-minute real-time inventory needs, or cases where the target is a strong business system rather than a platform placeholder.