Releases Youforce API & bestandsuitwisseling

We introduceren IP whitelisting voor onze Youforce Domain API's. Deze functie beperkt de toegang tot uw API tot specifieke IP-adressen of reeksen, wat verhoogde beveiliging biedt voor uw integraties met derden.   Interesse? Neem contact op met uw Youforce-consultant om deze functie te activeren.

Deze release notes zijn van technische aard en bedoeld voor File API ontwikkelaars die rechtstreeks met de File API integreren of de technische werking van de File API kennen. Deel deze release notes met jouw IT afdeling.   IP Whitelisting voor File API Applicaties Huidige Situatie  Momenteel ondersteunt de File API geen IP-whitelisting, dus jouw File API-verzoeken kunnen overal worden gedaan.   Nieuwe Situatie Vanaf heden, 22 oktober 2024, is de ondersteuning van IP whitelisting beschikbaar, dus als je dat wenst, kun je deze configuratie nu al aanvragen voor jouw File API applicatie en jouw publieke IP(s) om de veiligheid van File API verzoeken te vergroten.   Jouw Actie:  Maak een 4me-verzoek aan met de onderstaande informatie:   Jouw openbare IP-adressen in CIDR-indeling (bijvoorbeeld: 192.0.2.0/24) vanwaar met de File API wordt gecommuniceerd. Jouw ClientId dat wordt gebruikt om bij de File API te authenticeren.

Deze release notes zijn van technische aard en bedoeld voor File API ontwikkelaars die rechtstreeks met de File API integreren of de technische werking van de File API kennen. Deel deze release notes met jouw IT afdeling.   File API Healthcheck Endpoint Huidige Situatie   Een goede gewoonte bij het gebruik van API's is het controleren van hun status voordat ze daadwerkelijk worden aangeroepen. Momenteel is de enige manier om erachter te komen of de File API operationeel is, het aanroepen van een van de beschikbare eindpunten (bijvoorbeeld het List-eindpunt) en het controleren van het resultaat. Als het resultaat een fout is, moet uw uitwisselingsproces de fout afhandelen..   Een betere manier is om de status van de File API te controleren voordat u uw uitwisselingsproces start. Om dit te vergemakkelijken en verbeteren hebben we een nieuw “Health Check”-eindpunt geïntroduceerd dat kan worden aangeroepen voordat uw uitwisselingsproces begint. Nieuwe situatie   Vanaf heden, 22 oktober 2024, is het ‘Health Check’ eindpunt beschikbaar om de status van de File API te controleren.   Dit nieuwe eindpunt vertelt je of de File API volledig operationeel is of dat er sprake is van een storing. In geval van een storing kunt u uw uitwisselingsproces uitstellen tot een later tijdstip.   Het eindpunt kan op 3 verschillende manieren worden gebruikt:   Handmatig (bijv met Postman) om de beschikbaarheid op een willekeurig moment te kunnen controleren. Automatisch (als onderdeel van uw monitoringsysteem) om regelmatig de status van de File API te controleren. Automatisch (als onderdeel van uw uitwisselingsproces) vlak voordat uw geautomatiseerde uitwisselingsproces begint. In de toekomst zullen de resultaten van de health check ook in Youforce worden weergegeven, waardoor de handmatige verificatie veel sneller en intuïtief zal verlopen.   Response van het ‘Health Check’ eindpunt   Het eindpunt retourneert de algemene status van de File API en de status van elk individueel eindpunt.  De mogelijke waarden voor de algemene status van de File API zijn:   Operational: Wanneer de status van alle eindpunten “healthy” is. Major Outage: Wanneer de status van een van de meest gebruikte eindpunten ‘unhealthy’ is. De meest gebruikte eindpunten zijn:  Publisher UploadMultipart Subscriber Delivery Subscriber List Subscriber Download Partial Outage: Wanneer de status van de meest gebruikte eindpunten ‘healthy’ is, maar de status van een van de minder gebruikte eindpunten ’unhealthy’ is. De minder gebruikte eindpunten zijn: Publisher UploadResumable Publisher List Publisher Download Subscriber DownloadByChunks Subscriber Delete Jouw Actie  Als u het Health Check-eindpunt wilt gaan gebruiken om de status van de File API te controleren, volgt u de stappen zoals die worden uitgelegd in onze technische File API-documentatie.  Zie onderstaande technische links: File API documentation  File API Swagger  File API Postman Collection 

