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.
Op 19-02-2024 hebben wij een nieuwe versie (1.22) van de PowerShell scripts gepubliceerd met de volgende verbeteringen:
Vermelding van de minimale vereiste .NET versie 4.8 in de readme bestanden.
Verbetering van het download proces.
Verplicht gebruik van TLS 1.2 toegevoegd in het Upload script.
Vermelding van versies van: de PowerShell scripts, Windows en .NET versie tbv een betere ondersteuning.
Je vind de PowerShell scripts hier.
Verbergen van bestanden in Ontvang pagina.
We hebben regelmatig vragen gekregen of het mogelijk was om in Bestandsuitwisseling in de Ontvang pagina bestanden te kunnen verwijderen als je ze niet wilt ontvangen. Sommige van jullie krijgen zoveel bestanden in de lijst die je niet echt wilt ontvangen dat deze bestanden het moeilijker maken de bestanden die je WEL wilt ontvangen te vinden en te ontvangen.
Met ingang van 1 feb 2024 is het bij Bestandsuitwisseling nu mogelijk om bestanden in de Ontvang pagina te 'Verbergen' als je ze niet wilt ontvangen.
We hebben gekozen voor de term Verbergen omdat de bestanden niet echt worden verwijderd bij deze functionaliteit, maar ze worden niet meer getoond in de Ontvang bestandslijst waardoor je eenvoudiger de bestanden die je WEL wilt ontvangen kunt vinden. Doordat de bestanden niet echt worden verwijderd is het gedurende 30 dagen nog mogelijk om met de juiste filters de verborgen bestanden weer zichtbaar te maken en eventueel alsnog te ontvangen.
Dit artikel beschrijft hoe je de Verberg functionaliteit kunt gebruiken.
LET OP! Als je bestanden verbergt zijn ze ook niet meer zichtbaar voor andere gebruikers van Bestandsuitwisseling binnen jouw bedrijf.
De bestanden worden zoals vermeld echter niet verwijderd uit Bestandsuitwisseling. Verderop in het artikel wordt uitgelegd hoe je met de juiste filters ook de verborgen bestanden weer in de lijst zichtbaar kan maken zodat je ze eventueel nog kunt ontvangen.
Nieuw Acties ikoon Verberg
Er is een nieuw Acties ikoon zichtbaar waarmee het geselecteerde bestand verborgen kan worden. Als je op het ikoon klikt dan wordt het bestand direct verborgen en is hij niet meer zichtbaar in de lijst.
Deze optie kan heel handig zijn als je meerdere bestanden tegelijkertijd wilt ontvangen maar er staan in de lijst ook bestanden die je niet wilt ontvangen. Als je de gewenste bestanden niet allemaal individueel wilt selecteren, verberg dan eerst de bestanden die je niet wilt ontvangen en vink daarna de Selectie box aan in de rij met kolomnamen om alle nog zichtbare bestanden te selecteren voor ontvangen.
Aangepaste filters
Om optimaal gebruik te kunnen maken van de nieuwe functionaliteit zijn de filters iets aangepast.
Als de Ontvang pagina wordt geopend worden standaard de bestanden die Ontvangen status 'Nog Niet Ontvangen' en Verberg status 'Zichtbaar' hebben, getoond. Dat is dezelfde functionaliteit als in de oude situatie.
Het is mogelijk de verborgen bestanden weer in de lijst te tonen door bij de Verberg status de optie 'Verborgen' te activeren.
Door op de 'Bekijk Resultaten' knop te klikken worden nu ook de verborgen bestanden getoond.
Met dit 'Verberg status' filter worden alle bestanden, Zichtbaar en Verborgen, getoond.
Verborgen bestanden kun je herkennen aan een vinkje in de Verberg kolom.
Net als bij ontvangen bestanden kun je bij verborgen bestanden op het (naar beneden) vinkje klikken in de meest linkse kolom om te zien wie het bestand verborgen heeft.
Ontvangen van verborgen bestanden.
Belangrijk om te weten is dat ook verborgen bestanden nog steeds kunnen worden ontvangen. Hiervoor moet je dan wel eerst de Verborgen optie activeren in het Verberg status filter. Als het bestand dan in de lijst wordt getoond kun je het, zoals gewend, ontvangen door op het Acties ikoon Ontvangen te klikken.
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.