Qeasy Cloud
Get Started

Authoritative Tutorial: User/Personnel Query Interface Field Manual for XiaoMan OKKICRM

· 陈洁琳· Engineering Best Practices· 41 views· 4 min read
小满OKKICRMKingdee Cloud接口字段手册用户人员金蝶业务员轻易云主数据同步

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/pageSize or offset/limit combination); 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_id deduplication. 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 NameTypeMeaningPractical Notes
user_idstringUser's unique identifier in the XiaoMan systemThe true primary key, used for deduplication and cross-system reconciliation
nicknamestringNickname / login nameConfigured as both id and number in metadata; in practice, treat it as a business code, not the primary key
full_namestringUser's real nameUsed for document display; can be mapped to Kingdee salesperson name FName
emailstringEmail addressCan be used for identity verification, but note that emails may persist after an employee leaves
department_idstringDepartment IDKey field for mapping to Kingdee department codes and synchronizing organizational structure
department_namestringDepartment nameFor 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

  1. Choose the primary key carefully: In multiple solutions, metadata configures nickname as both id and number, but nicknames carry a risk of duplication. In real scenarios, always use user_id as the technical primary key.
  2. Sync organizational structure before personnel: Department data must be synchronized before personnel; otherwise department_id cannot find a corresponding department, and subsequent document ownership will fail.
  3. 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 mapping full_name ↔ FName.
  4. 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.
  5. 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.
  6. 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 nickname directly as the primary key downstream, resulting in overwrites for users with duplicate nicknames. The safe approach is to uniformly use user_id as the technical primary key, and nickname only 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_id does not, leading to silent email inconsistencies. Mark email as 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-086-ok-d70d

Comments