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.
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
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.
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.
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.
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.
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 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.