Kennisbank Youforce API & bestandsuitwisseling

Eigen rubrieken toevoegen aan de API, wat is er mogelijk, wat moet je vooraf afstemmen en hoe vraag je het aan.

Deze pagina beschrijft de benodigde stappen om een Youforce-bestand te koppelen aan de File API.

Wij proberen continu onze powershell scripts voor de File API te verbeteren en fouten op te lossen. Hierdoor zullen er door ons indien nodig nieuwe scripts worden gemaakt.   De nieuwe scripts vervangen zonder verdere aanpassingen de 'oude' scripts en mogen eenvoudig 'er over heen' gekopieerd worden. Er zijn geen configuratie of andere handelingen nodig. Alle overige scripts en processen blijven ongewijzigd.   Deel de inhoud van dit artikel met jullie ICT mensen zodat zij deze aanpassingen kunnen uitvoeren.   Als je ook zeker wilt weten dat je de nieuwste powershell scripts gebruikt, doorloop dan de volgende stappen om deze scripts te downloaden en te installeren.   1. Controleer welke versie scripts je nu gebruikt door een dagelijks logbestand te openen. De dagelijkse logbestanden vind je in de Log Directory die je in je powershell scripts CONFIG...XML bij sectie <Logs> hebt geconfigureerd. Bij elk begin van een download of upload staan de versies van verschillende componenten genoemd.   2. Ga met je browser naar deze ReadMe URL en controleer wat de laatste versie is van de scripts. Deze staat altijd bovenaan. Als deze versie nieuwer is als wat je zelf gebruikt ga dan verder met de volgende stappen.   3. Selecteer nu in de browser in het linker Files menu het downloadscript 'Downloadfiles.ps1' 4. Download het 'DownloadFiles.ps1 script door op de Download button rechtsboven te drukken. Het bestand wordt direct gedownload en je kunt het terugvinden in de Download directory van je browser.   5. Selecteer nu in de browser in het linker Files menu het uploadscript 'Uploadfile.ps1'   6. Download het 'UploadFile.ps1 script door op de Download button rechtsboven te drukken. Het bestand wordt direct gedownload en je kunt het terugvinden in de Download directory van je browser.   7. Maak een kopie/backup  van je Visma Raet Powershell installatie directory   8. Kopieer de 2 nieuwe scripts vanuit je Browser's Download directory naar je geinstalleerde powershell scripts en overschrijf de bestaande scripts, het 'DownloadFiles.ps1' script in de download directory en het 'UploadFile.ps1' script in de upload directory.  

Status  De Bestandsuitwisseling module is nu “Algemeen Beschikbaar” voor HR Core Online gebruikers. Dit betekent dat je geen 4Me-ticket meer hoeft in te vullen om Bestandsuitwisseling voor jouw gebruikers te activeren, maar dat je zelf de autorisatie kunt toekennen in Autorisatiebeheer. Bestandsuitwisseling is de vervanger van handmatig Zenden/Ontvangen met IBU.   Enkele voordelen: Intuïtief en gebruiksvriendelijk Geen lokale installatie of configuratie nodig Betrouwbaar, veilig en automatisch opschalen tijdens piek uren Vanaf heden zal de applicatie Bestandsuitwisseling standaard beschikbaar in Autorisatiebeheer. De autorisatie van elke gebruiker voor de verschillende file types kan door de Autorisatiebeheer administrator worden gedaan door het toekennen van de juiste rechten.   Wat je moet doen Als je al de juiste rollen hebt gedefinieerd in Autorisatiebeheer, volg dan onderstaande stappen. Zo niet, volg dan eerst de stappen zoals beschreven in dit artikel en daarna de stappen zoals hieronder beschreven.   Stap 1: Voeg de applicatie Bestandsuitwisseling toe aan de gewenste rol(len) met de volgende rechten: Toegang tot Bestandsuitwisseling Zend testbestanden naar Bestandsuitwisseling Ontvang testbestanden van Bestandsuitwisseling Op dit punt hebben de gebruikers toegang tot Bestandsuitwisseling, maar alleen toegang tot testbestanden en nog geen toegang tot applicatie specifieke bestanden.   Stap 2: Voeg alle gewenste applicaties en hun specifieke rechten toe aan de juiste rollen: Betaalmanager Ontvang opdrachten van Betaalmanager Gemal Ontvang downloads van Betaalmanager Gemal HR Core Zend bestanden naar HR Core Online Ontvang bestanden van HR Core Online Oude Zend-Ontvang naam was Zenden naar Hosted BO4  / Ontvangen van Hosted BO4 Payroll Gemal Direct Ontvang bestanden van Payroll Gemal Direct Personeelsdossier Zend bestanden naar Personeelsdossier Ontvang bestanden van Personeelsdossier Salarisdossier Gemal Ontvang bestanden van Salarisdossier Gemal Youforce Account Beheer  Zend XSSO bestanden naar Gebruikersbeheer Self Service  Zend HI CSV bestand naar Self Service Zend HI XML bestand naar Self Service Managementinformatie Ontvang HR datafeed bestanden van Managementinformatie Stap 3. Controleer of je gebruikers die Bestandsuitwisseling al gebruiken ook de juiste rollen hebben toegewezen gekregen. Indien nodig kun je rechten toekennen aan individuele gebruikers.   Stap 4. Koppel de Youforce bestanden aan de Bestandsuitwisseling. Zie instructies.     Stap 5. Bestandsuitwisseling is op dit moment beschikbaar in Mijn Youforce, maar kan ook worden bereikt via de "Bestandsuitwisseling" -tegel op de Youforce Desktop. In dat laatste geval moet de tegel wel worden geautoriseerd via Toegangsbeheer.  Extra informatie Gebruikers moeten zich aanmelden via de nieuwe login om gebruik te kunnen maken van de Bestandsuitwisseling applicatie. Bestanden kunnen gedurende 1 maand worden opgehaald/ontvangen. Bestanden kunnen gedurende 1 maand zo nodig meerdere malen worden ontvangen. Ontvangen bestanden worden opgeslagen in de Download directory die in je browser is geconfigureerd. Wil je bestanden in verschillende directories ontvangen dan kan dat door je browser zo te configureren dat hij bij elke download vraagt om een directory waar de bestanden gedownload moeten worden. De Nederlandse taal wordt ondersteund. De gebruikte taal volgt de keuze die je bij de persoonlijke instellingen in Mijn Youforce hebt gemaakt. Het is al mogelijk om tegelijkertijd meerdere bestanden te ontvangen. Zie Release-opmerkingen Bestandsuitwisseling update 16-10-2023 De Gemal Salaris tabellen die je gebruikt worden bij elke vernieuwing automatisch op de J-schijf geplaatst in de nieuwe Payroll-Tables directory. Bestandsuitwisseling toont gebruiker informatie van degene(n) die een bestand hebben ontvangen of verzonden. Zie dit artikel voor meer informatie. Kennisartikelen Zenden en Ontvangen met de IBU stopt Hoe richt ik de rechten voor Mijn Youforce zo overzichtelijk mogelijk in 'autorisatiebeheer'? Youforce-bestanden koppelen aan Bestandsuitwisseling.   Hoe Bestandsuitwisseling testen met dummy-bestanden Releases voor bestandsuitwisseling  

