Aannemen medewerkers met de recruitment API

[#1]

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

[Bas Menken - Gemeente Leiden]

Interessante ontwikkeling, wat ik mij afvraag is hoe jullie omgaan met meerdere organisaties binnen 1 omgeving. Het kan namelijk zo zijn dat iemand al heeft gewerkt of nog werkt bij organisatie x maar nu bij organisatie Y heeft gesoliciteerd en in dienst komt.

Ook al bestaat de medewerker dan al in beaufort, er moet dan geen nieuw dienstverband worden aangemaakt maar een nieuw personeelsnummer.

[Raymond_de_Rozario]

Dit klinkt heel interessant. Begrijp ik het nu goed dat deze api ook kan communiceren met andere Recruitment systemen, ook als ze niet van Visma zijn? Welke systemen hebben jullie al succesvol getest? Zijn hier al connectoren voor?

[Wesly van Horssen]

@Raymond_de_Rozario Ja de recruitment API kan ook ingezet worden bij recruitment-systemen die niet van Visma zijn. Ubeeo heeft de connector al gereed en in gebruik, bij andere recruitment-systemen zie je dat de connector wordt gemaakt door een partner van het betreffende recruitment-systeem. Stuur me gerust een e-mail als je de status van een of meerdere recruitment-systemen wilt weten (wesly.vanhorssen@visma.com).