Authoritative Tutorial: User/Personnel Query Interface Field Manual for XiaoMan OKKICRM
What This Interface Solves
The XiaoMan OKKICRM "Query User/Personnel" interface (/v1/user/list) is used to pull user master data from the CRM. This data underpins business processes such as sales order ownership, customer owner assignment, performance accounting, and permission allocation. Typical use cases include: mapping XiaoMan users to Kingdee salespersons, initializing organizational structure, and reconciling user identity across systems. Across multiple customer projects, we have found that this interface is often the starting point of the master data synchronization chain—get the people right first, and subsequent documents and reports will have reliable owner fields.
Interface Capability Overview
- Authentication: XiaoMan OKKICRM standard AppKey/AppSecret signature authentication, with an access token carried in the request header.
- Request Structure: GET method, path
/v1/user/list, supports filtering by department, status, etc. The response is a JSON array, with each record representing one user. - Pagination: Supports pagination parameters (commonly a
page/pageSizeoroffset/limitcombination); in real scenarios you must loop through pages until all data is fetched. - Incremental Mode: The interface itself returns the full list; incremental identification relies on
user_iddeduplication. Some customers use an update-time field for incremental filtering. - Strategy Type: QUERY_ONLY (query only); the Target is configured as "write no-op", used purely for data fetching and mapping.
- Scheduled Task: Typical crontab is
25 3 * * *, executed once daily in the early morning.
Typical Field Mappings
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| user_id | string | User's unique identifier in the XiaoMan system | The true primary key, used for deduplication and cross-system reconciliation |
| nickname | string | Nickname / login name | Configured as both id and number in metadata; in practice, treat it as a business code, not the primary key |
| full_name | string | User's real name | Used for document display; can be mapped to Kingdee salesperson name FName |
| string | Email address | Can be used for identity verification, but note that emails may persist after an employee leaves | |
| department_id | string | Department ID | Key field for mapping to Kingdee department codes and synchronizing organizational structure |
| department_name | string | Department name | For display only; prefer department_id for cross-system reconciliation |
How to Configure on Qeasy Cloud
On the Qeasy Cloud Data Integration Platform, calls to this interface are typically wrapped by a "Query Adapter": select XiaoMan OKKICRM as the source system, choose the "User/Personnel List" interface, and enter the AppKey and AppSecret. Qeasy's field mapper automatically maps user_id, nickname, full_name, department_id, and other fields to generic concepts (such as user_id, user_code, full_name, department_id), without the need for manual configuration. When the strategy is QUERY_ONLY, simply configure the Target as "no-op"; the fetched data will be temporarily stored in the Qeasy middleware for subsequent cross-mapping with Kingdee salespersons.
Cross-Solution Practical Points
- Choose the primary key carefully: In multiple solutions, metadata configures
nicknameas both id and number, but nicknames carry a risk of duplication. In real scenarios, always useuser_idas the technical primary key. - Sync organizational structure before personnel: Department data must be synchronized before personnel; otherwise
department_idcannot find a corresponding department, and subsequent document ownership will fail. - Mapping to Kingdee salespersons is the core value: The real落地 scenario of this interface is almost always the two-way mapping "XiaoMan user ↔ Kingdee salesperson"—code mapping
nickname↔ FNumber, name mappingfull_name↔ FName. - Balance pagination and rate limiting: In customer practice, we have found that the interface returns a limited number of records per page. Be sure to configure looping logic in Qeasy Cloud and add retry on failure.
- Incremental identification requires custom fields: The interface itself does not return a clear update timestamp; incremental synchronization requires an additional record of the set of already-fetched
user_ids, and a difference set on the next pull. - Schedule execution to avoid business peaks: A crontab at 3:25 AM both ensures data is ready by morning and avoids XiaoMan CRM's daytime high-frequency call window.
Pitfall Review
- Pitfall 1: nickname used as primary key causes duplicates. One retail enterprise wrote
nicknamedirectly as the primary key downstream, resulting in overwrites for users with duplicate nicknames. The safe approach is to uniformly useuser_idas the technical primary key, andnicknameonly as the business code. - Pitfall 2: empty department_id causes downstream errors. Some users have no department, and the field returns null, making it impossible to find the Fdept code on the Kingdee side. It is recommended to add a null filter layer in Qeasy Cloud, or first complete department assignments on the source side.
- Pitfall 3: email changes do not trigger synchronization. Email as a contact field may change with employee adjustments, but
user_iddoes not, leading to silent email inconsistencies. Markemailas a "changeable field" in the field mapper and keep a change log. - Pitfall 4: full pulls are time-consuming. When the user count reaches tens of thousands, a single full pull may time out. The safe approach is to filter by department in batches, or do a full pull first and incrementals thereafter.
- Pitfall 5: authentication token expires without retry. XiaoMan's access token has a limited validity period; if the token expires mid-task in the early morning, data will be truncated. Qeasy's adapter comes with automatic token refresh—make sure it is enabled.
When to Use This Interface
This interface is suitable for scenarios where XiaoMan CRM user master data needs to be synchronized to an ERP (such as Kingdee Cloud Stellar salesperson data), to establish organizational structure, or to provide owner fields for subsequent sales orders, customer master data, and other business documents. The boundary is: it only solves the synchronization of "people", not security dimensions like permissions and roles; if real-time two-way synchronization of user status changes is required, an additional change-capture mechanism must be configured.