Developer portal, een account aanmaken, applicatie registreren en toegang tot de klantgegevens

Nedap Ons is een populair systeem dat zorgprofessionals veel administratieve taken uit handen neemt door personeelsplanningen te maken en deze te koppelen aan Elektronische CliëntenDossiers (ECD).    Visma | Raet levert, met het toonaangevende Youforce platform, een volledig digitale HR-administratie waarmee de werkgever ‘in control’ is over alle processen in de employee lifecycle: van recruitment tot offboarding.   De integratie specialisten van Visma Connect hebben een API connector ontwikkeld die de overdracht van HR data tussen de applicaties van Visma | Raet en Nedap automatiseert.   Youforce API en import ONS Nedap De Youforce Workforce Management (WFM) API met de Extenions API, welke het mogelijk maakt om flexibel 'eigen' rubrieken toe te voegen, vormen de bron voor de connector.  Via de API's wordt de data opgehaald uit HRCoreOnline, waarnodig getransformeerd en aangeboden aan de API van ONS Nedap of via de XML-import van ONS Nedap zodat de data zichtbaar is in de applicatie van ONS Nedap.       Om gebruik te kunnen maken van de connector dien je contact op te nemen met je Customer Success Manager.   Frequentie van het ophalen van de data via de Youforce WFM API en het aanbieden aan ONS Nedap via de API en via de XML-import is ieder uur.   Via onderstaand tabel zie je de betreffende HRCoreOnline-velden die worden uitgewisseld. De velden maken deel uit van een 'scope' (deelgebied), als klant kan je kiezen welke scope(s) je op wilt nemen in de koppeling, bespreek dit met de Raet Consultant.   Benodigde voorbereiding    Eigen rubrieken aanmaken Een belangrijk deel van de informatie wordt via Eigen rubrieken vastgelegd, deze velden zijn essentieel om ONS Nedap goed te kunnen gebruiken, de aanwezigheid van deze velden in HRCoreOnline zijn dus een vereiste. Het aanmaken van de velden met de refentietabellen kan eenvoudig via XML-importbestanden, vraag die op bij je consultant. De wijze van import in HRCoreOnline staat hier beschreven:   https://community.visma.com/t5/Nieuws-Youforce-HR-Core-Beaufort/Rubrieken-voor-eigen-HRSS-inrichting-betaald-ouderschapsverlof/ba-p/504058   Let op, de velden zijn dan beschikbaar in HRCoreOnline desgewenst dien je ze ook op te nemen in de Selfservice-workflows.   ONS Nedap API en XML-import toegang Als klant vraag je bij ONS Nedap het volgende aan: Login credentials voor de ONS Nedap API (met Certificaat) Gebruikersnaam en wachtwoord voor de XML-import Je deelt dit met de Raet Consultant.   Youforce API filter Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen. Bekijk de mogelijkheden via: https://community.visma.com/t5/Kennisbank-Youforce-API/Autorisatie-WFM-api/ta-p/557545     Inhoud van de koppeling   Scope Basis (Persoonsgegevens, dienstverbanden en inzetregels).   HRCoreOnline - veld Import via ONS Nedap API-veld Import via Nedap XML-  veld Opmerking  Persoon P01001 - Persoonsnummer  employee.identificationNo        P00303 - Voorletters  employee.initials       P01003 - Roepnaam employee.firstName       P00301 - Geboortenaam employee.birthName       P00302 - Geboortenaam-voorvoegsels employee.partnerName       P01008 - Samengestelde naam employee.lastName       P01009 - Samengestelde naam-voorvoegsels employee.prefix       P00304 - Gebruik achternaam employee.preferredNameType       P00390 - Partner-naam employee.partnerName       P00391 - Partner-voorvoegsels employee.partnerNamePrefix       P00330 - Geslacht employee.gender       P00321 -Geboorte datum employee.dateOfBirth               Contact- gegevens Business: P01035 - E-mail adres werk employee.emailAddress       Business :P01037 - Telefoonnr werk employee.mobilePhoneNumber               Dienst- verband P01101 - volgnr dienstverband employee.identificationNo-[Volgnr van WFM]         contract.beginDate         contract.endDate         Employee.type   Heeft een vaste waarde 0 (regular)   P01102  - Soort Arbeidsrelatie contract.contractType     P01119 - Max. uren per week payroll.Contract.var /contract.hoursVar               Inzet-regels P01125 - Ingang inzet teamAssignments.beginDate       P01126 - Einde inzet teamAssignments.endDate       P01121 - Operationele org. eenheid team_assignments.teamObjectId       P01124 - Uren inzet per week payroll.Contract.fixed /contract.hoursFixed       Einddatum van het contract in ONS is gebasseerd op de einddatum van de inzetregel.      Scope Extensies (Eigen rubrieken)     HRCoreOnline - veld Import via ONS Nedap API-veld Import via Nedap XML-  veld Opmerking Extentie-velden WKKRT1 - Weekkaartprofiel   registrationprofile     AGB001 - AGB-code 1   employee. agb.primaryAgbCode     AGB002 - AGB-code 2   employee.agb.agbCode     P09165 - BIG-nummer (1)   employee.bigCode     BIG002 - BIG-nummer (2)   employee.bigCode     BIG003 - BIG-nummer (3)   employee.bigCode     DBC001 - Cono-/DBC-beroepsgroep 1   employee. conoBeroepsgroep     DBC002 - Cono-/DBC-beroepsgroep 2   employee. conoBeroepsgroep     DBC003 - Cono-/DBC-beroepsgroep 3   employee. conoBeroepsgroep     AUT001 - Authenticatienummer employee. authentication MobilePhone employee. authenticationNumber     CAO001- CAO-code Ons   collectiveagreement. agreement     DEP001- Deskundigheids-profiel   education.id     COMP01- Compensatie berekenen     Wordt toegevoegd   COMP02- Compensatie begindatum     Wordt toegevoegd   COMP03 -Compensatie uitbetalen     Wordt toegevoegd   ONAN001- Onderaannemer     Niet beschikbaar      Scope Prive (Adres, telefoonnummer en e-mailadres)   HRCoreOnline - veld Import via ONS Nedap API-veld Import via Nedap XML-  veld Opmerking Adres (thuis) P01014 straatnaam EmployeeAddress.street     Adres (thuis) P01016 Huisnummer EmployeeAddress. homeNumber     Adres (thuis) P01018 Huisnummer toev EmployeeAddress. homeNumberExtension     Adres (thuis) P01020 Postcode EmployeeAddress.zipcode     Adres (thuis) P01022 Plaatsnaam EmployeeAddress.city     Adres (thuis) P01024 Land EmployeeAddress.country     Adres (post) P00365 straatnaam EmployeeAddress.street     Adres (post) P00367 huisnummer EmployeeAddress. homeNumber     Adres (post) P00368 huisnummer toev EmployeeAddress. homeNumberExtension     Adres (post) P00308 plaatsnaam EmployeeAddress.zipcode     Adres (post) P00313 postcode EmployeeAddress.city     Adres (post) P00847 land EmployeeAddress.country     Telefoonnummer Home: P01027 - telefoonnr woonadres EmployeeAddress. telephoneNumber     Telefoonnummer Mobile : P01036 - Telefoonnr mobiel EmployeeAddress. telephoneNumber2     E-mailadres Prive: P01034 - E-mail adres privé EmployeeAddress.email     Type Adres   typeString   Standaard wordt de volgende waarde gebruikt: 1: Living (bij Adres Thuis) 2: Postal (bij Adres Post) Type persoon   personType   Standaard wordt de volgende waarde gebruikt: 2: Employee Type verblijf   residentType   Standaard wordt de volgende waarde gebruikt: 0: Unknown     _______________________       Scope Salaris details   HRCoreOnline - veld Import via ONS Nedap API-veld Import via Nedap XML-  veld Opmerkingen Berekend uurloon P01160 Berekend garantie uurloon   employee.HourlyWage.wageInCents         employee.HourlyWage.startOfWage Datum waarop dit uurloon is ingegaan.  *Bestaat niet in Youforce,  eventueel contract datum nemen       employee.HourlyWage.endOfWage Datum waarop dit uurloon niet langer valide is. *Bestaat niet in Youforce eventueel contract datum nemen _____________________         Scope Verlof (rechten)   HRCoreOnline - veld Import via ONS Nedap API-veld Import via Nedap XML-  veld Opmerkingen Verlofsoort (WET, BW etc.) P01430 code verlofsoort werknemer   VacationAmount.plb   Jaar verlofrecht P01440 verlofjaar verlofrechten   CurrentDate   Verlofrechten huidig jaar P01443 verlofrecht huidig jaar in uren   VacationAmount.absolute      

