Zoeken
Mijn Communities
Help

Aannemen medewerkers met de recruitment API

19-08-2024 16:31 (Bijgewerkt op 16-09-2024)
  • 3 Antwoorden
  • 1 kudos
  • 528 Weergaven

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.

RenSanders_0-1723732054292.png

 

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
Labels:
Opmerkingen
Bas Menken - Gemeente Leiden
CHAMPION ***
‎20-08-2024 07:59
door 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
ACTIVE CONTRIBUTOR ***
‎20-08-2024 08:59
door 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
VISMA
VISMA
‎20-08-2024 14:00
door 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).

Medewerkers
Choose your region:
Choose your Region
Go