TM Employee Syncronization API

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.