Zenden en Ontvangen, waarbij IBU wordt gebruikt, en Bestandsuitwisseling, die gebruik maakt van de File API, zijn 2 verschillende Youforce modules. Ze hebben elk hun eigen bestanden. Standaard worden Youforce bestanden voor jou naar Zenden en Ontvangen gestuurd. Om de bestanden ook beschikbaar te krijgen voor Bestandsuitwisseling moet je sommige Youforce modules die je gebruikt vertellen dat ze de bestanden naar Bestandsuitwisseling sturen.   Deze pagina beschrijft voor elke module waar een aanpassing voor nodig is, de benodigde stappen om een Youforce-bestand te koppelen aan Bestandsuitwisseling.  Omdat  Bestandsuitwisseling ook gebruik maakt van de File API wordt in de beschrijvingen vaak alleen gerefereerd aan de File API. Hier mag je dus ook Bestandsuitwisseling voor lezen. Gebruik je straks zowel Bestandsuitwisseling (interactief) als File API (automatische koppeling) voor dezelfde Youforce module dan hoef je de stappen voor die module slechts 1x uit te voeren.   Voor de volgende Youforce-modules zijn aanpassingen nodig:     Payroll Gemal Direct Payroll Gemal - Ontvang Bestandsuitwisseling biedt de mogelijkheid om de bestanden die in een Payroll Gemal-productie zijn afgeroepen, te downloaden naar je lokale omgeving. Het gaat om het ophalen van data bestanden zoals bijv. de journaalposten, flexbestanden, loonstaten in csv; zoals deze in bestandsvorm bij Zenden en Ontvangen gedownload kunnen worden.   Onderstaande werkgevercode is voor alle klanten die met losse Gemal output (zie bestandsnamen verderop) werken in Zenden en Ontvangen en zij kunnen dit onderdeel via Bestandsuitwisseling laten verlopen zodra deze stap is uitgevoerd.   Hoe Werkgeverscode 30050 is vanaf 2022-10 beschikbaar in Gemal Direct Inrichting om de ontvangen bestanden naar beiden (IBU en File API) of alleen naar Bestandsuitwisseling (File API) te sturen. Deze werkgevercode vind je in Gemal Direct Inrichting via Selecteren werkgever-productie / werkgevergegevens / overzicht en bestanden / algemeen   Werkgeverscode 30050 File-API 0 = Bestanden via 'Zenden&Ontvangen' 1 = Bestanden via 'Zenden&Ontvangen' en via de File API  / Bestandsuitwisseling 2 = Bestanden via File API / Bestandsuitwisseling - (werkt voorlopig nog gelijk aan waarde 1, maar ben je over op Bestandsuitwisseling (File API), leg deze waarde dan vast)         Als de waarde 0 is, worden de bestanden op de oude/huidige manier verzonden. Een waarde van 1 maakt de bestanden ook beschikbaar in Bestandsuitwisseling. Waarde 2 heeft nu nog hetzelfde effect als 1, maar door dit vast te leggen als je over bent, krijgen we inzicht in de mate waarin klanten deze stap hebben gezet. Op termijn zal waarde 2 conform de beschrijving alleen via Bestandsuitwisseling worden verwerkt. Gewijzigde bestandsnamen LET OP! Daarnaast zijn de bestandsnamen als deze via Bestandsuitwisseling worden aangeboden, aangepast. Hierdoor wordt het meer helder welk bestand je daar ziet staan. In 'Zenden en Ontvangen' blijven de huidige benamingen van toepassing. Zie onderstaande figuur voor een weergave van de nieuwe namen.   Werkgeverscode 30050 hoeft alleen geregistreerd te worden bij instelling nummer 1.   Tenslotte: De Salaristabellen zijn voor HR Core On Premise klanten beschikbaar via  Bestandsuitwisseling. Na elke nieuwe publicatie van de Salaristabellen worden de Salaristabellen die je gebruikt automatisch beschikbaar gesteld in Bestandsuitwisseling. Voor HR Core Online klanten worden nieuwe versies van de Salaristabellen automatisch geplaatst op de J-Drive in de nieuwe Payroll-Tables directory. HR Core online HR Core Online Hosted - Ontvang   De bestanden moeten worden geplaatst in de nieuwe map 'Hosted-Klant-Files'. Vanuit deze map worden de bestanden gekoppeld aan Bestandsuitwisseling.  HR Core Online Hosted - Zend De ingestuurde bestanden worden op de J-schijf geplaatst in de map J:\Raet\Klant-Hosted net zoals je gewend was met IBU Zenden. Betaalmanager  Betaalmanager Gemal Downloads Betaalmanager Gemal Opdrachten Betaalmanager VIPS Disbursements Downloads Betaalmanager VIPS Disbursements Opdrachten   Betaalmanager biedt de mogelijkheid automatisch betaal- en downloadbestanden te ontvangen in de klantomgeving met behulp van Bestandsuitwisseling.  Op het scherm Beheer > Instellingen is het veld Zenden naar gesplitst in drie velden SEPA-betalingen zenden naar, Downloads zenden naar en non-SEPA zenden naar. Om instellingen aan te passen is rechts een knop Aanpassen toegevoegd:   Indien je op de knop Aanpassen klikt, dan wordt een apart scherm Instellingen rekening aanpassen getoond waarin je eventuele rekeninginstellingen kunt wijzigen:   Als je een nieuw IBAN van afschrijving gaat gebruiken, dan blijft de initiële inrichting: SEPA betalingen zenden naar EQUENS-CPS, Download zenden naar Zenden Ontvangen en Non-SEPA betalingen zenden naar Zenden Ontvangen.  Het is niet mogelijk om achteraf nog bestanden te achterhalen. Mocht je gebruik willen maken van de Bestandsuitwisseling/File Api, adviseren wij om de Online Help van de Betaalmanager door te lezen, waarin onder andere het volgende is opgenomen:   Als bij Beheer > Instellingen >  Aanpassen > SEPA betalingen zenden naar gekozen is voor verzenden naar File Api dan maakt de Betaal Manager het SEPA-betaalbestand aan en biedt dit aan aan de File Api. De betaalbestanden worden dan beschikbaar gesteld in Bestandsuitwisseling. De status van een verzonden betaalopdracht ziet u bij de details van de betaalopdracht bij Betaalopdrachten bekijken.  

