MLM API - Domain model and concepts

[#1]

• MLM API
• Handle full loads & changes
• Pagination of the result set
• Handle deletions
• Historical, current & future data
• Response times API
• Versioning of the different endpoints
• Entity model
• How to ‘match’ entities?

MLM API

The available API’s of Visma | YouServe are developed corresponding with the data which is required for a specific HR domain. This MLM API has an ‘outside in’ set up, which means that each domain contains only the data and endpoints they need. The API’s support all common and domain-specific fields. For instance, the social security number is only available in domains with a legitimate reason, like Medical Leave Management. In other domains, other fields could be available. By using customer-specific ‘extensions’ it’s possible to add extra fields for an API user.

This Medical Leave API will expose the necessary data which is needed to do your sickness case management according to the Dutch law ‘Wet Poortwachter’.

Currently, we support the data entities People, Organisation Units, Sickness registrations, Value lists, Maternity Leaves, RoleAssignments, JobProfiles & Companies by exposing these via different endpoints. 

Handle full loads & changes

By calling the API the user will by default retrieve the tenant-specific data in full loads. In cases the user prefers to fetch only the changed data, we provide the possibility to use the parameters ‘ChangedAfter' & ‘ChangedUntil’ (see example).

Example date-time format :

changedAfter - 2020-08-21T00:00:00.000Z
changedUntil - 2020-08-21T12:01:46.077Z

Pagination of the result set

To reduce the load of an endpoint each endpoint supports paging. In case the results of an endpoint contain more than 500 records, a ‘nextLink tag’ is available to retrieve the next page of the result.

The nextLink tag is part of the body of the response and is also returned in the header of the response.

Example of nextlink in the in the body:

"nextLink": "/persons?pageToken=20220207T1409148404911Z-20210121-B2011&take=500"

Example of nextlink in the header:

x-nextlink: /persons?pageToken=0GXW0HLDWLoPqg3c63IGhbQuQhYB9mixdwbEP4+w52UUGnxYuKqsNBNDvK03lnoH&take=500"

The nextLink indicates that there are more pages to load. If there is no nextLink available, this means that it’s the last page of the result set.

Handle deletions

The existing endpoints will provide the API consumers a status field that says something about the (in)active status of a specific record. For example in situations where sickness cases were deleted in the core system.
The response bodies of the endpoints will have the following flag :

"iD" : "123456"
"IsDeleted":"false"

The active value will be stated as “False” and an inactive (deleted) record will be stated as “True”.
All the remaining fields in the deleted records will be empty and not visible in the output anymore.

Historical, current & future data

The different endpoints in the MLM API provide the most accurate data corresponding with the different data entities (Employee; Employments, Sickness cases, etcetera.).

By executing full loads (and changed) the API exposes default data until 4 years back in history (from today’s date). Besides historical data also future changes will be exposed via the API. All these different data sets will show in ‘versions' by using a ‘ValidFrom’ and a “ValidUntil’ date. These ‘ValidFrom’ and ‘ValidUntil’ are functional dates which are sent to the API by the Visma core systems along with the corresponding data. These dates indicate the duration for which this version of the entity is valid. This makes it possible to expose for example contract details of an Employee multiple years back in time and also the future changes. In case a future change is added to the core system (from 24 hours p/w to 32 hours p/w per 01-01-2021) the API exposes all these versions in ‘time slices’.

EXAMPLE OF RECORDS VERSIONS
In the example below, the employee changes his working hours on 01-11-2018 into 32 hours. After this change, the system creates a new version of the record with a validFrom and validUntil. On 01-04-2019 he becomes UX designer in the UX team, so the next version is created.

Response times API

Visma Verzuim (a.k.a. DWC) is a Visma | YouServe partner that integrates with Youforce for employee, organization and sickness data. The data is made available to Visma Verzuim using the Youforce API for Medical Leave Systems (In short: ‘MLM API’). 

The Youforce APIs are optimized for availability and scalability: the data is being ‘pre-processed’ for the API consumer. In this way we ensure that data is always available to integrated systems. 

Pre-processing means the data is stored in a read optimized database to which the API is connected. The pre-processing also takes data authorization into account. In this way the API and HR Core system remain responsive when dealing with peak loads from consuming systems. 

As a consequence it takes time before transactions in Youforce are available to other systems. This is known as ‘stale data’. The delay is normally within 10 to 30 minutes. Structural delays of more than 30 minutes are considered an issue. 

Versioning of the different endpoints

Some endpoints of the Medical Leave API might offer you multiple versions. Currently, the /employees endpoint has two functional versions.
The technical usage of the different versions will be explained below.

SWAGGER : In the Swagger tool this can be executed by switching the version in the right top bar 'Select a definition’ (see example).

After selecting the right version (f.e. V2), the corresponding version will show up in the Swagger documentation.

POSTMAN: In the Postman tool versioning can be managed by changing the Key 'Accept-Version' to 2.0 (see example).

Entity model

The MLM domain model contains the following entities

Endpoint	Entity	Description
Employee endpoint	Person	A natural person. In HR it is more common to talk about employees, but the entity Person is broader than the entity employee. The entity could also contain Persons without any employment with the employer, like contact persons, suppliers, etc.
	Employee	An employee is a person who had, has, or will have employment with the employer.  In natural language, we talk about employees, old employees or former employees.
	Employment	An Employment or Employment relationship defines the official relation between the employee and the employer. The employment can be based on multiple contracts as long it describes one continuous period of which the employee was employed to the same employer.
Sickleave endpoint	Sickness leave	A sickness leave describes an uninterrupted period of absence because of sickness. Within this period an Employee can be partially recovered, but the sick leave will ends when the Employee is fully recovered.
Maternity Leaves endpoint	Maternity leave	The maternity leave period that the employee is absent because of maternity leave. Sickness related to the pregnancy before or after the Maternity leave is not part of the Maternity leave itself but are separate sickness leave.
Company endpoint	Company	The (legal) company as know by the core system Note: not all Core systems support the legal company, but only the Payroll company. There could be some payroll reasons to split a legal company into 2 different Payroll companies. For instance, if the legal company supports more than one payroll period (e.g. Month + 4 weeks). In that case, the official legal company does not exist.
OrgUnits endpoint	Organizational Unit	The organization structure describes the organization in terms of Business unit, department, teams, etc. and how there are related to each other. Based on the organization structure it's clear how the organization is structured and "which" department is responsible for "what"
RoleAssignments endpoint	Role Assignment	The role assignment describes "who" is responsible for "which role"  for "which period" for the organization unit. For instance "who is the manager" or "who is the financial controller", etc.
JobProfiles endpoint	JobProfiles	All job profiles of the organization.
	User	The user account of a single employee

Based on the HR domain model we’ve defined the following endpoints :

• Endpoint GET /employees (current versions) 

• Endpoint GET /contracts (all versions) 

• Endpoint GET /persons (all versions) 

• Endpoint GET /organizationUnits (all versions) 

• Endpoint GET /sickleaves (all versions) 

• Endpoint GET /maternityleaves (all versions) 

• Endpoint GET /jobprofiles (all versions) 

• Endpoint GET /roleassignments (all versions) 

How to ‘match’ entities?

As a user, you are able to ‘match’ corresponding datasets, based on entity-specific unique identifiers. These specific keys per entity are unique and do not change during time.