Gebruikersautorisaties door CEA-nummers voor Payroll Gemal Exports   Huidige situatie: Op dit moment hebben de gebruikers die geautoriseerd zijn voor het bestandstype "Payroll Gemal Exports" de mogelijkheid om de bestanden van alle CEA-nummers van de organisatie te ontvangen. Het is niet mogelijk om gebruikers te autoriseren om alleen bestanden van specifieke CEA-nummers te ontvangen. Vanaf 7 oktober 2024 komt in Bestandsuitwisseling nieuwe functionaliteit beschikbaar waarmee het toekennen van het ontvangen van specifieke CEA-nummers voor het bestandstype "Payroll Gemal Exports" mogelijk wordt gemaakt voor gebruikers.   Jouw actie: Werkt jouw organisatie niet met meerdere CEA-nummers, of mogen jullie gebruikers de informatie van alle CEA-nummers downloaden, dan hoef je niets te doen. Werkt jouw organisatie wel met meerdere ceanummers en wil je specifieke gebruikers autoriseren om alleen bestanden van bepaalde CEA-nummers te mogen downloaden, volg dan de onderstaande instructies om de autorisaties toe te kennen.   Gebruikers autoriseren voor specifieke CEA-nummers voor Payroll Gemal Exports: In Autorisatiebeheer komt per 7 oktober een nieuw recht beschikbaar: "Toegang tot Bestandsuitwisseling-instellingen" onder de applicatie "Bestandsuitwisseling".     Beheerders die voor dit nieuwe recht worden geautoriseerd, krijgen een nieuw tabblad genaamd "Instellingen" te zien in Bestandsuitwisseling.     In dit tabblad hebben beheerders de mogelijkheid om via het schuifje "Activeer autorisatie voor Payroll Gemal Export" de nieuwe functionaliteit te activeren. Deze optie is standaard uitgeschakeld omdat alle gebruikers op dit moment toegang hebben tot alle CEA-nummers van de organisatie.   Wanneer je het schuifje naar ‘Actief’ zet, voeg dan één voor één de gebruikers toe via de knop ‘Gebruiker Toevoegen’ en geef per gebruiker aan tot welk(e) CEA-nummer(s) zij toegang krijgen voor het bestandstype "Payroll Gemal Exports".   De gebruikers die op deze manier geautoriseerd worden, zullen in de “Ontvang bestanden" tab dan alleen de bestanden van dit bestandstype zien die gerelateerd zijn aan de opgegeven CEA-nummers.   Let op: de gebruikers die niet in de lijst staan, zullen geen enkel bestand van dit bestandstype in de “Ontvang bestanden" tab zien.          

In deze update hebben we het filter 'ValidOn' toegevoegd aan verschillende endpoints. Dit filter maakt het mogelijk om enkel de records te verkrijgen die op een bepaalde datum geldig zijn. Zo zullen bij het endpoint voor roltoewijzing (Role Assignment) zonder dit filter alle rollen, inclusief hun start- en einddatum, getoond worden - zelfs die met een toekomstige startdatum. Dankzij het nieuwe filter kan je nu alleen de roltoewijzingen ophalen die geldig zijn op een specifieke dag. Het filter is beschikbaar in de volgende endpoints: Employments/timelines SalaryDetails/timelines extensions/person/timelines extensions/employment/timelines Bijgevoegd is een voorbeeld van hoe het filter in een API-aanroep voor Roltoewijzing kan worden gebruikt:   https://api.youforce.com/iam/v1.0/RoleAssignments?organizationUnit=912&validOn=2024-09-12 Onderstaand vindt u de outputverschillen van een API-call met en zonder het gebruik van dit filter, waarbij u een duidelijk verschil zult zien in de resultaten.            

