Releases Youforce API & bestandsuitwisseling

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.  

Deze releasenotes zijn technisch van aard en bedoeld voor File API-ontwikkelaars die direct met de File API integreren of bekend zijn met de technische werking ervan. Deel deze release notes graag met de IT-afdeling van jullie organisatie.   Inleiding   De file API maakt op dit moment gebruik van het veilige OAUTH 2.0 protocol om gebruikers te authenticeren en bestanden uit te wisselen. Dit OAUTH 2.0 protocol is een wereldwijde standaard voor gegevensuitwisseling via API’s en wordt beschouwd als zeer veilig. Een 100% veiligheid is in onze huidige IT wereld echter moeilijk te garanderen. We proberen dan ook steeds de kansen op gegevensverlies nog verder  te minimaliseren. Zo is er ook voor het OAUTH 2.0 protocol een uitbreiding bedacht die deze kansen nog verder minimaliseert, de DPOP-token implementatie. Het implementeren van het DPoP token vereist een programmatische aanpassing aan de klantzijde. Daarom is deze optie vooral bedoeld voor klanten die zelf software ontwikkelen/hebben ontwikkeld voor gebruik met de File API. Neem zo nodig contact op met je IT afdeling of dit voor jullie een optie is. Gebruiken jullie op dit moment de powershell scripts om met de File API te communiceren, houd dan dit kanaal in de gaten. In de nabije toekomst zullen we het DPoP-token ook in de powershell scripts implementeren.   Huidige situatie Momenteel ondersteunt de File API geen DPoP-tokens als OAuth-bewijstype.   Nieuwe situatie Vanaf vandaag, 26 februari 2025, worden DPoP-tokens ook ondersteund.   Jouw actie: Indien je er zorg voor wilt dragen dat uitsluitend de rechtmatige ‘client’ een specifiek toegangstoken kan gebruiken, kun je de DPoP-stroom implementeren in je File API applicatie. Zodra de wijzigingen aan jullie kant zijn geïmplementeerd, kan je de onderstaande toggle activeren in het Visma Developer Portal → My Applications → Details. Deze wijziging zorgt voor een nog betere beveiliging van jouw File AP integratie.   Officiële specificatie: RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP) Ondersteunde cryptografische algoritmen: Onze implementatie hanteert strikte beveiligingsmaatregelen en ondersteunt uitsluitend de volgende cryptografische algoritmen: RSA: RS256, RS384, RS512, PS256, PS384, PS512 ECDSA: ES256, ES384, ES512 Het gebruik van het algoritme 'none' wordt expliciet geweigerd. Unieke identificator voor de DPoP-proof JWT: Deze implementatie bevat een validatie om reply-aanvallen te voorkomen. Hiervoor worden de waarden die in de jti-claim worden verzonden gedurende het geldigheidsvenster opgeslagen, zodat wordt gewaarborgd dat deze waarde uniek is en slechts één keer wordt gebruikt. Zorg ervoor dat je bij elke aanvraag een unieke GUID opgeeft in de jti-claim.

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.    

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.    

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 afgelopen periode zijn de volgende verbeteringen in de API's doorgevoerd:   IAM API Nieuwe endpoint voor Employments  De IAM API is uitgebreid met een nieuwe endpoint employmentTimelines . Het endpoint employmentTimelines is gebaseerd op de historie tabel van Beaufort waardoor het endpoint de ingangsdatum bevat.  Het endpoint  bevat dezelfde velden als het oorspronkelijk endpoint employments maar dus nu ook inclusief ingangsdatum waardoor er een soort tijdlijn ontstaat. Voor het endpoint geldt dat de ingangsdatum uit de historie tabel van Bo4 komt.  Onderstaand een voorbeeld van het nieuwe endpoint employmentTimelines:  

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.        

  Dit zijn de fixes sinds versie 1.24: Probleem opgelost bij het downloaden in Chunks (delen) Het automatisch opnieuw downloaden bij fouten tijdens de download herkent nu naast status 500 Server Fout, ook status 499 (client disconnect) De ChunkSize limiet is verhoogt naar 1000 MB. Dit betekent dat bestanden tot 1000 MB grootte nu met 1 request kunnen worden gedownload. Afhankelijk van jouw infrastructuur kan het aan te bevelen zijn om een kleinere ChunkSize in te stellen. Dit doe je in het config.xml bestand.   Volg de instructies in ons kennisbank artikel om de nieuwste scripts (1.25) te installeren.

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.            

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

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.