Om de webservice aan te roepen moet er gebruik worden gemaakt van SOAP, ofwel Simple Object Access Protocol. Middels dit protocol kunnen XML-berichten naar/van de e-UUR-webservice worden verstuurd/ontvangen. Om gebruik te kunnen maken van deze functionaliteit moet de ontwikkelaar op de hoogte zijn van de volgende zaken:
- Middels welke URL de webservice beschikbaar is;
- Welke functie van de webservice aangeroepen moet worden;
- Wat de inhoud van het XML-bericht moet bevatten;
- Een gebruikersnaam en wachtwoord om in te kunnen loggen op de webservice.
1. De URL van de webservice is gekoppeld aan de URL van de e-UUR-omgeving waar de informatie naar gezonden moet worden. Indien de e-UUR-omgeving te vinden is op http://xyz.flexportal.eu/, dan is de webservice-URL als volgt: http://xyz.flexportal.eu/service.php.
2. Als deze URL geopend worden met een browser, wordt een WSDL-omschrijving van de verschillende functies getoond. Hier kan meer gedetailleerde informatie van de functies opgevraagd worden. Hieronder vind je ook een overzicht van beschikbare functies.
3. De inhoud van de XML-berichten wordt in de verschillende artikelen in de map SOAP webservice toegelicht. In de artikelen zijn XML-voorbeelden met commentaar beschikbaar.
4. De benodigde gebruikersnaam en wachtwoord worden voor de meeste webservices aangeleverd door Akyla. Sommige webservices worden als inlener aangeroepen en niet als leverancier. De inloggegevens voor deze webservices kunnen door de leverancier aangeleverd worden. In de uitleg van deze webservices wordt expliciet benoemd dat er inlener-specifieke inloggegevens benodigd zijn.
Beschikbare functies
De webservice op service.php biedt de volgende functionaliteit:
- UpStaffingCustomer: een inlener opsturen richting e-UUR;
- UpHr: een flexkracht opsturen richting e-UUR;
- UpAssignment: een plaatsing opsturen richting e-UUR;
- UpReservations: reserveringen opsturen richting e-UUR;
- GetNewHumanResource: een nieuwe of gewijzigde uitzendkracht ophalen uit e-UUR;
- GetLoginURL: het opvragen van een Single Sign-on URL;
- GetNewTimecard: een urenbriefje ophalen uit e-UUR;
- UpTimecardImport: een urenbriefje ter import aanbieden aan e-UUR;
- UpPayslip: een loonstrook opsturen richting e-UUR;
- UpInvoice: een factuur opsturen richting e-UUR;
- UpDocument: een document opsturen richting e-UUR;
- GetNewDocument: een nieuw document ophalen uit e-UUR.
- GetSpecialTimecard: een urenbriefje met speciale status ophalen uit e-UUR
- PostNewTimecard: een nieuw urenbriefje plaatsen
- UpStaffingOrganization: een bemiddelaar opsturen richting e-UUR
- UpRegistration: een inschrijving opsturen richting e-UUR
- UpCao: een Cao opsturen richting e-UUR
- UpFunctiongroup: een functiegroep opsturen richting e-UUR
- UpStaffingCustomerFunctionGroup: een inlener functiegroep opsturen richting e-UUR
- UpInvoiceCustom: een maatwerk factuur opsturen richting e-UUR
- UpErroneousExport: een foutenrapport opsturen richting e-UUR
- UpException: een exceptierapportage opsturen richting e-UUR
- UpStaffingCustomerDelegate: een inlenergebruiker opsturen richting e-UUR
- UpMediatorDelegate: een bemiddelaar gebruiker opsturen richting e-UUR
- GetHumanResource: een uitzendkracht ophalen uit e-UUR
- GetStaffingCustomer: een inlener ophalen uit e-UUR
- GetAssignments: een plaatsing ophalen uit e-UUR
- GetAssignmentsAlteration: een gewijzigde plaatsing ophalen uit e-UUR
- UpApproveTimecard: een goedgekeurd urenbriefje opsturen richting e-UUR
- UpInternalMessage: een intern bericht opsturen richting e-UUR
- UpMediator: een bemiddelaar opsturen richting e-UUR
- UpHrOnboarding: een flexkracht in de onboarding (importeren) opsturen richting e-UUR
De webservice gebruiken
Elke aanroep van een webservicefunctie werkt met enkel één object. Je kunt per aanroep dus maar één object opsturen of één object ophalen.
Voor het opsturen van gegevens, wat in e-UUR-termen 'Provisioning' heet, geldt dat een XML met data opgestuurd wordt. De webservice probeert deze XML dan te verwerken en stuurt een code terug die de status van verwerking weergeeft. In het artikel Overzicht foutcodes en betekenis vind je een overzicht van de codes.
Voor het ophalen van gegevens, wat in e-UUR termen 'Retrieval' heet, geldt dat een XML met data opgehaald wordt. Als er geen XML wordt opgehaald maar een code 100, betekent dit dat alle gegevens opgehaald zijn. Om dus bijvoorbeeld alle urenbriefjes op te halen van de e-UUR-omgeving moet de functie GetNewTimecard aangeroepen worden tot de code 100 geretourneerd wordt.
Volgorde opsturen gegevens
De volgorde waarin gegevens opgestuurd worden is van belang. Een plaatsing is bijvoorbeeld gekoppeld aan een inlener en aan een uitzendkracht. Om de plaatsing op te kunnen sturen moeten eerst de inlener en de uitzendkracht opgestuurd worden.
Ontbreken gegevens
De webservice verwacht complete gegevens van de objecten die opgestuurd worden. Als een bepaald component van een object ontbreekt, gaat de webservice er vanuit dat dit component niet langer op het object van toepassing is. Deze wordt dus in e-UUR als verwijderd gekenmerkt. Op deze manier is de webservice in staat om verschillen te detecteren tussen het opgestuurde object en het object dat reeds in e-UUR bekend is.
We nemen de afdeling van een inlener als voorbeeld. Als een inlener wordt opgestuurd met afdelingen A en B, worden dit de twee afdelingen van de inlener. Als dezelfde inlener later nog een keer wordt opgestuurd, deze keer met afdelingen A en C, dan wordt afdeling C toegevoegd aan de inlener en wordt afdeling B als verwijderd gekenmerkt.
Wanneer een object in zijn totaliteit niet wordt opgestuurd, verandert het object ook niet.
Webservice status codes
In het artikel Overzicht foutcodes en betekenis vind je een overzicht van de codes. De meest voorkomende foutcode, met name tijdens het ontwikkelen van een koppeling, is code 200. Dit betekent dat de XML niet opgebouwd is volgens de standaard die is omschreven in de HR-XML XSD. Deze XSD-bestanden kunnen door Akyla worden aangeleverd. Over het algemeen is het verstandig om de XML op te bouwen op eenzelfde manier als het voorbeeld-XML. In de verschillende artikelen onder de zoekopdracht 'Soap' vind je voorbeelden van een XML.
Wanneer je een code 900 krijgt, kloppen de door jou gebruikte gebruikersnaam en wachtwoord niet of heeft deze niet de juiste privileges. Mocht dit voorkomen en heb je deze gegevens wel gecontroleerd, dan kun je contact opnemen met Akyla.