Releases Youforce API & bestandsuitwisseling

Bij het inrichten van een nieuwe connectie voor een bepaald systeem, wordt vaak in overleg met de consultant een autorisatie filter voor de connectie geconfigureerd. Dit autorisatie filter zorgt ervoor dat alleen relevante medewerkers in de connectie worden opgenomen. Dit maakt het mogelijk om in een MLM-systeem uitsluitend de eigen medewerkers te betrekken. Echter dit autorisatie filter werd niet toegepast op het endpoint voor RoleAssignment. Daardoor waren voor een extern systeem alle rollen en personeelsnummers toegankelijk. Hoewel dit alleen de personeelsnummers betrof, waren dit desondanks records die door een extern systeem zouden moeten worden uitgefilterd. Om het integratieproces te stroomlijnen, wordt nu ook het autorisatie filter toegepast op het RoleAssignment endpoint.

De recruitment API is uitgebreid met aantal nieuwe endpoints voor het aannemen kandidaat uit een recruitment systeem. Vanuit het proces worden de volgende situaties ondersteund:   Aannemen nieuwe medewerker van een nog onbekende persoon, waarbij zowel een nieuw persoon als dienstverband wordt aangemaakt.  De zogenaamde new hire. Aannemen van een medewerker die eerder indienst is geweest, waarbij de persoonsgegevens geactualiseerd kunnen worden en er een nieuwe contract aangemaakt kan worden. De zogenaamde new contract. Aannemen van een interne medewerker waarbij de medewerker via een interne sollicatie is aangenomen en het bestaande contract wordt aangepast. De zogenaamde contract adjustment.   In de API wordt voor een aangenomen medewerker een workflow in HR Self Service gestart. Afhankelijk van bovenstaande situatie kunnen dat andere workflows zijn. Ook is het mogelijk om bij het aannemen van de kandidaat attachements mee te geven.   API & Connector De integratie tussen Youforce en het recruitment systeem is een complex proces waarbij interactie tussen het Recruitment systeem en de recruitment API vereist is. In onderstaand schema worden deze interactie tussen beide systemen weergegeven.   Belangrijk om te vermelden is dat de recruitment API enkel een single tenant omgeving ondersteunt. Dat wil zeggen dat het niet mogelijk is de recruitment API te gebruiken als je in Beaufort en HR Self Service meerdere klanten in één database heb samengevoegd.    Endpoint search Person Hiervoor biedt de API een endpoint waarmee het recruitment systeem kan zoeken of de betreffende kandidaat als persoon bestaat in het HR Core systeem. Velden waarop gezocht kan worden zijn: knownAs lastNameAtBirth lastNameAtBirthPrefix birthDate birthPlace Het endpoint is:   GET https://api.youforce.com/recruitment/v1.0/persons/search Note: Het endpoint is bedoeld om te bepalen of de persoon al in het Core systeem bestaat en daarbij het persoonsnummer op te halen. Dit betekent dat er altijd één of meerdere zoekcriteria opgegeven moeten worden. Bij meer dan 10 resultaten wordt er een foutmelding gegeven en wordt verzocht de zoekcriteria meer specifiek te maken. Het endpoint zoekt altijd over de hele populatie van de klant. Dus ook oud-medewerkers en eventuele andere personen die de klant in zijn core systeem heeft opgenomen   De endpoints new hire, new contract  en contract change Op basis van het feit of het om een nieuwe of een bestaand persoon gaat wordt het endpoint voor een nieuwe hire of een nieuw contract opgestart.   Het endpoint voor de hire is: POST https://api.youforce.com/recruitment/v1.0/hires   Het endpoint voor een re-hire is: POST https://api.youforce.com/recruitment/v1.0/persons/xxxx/contracts  waarin xxxx het persoonsnummer van de bestaande medewerker is.   Het endpoint voor een change contract: POST https://api.youforce.com/recruitment/v1.0/persons/xxxx/contracts/yyy/Adjustments  waarin xxxx het persoonsnummer van de bestaande medewerker is en yyy het dienstverband volgnummer.   De endpoints werken asynchroon. Dat wil zeggen dat een POST eerst intern in de API wordt weggeschreven en op de achtergrond een workflow start. De POST call geeft dan ook enkel een ID teruggeeft. Dit ID kan gebruikt worden om via een status endpoint, de status van de API call en de workflow informatie op te vragen.   De endpoints die gebruikt kunnen worden om de status op te vragen zijn: GET https://api.youforce.com/recruitment/v1.0/hires/zzzz-zzzzz-zzzz/status waarin zzzz-zzzzz-zzzz het ID van de API call is   GET https://api.youforce.com/recruitment/v1.0/persons/xxxx/contracts/zzzz-zzzzz-zzzz/status waarin xxx de persoonscode is en zzzz-zzzzz-zzzz het ID van de API call is     Te starten workflow Default workflow: Indien in de header van de API call geen workflow wordt meegegeven, dan wordt de workflow gestart zoals die bij de configuratie door de API consultant is ingericht. Specifiek workflow: Bij de API call kan ook een workflow meegegeven worden. Bijvoorbeeld om onderscheid te maken tussen een Nieuwe verloonde medewerker of een Inhuurkracht (PNIL).   De header X-Raet-Workflow stuurt welke workflow wordt gestart.      De medewerker gegevens Voor zowel de hire en re-hire wordt de medewerker data in de body meegegeven. Bij een hire worden de persoonsgegevens gebruikt om een nieuwe persoon te creëren. Bij de Re-hire worden de persoonsgegevens gebruikt om bestaande gegevens bij te werken. Bijvoorbeeld als de medewerker sinds zijn laatste uitdiensttreding is verhuisd.   De API werkt met een standaard mapping tussen de API en de Beaufort rubrieken. Eventueel kan de API consultants afwijkende mapping voor specifieke rubrieken vastleggen. Bijvoorbeeld als u een eigen rubriek gebruikt voor het vastleggen van de soort arbeidsrelatie.    Eigen rubrieken Naast dat de consultant de mapping van de velden kan aanpassen, is het ook mogelijk om extra rubrieken in de API mee te geven.  Hiervoor dient u wel de rubrieksnummers uit HR Self Service te gebruiken en dient het een PS of DV rubriek te zijn. De extra rubrieken kunnen in de body meegegeven worden als customFields. "customFields": [ {"fieldCode": "B12071", "fieldValue": "BE56363123456788"}, {"fieldCode": "B12081", "fieldValue": "BBRUBEBB"} ]    Attachements Bij zowel de hire, re-hire en contract changes endpoint kan naast de medewerker data ook één of meerdere attachements toegevoegd worden.  Hierbij geldt wel de volgende restricties: Maximaal 20 attachments per kandidaat Maximale file size is 4 mb per bestand Maximale bericht omvang (data + bestanden) is 28 mb De volgende bestandstypen worden ondersteund: Simpele tekst bestanden zonder opmaak (text/plain) Pdf documenten (application/pdf) MS Word documenten DOCX formaat (vanaf 2007) (application/vnd.openxmlformats-officedocument.wordprocessingml. document) MS Word documenten (pre-2007) (application/msword) Open document formaat bijvoorbeeld van OpenOffice en LibreOffice (application/vnd.oasis.opendocument.text) Diverse soorten images (image/*) Voor het toevoegen van de attachements kan een sectie files aan de API call toegevoegd worden met de volgende informatie: Name : De file name (maximaal 150 tekens lang). Category(optional) : De label of category indien dit in HRSS in geconfigureerd. contentBase64 : Het bestand in Base64 formaat   "files": [ {"name": "Application letter.txt", "category": "Demo", "contentBase64": "VGhpcyBpcyBhIHRlc3Q=" }, {"name": "curriculum vitae.txt", "category": "Demo", "contentBase64": "VGhpcyBpcyBhIHRlc3Q=" } ]   Verdere informatie Meer technische informatie is te vinden op Youforce API Documentation. Daar vindt u de swagger documentatie en een link naar een postman collectie met voorbeeld.        

