Remoting API



Foreword

HR Manager Talent Solutions offers a remoting web service for its recruitment application Talent Recruiter that allows third party systems to integrate and manage major operations in the applications. This document provides an overview of this remoting web service.

URLs

There are two main URLs to know when using Remoting Web Service:

  1. https://recruiter-api.hr-manager.net/Remoting.svc?singleWsdl
    This URL returns the full WSDL of the Remoting Web Service. Use this to create service reference, various proxy models and validation rules.
  2. https://recruiter-api.hr-manager.net/Remoting.svc
    This is the primary URL of the Remoting Web Service and offers endpoints for SOAP 1.1 over HTTP and HTTPS.

General Requirements

Following are the general requirements to use the Remoting Web Service:

  • The Remoting Web Service must be enabled in the Customer’s account in the System.
  • An api key must be configured in the Customer’s account in the System. This key is used to authenticate calls made to the web service.
  • Certain functions in the web service must be explicitly enabled for the Customer’s account in the System, such as Batch Synchronization of Users.
  • If SOAP 1.2 is being used, then X.509 certificates must be configured on both System’s and Customer’s sides.

Important to Know

A few base ideas and patterns are vastly in use throughout the API. It can be a good idea to get familiar with them before diving into the details of the API functions.

Consume-Only

The web service is consume-only. It never initiates communication to Customer’s systems on its own.

Synchronous and Asynchronous Functions

Most of the functions in the web service are synchronous. These functions process the request and return the results immediately to the caller.

Some of the functions in the web service are asynchronous. These functions simply validate the request and return the validation results to the caller. If the validation passes, the function adds the request to an internal queue for later processing. Separate functions are available to retrieve processing status of queued requests.

The API Function Signature Pattern

Each API function pairs with dedicated request and response objects. The idea is to send a single “package” of parameters to invoke the API function, and receive a single “package” of parameters in return. This pattern allows simpler extension of the request and response objects without breaking the implementations.

The corresponding request and response objects share the same name as the API function and end with suffixes Rqt for request and Rsp for response. For example, the function “CreateQuestionnaire” creates a new questionnaire.

Remotable Entity

Every entity in the System that can be created and managed through remoting API is called a RemotableEntity. Examples of such entities are User, Department, Position, Document, Candidate, Questionnaire etc. The base properties of RemotableEntity are as follows:

PropertyTypeDescription
IdRemotableIdId of the entity (se next session)
ParentDepartmentIdRemotableIdId of the department where the entity belongs
TitleStringTitle, name, text or value of the entity

Remotable Id

Each RemotableEntity has ability to store two different ids – one System id and one third-party id. The API functions requiring a RemotableId expect one or both of these ids, depending on the API function. The base properties of RemotableId are as follows:


PropertyTypeDescription
IdTThe unique id of the entity in the system. This id can be a String, Integer, Long or some other data type.
ThirdPartyIdStringThe unique id of the entity in the third party system

Property Bag

As no two system are equal in terms of functionality or data they store, the System provides a way to store additional information from third party systems together with the entities. This information is stored in a PropertyBag of the entity. A property bag is a basic list of key-value pairs of strings.

Property

A single Property in a PropertyBag consists of following properties.


PropertyTypeDescription
KeyStringIdentifying key of the property. The key must be unique within a single entity.
ValueStringValue of the property

The Request Objects

Each request object in an API function inherits from an abstract class called RequestBase that defines base properties for each request regardless of API function. These properties are as follows:


PropertyTypeDescription
CustomerIdIntegerSystem id of the Customer. Always the same for a given Customer.
DepartmentIdRemotableIdSystem or third party id of the department for which the API function is being called.
SystemLanguageTypeEnumerator

Some of the properties in entities, such as dropdown items, store multi-lingual values. This property defines which language to use when reading/writing such properties in the corresponding API function.

  • Default - Default available language
  • English
  • NorwegianBokmal
  • Swedish
  • Danish
  • Finnish
  • German
  • Spanish
  • French
  • NorwegianNynorsk


AuthenticationTokenStringThe api key that is set in department settings in HRMTS
ReferenceTokenStringA unique token sent by the third party system with each API function request. The same token is returned to the third party system in the corresponding response.
IncludeDebugOverviewBooleanA reserved flag to use in conjunction with HR Manager Support to debug various issues in API functions.

The Response Objects

Each response object in an API function inherits from an abstract class called ResponseBase that defines base properties for each response regardless of API function. These properties are as follows:


PropertyTypeDescription
TransactionStatusTransactionStatusA custom object representing the state of the transaction along with potential error/failure information.
SystemLanguageTypeEnumerator

Some of the properties in entities, such as dropdown items, store multi-lingual values. This property defines which language to use when reading/writing such properties in the corresponding API function.

  • Default - Default available language
  • English
  • NorwegianBokmal
  • Swedish
  • Danish
  • Finnish
  • German
  • Spanish
  • French
  • NorwegianNynorsk


ReferenceTokenStringThe unique third party token sent with the corresponding request object.

The List Request Objects

For API functions that returns lists, the request objects inherit from an abstract class called ListRequestBase that again inherits from RequestBase as described above. This class defines base properties that are unique for list operations regardless of API function. These properties are as follows:


PropertyTypeDescription
LimitReturnedDataSizeToBytesLongDefines a limit in bytes for how much data to return in current transaction. Send 0 to get one complete list item..
IncludeDetailsBoolean

Flag to include details of items being returned. This feature must be enabled in Customer configuration on the server to function.

ItemIdListList<Integer>List of System ids of items to fetch. This property is usually used in consecutive calls to fetch items that were not returned in the first or previous call.


The List Response Objects

For API functions that returns lists, the response objects inherit from an abstract class called ListResponseBase that again inherits from ResponseBase as described above. This class defines base properties that are unique for list operations regardless of API function. These properties are as follows:


PropertyTypeDescription
RemainingItemIdListList<Integer>List of System ids of items that matched the criteria, but were not returned in the current call. Pass this property to the same function call again to get these items.