Met het veld Reden einde dienstverband (P01113) in Beaufort wordt aangegeven op welke grond het dienstverband is beëindigd. Afhankelijk van de reden is het soms wenselijk in een Learning systeem of in een IAM systeem anders te handelen. Om dit mogelijk te maken, is het veld Termination Reason toegevoegd aan het employment endpoint in zowel de Learning als de IAM API.    

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.        

De Youforce Suite is uitgebreid met een nieuwe API voor sociale werkbedrijven. Deze API is speciaal ontworpen om beter aan te sluiten bij systemen voor de uitvoering van de Participatiewet en de Wet Sociale werkvoorziening. De API biedt alle noodzakelijke informatie om Youforce effectief te gebruiken als het primaire HR-systeem voor de registratie van alle medewerkers, waarbij de API zorgt voor de integratie met een cliëntvolgsysteem dat voldoet aan de wettelijke eisen van de Participatiewet en de WSW. De kernfunctionaliteiten van deze API omvatten: Medewerker Data: Mogelijkheden voor het ophalen van gedetailleerde gegevens over medewerkers, wat essentieel is voor zowel het beheer van human resources als het volgen van cliënten binnen de wettelijke kaders. Organisatiestructuur & Roltoewijzing: Biedt endpoints die inzicht geven in de hiërarchie en structurele opbouw van een organisatie, samen met de koppeling van rollen aan specifieke medewerkers. Deze informatie is cruciaal voor het begrijpen van de verantwoordelijkheden binnen een organisatie, alsook voor het toewijzen van cliënten aan specifieke casemanagers of begeleiders. Werkpatronen & Afwezigheid: Functionaliteit voor het bijhouden van de werkschema's van medewerkers, evenals eventuele afwezigheid door ziekte of verlof. Deze aspecten zijn belangrijk voor rapportage in het kader van de wet- & regelgeving zoals vastgelegd in de Participatiewet en de WSW   Extensie API Tevens is het mogelijk om de API uit te breiden via een extensie API, waarmee aanvullende gegevens uitgewisseld kunnen worden. Dit biedt flexibiliteit en zorgt ervoor dat de API kan worden aangepast aan de specifieke behoeften van elke organisatie.   Autorisatie Wanneer de API wordt geactiveerd, wordt in samenspraak met een API-consultant bepaald welke endpoints beschikbaar komen op basis van scopes. Daarnaast kan een autorisatiefilter worden geconfigureerd om nauwkeurig te bepalen welke medewerkers in de API worden opgenomen.   Technische informatie Technische informatie, zoals swagger documentatie en een voorbeeld postman collectie is terug te vinden op de Youforce API Documentation   

De MLM API is uitgebreid met een nieuw endpoint Payroll Clients. Dit endpoint komt overeen met de referentie tabel Opdrachtgever uit HR Core Beaufort.   GET https://api.youforce.com/mlm/v1.0/payrollClients   Hieronder een voorbeeld van het endpoint en het bijbehorende HR Core Beaufort scherm.      

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 WFM api is uitgebreid met een nieuw endpoint voor het ophalen van het werkpatroon uit HR Core Beaufort. Dit endpoint komt overeen met het werkpatroon uit de verlofmodule van HR Core Beaufort.   De data uit het endpoint is afkomstig van het scherm werkpatroon werknemer:   Het endpoint   GET https://api.youforce.com/wfm/v1.0/workPatterns?personCode=100001    

Voor HR Core OnPremise en Payroll Only klanten is het vanaf 30/04/2024 mogelijk om met Bestandsuitwisseling Organisatie en Roltoewijzing bestanden in te zenden naar Youforce Gebruikersbeheer.   Hiervoor moet je nog wel in Autorisatiebeheer de juiste rechten toekennen. Bekijk hiervoor de instructies in dit kennisbank artikel.

