TM Employee Syncronization API
Introduction
The Remoting Web Service is a larger service that consists of many different functions that allow Customers to integration with the System on different levels.
This documentation focuses on the functions used for batch synchronization of employees through Remoting Web Service. These functions allow the Customers to pull out a subset of employees from their directory service, and send them to HR Manager as employees of the System. Using these functions, the Customers gain following major benefits:
- They can create automated rules for their employees’ access to the System.
- New employees joining the organization automatically get access to HRMTS System.
- Employees leaving the organization automatically loose access to the System.
- Change of employees’ roles in the organization automatically reflect in the System.
- Transparent management of Single Sign-On configuration for employees.
API Functions
Following is a brief overview of the API functions used in synchronization of employees. Synchronization of employees 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 employees
Use the API function BatchSyncEmployees to submit a request to synchronize employees.
Request
The request object, BatchSyncEmployeeRqt, requires following properties in addition to the general requirements of requests made to Remoting Web Services.
| Property | Type | Description |
|---|---|---|
| SendSignInInfoToNewEmployees | Boolean | Flag to indicate whether an email should be sent to newly created employee containing sign-in link, sign-in id and password. |
| NewEmployeesMustChange PasswordOnFirstSignIn | Boolean | Flag to indicate whether new employees must change password the first time they sign into the system. |
| PlaceEmployeeOnRootIfAcce ssDepartmentDoesNot Exist | Boolean | Flag to indicate that if employee's primary access department does not exist, then place the employee on root department. When it happens, the employee get account is automatically locked. |
| DoNotDeleteUnlistedSynchronizedEmployees | Boolean | Flag to indicate whether previously synchronized employees, that are not listed in current request, should be deleted or not. |
| AutoCreateJobTitles | Boolean | Flag to indicate whether Job Titles should be created automatically when it does not exists in the DDList. The auto-creation will only work if the customer is using 'ThirdpartyId' for JobTitle. See: JobTitleId |
| EmployeeList | List of Employees | List of employees to synchronize. The list must contain at least one valid employee. |
Employee
The Employee object consists of many properties that represent a employee in the System. Following are the properties required for the synchronization.
| Property | Type | Description |
|---|---|---|
| Id | Remotable id of type Integer | Id of the employee. In case of new employees, the Id-part must be empty, but a unique ThirdPartyId-part can be supplied. In case of existing employees, either the Id-part or the ThirdPartyId-part must be supplied. |
| Username | String | Email address of the employee. Must be unique for each employee. |
| FirstName | String | First name of the employee. |
| LastName | String | Last name of the employee. |
| Details. ThirdPartyUsername | String | Login id of the employee in Customer’s network. This property is only required if Single Sign-On is in use. |
| Details | EmployeeDetails | Details of the employee. |
EmployeeDetails
The EmployeeDetails object consists of many properties that represent details of a employee in the System. Following are the properties required for the synchronization.
| Property | Type | Description |
|---|---|---|
| ThirdPartyUsername | String | Login id of the employee in Customer’s network. This property is only required if Single Sign-On is in use. |
| Address | String | |
| Address2 | String | |
| Zip | String | |
| City | String | |
| Country | String | |
| Nationality | String | |
| Gender | Enum | Valid values: Male, Female, Other |
| BirthDate | Nullable<DateTime> | |
| AnniversaryDate | Nullable<DateTime> | |
| PersonId | String | |
| AlternateEmail | String | |
| PhonePrivate | String | |
| PhoneMobile | String | |
| PhoneFax | String | |
| PhoneWork | String | |
| PhonePrivateCountryCode | String | |
| PhoneMobileCountryCode | String | |
| PhoneWorkCountryCode | String | |
| EmploymentId | String | |
| EmploymentDate | Nullable<DateTime> | |
| WorkTimeStart | int | |
| WorkTimeEnd | int | |
| WorkPercentage | int | |
| WorkLocation | string | |
| BankAccountNumber | string | |
| MaritalStatusId | RemotableId<int> | |
JobTitleId | RemotableId<int> | |
| JobTypeId | RemotableId<int> | |
| NoticeTimeId | RemotableId<int> | |
| EducationLevelId | RemotableId<int> | |
| ProbationPeriodId | int | |
| ParentEmployeeId | int | |
| ParentEmployee | RemotableId<int> | |
| CostCenter | string | |
| StaffCategory | string | |
| LastName2 | string | |
| AvailabilityDate | Nullable<DateTime> | |
| ResignationDate | Nullable<DateTime> | Should not be used. Will be deprecated soon. (01.05.2021) 'Lastworkingdate' should be used instead (24.02.2021) |
| Salary | string | |
| AppraisalImageFileName | string | |
| SeniorityDate | Nullable<DateTime> | |
| ReasonForLeavingId | RemotableId<int> | |
| FTE | double | |
| BankRegistrationNumber | string | |
| LastWorkingDate | Nullable<DateTime> | |
| EmploymentEndDate | Nullable<DateTime> | |
| RelativeInfo1Email | string | |
| RelativeInfo1RelationId | Remotable<int> | |
| RelativeInfo1Name | string | |
| RelativeInfo1Phone | string | |
| RelativeInfo2Email | string | |
| RelativeInfo2RelationId | Remotable<int> | |
| RelativeInfo2Name | string | |
| RelativeInfo2Phone | string | |
| AccessLevelList | List<UserAccessInfo> | List of UserAccessInfo entries that define employee’s access and roles in different departments. At least one AccessInfo entry must be supplied. The first entry in the list servers as employees’ default access. |
| KeyInformationAnswerList | List<EmployeeKeyInformationAnswer> | |
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. |
RemoteableId
xxxx
| Property | Type | Description |
|---|---|---|
| Id | <T> | Internal, system-generated identifier |
| ThirdPartyId | string | Customer generated unique identifier |
EmployeeKeyInformationAnswer
xxxx
| Property | Type | Description |
|---|---|---|
| ParentQuestionId | int | |
| QuestionId | int | |
| QuestionGroupId | int | |
| AnswerGroupId | int | |
| CustomAnswer | string | |
| DateTimeAnswer | Nullable<DateTime> | |
| ParentAnswerOptionId | int | |
| RowId | int | |
| AnswerOptionsIdList | List<int> | |
Response
The API function returns BatchSyncEmployeeRsp 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 employees
The function to batch synchronize employees 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 GetBatchSyncEmployeesStatus to get status of the actual synchronization.
Request
The request object, GetBatchSyncEmployeesStatusRqt, 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 GetBatchSyncEmployeesStatusRsp 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 BatchSyncEn tityStatus | 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 employee must have unique Id, Username, ThirdPartyId and ThirdPartyUsername.
- For each employee in the request, if no matching employee exists in the System, then a new employee is created and marked synchronized.
- For each employee in the list, if a matching employee exists in the System, then the existing employee is updated and marked synchronized.
- If the employee was previously deleted or locked, then the employee is reactivated.
- Existing employees in the System that are marked synchronized, but not present in the synchronization request, are marked deleted.
- The employees are soft-deleted to maintain their history.