Department Synchronization API

Department Synchronization

This document describes batch synchronization of department through the Remoting Web Service.



Description

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. The service is continuously growing with new functions all the time.

This document focuses on the functions used for batch synchronization of departments through Remoting Web Service. These functions allow the Customers to pull out a subset of departments from their directory service, and send them to HR Manager as departments of the System. Using these functions, the Customers gain following major benefits:

  • Change of department hierarchy in the organization automatically reflect in the System.

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 departments from internal directory service.

 

2

Apply filtration rules.

 

3

Send request to synchronize departments.

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.

10

Process and/or display response.

 

API Functions

Following is a brief overview of the API functions used in synchronization of departments. Synchronization of departments 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 Departments

Use the API function BatchSyncDepartments to submit a request to synchronize departments.

Request

The request object, BatchSyncDepartmentsRqt, requires following properties in addition to the general requirements of requests made to Remoting Web Services.

PropertyTypeDescription

DoNotDeleteUnlistedSynchronizedDepartments

BooleanFlag to indicate previously synchronized departments, that are not listed in current request, should be deleted. When true, the unlisted synchronized departments are not deleted.
DoNotUnpublishAndDeactivateProjectsInDeletedDepartmentsBooleanFlag to indicate whether projects in departments being deleted should be unpublished and deactivated. When true the departments with published projects are not deleted.
DoNotDeleteUsersInDeletedDepartmentsBooleanFlag to whether users in departments being deleted should be marked deleted. When true, the users in departments being deleted are moved to root department and locked.
DepartmentUpdateBypassTypesEnumerator

One or more properties to bypass when updating existing departments. See details below

DepartmentListList<Departments>

List of departments to synchronize.

The list must contain at least one valid department.

DepartmentUpdateBypassTypes

When editing a department in the administration interface of the System, there is a setting called “Bypass Synchronization”. This setting allows departments to be “immune” to synchronization. It means that any information sent through web service to update such departments is ignored.

While the administration interface allows individual departments to be immune to synchronization, the property “DepartmentUpdateBypassTypes” allows a similar immunity to all existing departments 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 departments 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 department details.
  • SystemLanguageList: Bypass list of system languages available for the department.
  • SubDepartmentList: Bypass the list of sub departments.

Department

The Department object consists of many properties that represent a department in the System. Following are the properties required for the synchronization.


PropertyTypeDescription

Id

RemotableID/

Integer

Id of the department.

In case of new departments, the Id-part must be empty, but a unique ThirdPartyId-part can be supplied.

In case of existing departments, either the Id-part or the ThirdPartyId-part must be supplied.
TitleStringName of the department.
ParentDepartmentIdStringId of parent department in department hierarchy. A null value here would indicate that it is the root department, which is not allowed to be synchronized.
DetailsDepartment Details

Details of the department. (see below)

DepartmentDetails

The DepartmentDetails object consists of many properties that represent details of a department in the System.  Following are the properties for this object.


PropertyTypeDescription

InternalName

String

Internal name of the of the department.

IsRoot

Boolean

Determines whether the department is a root.

IsVirtualRoot

Boolean

Determines whether the department is a virtual root.

IsSynchronized

Boolean

Determines whether the department is synchronized.

IsProjectCreationAllowed

Boolean

Determines whether the project created is allowed in this department.

IsDeletable

Boolean

Determines whether the department can be deleted.

SiblingSortOrder

Integer

Sort order of the department among the siblings.

SystemLanguageList

List of SystemLanguageTypes

List of system languages available for the department.

ContactPerson

String

Contact person for the department.

Address

Address

Address of the department.

Phone

Phone

Phone of the department.

Email

String

Email address of the department.

Website

String

Website of the department.

ParentDepartmentIdCsv

String

Ordered CSV of the parent department ids.

This is a read-only field.

SubDepartmentIdCsv

String

Ordered non-recursive CSV of the sub department ids.

This is a read-only field.

SystemLanguageTypes

The SystemLangaugeTypes object is an enumerator that represents the supported languages in the System.

Address

The Address object consists of properties that represent a single address.  Following are the properties for this object.


PropertyTypeDescription
AddressLine1

String

Address line 1.

AddressLine2

String

Address line 2.

PostOfficeBox

String

P.O. Box.

City

String

City.

ZipCode

String

Zip code.

County

String

County.

Country

String

Country.

 

Phone

The Phone object consists of properties that represent a collection of phone numbers.  Following are the properties for this object.


PropertyTypeDescription
Landline

PhoneNumber

Land line.

Mobile

PhoneNumber

Mobile.

Fax

PhoneNumber

Fax.

PhoneNumber

The PhoneNumber object consists of properties that represent a single phone number.  Following are the properties for this object.


PropertyTypeDescription
CountryCode

String

Country code.

AreaCode

String

Area code.

Number

String

The actual number.

IsPreferredNumber

Boolean

Flag to indicate whether this is the preferred number.

 

Response

The API function returns BatchSyncDepartmentsRsp as result of the request. In addition to standard response from Remoting Web Service, it returns following properties:


PropertyTypeDescription

BatchSyncStatusType

Enumerator

Status of the request registration.

 

Get Status of Batch Synchronize Departments

The function to batch synchronize departments 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 GetBatchSyncDepartmentsStatus to get status of the actual synchronization.

Request

The request object, GetBatchSyncDepartmentsStatusRqt, requires following properties in addition to the general requirements of requests made to Remoting Web Services.

PropertyTypeDescription

InitialReferenceToken

String

The reference token of the initial submission you are trying get the status of.

Response

The API function returns GetBatchSyncDepartmentsStatusRsp as result of the request. In addition to standard response from Remoting Web Service, it returns following properties:


PropertyTypeDescription

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.


PropertyTypeDescription

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.

 

Limitation(s)

  • It is not possible to synchronize the root department.

 

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 department must have unique Id.
  • For each department in the request, if no matching department exists in the System, then a new department is created and marked synchronized.
  • For each department in the list, if a matching department exists in the System, then the existing department is updated and marked synchronized.