De afgelopen periode zijn de volgende verbeteringen in de API doorgevoerd.
Learning API
Nieuw endpoints Person & Employment ter vervanging van Employees endpoint Endpoints: Persons and Employments; Employees endpoint deprecated Het het huidige employee endpoint is een samengesteld endpoint dat zowel de persoons- als dienstverbandgegevens van medewerkers bevat. Afgelopen jaar is gebleken dat het combineren van deze data de complexiteit van het endpoint heeft verhoogd en de performance en stabiliteit achter blijft op de door ons gestelde eisen. We hebben dan ook besloten om het employee endpoint te splitsen in een endpoint met de persoonsgegevens en een endpoint met de dienstverbandgegevens.
Hiervoor hebben wij 2 nieuwe endpoints aan de learning API toegevoegd, te weten het endpoint Persons en het endpoint Employments. Beide endpoint bevatten alle gegevens uit het employees endpoint die horen tot de respectievelijk de persoon of het bijbehorende dienstverband. Het huidige Employee endpoint blijft voorlopig bestaan, echter het endpoint zal niet verder uitgebreid worden. Nieuwe velden of andere verbeteringen zullen enkel in de nieuwe endpoint voor Persons en Employments doorgevoerd worden.
Wij adviseren u om nieuwe koppelingen te baseren op de endpoints Persons en Employments en geen gebruik meer te maken van het Employee endpoint. Op termijn zal het huidige employee endpoint komen te vervallen.
IAM API
Person & Employment ter vervanging van Employees endpoint
Ook in de IAM api hebben wij naast het Employees endpoint een endpoint Persons en Employments beschikbaar. Deze Persons endpoint en Employments endpoint bevatten alle velden die ook in het employees endpoint voor respectievelijk persoon en dienstverband zitten.
Het huidige Employee endpoint blijft voorlopig bestaan, echter het endpoint zal niet verder uitgebreid worden. Nieuwe velden of andere verbeteringen zullen enkel in het endpoint voor Persons en Employments doorgevoerd worden. Wij adviseren u om nieuwe koppelingen te baseren op de endpoints Persons en Employments en geen gebruik meer te maken van het Employees endpoint. Op termijn zal het huidige employees endpoint komen te vervallen.
autorisatie filters
De IAM api is uitgebreid met autorisatie mechanisme. Op basis van dit autorisatie mechanisme kan de API consultant bij Visma Raet een autorisatie filter inrichten. Dit autorisatie filter zorgt ervoor dat het externe systeem alleen die medewerkers in de API te zien krijgt die voldoen aan het filter. Zo kunt u bijvoorbeeld ervoor kiezen om alleen interne medewerkers op basis van het veld Soort Arbeidsrelatie in de IAM api te laten opnemen. De consultant kan deze een autorisatie filter inrichten op basis van de volgende velden:
P01103 CEA-nummer / Payroll Client Code
P01104 Instelling nummer / Payroll Institution Code
P01102 Soort arbeidsrelatie / Employment type
P01110 Code doelgroep / Classification
P05041 Learning API
Raadpleeg uw customer succes manager als u in contact wilt komen met de API consultant voor het inrichten van deze filters.
Learning API verbeterd
Afgelopen maand is de learning API verbeterd. Hieronder wordt een overzicht gegeven van de belangrijkste verbeteringen:
Performance & stabiliteit
alle endpoints
In het verleden kon het nog wel eens voorkomen dat de API geen response gaf waardoor er time-outs ontstonden. De afgelopen maand is de architectuur van de API gewijzigd waardoor de performance van de API is verbeterd en de kans op time-outs is geminimaliseerd.
Loonverdelingsregels als endpoint toegevoegd Endpoint: costAllocations
Aan de learning API is een nieuwe endpoint met de Cost Allocation toegevoegd. Dit endpoint komt overeen met de entiteit Loonverdeling uit Beaufort. Met behulp van het endpoint kan per medewerker de kostenplaats, kostensoort en eventueel kostendrager uit Beaufort gehaald worden.
Adresgegevens uitgebreid
Endpoint : Employees
Bij de adresgegevens naast de landcode ook de naam van het land getoond. Dit betreft de naam zoals ook wordt weergegeven in Beaufort zelf.
Naam van onder andere organisatie eenheid, functie en classificatie als extra veld toegevoegd
Endpoint Employees
In de endpoints Employee wordt bij de dienstverband gegevens naast een code voor functie, classificatie, organisatie eenheid, ect ook de naam getoond. Hierdoor wordt het eenvoudiger om vanuit één endpoint de naam in het IAM systeem op te nemen. Voor organisatie eenheid is naast de naam ook nog een extra veld met de logisch code toegevoegd.
Meer records per page
[alle endpoints]
Door het verbeteren van de architecture is het ook mogelijk meer records in response weer te geven. Standaard wordt bij elke endpoint maximaal 100 records terug gegeven. Mocht de tabel meer records bevatten dat wordt middels een NextLink de volgende data set aangeboden.
Vanaf deze release is het echter ook mogelijk meer dan 100 records in één pagina op te vragen. Dit kan middels de parameter take toe te voegen aan de url.
Hieronder een voorbeeld waarbij 125 records per pagina wordt opgehaald.
GET https://api.youforce.com/learning/v1.0/employees?take=125
In de nextLink wordt deze page size overgenomen, zodat ook de vervolg pagina's maximaal 125 records bevat.
U kunt een page size tot maximaal 1000 records opvragen.
IAM API verbeterd
Afgelopen maand is de IAM api verbeterd. Hieronder wordt een overzicht van de belangrijkste verbeteringen.
Performance & stabiliteit
alle endpoints
In het verleden kon het nog wel eens voorkomen dat de API veel tijd nodig had om de response te genererende API waardoor er soms time-outs konden ontstaan. De afgelopen maand is de architectuur van de API gewijzigd waardoor de performance API is verbeterd en minder kans op time-outs ontstaat.
Adresgegevens uitgebreid
Person en Employee endpoint
Bij de adresgegevens naast de landcode ook de naam van het land getoond. Dit betreft de naam zoals ook wordt weergegeven in Beaufort zelf.
Naam van onder andere organisatie eenheid, functie en classificatie als extra veld toegevoegd
Employee en Employment endpoint
In de endpoints Employee en Employment wordt bij de dienstverband gegevens naast een code voor functie, clasificatie, organizatie eenheid, ect ook de naam getoond. Hierdoor wordt het eenvoudiger om vanuit één endpoint de naam in het IAM systeem op te nemen. Voor organisatie eenheid is naast de naam ook nog een extra veld met de logisch code toegevoegd.
Veld Youforce Account toegevoegd
[Person en Employee endpoint]
In de endpoints Person en Employee is een nieuw veld YouforceAccount toegevoegd. Dit betreft de rubriek P15013 Youforce gebruiker uit Beaufort. Met dit veld aangegeven voor de betreffende persoon een Youforce account is aangemaakt. Alleen voor personen waarvoor een Youforce account is aangemaakt, kan het User endpoint gebruikt worden om de Identity terug te schrijven. Bij medewerkers zonder Youforce account zal het User endpoint een foutmelding geven.
Note: Om van dit veld gebruik te kunnen maken, dient u wel over te zijn op de nieuwe werkwijze in Beaufort. Meer hierover kunt u lezen in de Beaufort release 2022-02
Consistentie tussen endpoints Person, Employments en Employee verbeterd
[Endpoints Employee , Person en Employment]
Het endpoint Employee is een gecombineerd van de endpoints Person & Employment. Functioneel betreft het echter dezelfde entiteiten uit Beaufort. Het bleek echter dat in beide endpoints (Person/Employment versus Employee) niet dezelfde velden zichtbaar waren. Daardoor moest soms het employee endpoint gecombineerd worden met het Employment endpoint, terwijl beiden eigenlijk vergelijkbaar zijn.
Vanaf nu bevatten de endpoints Person & Employment dezelfde velden als het endpoint Employee en visa versa. Enige verschil tussen deze endpoints is dat bij het Employee endpoint de data gecombineerd is en bij het Person en Employment de data per entiteit gescheiden is.
Ook is het gedrag van beide endpoints vergelijkbaar. Bij de inrichting van de API wordt een bewaartermijn vastgelegd. Deze bewaartermijn bepaald hoe lang dienstverbanden nog zichtbaar zijn in de API als deze dienstverbanden uitdienst zijn. Bij de default inrichting van de API wordt deze bewaartermijn op 90 dagen ingesteld. Dat wil zeggen dat alleen de dienstverbanden worden getoond waarvoor de datum uitdienst jonger is dat de systeem datum [minus] 90 dagen. Als de datum uitdienst ouder is dan deze 90 dagen dan wordt het dienstverband niet getoond. Zowel niet in het Employment endpoint als ook niet in het Employee endpoint.
Als op basis van deze regel er geen enkele dienstverband bij een persoon is vastgelegd dan wordt ook het bijbehorende persoon record niet getoond of verwijderd beschouwd. Bij verwijderen wordt enkel het ID van de persoon getoond met een attribute IsActive = False.
Meer records per page
[alle endpoints]
Door het verbeteren van de architecture is het ook mogelijk meer records in response op te nemen. Standaard wordt bij elke endpoint maximaal 100 records terug gegeven. Mocht de tabel meer records bevatten dat wordt middels een NextLink de volgende data set aangeboden.
Vanaf deze release is het echter ook mogelijk meer dan 100 records in één paging op te vragen. Dit kan middels de parameter take toe te voegen aan de url.
Hieronder een voorbeeld waarbij 125 records per pagina wordt opgehaald.
GET https://api.youforce.com//iam/v1.0/persons?take=125
In de nextLink wordt deze page size overgenomen, zodat ook de vervolg pagina's maximaal 125 records bevat.
U kunt een page size tot maximaal 1000 records opvragen.
Improvements
Learning API: New endpoints for uploading other type of documents
We have added new endpoints for the following document types:
certificate / Certificaat
diploma / Diploma
career agreement / Loopbaan afspraak
career mail / Correspondentie loopbaan
career other / Overige loonbaan documenten
appraisal Review / Beoordelingsgesprek
performance Review / Functioneringsgesprek
To use these endpoints, the document type needs to be activated in the personal file system (authorisation & configuration Personal file system). All these endpoint are available as version 1.1.
See here for more information
Solved issues
SIVI API : Postal code in uppercase and without spaces
In HR Core Beaufort it is possible to store the postal code in different formats. For instance with spaces (1234 AB) or in lower case (1234 ab). The Sivi standard requires a fixed format without spaces and in uppercase (1234AB). Note: The API will not change the postal code if it's invalid or doesn't exists.
The issue is solved