Recruitment API: nieuwe endpoints voor aannemen kandidaat

[#1]

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.