Veel arbodiensten gebruiken een eigen systeem om terugkoppelingsdocumenten op te stellen. Deze documenten zijn bedoeld voor betrokkenen binnen de klantorganisatie. Om deze terugkoppelingsdocumenten ook in Verzuim Management beschikbaar te krijgen, is het nodig om deze documenten handmatig in te voeren. Dit leidt echter tot dubbele invoer van de documenten en is bovendien foutgevoelig. Om deze dubbele invoer én eventuele fouten te voorkomen, is de SIVI documenten interface ontwikkeld.   Bij gebruikmaking van SIVI documenten leveren de arbodiensten de bestanden geautomatiseerd aan Visma Raet, via een beveiligde verbinding. Deze bestanden worden gekoppeld aan in Verzuim Management bestaande acties die zijn ingericht met een verwijzing naar de Identificatie document soort van SIVI.   Het aanleveren van de bestanden aan Visma Raet gebeurt via onze File API, de werking van de File API is hier gedocumenteerd.   De pagina Getting Started beschrijft hoe je een access token opvraagt en via Publishers/Multipart upload staat de API call beschreven die zorgt voor de upload.    Het bestand is het door SIVI voorgeschreven (XML)format versie 2020, de XML-bestandsnaam moet bij insturen via de File API voldoen aan het volgende formaat:   DO-XXXXXXXXXXXXXXX_YYYYMMDDHHMMSSFFF.xml of DO-XXXXXXXXXXXXXXX_YYYYMMDDHHMMSSFF.xml of DO-XXXXXXXXXXXXXXX_YYYYMMDDHHMMSS.xml   Voorbeelden:  DO-Tussentijdse evaluatie_20180622010203444.xml DO-Evaluatie n.a.v. gesprek 1_20180622010203444.xml   Toelichting: Onderdeel inhoud DO- Vaste waarde XXXXXXXXX Vrij in te vullen waarde. Variabel, minimaal 1 positie, maximaal 160 posities. Toegestane waarden:  alfa numeriek: A-Z, a-z, 0-9. punten. spaties _ Vast waarde, scheidingsteken YYYY Jaar, 4 posities MM Maand, 2 posities dd Dag, 2 posities HH Uur, 2 posities MM Minuut, 2 posities SS Seconden, 2 posities FF of FFF Milliseconden 0, 2 of 3 posities .xml Vaste waarde, extensie   Om het bestand via een File API-call te versturen naar Visma Raet dient businessTypeID 124000 gebruikt te worden in de call. Dit businessTypeID staat in Youforce voor de SIVI Documenten en dient samen met de bestandsnaam als metadata worden toegevoegd aan de API call. Een voorbeeld van de API-call:     Je kan de upload testen door gebruik te maken van onderstaande API-credentials API Key: VRA_fileapi_4001401_uploadsivi Secret Key: F0m9N5kbdXB4xEPQTkQRpd76H4JZw6CYoJQbskQ9zAJDdtu8WalC687ozkjoZ6tm TenantID: f556855c-a0c4-42c7-88f1-98bf5b209393   Met onderstaande variabelen in het SIVI document-XML-bestand voor een succesvolle test-verwerking:        <IdInzndr>ArbodienstX/IdInzndr> <IdOntvngr>Visma - Raet</IdOntvngr>  <HndlsnmOrg>RAET SIVI TEST</HndlsnmOrg> <IdWrkgvrArbdnst>test12345test</IdWrkgvrArbdnst> <AansltnrGeguitwlngArbdnst>6431</AansltnrGeguitwlngArbdnst> <Lhnr>999999999999</Lhnr> <SrtDocumentCd>999</SrtDocumentCd> <SrtDocumentOms>Overig</SrtDocumentOms> <KenmerkZendPartij>ArbodienstX</KenmerkZendPartij>   <IdWrknmr>1945</IdWrknmr> <IdDnstvbnd>1</IdDnstvbnd> <PersNr>1945</PersNr> <VrzmgvlId>1945 1 1809</VrzmgvlId> <DatEerstVrzmdg>2022-05-24</DatEerstVrzmdg>   Wanneer de File API een 201 (Created) teruggeeft dan is de upload succesvol geweest, neem met Visma Raet contact op om samen te controleren of het document daadwerkelijk is toegevoegd aan het verzuimdossier van de betreffende medewerker (persoonsnummer 1945, verzuimdossier 24-05-2022), een specifieke bestandsnaam van het document (<Bestandsnm>) helpt bij de controle.    

