Business use
The Bulk Import feature in Harmonized Identity Management (HIDM) enables administrators and integrators to import large volumes of identity data into Vynamic Retail Management systems efficiently. Bulk imports are processed asynchronously, making them suitable for initial environment setup, data migration, and large-scale updates.
Bulk Import is commonly used to:
- Initialize identity data for new environments
- Migrate users and organizational structures from legacy systems
- Synchronize large data sets during system integration
- Reduce manual setup effort and execution time
Overview
The feature supports both creating and updating entities in a single operation and provides status tracking through a Bulk Import ID.
Audience
- Backend developers
- Retail System integrators
- API consumers managing identity data provisioning
Prerequisites
- Basic understanding of REST APIs and JSON payloads
- Familiarity with HIDM entities (Users, Roles, Business Units, etc.)
- Access to and authorization for HIDM bulk import APIs
Supported Entities
Bulk import APIs are available for the following HIDM entities:
- Permission Groups
- Roles
- Business Unit Types
- Business Units
- Users
Each entity type has a dedicated endpoint to enforce validation and dependency rules.
Bulk Import Endpoints
HIDM provides the following REST endpoints to perform bulk import operations:
- POST /permissionGroups/bulkImport
- POST /roles/bulkImport
- POST /businessUnitTypes/bulkImport
- POST /businessunits/bulkImport
- POST /users/bulkImport
Each request returns a Bulk Import ID that can be used to retrieve processing status and results.
Bulk Import Behavior and Constraints
| Behavior | Constraints |
|---|---|
| Processing Mode | - Bulk import operations are handled asynchronously - Requests are validated before processing begins |
| Payload and Validation Rules | - Maximum payload size: 30 MB - If the JSON structure is invalid or contains incorrect data types, the request fails, and no data is processed - The backend enforces all field-level validations |
| Create vs Update Logic | - If an entity with the same External ID already exists, the entity is updated. - If the External ID does not exist, a new entity is created. |
End-to-End Flow
Bulk import operations must be performed in a specific sequence because several HIDM entities depend on one another. Parent entities must exist before child entities or assignments can be created.
NOTE:
- All referenced IDs must already exist in the system.
- Invalid references result in validation errors.
- Sensitive fields should comply with customer security policies.
Bulk Import Flow Diagram
The diagram below illustrates the required import order and entity dependencies:
Recommended End-to-End Import Order
Follow the steps below to ensure a successful bulk import:
| Step | Recommended Import Order | When Bulk Importing | Ensure That | Remarks |
|---|---|---|---|---|
| 1 | Permission Groups | Permission Groups | Permissions exists | - Permissions exist by default as they are imported with core data during the environment deployment. |
| 2 | Roles | Roles | Permission Groups exist | - Import parent (highest-level) roles first. - Import child roles only after their parent roles are available, so the hierarchy can be established correctly. - Assign each role to the appropriate Permission Group during or after the import. |
| 3 | Business Unit Types | Business Unit Types | Permission Groups and Roles exist | - Business Unit Types must exist before Business Units can be created. Please note that we have added Permission Groups and Roles as a prerequisite here for Step 3. This is only to ensure logical order for the sake of Step 5; which is further described in the Scenario: Bulk Import of Users with Assignment. However, you do not need Permission Groups or Roles to exist solely to bulk import Business Unit Types (Step 3) and Business Units (Step 4). |
| 4 | Business Units | Business Units | Permission Groups, Roles, and Business Unit Types exist | - Import Business Units after their corresponding Business Unit Types are available. |
| 5 | Users with Assignments | Users with Assignments | Permission Groups, Roles, Business Unit Types, and Business Units exist | - Once roles, permission groups, and business units are in place, import Users and include their role and business unit assignments in the request payload. |
WARNING:
- Do NOT use predefined roles or permission groups created during system deployment.
The core R&D team controls these objects and may change at any time. - Always create and manage customer‑specific roles and permission groups for each project.
Scenario: Bulk Import Users with Assignments
This scenario explains how to import users with their assignments using the Bulk Import Users endpoint and how this affects the HIDM UI.
In this scenario, we are importing two users (one already exists, and one is newly created) via the Swagger portal and checking the impact on the HIDM UI. This example assumes that the Business Unit (BU) is not a leaf BU.
- Existing username: Mayur Khond
- Newly created username: Test User
NOTE: It is assumed that the Permission Groups, Roles, Business Unit Types, and Business Units have already been imported before proceeding with the request payload to import users and their assignments.
Follow these steps to execute the payload request in Swagger:
- Navigate to the HIDM Swagger API.
- Press the Authorize button.
- Enter the valid Client ID and Client Secret and press Authorize.
- Navigate to the POST /users/bulkImport endpoint.
- Press the Try it out button.
- Fill the request body, including all mandatory fields, and map the correct external IDs to the respective users.
{
"users": [
{
"id": "maykho160", //id represents the user’s External ID in HIDM.
"login": "mayur.khond",
"fullName": "mayur khond",
"password": null,
"passwordChangeFlag": false,
"ownerBusinessUnitGroupId": null, // ownerBusinessUnitGroupId is the logged-in user's Business Unit external ID. For example, if a user logs in using Company as a BU, then it is the external ID of Company
"assignments": [
{
"applicationId": "hidm_1", // applicationId is the application external ID
"businessUnitGroupId": "1", // businessUnitGroupId is the business unit external ID
"globalLocationNumber": null, // GLN is a reference to a unique ID of the newly created Business Unit in an external system. This field is mandatory only if the BU or any of its child BUs is a leaf-type BU (islocation=True)
"roleId": "root_1" // roleId is the role external ID. Sample value, root_1 is for illustrative purposes.
}
],
"email": "[email protected]",
"countryCode": null,
"phoneNumber": "8877665544",
"isLocked": false,
"locale": null,
"accessCode": null,
"accessCodeChangeFlag": false,
"dallasKey": null,
"dallasKeyExpiration": null,
"rfid": null,
"rfidExpiration": null,
"msr": null,
"msrExpiration": null
},
{
"id": "456789",
"login": "Test User",
"fullName": "Test User",
"password": null,
"passwordChangeFlag": false,
"ownerBusinessUnitGroupId": null,
"assignments": [
{
"applicationId": "hidm_8",
"businessUnitGroupId": "2",
"globalLocationNumber": null,
"roleId": "2"
}
],
"email": "[email protected]",
"countryCode": null,
"phoneNumber": null,
"isLocked": false,
"locale": null,
"accessCode": null,
"accessCodeChangeFlag": false,
"dallasKey": null,
"dallasKeyExpiration": null,
"rfid": null,
"rfidExpiration": null,
"msr": null,
"msrExpiration": null
}
]
}The table describes various scenarios for request parameters and their responses.
| Request Action | Response Action | Remarks/Messages |
|---|---|---|
| Process the Bulk Import request without Authorization | 401 Unauthorized | Use the valid credentials (Client ID and Client Secret) to authorize. |
| Update the request without the id (External ID) of a user | 400 Bad Request | The Id field is required. |
| Update the request without the login (Username) of a user | 400 Bad Request | The Login field is required. |
| Update the request without the full name of a user | 400 Bad Request | The FullName field is required. |
| Fill in the following required fields and process the Bulk Import request: - id - login - fullname - roleId | 200 OK | The request was processed. |
Sample Request Parameters
The following request body contains the import of two users (one already exists, and one is newly created).
The following are the mandatory fields in this request body for both existing and new users:
- id (Users' external ID)
- login (Username)
- fullname
- roleId
The table describes the properties that can be updated for the Bulk Import of users:
| Property | Can be Updated | Description |
|---|---|---|
| Id | No | - The Id (External ID) field is unique for each user (cannot be changed); if you change it, the system will create a new user. - The maximum character limit for Id is 255. |
| login | No | - The login (Username)field is unique for each user (cannot be changed); if you change it, the system will create a new user. - If you add the existing login (username) to another user in the request body, the system displays the following message in the response: Login name cannot be same - The maximum character limit for login is 40. |
| fullName | Yes | - Can be updated. - The maximum character limit for fullName is 50. |
| password | Yes | - Can be updated. - The maximum character limit for password is 50. |
| passwordChangeFlag | Yes | - Can be updated. - It is a Boolean value, and the valid values are true or false. |
| ownerBusinessUnitGroupId | Yes | - Can be updated. - ownerBusinessUnitGroupId is the logged-in user's Business Unit external ID. For example, if a user logs in using Company as a BU, then it is the external ID of Company. - The maximum character limit for ownerBusinessUnitGroupId is 255. |
| applicationId | Yes | - Can be updated. - applicationId is the application's external ID. - The maximum character limit for applicationId is 255. |
| businessUnitGroupId | Yes | - Can be updated. - businessUnitGroupId is the ID of the Business Unit assigned by its owner. - The maximum character limit for businessUnitGroupId is 255. - Please note that this is conditionally required if globalLocationNumber is not available. |
| globalLocationNumber | Yes | - Can be updated. - globalLocationNumber is a reference to a unique ID of the newly created Business Unit in an external system. This field is mandatory only if the BU or any of its child BUs is a leaf-type BU (islocation=True). - The maximum character limit for globalLocationNumber is 255. - Please note that this is conditionally required if businessUnitGroupId is not available. |
| roleId | Yes | - Can be updated. - roleId is the role external ID. Sample value, root_1 is for illustrative purposes. - The maximum character limit for roleId is 255. |
| Yes | - Can be updated. - The maximum character limit for email is 255. | |
| countryCode | Yes | - Can be updated. - Country Code cannot be null if phone number is present. - The maximum character limit for countryCode is 10. |
| phoneNumber | Yes | - Can be updated. - The maximum character limit for phoneNumber is 50. |
| isLocked | Yes | - Can be updated. - It is a Boolean value, and the valid values are true or false. |
| locale | Yes | - Can be updated. |
| accessCode | Yes | - Can be updated. - The maximum character limit for accessCode is 64. |
| accessCodeChangeFlag | Yes | - Can be updated. - It is a Boolean value, and the valid values are true or false. |
| dallasKey | Yes | - Can be updated. - The maximum character limit for dallasKey is 50. |
| dallasKeyExpiration | Yes | - Can be updated. - Configurable as per the Dallas key expiration policy. |
| rfid | Yes | - Can be updated. - The maximum character limit for RFID is 50. |
| rfidExpiration | Yes | - Can be updated. - Configurable as per the RFID expiration policy. |
| msr | Yes | - Can be updated. - The maximum character limit for MSR is 50. |
| msrExpiration | Yes | - Can be updated. - Configurable as per the MSR expiration policy. |
Fields Mapping to HIDM UI
The following table describes the IDs of the request body that are mapped to the HIDM UI:
| Fields | Description |
|---|---|
| id | - Indicates the user's external ID, for example: |
| applicationId | - Indicated the application's external ID, for example: |
| businessUnitGroupId | - Indicates business unit external ID, for example: - Please note that Business Unit and Business Unit Group are the same entity, and our payload uses the businessUnitGroupId and ownerBusinessUnitGroupId. |
| roleId | - Indicates role external ID, for example: |
- Press the Execute button.
- Check the response code. The 202 response code indicates a successful request and returns the bulk import ID; whether the import was successful can be checked via the bulk import ID.
- On the HIDM UI, search for the newly imported user.
The application displays the newly imported user.
Track the Bulk Import Status
Use the following endpoint to retrieve the status of a bulk import request:
- GET /bulkImport/{bulkImportId}
This endpoint returns processing status and error details, if any occurred during import.