Department Synchronization API
- Syed Fida Ul Hassan (Unlicensed)
- Thomas Hellstrøm (Unlicensed)
Department Synchronization
This document describes batch synchronization of department through the Remoting Web Service.
Terminology
Remoting Web Service
Please make sure you have read about the base concepts of 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.
| Property | Type | Description |
|---|---|---|
DoNotDeleteUnlistedSynchronizedDepartments | Boolean | Flag to indicate previously synchronized departments, that are not listed in current request, should be deleted. When true, the unlisted synchronized departments are not deleted. |
| DoNotUnpublishAndDeactivateProjectsInDeletedDepartments | Boolean | Flag to indicate whether projects in departments being deleted should be unpublished and deactivated. When true the departments with published projects are not deleted. |
| DoNotDeleteUsersInDeletedDepartments | Boolean | Flag 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. |
| DepartmentUpdateBypassTypes | Enumerator | One or more properties to bypass when updating existing departments. See details below |
| DepartmentList | List<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.
| Property | Type | Description |
|---|---|---|
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. |
| Title | String | Name of the department. |
| ParentDepartmentId | String | Id 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. |
| Details | Department 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.
| Property | Type | Description |
|---|---|---|
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. |
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.
| Property | Type | Description |
|---|---|---|
| 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.
| Property | Type | Description |
|---|---|---|
| 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.
| Property | Type | Description |
|---|---|---|
| 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:
| Property | Type | Description |
|---|---|---|
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.
| Property | Type | Description |
|---|---|---|
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:
| 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 BatchSyncEntityStatus | 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.
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.