TM Employee Syncronization API
- 1 Introduction
- 2 API Functions
- 2.1 Batch synchronize employees
- 2.1.1 Request
- 2.1.1.1 Employee
- 2.1.1.2 EmployeeDetails
- 2.1.1.3 UserAccessInfo
- 2.1.1.4 RemoteableId
- 2.1.1.5 EmployeeKeyInformationAnswer
- 2.1.2 Response
- 2.1.1 Request
- 2.2 Get status of batch synchronize employees
- 2.2.1 Request
- 2.2.2 Response
- 2.2.2.1 BatchSyncEntityStatus
- 2.3 Important to know
- 2.3.1 Configuration
- 2.3.2 Submitting Requests
- 2.3.3 Processing
- 2.1 Batch synchronize employees
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 | 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. |
EmployeeList | List of Employees | List of employees to synchronize. |
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. |
Username | String | Email address of the employee. |
FirstName | String | First name of the employee. |
LastName | String | Last name of the employee. |
Details. | String | Login id of the employee in Customer’s network. |
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. |
Address | String |
|
Address2 | String |
|
Zip | String |
|
City | String |
|
Country | String |
|
Nationality | String |
|
Gender | Enum | Valid values: |
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) |
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. |
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 | List of remotable ids of roles for the user in the specified department. |
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.