Het endpoint Job profiel is uitgebreid met de volgende velden: De velden zijn beschikbaar in alle API met het endpoint Job Profile. De data van de velden is afkomstig van het scherm Functie uit Beaufort.  

De recruitment API is uitgebreid met een nieuw endpoint employmentTypes. Dit endpoint komt overeen met de referentie tabel Soort Arbeidsrelatie uit Beaufort.   GET https://api.youforce.com/recruitment/v1.0/employmentTypes   Onderstaand een voorbeeld van de API en het bijbehorende HR Core Beaufort scherm.         

Het endpoint JobProfile is uitgebreid met de volgende velden:   type costUnit costType  Deze velden komen overeen met de HR Core Beaufort velden functie type, kostendrager en kostensoort.       Deze velden zijn beschikbaar in alle API's waar het endpoint jobProfile beschikbaar is.

Het endpoint Assignment (inzet) is toegevoegd aan de learning & Recruitment API De url van het endpoint is respectievelijk: GET https://api.youforce.com/learning/v1.0/Assignments GET https://api.youforce.com/recruitment/v1.0/Assignments   Het endpoint laat de volgende gegevens zien: Deze gegevens zijn afkomstig van het scherm "inzet" uit Beaufort.        

De afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:       Het veld expectedRecoveryDate toegevoegd aan het endpoint Sickleaves (WFM api) Aan het endpoint sickleaves is een nieuw veld "expectedRecoveryDate" toegevoegd. Dit veld komt overeen met de Beaufort rubriek  "P01605 Datum verwacht herstel" en wordt gebruikt om bij een ziekte een verwachte herstel datum vast te leggen.    GET https://api.youforce.com/wfm/v1.0/sickleaves   Synchronisatie met HR Core voor de Extension API verbeterd De afgelopen periode is de integratie tussen HR Core Beaufort en de Extension API verbeterd. Daardoor wordt de data vaker gesynchroniseerd en zullen  wijzigingen in Beaufort ook eerder zichtbaar zijn in de extensie API.    Youforce Extensions uitgebreid met extra endpoints voor het MLM domain Vanaf nu is het ook mogelijk om de Youforce Extension API te gebruiken in combinatie met de MLM base API.  Zie hiervoor het algemeen gebruik van de extension API Eigen rubrieken met de Extensions API    De nieuwe endpoint hiervoor zijn: api.youforce.com/extensions/v1.0/mlm/persons      api.youforce.com/extensions/v1.0/mlm/employments     Eerste versie Recruitment API beschikbaar Er is een eerste versie van de recruitment API beschikbaar. Deze eerste versie bevat endpoint voor het ophalen van de organisatie structuur en de basis gegevens van de medewerkers. Met deze eerste versie is het mogelijk om uw huidige medewerkers in uw recruitment systeem op te nemen als mogelijk interne kandidaten.   Beschikbare endpoints zijn: GET Persons  GET Employments GET Users GET Organisation Units GET Role Assignments GET Job Profiles Meer informatie over de recruitment API is te vinden op:  Kennisbank Recruitment API 

    Mededelingen  Youforce Developer Portal gaat offline Begin juni wordt de Youforce Developer Portal (https://developers.youforce.com/) offline gehaald. Daarmee is het niet meer mogelijk om applicaties te aan te melden op de Youforce Developer portal. Nieuwe applicatie en credentials moeten vanaf nu via de Visma Developer Portal (https://developer.visma.com/) aangemaakt worden.    Voor klanten die nog credentials uit de oude Youforce Developer Protal in gebruik hebben, veranderd er op dit momenteel nog niets. De credentials blijven geldig en werken met de domein api's en file API. Wel wordt u verzocht om, in samenspraak met uw software leverancier, over te stappen op de Visma Developer Portal.    Meer informatie over de Visma Developer Portal vindt u op de community via onderstaande links: De nieuwe Visma Developer Portal Een API-applicatie overzetten naar de Visma Developer Portal   Nieuwe functionaliteit en verbeteringen De afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:   De velden kostenplaats, kostendrager, kostsoort en type toegevoegd aan het endpoint Assignment (WFM & IAM api)  Het endpoint Assignment in de WFM en IAM api is uitgebreid met de volgende velden: costCenter - P01128 - Kostenplaats Inzet costUnit - P01129 - Kostendrager Inzet costType - P01127 - Kostensoort Inzet type - P01123 - Soort Inzet     Extensions API uitgebreid met extra endpoints voor het Recruitment domain Vanaf nu is het ook mogelijk om de Youforce Extension API te gebruiken in combinatie met de Recruitment API.  Zie hiervoor het algemeen gebruik van de extension API Eigen rubrieken met de Extensions API    De nieuwe endpoint hiervoor zijn: api.youforce.com/extensions/v1.0/recruitment/persons      api.youforce.com/extensions/v1.0/recruitment/employments     Tips  Gebruik   api.youforce.com Op dit moment kunt u voor de domein API's zowel de url api.youforce.com als ook de url api.raet.com gebruiken. We adviseren u echter om zoveel mogelijk de url api.youforce.com te gaan gebruiken. De komende tijd blijven beide url's zeker nog actief maar de toekomst kan daar mogelijk verandering in komen. Om deze verandering voor te zijn, adviseren wij u de url api.youforce.com te gebruiken.  

  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.