Domain model   The IAM model       Data mapping Person  The personal details of an employee. This could also contains person without a (active) employment. HR Core Beaufort: Persoon id The globally unique id assigned to an employee 32789 P01001 Persoonsnummer personCode The unique id assigned to the employee 32789 P01001 Persoonsnummer personId The globally unique id assigned to an employee 32789 P01001 Persoonsnummer initials The initials of the employee A.B. P00303 Voorletters firstNames The official given names of the employee Amy Beatrice P01002 Voornamen knownAs The name which is used by the employee as first name Amy P01003 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries P00301 Geboortenaam lastNameAtBirth Prefix The prefix of the employee's last name at birth de P00302 Geboortenaam voorvoegsels lastName The last name used by the employee at present Vries - Van Eijck P01008 Samengestelde naam lastNamePrefix The prefix of the employee's last name at present de P01009 Samengestelde naam voorvoegsel nameAssemble Order Code of the assemble order used by the core system for the last name. C P00304 Gebruik achternaam partnerName The last name of the employee's partner Eijck P00390 Partner naam partnerName Prefix The prefix of the partner's last name Van P00391 Voorvoegsel partner titlePrefix Formal title prefix drs. P00305 Titulatuur voor de naam titleSuffix Formal title suffix Msc P03937 Titulatuur achter de naam gender Gender of the employee Female P00330  Geslacht dateOfBirth Date of birth 1986-12-02 P00321 Geboorte datum deceased This field indicates if an employee is deceased when false the property is not returned true P01005  Datum overlijden UserUID Digital Identity of the user from the portal bdd38fd2-FAKE-4313-FAKE-671c786d0758   Ping ID directly from the portal youforceAccount Indicaties if the person do have a user account J P15013 Youforce gebruiker phoneNumbers List of phone numbers and types Home +3188 123 45 67 P01027 Telefoonnummer woonadres Business +3188 345 67 89 P01037  Telefoonnummer werk Mobile +316 12 34 56 78 P01036 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Business b.user@example.com P01035 E-mail adres werk Private p.user@example.com P01034 E-mail adres privé Addresses List of addresses   type Home street Kerkstraat P01014  Straat houseNumber 1 P01016 Huisnummer houseNumber Addition C P01018  Huisnummer toevoeging postalCode 1234 AB P01020  Postcode city Amersfoort P01022  Woonplaats country NL P01024 Woonland effectiveDate 2023-08-01 P01012  Adres m.i.v.   type Postal street Poststraat P00365 Straatnaam houseNumber 1 P00367 Huisnummer houseNumber Addition A P00368 Huisnummer toevoeging postalCode 1234 AB P00313 Postcode city Amersfoort P00308 Plaatsnaam country NL P00847 Land effectiveDate 2023-08-01 P00847 Adres m.i.v.     Employments  The employment of the employee. A person can have multiple employments at the same time.   HR Core Beaufort: Dienstverband employmentCode The code of the employment 1 P01101  Volgnummer dienstverband originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 P00834 Datum in dienst CAO dischargeDate The end date or discharge date of the employment. This is always an "up to and including" date. In case of no values the field will not be returned as part of te response body 2018-12-31 P00830  Datum uitdienst hireDate Date of hire for the employment 2017-05-01 P00322 Datum in dienst classification Cost allocation of the employment 123 P01110 Code doelgroep employmentType Code of the employment type 4 P01102 Soort arbeidsrelatie workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   P01109 Uren per week unitOfWork: unit of work that specifies the unit for the amount Hours P01109 Uren per week periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter P01109 Uren per week jobProfile The job profile code 9909 DEV P01107 Primaire functie organizationUnit The organization unit id 1234567 ZKH P01106 Hiërarchisch organisatorische eenheid Payroll Client Code     P01103  CEA-nummer Payroll Institution Code      P01104 Instelling nummer Company PayrollClientCode and PayrollInsituationCode combined       Assignments  The possible assignments of an employee for their employment. In example, employee works is assigned to a different department as temporary replacement or to help another department without changing his own employment. HR Core Beaufort: Inzet id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.   100 1 12 1234 20200923 system field Unique id of the assignment personCode The unique id assigned to the employee 32789 P01001 Persoonsnummer personId The globally unique id assigned to an employee 32789 P01001 Persoonsnummer employmentCode The code of the employment of the person 1 P01101  Volgnummer dienstverband startDate The start date of the assignments 2017-05-01 P01125 Ingang inzet endDate The end date of the assignment. This is always an "up to and including" date. In case of no values the field will not be returned as part of te response body 2017-11-30 P01126 Einde inzet jobProfile Job title or job profile code of the assignment. DEV P01122 Operationele functie organizationUnit The organization unit id of the assignment. PD P01121 Operationele organisatorische eenheid workingAmount Working amount of the employment.. amountOfWork: numeric value representing the work amount 40   P01123 Uren inzet per week unitOfWork: unit of work that specifies the unit for the amount Hours P01123 Uren inzet per week periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Week P01123 Uren inzet per week costCenter The cost center of a Assignment     P01128 - Kostenplaats Inzet costUnit The cost unit of an Assignment     P01129 - Kostendrager Inzet costType The cost type of an Assignment     P01127 - Kostensoort Inzet type Type of assignment     P01123 - Soort Inzet   Cost allocation  The cost allocation of an employee. The cost allocations are generated by Beaufort. An employee can multiple cost allocations. Mostly the cost allocation with sequence number 0 or the one with the highest percentages  is the main cost allocation.  HR Core Beaufort: Loonverdeling id Unique id of the cost allocation. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.   32789 1 0 system field Unique id of the assignment PersonCode The unique id assigned to the employee 32789   Persoonsnummer employmentCode The code of the employment of the person 1   Dienstverband volgnummer sequenceNumber Unique sequence number or row number of the cost allocation within the employee 0 P01131 regelnummer loonverdeling costTypeCode code of the cost type  4004 P01133 Kostensoort loonverdeling CostTypeName full name of the cost type Loonkosten   Omschrijving kostensoort (referentie tabel) costCenterCode code of the cost center 4000 P01134 Kostenplaats loonverdeling costCenterName full name of the cost center KNO Operaties   Omschrijving kostenplaats (referentie tabel) costUnitCode code of the cost unit 4100 P01135 Kostendrager loonverdeling costUnitName full name of the cost unit KNO   Omschrijving kostendrager (referentie tabel) percentage percentage of the cost allocation 100 P01132 loonverdeling loonverdeling   Organization Units  The organization structure describes the organization in terms of business unit, departments, divisions, etc. and how these are related to each other. Based on the organization structure it's clear “how” units are related and "which" department is responsible for "what". HR Core Beaufort: Organisatie eenheden validFrom The date from which the record is valid 2020-04-01 N/A Data niet beschikbaar in de API validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01 9999-12-31 N/A Data niet beschikbaar in de API id Unique id of the organization unit PD P01061 Code organisatorische eenheid shortName Code or short name of the Organization Unit PD P01061 Code organisatorische eenheid fullName Name or full title of the Organization Unit Product Development   Naam organisatorische eenheid parentOrgUnit Code of the parent organization unit PD_EU   Organisatie eenheid > Onderdeel van organizationUnitType Type of organization unit Divisie   Type organisatorische eenheid   Role Assignments  The role assignment describes "who" is responsible for “what“ and “when“ within the organization unit. HR Core Beaufort: Rol toewijzing validFrom The date from which the record is valid 2020-04-01 N/A Data niet beschikbaar in de API validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01 9999-12-31 N/A Data niet beschikbaar in de API id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. R1 - N/A BO4 - 78000 1877 MGR 20200101   Id van het record personId The unique id assigned to the employee 10017   Persoonsnummer van de houder van de rol organizationUnit The organization unit id of the assignment. 459   Code van organisatorische eenheid shortName The code of the role MGR   Code van de rol personCode The code of the person 12345   Persoonsnummer van de houder van de rol (gelijk aan personID) startDate Start date of role assignment 2013-04-17 N/A Data niet beschikbaar in de API endDate End date of role assignment 2020-01-31 N/A Data niet beschikbaar in de API   Job Profiles  All job profiles that have been defined within the tenant. HR Core Beaufort: Functie shortName Code or short name of the Job Profile SE Functie code fullName Name or full title of the Job Profile Software Engineer 5 Functie omschrijving jobFamily Code or short name of the Job Family PD5 Functie groep code validFrom The date from which the record is valid 2020-04-01 Data niet beschikbaar in de API validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 Data niet beschikbaar in de API  

