Mijn Communities
Help

IAM API - Domain model and concepts

30-01-2022 09:37 (Bijgewerkt op 23-05-2025)
  • 0 Antwoorden
  • 0 kudos
  • 1595 Weergaven

 

IAM API

This API is intended for identity & access management systems and enabling the provisioning of users in other systems like Active Directory or IDP’s:

  • Retrieve employee data from HR Core Business

  • Retrieve organizational structures from HR Core Business

  • Retrieve job profile information from HR Core Business

 

Model

RoelofPostmus_0-1748014805863.png

 


 

Pagination

The IAM API supports pagination with the help of a nextToken. With the help of the following properties: dateTime, validFrom and id a “bookmark“ is generated ensuring no records are “lost“ when skipping through pages. Below a breakdown of the nextToken url generated at the end of the response body.

 

RoelofPostmus_0-1643531623434.png

 

  1. Next page token - Token generated at the end of the resultset page

  2. Date timestamp - The date timestamp of the last record of the result set page

  3. validFrom - The validFrom of the last record of the result set page

  4. Id - Primary key of the last record of the result set page.

 

Person layer in HR Core Business

An additional requirement to use the Persons endpoint: the Person layer needs to be enabled in HR Core Business. 

 

Retention time of data

Retention time refers to the duration that data is stored and available in the API. In the context of GDPR legislation, it is important to define and enforce appropriate retention times to ensure personal data is not kept longer than necessary, aligning with principles of data minimization and privacy.

Retention time can be defined at the API level per customer, giving them control over how long their data is stored for the purpose of APIs.

To change the retention time you can create a support ticket. Please note that any changes to the retention time require a reload of the data to take effect.

Each night, the system automatically evaluates and cleans up data in the API system, based on predefined retention policies. The retention time is calculated using a specific reference dates for each endpoint. The table below outlines the reference dates used per entity to determine the applicable retention period.

 

Endpoint reference date
Companies validUntil
Employees dischargedate
Employments dischargedate
Jobprofiles validUntil
Organization Units validUntil
Persons If a person has no employment, the person is no longer available in the API
Role Assignments validUntil
Valuelists validUntil

 

Example 1: Organisation Units

Retention time = 30 days

Data: New name for org unit C003 from "HR Advice" to "HR Advice corporate" per 1st of May 2025.

{
            "id": "23590975",
            "shortName": "C003",
            "fullName": "HR Advice",
            "validFrom": "2020-01-01",
            "validUntil": "2025-04-30"
},
{
            "id": "23590975",
            "shortName": "C003",
            "fullName": "HR Advice corporate",
            "validFrom": "2025-05-01",
            "validUntil": "9999-12-31"
}

(for demonstration means, not all data of the endpoint is shown)

Retention policy, 30 days: The version (time slice) with "validFrom": "2020-01-01" to "validUntil": "2025-04-30" will be no longer available in the API on the 31st of May 2025. The 30 days of retention are passed.

 

Example 2: Employments

Retention time = 90 days

Data: no discharge date

{
            "id": "40259407",
            "personCode": "1014",
            "personId": "1014",
            "employeeCode": "1014",
            "validFrom": "2020-01-01",
            "validUntil": "9999-12-31",
            "dischargeDate": "",
            "company": "500"
}

(for demonstration means, not all data of the endpoint is shown)

No dischargedate is available, the employee is in service, employment will be available in the endpoint.

 

Example 3: Employments with dischargedate

Retention time = 90 days

Data: no discharge date

{
            "id": "40259407",
            "personCode": "1014",
            "personId": "1014",
            "employeeCode": "1014",
            "validFrom": "2020-01-01",
            "validUntil": "9999-12-31",
            "dischargeDate": "2025-06-30",
            "company": "500"
}

(for demonstration means, not all data of the endpoint is shown)

Retention policy, 90 days: The employment will be no longer available in the API on the 29th of September 2025. The 90 days of retention are passed at that time.