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:
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.
Use the API function BatchSyncEmployees to submit a request to synchronize employees.
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. |
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. |
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> | |
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. |
xxxx
Property | Type | Description |
---|---|---|
Id | <T> | Internal, system-generated identifier |
ThirdPartyId | string | Customer generated unique identifier |
xxxx
Property | Type | Description |
---|---|---|
ParentQuestionId | int | |
QuestionId | int | |
QuestionGroupId | int | |
AnswerGroupId | int | |
CustomAnswer | string | |
DateTimeAnswer | Nullable<DateTime> | |
ParentAnswerOptionId | int | |
RowId | int | |
AnswerOptionsIdList | List<int> | |
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. |
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.
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. |
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. |
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. |
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.
The Customer’s account in the System must be configured for use of Remoting Web Service.
Only the last submitted request is processed as long as it is registered without errors.