De Recruitment API speelt een belangrijke rol in het wervingsproces van moderne organisaties. Door de Recruitment API naadloos te integreren met uw bestaande recruitment systeem ontstaat een soepele overgang tussen het recruitment proces in het recruitment systeem en de onboarding is Youforce. Of het nu gaat om het aantrekken van nieuwe talent (hire), het faciliteren van de terugkeer van voormalige werknemers (re-hire), of het soepel doorvoeren van interne functiewijzigingen (Contract change), de API biedt een gestroomlijnde koppeling met HR Self Service.    Features van de API Onze API faciliteert een aantal flexibele en krachtige opties, waaronder: Specifieke endpoints: De API bieden verschillende endpoints voor specifieke taken zoals het aannemen van nieuwe medewerkers (hire), herindiensttreding (re-hire), en contractwijzigingen (contract change). Veelzijdige workflow-ondersteuning: Verschillende HRSS workflows worden ondersteund, waardoor op maat gemaakte HRSS processen gebruikt kunnen worden voor verschillende categorieën medewerkers, zoals vaste medewerkers en tijdelijk personeel of verloonde medewerkers en medewerkers niet in loopdienst, de zogenaamde PNIL-ers. Aanpasbare veldtoewijzing: Standaard en aangepaste veldtoewijzingen zorgen ervoor dat de API naadloos aansluit op uw HR Self Service configuraties, inclusief ondersteuning voor eigen rubrieken. Attachment Functionaliteit: Voeg essentiële documenten en bestanden toe aan elke HR-werkstroom, wat essentieel is voor het beheren van kandidaatdocumentatie en andere belangrijke informatie. Let op: De configuratie en inrichting van de API en HR Self Service is een ingewikkeld proces dat een diepgaande kennis van beide systemen vereist. Dit proces wordt meestal begeleid door gespecialiseerde HSS en API-consultants om te zorgen voor een nauwkeurige afstemming op uw organisatorische wensen en technische eisen.   API & Connector De integratie tussen het recruitmentsysteem en Youforce bestaat uit Youforce API en een Connector als onderdeel van het recruitmentsysteem. Onderstaand schema geeft de interactie weer tussen het recruitment systeem en de Youforce API.   Binnen de connector dient logica ontwikkeld te worden om te kunnen bepalen of een een hire of re-hire betreft. Ter ondersteuning hier is een search person endpoint beschikbaar.   Endpoint Search Person Met behulp van dit endpoint kan op basis van de volgende gegevens bepaald worden of de medewerker reeds bestaat in het Core systeem. knownAs lastNameAtBirth lastNameAtBirthPrefix birthDate birthPlace   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.   Endpoints hire, re-hire en contract change Afhankelijk van of het om een interne sollicitant gaat, een onbekende medewerker of een oud-medewerker, wordt een van onderstaande API calls uitgevoerd.   Het endpoint voor de nieuwe medewerker is: POST https://api.youforce.com/recruitment/v1.0/hires Het endpoint voor een nieuw dienstverband is: POST https://api.youforce.com/recruitment/v1.0/persons/{persoonscode}/contracts waarbij {persoonscode} het persoonsnummer van de bestaande medewerker is.   Het endpoint voor een change contract: POST https://api.youforce.com/recruitment/v1.0/persons/{persoonscode}/contracts/{dvb volgnr}/Adjustments waarbij {persoonscode} het persoonsnummer van de bestaande medewerker is en {dvb  volgnr} het dienstverband volgnummer dat gewijzigd moet worden.   Te starten workflow Bij de inrichting van de API wordt door de consultant per endpoint een default workflow geconfigureerd. Als er bij de aanroep van het endpoint vanuit het recruitment systeem geen specifieke workflow wordt meegegeven, dan start het systeem deze default workflow.   Echter om het mogelijk te maken om een afwijkende workflow te starten, kan het recruitment systeem bij de API call de naam van de te starten workflow in header meegeven. Uiteraard moet deze workflow wel in HR Self Service bestaan.   Medewerkergegevens De medewerkergegevens wordt bij alle endpoints in de body meegegeven. Bij een hire worden de persoonsgegevens gebruikt om een nieuw persoon te creëren. Bij een re-hire worden de gegevens gebruikt om de bestaande persoondata bij te werken. Uiteraard worden alleen velden bijgewerkt die ook in de workflow voorkomen. Een veld dat niet in de workflow zit, wordt ook niet bijgewerkt.  Voor een complete lijst van velden, zie onder bij Standaard veldtoewijzing   Attachements Bij elk van de endpoints kan het recruitment systeem ook attachments meegeven. Deze attachments gaan mee in de te starten worklfow.  Wel gelden de volgende restricties Maximaal 20 bijlagen per aanvraag Maximaal 4 MB per bijlage Totale maximale berichtomvang van 28 MB file formaat in API is CotentBase64 Ondersteunde bestandstypes zijn onder meer tekstbestanden, PDF's, Word-documenten, en afbeeldingen.   Eigen rubrieken Alle endpoints kennen ook een structuur om eigen rubrieken mee te geven.     Wijziging van standaard mapping De velden uit de API zijn standaard gemapt naar standaard velden in HR Self Service. Echter het kan voorkomen dat u in HR Self Service ervoor gekozen heeft om bepaalde standaard velden te vullen vanuit een eigen rubrieken.  Dit is soms het geval bij het veld Soort Arbeidsrelatie. In sommige gevallen wordt in HR Self Service gebruik gemaakt van een eigen rubiek, die vervolgens zorgt dat de standaard rubriek Soort Arbeidsrelatie een waarde krijgt.  Door de standaard mapping in de API, zou deze mogelijkheid vervallen. Echter bij de inrichting van de API is het mogelijk om een bepaald API veld naar een andere rubriek te mappen. Deze aanpassing kan echter alleen door de consultant gedaan worden.   Inrichting HSS worklfow n HR Self Service worden de workflows ingericht. In principe kan er gewerkt worden met de workflows uit de best practice van Visma Raet.  Wel wordt geadviseerd om een kopie van de bestaande workflow te nemen en hierin de stappen aan te passen.  Geef de workflow een herkenbare naam. Bijvoorbeeld  “YF API - Nieuwe medewerker” Vink “Uitsluiten startmenu” aan zodat de workflow niet door eindgebruikers gestart kan worden. Kies bij de workflow type voor “Standaard workflow” en niet “nieuwe medewerker”.  Geeft de 1e activiteit in de workflow altijd de naam 'Youforce API' met als knop 'verzenden'.   Standaard veldtoewijzing   API Field   Type Beaufort field lastNameAtBirth Mandatory string P00301 - Geboortenaam lastNameAtBirthPrefix optional string P00302 - Geboortenaam-voorvoegsels KnownAs Mandatory string P01003 - Roepnaam initials Mandatory string P00303 - Voorletters firstNames optional string P01002 - Voornamen gender optional number P00330 - Geslacht conversion 0 – O 1 – M 2 – V 9 - N Indien er geen gender wordt meegegeven, dan wordt standaard de waarde O gebruikt. birthDate Mandatory date P00321 -Geboorte datum birthPlace optional string P01032 - Geboorteplaats birthCountry optional string P01041 - Geboorteland Persoon titlePrefix optional string P00305 - Titulatuur voor de naam titleSuffix optional string P03937 - Titulatuur achter de naam maritalStatus optional string P00329 Burgerlijke staat lastNamePreference optional string P00304 - Gebruik achternaam lastNamePartner optional string P00390 - Partner-naam partnerNamePrefix optional string P00391 - Partner-voorvoegsels socialSecurityNumber optional string P00320 - BSN/Sofi-nummer PhoneNumberHome optional string P01027 - telefoonnr woonadres PhoneNumberMobile optional string P01036 - Telefoonnr mobiel         emailAddressPrivate Mandatory string P01034 - E-mail adres prive         homeAddress - street - number - numberAdditional - postalCode - city - country optional Street - string number - number number addition - string Postcode - string city - string Country - string Home: P01014 street P01016 number P01018 number additional P01020 postal code P01022 city P01024 country postalAddress - street - number - numberAdditional - postalCode - city - country optional Street - string number - number number addition - string Postcode - string city - string Country - string Postal: P00365 Street P00367 number P00368 number additional P00313 postal code P00308 city P00847 country         PayrollClientCode optional string P01103 - Payroll client / Opdrachtgever PayrollInstitutionCode optional string P01104 - Payroll company / Instelling hireDate Mandatory date P00322 - Datum in dienst originalHireDate optional date P00834 -Datum in dienst CAO EndDate optional date P00830 Datum Uitdienst employeeType Mandatory string P01102 - Soort arbeidsrelatie contractType optional string P08259 - Code contract (on)bepaalde tijd probationPeriodEnddate optional date P03406 -proefperiode einddatum organizationUnit Mandatory number P01106 - Hierarchische org. eenheid jobProfile Mandatory string P01107 - Primaire functie amountOfHours optional decimal P01109 - Uren per week parttimePercentage optional decimal P00404 percentage deelbetrekking salary optional decimal P01153 - Salaris hourlyRate optional decimal P01154 - nominaal uurloon payScale optional string P01151 schaal Salaris payScaleStep optional string P00326 Ancienniteit salaris payScaleAmountNo optional number P01152 Inpassingsnr salaris

