Please make sure you have read about the base concepts of the Remoting Web Service. |
This document focuses on the functions used for batch synchronization of users through Remoting Web Service. These functions allow the Customers to pull out a subset of users from their directory service, and send them to HR Manager as users of the System. Using these functions, the Customers gain following major benefits:
Following is a brief overview of the flow of information from Customer’s directory service to the System.
Step | Customer’s System | Direction | HRMTS System |
---|---|---|---|
1 | Pull list of users from internal directory service. | − |
|
2 | Apply filtration rules. | − |
|
3 | Send request to synchronize users. | → | Receive and validate the request. |
4 | Receive validation response. | ← | Send validation response. |
5 | Correct potential errors and repeat #1. |
|
|
6 |
| − | If validation passes, add request to internal queue. |
7 |
| − | Process request from internal queue. |
8 | Send request to get status of last request. | → | Receive and validate the request. |
9 | Receive status response. | ← | Send status response. |
Following is a brief overview of the API functions used in synchronization of users. Synchronization of users is handled asynchronously in the System. It means that there is one API function to submit the request, and another one to get the status of the request.
Use the API function BatchSyncUsers to submit a request to synchronize users.
The request object, BatchSyncUsersRqt, requires following properties in addition to the general requirements of requests made to Remoting Web Services.
Property | Type | Description |
---|---|---|
SendSignInInfoToNewUsers | Boolean | Flag to indicate whether an email should be sent to newly created users containing sign-in link, sign-in id and password. |
NewUsersMustChangePasswordOnFirstSignIn | Boolean | Flag to indicate whether new users must change password the first time they sign into the system. |
PlaceUserOnRootIfAccessDepartmentDoesNotExist | Boolean | Flag to indicate that if user's primary access department does not exist, then place the user on root department. When it happens, the user get account is automatically locked. |
UserUpdateBypassTypes | Enumerator | One or more properties to bypass when updating existing users. |
UserList | List of User | List of users to synchronize. The list must contain at least one valid user. |
When editing a user in the administration interface of the System, there is a setting called “Bypass Synchronization”. This setting allows users to be “immune” to synchronization. It means that any information sent through web service to update such users is ignored.
While the administration interface allows individual users to be immune to synchronization, the property “UserUpdateBypassTypes” allows a similar immunity to all existing users during a synchronization. This property is a multi-value enumerator where more than one values can be selected. When configured, the selected properties of existing users are not updated during synchronization.
The available values for this property are:
The User object consists of many properties that represent a user in the System. Following are the properties required for the synchronization.
Property | Type | Description |
---|---|---|
Id | Remotable id of type Integer | Id of the user. In case of new users, the Id-part must be empty, but a unique ThirdPartyId-part can be supplied. In case of existing users, either the Id-part or the ThirdPartyId-part must be supplied. |
Username | String | Email address of the user. Must be unique for each user. |
FirstName | String | First name of the user. |
LastName | String | Last name of the user. |
Details. ThirdPartyUsername | String | Login id of the user in Customer’s network. This property is only required if Single Sign-On is in use. |
Details | UserDetails | Details of the user. |
The UserDetails object consists of many properties that represent details of a user in the System. Following are the properties required for the synchronization
Property | Type | Description |
---|---|---|
ThirdPartyUsername | String | Login id of the user in Customer’s network. This property is only required if Single Sign-On is in use. |
AccessInfoList | List of UserAccessInfo | List of UserAccessInfo entries that define user’s access and roles in different departments. At least one AccessInfo entry must be supplied. The first entry in the list servers as users’ default access. |
The UserAcceessInfo object consists of two required properties.
Property | Type | Description |
---|---|---|
DepartmentId | String | Remotable id of an existing department where the user will have access. |
UserRoleList | List of remotable id of type Integer | List of remotable ids of roles for the user in the specified department. At least one existing role id must be supplied. |
The API function returns BatchSyncUsersRsp as result of the request. In addition to standard response from Remoting Web Service, it returns following properties:
Property | Type | Description |
---|---|---|
BatchSyncStatusType | Enumerator | Status of the request registration. |
The function to batch synchronize users is an asynchronous function that only registers the synchronization request in an internal queue. The queue is processed once a day, usually after midnight. Use the API function GetBatchSyncUsersStatus to get status of the actual synchronization.
The request object, GetBatchSyncUsersStatusRqt, requires following properties in addition to the general requirements of requests made to Remoting Web Services.
Property | Type | Description |
---|---|---|
InitialReferenceToken | String | The reference token of the initial submission you are trying get the status of. |
The API function returns GetBatchSyncUsersStatusRsp as result of the request. In addition to standard response from Remoting Web Service, it returns following properties:
Property | Type | Description |
---|---|---|
InitialReferenceToken | String | The reference token of the initial submission you are trying get the status of. |
BatchSyncStatusType | Enumerator | Status of the request processing. |
EntitySyncStatusList | List of BatchSyncEntityStatus | List of status for each synchronized entry. |
The BatchSyncEntityStatus object consists of two required properties.
Property | Type | Description |
---|---|---|
EntityId | Remotable id of type Integer | Remotable id of the entity being synchronized. Upon successful synchronization, the id always contains System’s internal id assigned to the entity. |
EntitySyncStatusType | Enumerator | Status of the entity synchronization. |
Description | String | Any other relevant information. |
The following points are important to know in relation to synchronization. Familiarizing with them will help understanding what to expect from using the API functions.