User Synchronization API




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.