De WIC API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een Werkbedrijf toegang heeft.  Het autorisatie mechanisme bestaat uit de volgende onderdelen:   Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties. Autorisatie op medewerkers  Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen. Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API.  Beide autorisatie mechanismes moeten door een consultant ingericht worden.     Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd.  Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.   Scope Omschrijving Endpoints Get_Basic Get basic data zoals medewerker- & organisatiedata GET persons GET employments GET employmentTimelines GET organizationUnits GET roleAssignments GET jobProfiles GetPrivateContactDetails Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres. GET persons   Dit betreft de volgende gegevens: ADRESGEVENS Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land TELEFOONNUMMERS Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel EMAILADRES Prive: P01034 - E-mail adres privé GetSocialSecurityNumber Lezen van het Burger Service Number als een privicy gevoelig gegeven GET persons P00320 BSN nummer Get_maternitityLeave Lezen van zwangerschapverlof van medewerkers GET maternityLeave Get_sicknessLeave Lezen van ziekmeldingen van medewerkers GET sickLeave Get_leave Lezen van verlofrechten en verlofopnames van medewerkers GET leaveEntitlements GET leaveHours       Autorisatie op basis van autorisatie filters De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.   Filteren in de API is mogelijk op de volgende Beaufort velden: P01102- Soort Arbeidsrelatie  P01103- Opdrachtgever  P01104- Instelling  P01110 - Code doelgroep  Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden.  Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.   Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.

Het was al mogelijk om de HR Datafeed bestanden met de File API powershell scripts op te halen maar vanaf 19/02/2024 is het ook mogelijk om HR Datafeed bestanden via Bestandsuitwisseling te ontvangen. Hiervoor moet je nog wel in Autorisatiebeheer het juiste recht toekennen.   Volg hier voor de volgende stappen: 1. Ga naar Autorisatiebeheer en zoek de groep waaraan je het Ontvangen HR Datafeed recht wilt toekennen. 2. Klik op de 'Bekijk details'-knop om de bijhorende applicaties in te zien     3. Klik op de knop 'Bewerken'   4a. Als de applicatie Managementinformatie nog niet in de lijst van applicaties voorkomt voeg deze dan toe door op de knop 'Applicatie toevoegen' te klikken.   4b. Selecteer in de popup de applicatie Managementinformatie en zet het vinkje AAN bij het recht 'Ontvang HR Datafeed bestanden van Managementinformatie', en klik vervolgens op de knop 'Toevoegen'. Ga verder met stap 6.   5. Als de applicatie Managementinformatie al wel in de applicatielijst (stap 3) staat klik dan op de knop 'Rechten bewerken' naast de applicatie Managementinformatie en zet in de popup het vinkje AAN bij het recht 'Ontvang HR Datafeed bestanden van Managementinformatie', en klik vervolgens op de knop 'Toevoegen'.   6. Druk op knop 'Opslaan' rechtsonder in het scherm om de wijziging op te slaan.      

Om de veiligheid van jouw en onze systemen en gegevens beter te kunnen waarborgen zijn wij genoodzaakt enige beperkingen te stellen aan de naamgevingsconventie voor bestanden die worden ingezonden naar Youforce m.b.v. IBU, Bestandsuitwisseling en File API (bv Powershell scripts). Vanaf heden zijn bij de naamgeving van in te zenden bestanden alleen de volgende karakters toegestaan: Alle alfanumerieke karakters: Letters (klein en hoofd) en Cijfers underscore (_), min-teken (-), punt (.), komma (,), dollar-teken ($) en ronde haakjes ( en ). Spatie Tevens zijn de volgende bestand-extensies NIET meer toegestaan: action,apk,app,asa,asax,asp,axd,bat,bin,cer,cfc, cfm,cgi,cmd,com,command,cpl,csh,css,dbm,dll,do, exe,gadget,htm,html,inc,inf,ins,inx,ipa,isu,jar, job,js,jse,jsp,jsv,jsw,jsx,ksh,lnk,msc,msi,msp, mst,osx,out,paf,phar,php,php2,php3,php4,php5,php6, php7,phps,pht,phtm,phtml,pif,pl,prg,ps1,rem,reg, rgs,run,scr,sct,shb,shs,shtml,swf,u3p,vb,vbe,vbs, vbscript,workflow,ws,wsf,wsg,wss,xap   LET OP! Bij inzenden met Bestandsuitwisseling en File API (powershell scripts) krijg je direct een foutmelding als je het bestand probeert in te zenden. Bij IBU lijkt het bestand echter normaal ingezonden, echter wordt het bestand verderop in onze systemen afgekeurd. We kunnen voor deze afkeuring helaas geen terugkoppeling geven, maar het bestand wordt niet afgeleverd op de gewenste bestemming.

Bestandsuitwisseling Test file type is gedefinieerd in Bestandsuitwisseling voor test doeleinden. Het bestandstype kan worden gebruikt om de upload en download van dummy-bestanden te testen. Dit file type kan al geautoriseerd worden via Autorisatiebeheer.   Doorloop de volgende stappen om dit file type te gebruiken:   1 - Voeg het rechten “Zend testbestanden naar Bestandsuitwisseling” en “Ontvang testbestanden van Bestandsuitwisseling” toe in Autorisatiebeheer, onder de Applicatie “Bestandsuitwisseling”.   2 - Ga naar de Bestandsuitwisseling applicatie en klik op “Send Files”. 3 - Selecteer het nieuwe bestandstype uit de keuzelijst, selecteer een dummybestand door op "Select Files" te klikken en activeer vervolgens het verzenden door op de "Upload" knop te klikken. 4 - Als het bestand succesvol is ingestuurd verschijnt het in de “Sent Files” lijst.   5 - Een paar seconden later zal het bestand ook verschijnen in de "Receive Files" sectie.  6 - klik op het download-icoon om het te downloaden.    

