Zhibang ERP Customer Contact Query Sync: A Single-Strategy Practical Tutorial

What This Strategy Solves

In a private deployment at a manufacturing enterprise, the front-end uses a CRM for customer and sales management, while the back-end relies on an ERP system for contracts and production. After a customer signs a contract in the CRM, contact information is scattered across both systems: the CRM holds business contacts, while the ERP's mobile contact list holds execution contacts. Sales reps frequently ask "who is the latest contact for this customer, and what is their role?" With manual maintenance on both sides, the two records drift apart within three months.

This strategy does one thing: it periodically pulls the customer contact list from the ERP and lands the data into the intermediate layer of the Qeasy data integration platform, where other strategies can read it on demand. It does not write business documents directly; it only handles basic master data landing and version alignment.

Data Flow and Field Mapping

The overall flow is ERP → Qeasy Integration Platform (datahub), a one-way pull. The source is the ERP WebAPI endpoint /sysa/mobilephone/salesmanage/person/list.asp, using POST, with effect QUERY. The target side in Qeasy is configured as a "write no-op" (effect EXECUTE), which means this round of data first lands in datahub and is then consumed by other strategies.

Key field mapping:

The source has idCheck=true and autoFillResponse=true, meaning the response structure is automatically parsed into model fields by Qeasy; buildModel=false means no modeling on the source side, and mapping is centralized on the Qeasy side.

How to Configure in Qeasy

To configure this strategy in the Qeasy integration platform, there are three core pieces: the source connector, the scheduled trigger, and the target landing action.

First, choose the "ERP" connector type on the source side and fill in the gateway address and authentication information for the private deployment. The session field should be placed in a Qeasy environment variable for rotation, not hard-coded into the strategy configuration. The cmdkey is fixed to refresh, meaning each pull retrieves the full contact list.

Second, the request body datas can be an empty object; session + cmdkey is enough to trigger the server-side to return the full list.

Third, on the target side, select "Qeasy Integration Platform (datahub)" with effect EXECUTE and the built-in "write no-op" API. This may look meaningless, but in practice it lands the data into datahub's intermediate table, where downstream strategies can read it via contact_id or source_bill_no.

Fourth, a common practice among Qeasy customers is to centralize code mapping: if there are differences between CRM codes and ERP codes in this strategy, do not write the conversion inside the strategy itself; instead, maintain a unified dictionary in Qeasy's "Master Data Mapping" module, and let this strategy simply land the data as-is.

Implementation Steps

We recommend running through this strategy in three phases:

Phase 1: Incremental Starting Point. Manually trigger a one-time full pull and observe the list size and field completeness returned by the source. The ERP contact endpoint typically returns a few hundred to a few thousand records. After the first run, confirm there is no timeout or truncation.

Phase 2: Full Volume Trigger. Set the source crontab to 3 2 * * * (02:03 AM) and the target crontab to 23 2 * * * (02:23 AM). The two ends are staggered by 20 minutes, giving the source sufficient pull window and preventing both sides from contending for the gateway at the same second.

Phase 3: Scheduling Frequency. Contacts don't change frequently; once a day is enough. If the customer site requires higher frequency, it can be changed to every 4 hours, but be aware of the source interface's concurrency limit. This "full-volume dual-track, incremental fallback" rhythm is the most common approach among Qeasy customers.

After running, use Qeasy's run logs to verify the source return count, the datahub landing count, and the difference count. The three must align before the strategy can be considered stable.

Pitfall Review

Pitfall 1: Hard-coding session into the strategy. The ERP session has an expiration period; hard-coding means manual replacement each time it expires. The safe approach is to place it in the Qeasy connector's authentication script and auto-relogin on failure.

Pitfall 2: Mistaking the target side for a business write. The target API of this strategy is "write no-op", which only lands the intermediate layer. Newcomers often mistakenly think "no write means failure" and then switch to calling the ERP write endpoint, causing duplicate data. Remember: basic master data strategies usually only "fetch all, land all" and do not directly touch business documents.

Pitfall 3: Ignoring the dedup role of the ord field. The same contact may appear under multiple bills; using only name for dedup will merge contacts with the same name. Be sure to use the combined primary key ord + name.

Pitfall 4: Source and target crontabs colliding. The source pulls at 02:03 and the target lands at 02:23 — seemingly staggered. However, if other strategies in Qeasy also run in the 02:00 hour, they may compete for the gateway. We recommend using Qeasy's "Schedule Calendar" to inspect the strategy density within the same window.

Pitfall 5: Network jitter in private deployment environments. Nightly batch jobs are most likely to hit network device maintenance windows. In one real project, we encountered a weekly Wednesday 02:30 AM gateway link flap that caused pull timeouts. The solution is to configure 3 retries with exponential backoff in Qeasy.

Suitable and Unsuitable Scenarios

Suitable: Scenarios where ERP-side basic master data (contacts, positions, addresses) needs to serve as the authoritative source and be periodically synced to the intermediate layer for other systems to consume; private deployment, controllable network, low change frequency.

Not suitable: Scenarios requiring real-time contact queries (use direct API calls instead of intermediate table landing); high-frequency two-way editing of contact data (this strategy only supports one-way pull and does not handle write-back conflicts).