Gegevens uit de backoffice importeren in de onboarding

In het artikel Onboarding: Importdefinitie (Stap 5) kun je lezen dat je gegevens uit een bestand of een backoffice kunt importeren in de onboarding. In dit artikel wordt ingegaan op het importeren van gegevens uit de backoffice. Meer informatie over het importeren van gegevens uit een bestand vind je in het artikel Gegevens uit een bestand importeren in de onboarding.

Je kunt gegevens uit een bestand of de backoffice importeren in de flexkracht-onboarding en in de inlener-onboarding. In dit artikel worden de volgende onderwerpen behandeld.

• Algemene instellingen
• Velden koppelen
  • Vrije velden
  • Validatiefouten
• Onboardingen importeren
  • Webservice
  • XML bericht
• Onboarding status via de webservice
• Voorbeelden XML

Algemene instellingen

Ga naar Start > Flexkracht-onboarding > Onboardingstypes of Start > Inlener-onboarding > Onboardingstypes. Open het onboardingstype waarvan je de importdefinitie wilt instellen. Klik op Bewerken en daarna op 5 Importdefinitie.

Selecteer onder Algemeen bij Type Backoffice en kies bij de Backoffice voor een beschikbare backoffice. Je krijgt daarna de te importeren velden van de gekozen backoffice beschikbaar.

Eventueel kun je aangeven dat de onboarding automatisch wordt doorgezet. Zie voor meer informatie hierover Onboarding: Importdefinitie (Stap 5).

Velden koppelen

Om de gegevens uit de backoffice succesvol te kunnen uitlezen, moet er per veld worden geselecteerd welke 'waarde' er moet worden geïmporteerd, ook wel mapping genoemd. De bedoeling is de ingevulde waarde te 'mappen' met het veld welke ook in de inschrijving is ingericht. 

Onder Backofficeveld staan de gegevens die vanuit de backoffice worden opgestuurd naar e-UUR. 

Per veld moet je deze koppelen aan het Inschrijvingsveld. Je kunt hier selecteren uit de velden die in het formulier onder 2 Formulierconfiguratie zijn ingesteld.

Het is niet verplicht om alle velden te koppelen. Koppel je een veld niet, dan worden die gegevens niet in de onboarding geïmporteerd, ook als zij wel op de te importeren gegevens uit de backoffice staan. 

Vrije velden

Onder Vrije velden kun je zelf velden toevoegen. Dit is vergelijkbaar met de vrije velden bij de exportdefinitie. Vul onder Vrijveld ID de naam van de XML tag in. Deze tag wordt verwacht binnen de UserArea.

Voorbeeld

Voor het Vrijveld ID Leeftijd zal de XML eruit moeten zien zoals hieronder. Binnen de XML zal een waarde ‘32’ worden gevonden.

<UserArea>
  <Leeftijd>32</Leeftijd>
</UserArea>

In onderstaand geval vindt Vrijveld ID Leeftijd nog steeds 32. Dat komt omdat ‘Leeftijd’ als direct “kind” binnen de UserArea beschikbaar is. 

<UserArea>
  <Huisdier><Hond><Leeftijd>3</Leeftijd></Hond></Persoon>
  <Leeftijd>32</Persoon>
  <Persoon><Leeftijd>32</Leeftijd></Persoon>
</UserArea>

In onderstaand geval is het onduidelijk wat Vrijveld ID Leeftijd oplevert. Dat zal zijn: ‘32’ of '3'.

<UserArea>
  <Huisdier><Hond><Leeftijd>3</Leeftijd></Hond></Persoon>
  <Persoon><Leeftijd>32</Leeftijd></Persoon>
</UserArea>

Het is mogelijk om dit specifiek aan te geven. Stel dat we de leeftijd van de persoon willen hebben. Gebruik dan Vrijveld ID Persoon/Leeftijd. 

Ook onderstaande is mogelijk. De leeftijd wordt doorgegeven als attribuut. Gebruik hier om de leeftijd uit te lezen Vrijveld ID Persoon/@leeftijd.

<UserArea>
  <Persoon leeftijd="32">Jan</Persoon>
</UserArea>

Zie voor meer informatie over de naamgeving https://www.w3schools.com/xml/xpath_syntax.asp. 

Koppel de velden aan elkaar en vul ook de andere gegevens van het onboardingstype in. Klik daarna op Opslaan.

Validatiefouten

Bij het importeren van vrije velden kan het zijn dat er sprake is van validatiefouten waardoor de onboarding uitvalt. Als dit het geval is, dan kun je voor de flexkracht-onboarding in de log zien welke waarde niet goed is. Ga naar Start > Applicatiebeheer > Log. 

Het Bericht fwonboarding webservice resultaat: Fout (290) geeft aan dat de data in de XML niet goed is. Open het bijbehorende Bericht De onboarding bevat validatie fouten. 

Onder Log bericht kun je lezen welke waarde bij welk veld fout is. Daarnaast vind je onder Toevoeging 2 het externe nummer van het onboardingstype. Onder Toevoeging 5 vind je het externe nummer van de inlener (staffingCustomerId), eventueel het externe nummer van de bemiddelaar (MediatorId) en het externe nummer van de flexkracht (HumanResourceId).

Met deze gegevens kun je nakijken welke flexkracht-onboarding uitvalt en de gegevens aanpassen.