De IAM API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een Identity & Access Management toegang heeft.  Het autorisatie mechanisme bestaat uit de volgende onderdelen:   Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties. Autorisatie op medewerkers  Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.  Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.     Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd.  Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.   Scope Omschrijving Endpoints Invitation_only Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd.    Get_Basic Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie. Get basic data zoals medewerker- & organisatiedata GET Users GET persons GET employments GET employees GET assignments GET costAllocations GET organizationUnits GET roleAssignments GET jobProfiles Update_Identity Update van het veld Identity in de Youforce portal bij de medewerker. PATCH users GetPrivateContactDetails Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres. GET Employees   Dit betreft de volgende gegevens: ADRESGEVENS Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land TELEFOONNUMMERS Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel EMAILADRES Prive: P01034 - E-mail adres prive Write_Basic Update de HRCoreOnline-velden Email adres werk en of telefoonnummer werk. P01035 - E-mail adres werk P01037  - Telefoonnummer werk   Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.     Autorisatie op basis van autorisatie filters De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.   Filteren in de API is mogelijk op de volgende Beaufort velden: P01102- Soort Arbeidsrelatie  P01103- Opdrachtgever  P01104- Instelling  P01110 - Code doelgroep  P05040 - Selectie rubriek Domain API - IAM  Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden.  Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.   Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.

A step-by-step guide that helps you to select and test an API and after that how to get support and access to data of a Youforce customer.

Dit document beschrijft de 'HelloID - Visma Raet IAM API’-connector. Een koppeling gebaseerd op de Visma Raet IAM API.

Domain model       The Learning model     Data mapping Employee person details attribute description HR Core Beaufort id Unique id for the Person row within the tenant P01001 - Persoonsnummer personId Unique id for the Person row within the tenant P01001 - Persoonsnummer personCode The logical person code of the employee P01001 - Persoonsnummer Initials The initials of the employee. P00303 - Voorletters firstNames The official given names of the employee as stored in the HR Core system P01002 - Voornamen KnowAs The name which is used by the employee as his first name P01003 - Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name P00301 - Geboortenaam lastNameAtBirthPrefix The prefix of the last name at birth P00302 - Geboortenaam-voorvoegsels lastName The last which is currently used  by the employee as his last name P01008 - Samengestelde naam lastNamePrefix The prefix of the last name as used currently P01009 - Samengestelde naam-voorvoegsels nameAssembleOrder Code of the assemble order that the core system uses for the last name.    value E: birthname B: partnername & birthname C: birthname & partnername P: partnername P00304 - Gebruik achternaam partnerName The partner last name P00390 - Partner-naam partnerNamePrefix The prefix of the partner last name P00391 - Partner-voorvoegsels titlePrefix The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera P00305 - Titulatuur voor de naam titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science P03937 - Titulatuur achter de naam gender Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known P00330 - Geslacht Mapping details: M → Male V, F → Female Other values will shown as Not Known birthDate Date of birth P00321 -Geboorte datum deceased Indicated if the employee deceased  Based on the date of deceased. If the employee is deceased the boolean is set to True 0302568 - Datum overlijden UserUID Digital Identity of the user from the portal Ping ID directly from the portal emailAddresses type address List of the addresses of the employee.  The fields are: type like Business, Private, et cetera address   Business: P01035 - E-mail adres werk Prive: P01034 - E-mail adres prive Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country effectiveDate List of the addresses of the employee.  The fields are: type like Home, Post, et cetera street name house number house number additional Location designation Postal code City Region Country code   Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land P01012 adres m.i.v. Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land P01011 Adres m.i.v. phoneNumbers type number list of phone numbers of the employee type like Business, Home, Mobile, et cetera number   Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk     Employee employment details     HR Core Beaufort hireDate The hire date of the employment P00322 - Datum in dienst dischargeDate The end date or discharge date of the employment. P00830 - Datum uit dienst originalHireDate The first hire date or original hire date of an employee within the organization. P00834 -Datum in dienst CAO employmentType Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder" P01102 - Soort arbeidsrelatie jobProfile job profile code of the employment The job profile is a code that refers to the entity job profile P01107 - Primaire functie organizationUnit organization unit of employment. The organization unit is a code that refers to the entity organization units P01106 - Hierarchische org. eenheid workingAmount amountOfWork unitOfWork periodOfWork Work amount of employment.  The amount of work Unit of work that specifies the amount of work like "hours", "days", et cetera Period of work like "week" or "month" amount of work = P01109 - Uren per week* *Beaufort supports only the amount of work in "hours" a "week" contractType Contract type of the employee. It is the code that refers to the entity contract type. P08259 - Code contract (on)bepaalde tijd classification Classification of the employee. It is the code that refers to the entity Classification. P01110 - Code doelgroep Payroll Client Code   P01103 - CEA-nummer Payroll Institution Code    P01104 - Instelling nummer Company PayrollClientCode and PayrollInsituationCode combined   bigNumber   P09165 - Big nummer   Cost allocations       Id Unique id of the cost allocation. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. Unique id of the cost allocation row PersonCode The unique id assigned to the employee Persoonsnummer employmentCode The code of the employment of the person Dienstverband volgnummer sequenceNumber Unique sequence number or row number of the cost allocation within the employee P01131 -regelnummer loonverdeling costTypeCode code of the cost type  P01133 - Kostensoort loonverdeling CostTypeName full name of the cost type Omschrijving kostensoort (referentie tabel) costCenterCode code of the cost center P01134 -Kostenplaats loonverdeling costCenterName full name of the cost center Omschrijving kostenplaats (referentie tabel) costUnitCode code of the cost unit P01135 - Kostendrager loonverdeling costUnitName full name of the cost unit Omschrijving kostendrager (referentie tabel) percentage percentage of the cost allocation P01132 - loonverdeling loonverdeling   Organisation units Attribute Description HR Core Beaufort id Technical ID of the organisation unit   P01061 shortName Code or short name of the Organization Unit P01061 fullName Name or full title of the Organization Unit FullName parentOrgUnit Code of the parent organization unit Organisatie eenheid > Onderdeel van organizationUnitType type or organisation unit code orgUnit Type isBlocked True of false   Address     PhoneNumber     CostCenterCode     Role assignment Attribute description HR Core Beaufort id Unique id of the role assignment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user. Id van het record OrganizationUnitCode Code van organisatorische eenheid P01061 - Operationele org.eenheid shortName The code of the role P01062 - Rol roleName Description of the role P01062 - Rol personCode reference to the person Reference to Person code personID reference to the person Reference to Person ID startDate  start date of the role assignment startDate endDate   endDate    Job Profile Attribute Description HR Core Beaufort shortName Job profile code or short name functie code fullName Job profile name functie naam JobFamily Job family code functiegroep code    

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 Gebruikersbeheer Hiervoor moet je nog wel in Autorisatiebeheer de juiste rechten toekennen.   Volg hier voor de volgende stappen: 1. Ga naar Autorisatiebeheer en zoek de groep waaraan je de rechten wilt toekennen.   2. Klik op de 'Bekijk details'-knop om de bijhorende applicaties in te zien     3. Klik op de knop 'Bewerken'   4. Klik op de knop 'Rechten bewerken' naast de applicatie Youforce Account Beheer en zet in de popup het vinkje AAN bij de rechten  'Zend Organisatie bestanden naar Gebruikersbeheer' en 'Zend Roltoewijzing bestanden naar Gebruikersbeheer', en klik vervolgens op de knop 'Bewerken'.   6. Druk op knop 'Opslaan' rechtsonder in het scherm om de wijziging op te slaan. 7. Als de wijziging is opgeslagen kan het enkele minuten duren voordat de autorisatie in Bestandsuitwisseling is bijgewerkt.     

Publiceer jouw applicatie in de Visma App Store, op die manier kan een Visma Raet-consultant jouw applicatie koppelen aan een klant zonder invitatiecode.