Om het mogelijk te maken om de registratie van aan- en afwezigheid volledig in Beaufort te doen en het tijdregistraties systeem enkel te gebruiken voor de verantwoording van de (gewerkte) uren, is het werkrooster aan de WFM ap toegevoegd. Samen het de endpoints voor verlof en ziekte, is dit endpoint de basis voor een goede tijdregistratie.   De data voor dit nieuwe endpoint employment work schedule komt van het volgende scherm uit Beaufort:         Het endpoint  GET https://api.youforce.com/wfm/v1.0/employmentworkSchedules     Historie & toekomst beperkt beschikbaar. Het endpoint geeft het werkrooster tot maximaal 1 jaar in de toekomst weer. Indien u in Beaufort voor meer jaren vooruit het rooster heeft gegenereerd, dan worden alleen de records getoond die binnen binnen één jaar vanaf de systeem datum vallen.   Ook worden de oudere records op basis van de historical days setting terug gegeven. Dit is een setting die bij implementatie wordt bepaald. Standaard wordt uitgegaan van een 90 dagen historie. Deze periode kan in overleg met uw API consultant aangepast worden. Echter de bewaartermijn kan niet langer zijn dan 1 jaar.  Na één jaar worden automatisch alle oude record uit de API verwijderd.

Het endpoint Sickleave in HR Core Beaufort biedt nu uitgebreidere informatie over ziekteregistraties van medewerkers. Voorheen werd alleen de ingangsdatum van een ziekteperiode getoond. Vanaf deze update wordt ook de einddatum van het ziekteverlof weergegeven, rechtstreeks afkomstig uit HR Core Beaufort. Deze toevoeging maakt het sluiten van ziekteperiodes eenvoudiger en overzichtelijker.   GET https://api.youforce.com/wfm/v1.0/sickleaves    

Update 19-04-2024 Op vrijdag 19 april is het certificaat op onze server api.youforce.com vervangen. Het nieuwe certificaat is geldig tot 4 mei 2025 en vervangt het oude certificaat op de server.      Bericht van 15-04-2024 Wij willen u informeren dat het huidige certificaat voor de URL api.youforce.com op 23 april 2024 verloopt. Deze week zal dit certificaat worden vervangen door een nieuwe versie, waarbij de volgende fingerprint wordt toegepast: 2581422998C313AAFCA55D948ECCA393EF9E5197.   Indien u in uw IT-landschap een controle heeft ingesteld voor dit certificaat, willen wij u vriendelijk verzoeken om deze te updaten naar de nieuwe versie zodra deze beschikbaar is. Dit zorgt ervoor dat uw systemen correct blijven functioneren zonder onderbrekingen als gevolg van het verlopen certificaat.  

Na vele aankondigingen is het dan uiteindelijk zover! Sinds dinsdag 2 april 2024 om 18:00 uur is het niet meer mogelijk om van de IBU gebruik te maken. Dit geldt zowel voor de interactieve IBU die je via Zend/Ontvang gebruikte, als ook voor de StandAlone IBU die automatisch je bestanden inzond en/of ophaalde. Vanaf nu zijn Bestandsuitwisseling en File API de nieuwe tools waarmee je bestanden met Youforce uitwisselt.   Lees voor de laatste informatie ons recent gepubliceerde nieuws artikel.  

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.

Dit zijn de fixes sinds versie 1.22: Het upload script logde nog niet in de Monitor file. Dit is verholpen. Verbeterde afhandeling bij het verwijderen van tijdelijke bestanden Bug opgelost waarbij het genoemde aantal bestanden voor uploaden verkeerd werd getoond als er maar 1 bestand klaar stond om te uploaden. Upload script maakte log bestand aan met de verkeerde naam. Dit is verholpen. Volg de instructies in ons kennisbank artikel om de nieuwste scripts (1.24) te installeren.