Onboardingen importeren

Als het onboardingstype met de importdefinitie is ingericht, kunnen er vanuit de backoffice gegevens naar een onboarding worden verstuurd. Zodra via de webservice gegevens van de onboarding worden opgestuurd naar e-UUR, wordt er automatisch een nieuwe onboarding aangemaakt in e-UUR. 

Webservice

Voor het importeren van de onboardingen gebruik je de webservice. De webservice heeft 4 argumenten nodig; username voor de gebruikersnaam, password voor het wachtwoord, message met het hieronder beschreven XML bericht en een callfrom die gevuld kan worden met een beschrijvende naam van het pakket of de organisatie die het bericht verstuurd. 

Een flexkracht-onboarding kan door zowel de leverancier als de bemiddelaar worden geïmporteerd via de webservice.

Meer informatie over de webservice vind je in het artikel Inleiding SOAP webservice. 

XML bericht

Het XML bericht dat naar de webservice verstuurd moet worden, is een <HumanResource> HR-XML bericht. Dit is de XML voor het opsturen van een flexkracht naar e-UUR. Zie ook het artikel Flexkracht webservice voor meer informatie over de XML van de flexkracht. 

De functie die moet worden gebruikt, is voor de flexkracht-onboarding de UpHrOnboarding en voor de inlener-onboarding de UpScOnboarding. Voor de onboarding moet daarnaast aan de <UserArea> het volgende worden toegevoegd.

<!--extern number onboardingstype-->
<OnboardingTypeId>1001</OnboardingTypeId> 

Daar moet het Externe nummer van het te gebruiken onboardingstype worden ingevuld. Als de onboarding dan binnenkomt in e-UUR, wordt het onboardingstype uit de XML gebruikt. 

Nadat de XML e-UUR binnenkomt, wordt de onboarding gestart. Ga hiervoor naar Start > Flexkracht-onboarding > Flexkracht-onboardingen en open de onboarding. Gegevens uit de XML zijn nu ingevuld in de onboarding.

Bij de Status van de onboarding kun je zien of de onboarding is geïmporteerd via de backoffice of frontoffice. Bij Opmerking staat dan Geïmporteerd via webservice als de importdefinitie in het onboardingstype is ingesteld op Backoffice Algemeen/SETU. Als hier een specifieke backoffice is ingesteld, dan staat er Geïmporteerd vanuit [naam backoffice]. 

Vul de onbrekende gegevens in. De onboarding kan nu verder het proces in e-UUR volgen zoals is ingesteld in het onboardingstype.

Onboarding status via de webservice

Via de webservice kun je ook de status van een flexkracht-onboarding opvragen. De webservice functie GetFwOnboardingStatus is (alleen) beschikbaar voor de bemiddelaargebruiker. Hiermee kan de bemiddelaar de status van de onboarding opvragen die hij heeft aangeboden via de functie UpHrOnboarding.  

De volgende criteria kun je meegeven, waarvan er minimaal één verplicht is. 

• InternetEmailAddress; het e-mailadres van de flexkracht.
• OnboardingTypeId; het externe nummer van het onboardingstype.
• ImportDate; de datum waarop de onboarding is aangeboden via UpHrOnboarding.

<GetFwOnboardingStatus>
    <!-- InternetEmailAddress: The email address sent with the onboarding -->
    <InternetEmailAddress>nieuwemedewerker@akyla.nl</InternetEmailAddress>
    <!-- OnboardingTypeId: The onboardingtype sent with onboarding -->
    <OnboardingTypeId>120</OnboardingTypeId>
    <!--ImportDate: The date when the onboarding was sent to e-UUR -->
    <ImportDate>12-03-2021</ImportDate>
</GetFwOnboardingStatus>

Specifieke foutcodes die je kunt krijgen zijn de volgende.

• 200: Er zijn verplichte velden niet ingevuld (mogelijk door het ontbreken van een criterium).
• 201: Het aangeleverde XML bestand is niet valide opgebouwd.
• 900: Niet geautoriseerd. Verkeerde gebrukersgegevens of het betreft geen bemiddelaar.
• 500: Er is een interne fout opgetreden, zonder duidelijke oorzaak.

De webservice geeft voor elke gevonden onboarding de status terug. Tags worden altijd weergegeven. Als de waarde onbekend is, blijft de betreffende tag leeg. Zie de bijlage Flexkracht-onboarding - status voor een voorbeeld.

Voorbeelden XML

Als bijlage vindt je een voorbeeld van een XML met het externe nummer van het onboardingstype ingevuld. Dit is bijlage: Flexkracht-onboarding - basis.xml. Deze XML bevat alleen een aantal basisgegevens. 

Bijlage: Flexkracht-onboarding - extra.xml bevat ook onderstaande gegevens.

• Uren per week
• Dagen per week
• Contract type
• Contract startdatum
• Contract einddatum
• Functie
• Vakantiewerker Ja/Nee
• Kostenvergoeding Ja/Nee
• Bruto uurloon
• Naam Inlener
• Contactpersoon Inlener

Bijlage: Flexkracht-onboarding - status.xml is een voorbeeld voor het opvragen van de status van een flexkracht-onboarding.

Bijlage: Inlener-onboarding - basis.xml is een voorbeeld van een inlener-onboarding.