Releases Youforce API & bestandsuitwisseling

  Nieuwe functionaliteit en verbeteringen Veld effectiveDate toegevoegd aan adresgegevens (Alle API's) In het endpoint Person is bij de adresgegeven het veld effectiveDate toegevoegd. Dit veld komt overeen met het veld 'Adres m.i.v.'  uit het Beaufort scherm Additionele adresgegevens Persoon (rubriek P011012 / P01011) . Het veld is beschikbaar in alle API met een endpoint Person.     

In de afgelopen weken hebben we hard gewerkt aan nieuwe updates en verbeteringen van de Bestandsuitwisseling module. Hier volgt een overzicht van de belangrijkste nieuwe features en wijzigingen:   File Type Autorisaties  De autorisatie van file types is verplaatst van organisatieniveau naar gebruikersniveau. Dit betekent dat Product Development nu op gebruikersniveau autorisatie tot specifieke file types kan verlenen. Bestaande Bestandsuitwisseling gebruikers zijn geautoriseerd voor alle file types waar voorheen hun organisatie voor was geautoriseerd. Autorisaties voor nieuwe gebruikers of extra autorisaties voor bestaande gebruikers moeten worden aangevraagd via 4me.   Toegang Autorisatie voor HR Core Online gebruikers HR Core Online gebruikers blijven Policy Management gebruiken om toegang tot de Bestandsuitwisseling module te verlenen. Omdat er nu gebruik wordt gemaakt van gebruikersniveau autorisatie, zijn de toe te kennen rechten in Policy Management versimpeld. Het enige verplichte recht nodig voor toegang tot de applicatie is “Toegang tot Bestandsuitwisseling”.   Toegang Autorisatie voor Niet HR Core Online gebruikers Niet HR Core Online gebruikers zullen geen gebruik maken van Policy Management om toegang te verlenen tot de Bestandsuitwisseling module. Voor nu zal de toegang in de Bestandsuitwisseling module zelf worden geregeld door Product Development, en wel op hetzelfde moment als de gebruikers autorisatie voor de verschillende file types. In de toekomst zal deze functionaliteit terug te vinden zijn in Toegangsbeheer.   Hernoemd De naam van de module is gewijzigd van Visma Files naar File Exchange. Op dit moment wordt nog alleen de Engelse taal ondersteund. In de nabije toekomst zal de Nederlandse taal worden ondersteund en zal de module de naam Bestandsuitwisseling voeren.

De afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:     Learning API Big nummer toegevoegd aan het endpoint employment De Beaufort rubriek P09165 Big nummer is als veld toegevoegd aan het endpoint employment in de learning API. Dit veld kan door learning systemen gebruikt worden om het BIG register van de medewerker bij te werken.   WFM API Concept versie beschikbaar De afgelopen periode is de eerste versie van de workforce management API op de Visma developer portal gepubliceerd.  De WFM API is bedoeld voor het integreren van planning- & tijdregistratie systemen met HR Core Beaufort.  Deze eerste versie bevat enkel lees (GET) endpoints waarmee veel gebruikte data uit HR Core in het WFM systeem ingelezen kan worden.   De WFM api is op dit moment als concept versie beschikbaar. De komende maanden wordt de API ter validatie aan verschillende WFM partijen voorgelegd. Ook kunnen WFM partijen starten met het analyseren en bouwen van nieuwe integraties op basis van deze API. De API bevat diverse endpoint voor het ophalen van de medewerker en organisatie data. Ook kan de API met de Extensie API gecombineerd worden.  Zie ook Eigen rubrieken met de Extension API    Onderstaand domein model geeft een overzicht van entiteiten en endpoint die beschikbaar zijn binnen deze API.    Note: Op dit moment wordt voor de dienstverbandgegevens en salarisgegevens enkel nog de actuele gegevens uit Beaufort gebruikt.  In een volgende versie zal ook de ingangsdatum uit de historie in de API betrokken worden.  

De afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:     WFM API Nieuwe endpoints voor Employments en Salary Details beschikbaar De WFM API is uitgebreid met 2 nieuwe endpoints voor Employments en Salary Details. Beide endpoint zijn gebaseerd op de historie tabel van Beaufort waardoor de endpoints de ingangsdatum bevat.  De nieuwe endpoints zijn: employmentTimelines salaryDetailTimelines Het endpoint employmentTimelines bevat dezelfde velden als het oorspronkelijk endpoint employments maar dus nu ook inclusief ingangsdatum waardoor er een soort tijdlijn ontstaat. Hetzelfde geldt voor de endpoints salaryDetailTimelines en salaryDetails. Voor zowel het endpoint employmentTimelines als ook het endpoint SalaryDetailTimelines geldt dat data met ingangsdatum uit de historie tabel komen. In de standaard inrichting van Beaufort staat voor deze rubrieken de historie aan (zie Beaufort scherm standaard rubrieken). Onderstaand een voorbeeld van het nieuwe endpoint employmentTimelines   Op dit moment wordt de API data voor deze nieuwe endpoints één keer per dag om 18:00 UTC met Beaufort gesynchroniseerd.     Alle domein API's Het endpoint organisation units is uitgebreid met de velden indicatie geblokkeerd, kostenplaats en adresgegevens. Het endpoint organisation units van zowel de Learning, IAM als ook de WFM api is uitgebreid met de volgende API velden: isBlocked (True/false) Address  PhoneNumber CostCenterCode Deze velden komen overeen met de volgende gegevens uit Beaufort.   Note: het veld isBlocked (Inactief) wordt in Beaufort vaak gebruikt om organisatie eenheden inactief te maken tijdens een reorganisatie. Deze indicatie wordt dan gebruikt om aan te geven dat er geen nieuwe medewerkers meer op de organisatie eenheid mogen worden geplaatst. Echter bij een reorganisatie komt het regelmatig voor dat bestaande medewerkers nog herplaatst moeten worden. De indicatie IsBlocked wil dus niet zeggen dat er geen medewerkers meer aan gekoppeld zijn.     Visma Developer Portal Vanaf nu zijn alle domein API inclusief alle endpoints te gebruiken via de Visma Developer portal.  De Visma Developer Portal (https://oauth.developers.visma.com/) vervangt hiermee de oudere developer portal als de Youforce developer portal (https://developers.youforce.com/) of Raet developer portal (https://developers.raet.com/)   note:  De meest recente aanpassing betreft het endpoint Get users. Vanaf nu werkt ook dit GET users endpoint in de learning en IAM api met een Visma account uit de Visma developer portal. Heeft u nog credentials op één van de oude developer Portal dan kunt u die nog blijven gebruiken. Echter nieuwe credentials kunnen alleen nog aangemaakt worden via de Visma Developer Portal. Zie hiervoor: Aanmaken credentials Visma Developer Portal   Ook adviseren wij u om met uw applicatie over te gaan naar de nieuwe Visma Developer portal. De Visma developer portal heeft als voordeel dat u en u collega samen de apps en credentials kunt beheren.  Wel zijn daarbij enkele aandachtspunten waarmee uw development omgeving rekening moet houden, zie onderstaande tabel.    Oude Raet developer portal Oude Youforce Developer Portal Nieuwe Visma developer Portal Authencation token url:   https://api.raet.com/authentication /token  Met in de Body de volgende authenticatie gegevens uit de Raet developer portal: client_id client_secret  url:   https://api.youforce.com/authentication /token   Met in de Body de volgende authenticatie gegevens uit de Youforce developer portal: client_id client_secret  url:   https://connect.visma.com /connect/token   Met in de Body de volgende authenticatie gegevens uit de Visma developer portal: client_id client_secret  tenant_id Let op: De tenant_id is dus toegevoegd aan de authencation en wordt tussen de endpoint meegegeven in de bearer token. GET User endpoint niet beschikbaar In learning API is het endpoint beschikbaar via verschillende url versie zoals v0.1 en v.1.0 GET https://api.youforce.com//learning/v0.1/ users (employeeId=xxxx) GET https://api.youforce.com//learning/v1.0/ users (employeeId=xxxx) In de Learning en IAM is het endpoint enkel beschikbaar via de url versie v1.0 GET https://api.youforce.com//learning/v1.0/ users(employeeId=10010) All endpoints base url: api.raet.com met de volgende gegevens in de header bearer authorisation token uit het raet.com authorisation token Tenant_id. Dit is een 7-cijferig nummer dat de klant binnen Raet identificeert base url: api.youforce.com met de volgende gegevens in de header bearer authorisation token uit het youforce.com authorisation token Tenant_id. Dit is een 7-cijferig nummer dat de klant binnen Raet identificeert base url: api.youforce.com met de volgende gegevens in de header bearer authorisation token uit het visma.com authorisation token. In dit visma token zit de tenant_id al verwerkt Note: Het tenant_id hoeft dus niet meer bij elke API call meegegeven worden.  Wordt de tenant_id per ongeluk wel meegegeven in de API call dan wordt deze genegeerd  Daarnaast blijven de endpoints via de base url api.youforce.com       

De afgelopen periode zijn er weer een aantal verbeteringen in de API's doorgevoerd.   API's nu ook beschikbaar via Visma developer portal De Visma developer portal is binnen de Visma groep de centrale plaats voor delen en publiceren van API's uit de Visma groep voor derden.  Om hierbij aan te sluiten hebben we de afgelopen periode de IAM en Learning API op de Visma developer portal gepubliceerd.  De IAM en Learning API is ook nog beschikbaar via de oude Raet developer portal waardoor bestaande integraties niet zullen wijzigen. Voor nieuwe integraties zal er door de API consultant veelal voor gekozen worden om deze via de nieuwe Visma developer Portal te ontsluiten.  Ook nieuwe API zullen in de toekomst enkel nog via deze nieuwe Portal gepubliceerd worden.   Onze API consultants zullen developers en klanten tijdens de implementatie hierbij begeleiden.   Een uitgebreide beschrijving voor het aanmaken van een account staat beschreven op de deze pagina. Wij adviseren uit echter om vooraf eerst contact op te nemen met onze API consultant (api.consulting.raet@visma.com). Zij kunnen aanvullende uitleg geven over het gebruik van de Visma Developer portal.      Extension API toegevoegd aan Visma developer portal In de nieuwe Visma Developer portal is de Extensie API  als uitbreiding op een domein API, zoals zoals de IAM of Learning API, beschikbaar gekomen. Met deze extensie API is het mogelijk om extra velden aan de domein API toe te voegen. Bijvoorbeeld het toevoegen van een klant eigen rubriek behorende bij de persoon of het dienstverband. De extensie API dient altijd in combinatie met één van de domein API gebruikt te worden. Tevens kunnen enkel niet-ingedeelde rubrieken op het niveau Persoon of Dienstverband aan de API toegevoegd worden. Het toevoegen van extra velden kan op dit moment geregeld worden door een API consultant.  Uiteraard geldt wel dat het ontvangende systeem ook met extra velden en endpoints overweg moet kunnen gaan. Een uitgebreide beschrijving is te vinden op deze pagina   De extensies kunnen per per klant en domain API verschillend. Voor respectievelijk de IAM en learning API hebben wij de volgende endpoints beschikbaar. api.youforce.com/extensions/v1.0/IAM/persons  api.youforce.com/extensions/v1.0/IAM/employments  api.youforce.com/extensions/v1.0/learning/persons  api.youforce.com/extensions/v1.0/learning/employments   Afhankelijk van de gekozen endpoint worden de extensies op persoons- of dienstverband niveau weergegeven.  Indien de rubriek in Beaufort bestaat uit veld met een referentie tabel dan wordt ook de bijbehorende omschrijving uit de referentietabel in het endpoint weergegeven. Zie onderstaand voorbeeld bij rubriek API002.  

{English below} Nieuw IAM API: Nieuw endpoint voor lezen cost allocation (Loonverdelingsregels) De IAM API is uitgebreid met een nieuw endpoint voor het ophalen of lezen van de loonverdelingsregels van een medewerker uit Beaufort. De Loonverdelingsregels van Beaufort bevatten onder andere de kostenplaats(en) waarop de medewerker werkzaam is.  Het endpoint bevat de volgende gegevens Persoonsnummer van de medewerker Dienstverband volgnummer van de medewerker Volgnummer loonverdelingsregel Kostenplaats Kostensoort Kostendrager Percentage van de loonverdeling De loonverdeling betreft altijd de actuele situatie zoals die is vastgelegd in het scherm "Loonverdeling" in Beaufort.   De loonverdelingsregels kunnen opgevraagd worden via het endpoint:   https://api.youforce.com/iam/v1.0/CostAllocations De API kan met verschillende parameters gebruikt worden   Full list GET https://api.youforce.com/iam/v1.0/CostAllocations   By ID GET https://api.youforce.com/iam/v1.0/CostAllocations/35001%201%201   Filter by Person Code GET https://api.youforce.com/iam/v1.0/CostAllocations?personCode=35001     [english] New IAM API: New endpoint for cost allocation (Beaufort Loonverdeldingsregels) The IAM API has been expanded with a new endpoint for cost allocation. With this new endpoint IAM systems can get the cost allocation records of an employee from Beaufort.  The cost center is one of the attributes of this new endpoint.    The cost allocation entity concerns always the current situation as it is recorded in Beaufort with the screen "Loonverdeling".   You can access the enpoint with the url:   https://api.youforce.com/iam/v1.0/CostAllocations You can use the endpoint with the following parameters   Full list   GET https://api.youforce.com/iam/v1.0/CostAllocations     By ID   GET https://api.youforce.com/iam/v1.0/CostAllocations/35001%201%201     Filter by Person Code   GET https://api.youforce.com/iam/v1.0/CostAllocations?personCode=35001    

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

In this update you can find the improvements and solved issues in the domain api's.  Improvements IAM API: New fields are added to the employment endpoint The following fields are added to the employment endpoint. PayrollClientCode           ( P01103 Opdrachtgever) PayrollInsittutionCode   ( P01104 Instelling) Classification                   ( P01110 - Code doelgroep) Learning API: User endpoint added to version 1.0 The user endpoint is added to version 1.0 of the learning API. This endpoint will return the unique ID of the user which can be used for the SSO process of a customer.   For example: GET https://api.youforce.com/learning/v1.0/users(employeeId=10010) By adding this endpoint version 1.0 of the learning API is  backwards compatible with version 0.1.  Action API Consumer: We ask you to change the url of you api call to this new version. Version 0.1 is deprecated from now.    Solved issues Learning API : Texts with special chars were not displayed correctly [VRINA-1613]  Special characters for the fields 'FirstNames' or 'KnownAs' were not correctly processed in the API database. As result to API shows the name incorrectly. For example: -> "KnownAs": "Desirée" was showed as: -> "KnownAs": "Desir?e"   The issue is solved.