User Synchronization API
- Syed Fida Ul Hassan (Unlicensed)
- Thomas Hellstrøm (Unlicensed)
Terminology
Please make sure you have read about the base concepts of the Remoting Web Service.
Description
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:
- They can create automated rules for their users’ access to the System.
- New users joining the organization automatically get access to HRMTS System.
- Users leaving the organization automatically loose access to the System.
- Change of users’ roles in the organization automatically reflect in the System.
- Transparent management of Single Sign-On configuration for users.
Flow of Information
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. |
API Functions
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.
Batch Synchronize Users
Use the API function BatchSyncUsers to submit a request to synchronize users.
Request
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. |
UserUpdateBypassTypes
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:
- None: Default, it bypasses nothing.
- Details: Bypass all the properties that fall under user details.
- IsLocked: Bypass the flag to indicate whether the user is locked.
- ExpiresOnDateTimeUtc: Bypass the date and time in UTC when the user expires.
- LanguageTypes: Bypass the default language to use on screen, and for number and date formatting.
- AccessInfoList: Bypass the list of access information.
User
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. |
UserDetails
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. |
UserAccessInfo
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. |
Response
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. |
Get Status of Batch Synchronize Users
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.
Request
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. |
Response
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. |
BatchSyncEntityStatus
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. |
Important to Know
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.
Configuration
- The Customer’s account in the System must be configured for use of Remoting Web Service.
Submitting Requests
- The requests for synchronizations are processed once a day after midnight.
- Submit the request for synchronizations before midnight.
- Call the function to get the status of the submitted request after 08:00 the following morning.
Processing
- Only the last submitted request is processed as long as it is registered without errors.
- Each user must have unique Id, Username, ThirdPartyId and ThirdPartyUsername.
- For each user in the request, if no matching user exists in the System, then a new user is created and marked synchronized.
- For each user in the list, if a matching user exists in the System, then the existing user is updated and marked synchronized.
- If the user was previously deleted or locked, then the user is reactivated.
- Existing users in the System that are marked synchronized, but not present in the synchronization request, are marked deleted.
- The users are soft-deleted to maintain their history and connections to various projects.
- Exception: The user that are project leaders in active projects are not deleted.