EF2GO GraphQL API

De EF2GO GraphQL API biedt een set aan operaties waarbij informatie met EF2GO kan worden opgevraagd en of worden gewijzigd. De EF2GO GraphQL API kan worden ingesteld per “omgeving” en bestrijkt dan ook de scope tot deze omgeving. Eventuele werkmaatschappij parameters kunnen afhankelijk van de methode worden toegevoegd.

Activeren koppeling

Via Sales kan de koppeling worden geactiveerd binnen jouw omgeving. Vervolgens kun je in EF2GO via ‘Beheer > Koppelingen > Easyflex2go’ de koppeling inschakelen.
Vanuit hier kun je een token aanmaken. Deze tokens kun je een duidelijke naam geven, afschermen voor een bepaald IP adres en actief stellen tot een bepaalde datum.
Daarnaast vind je hier ook het endpoint voor de koppeling (KLANTNAAM.easyflex2go.nl/graphql) en kun je het schema downloaden.
De GraphQL API maakt gebruik van het HTTP POST protocol en dient te worden voorzien van een Authorization header met een Bearer Token.
Indien je gebruikt maakt van Postman kun je dit schema eenvoudig importeren. Na het importeren vind je de methodes die kunnen worden gebruikt.

Binnen de geïmporteerde collectie kun je de globale variabele instellen.

Via Insomnia krijg je na het instellen van het endpoint een mogelijkheid om het schema te downloaden. Zodra het schema is gedownload kun je op het knopje schema drukken om de documentatie te bekijken.
Daarnaast zal Insomnia zorgen voor type hints bij het creëren van de queries.

Mutations

De mutatie berichten bestaan uit twee verschillende objecten. In het eerste object geeft men alle wenselijk mutaties mee. In het tweede object geeft men de gewenste retourvelden aan.

saveCandidate

Operatie voor het opslaan en bewerken van een inschrijving. Binnen deze operatie is enkel de achternaam verplicht. Alle overige velden kunnen optioneel worden meegegeven. De validatieregels voor de velden zijn terug te vinden in het schema.
Indien de ID parameter wordt meegegeven aan deze operatie wordt de kandidaat ge-update. Indien een veld niet wordt meegegeven wordt hij niet overschreven. Voor het resetten van een waarde kan men een null waarde meegeven.

Voorbeeld:

Request:
mutation {
  saveCandidate(
      gender: 20092
      email: "test@email.nl"
      phone: "0612345678"
      firstname: "Johan"
      marital_condition: 21662
      initials: "JB"
      insertion: "de"
      lastname: "Wit"
      birthdate: "1984-01-01"
      bsn: "252243614"
      iban: "NL04RABO7070755813"
      bic: "RABO4U"
      identification_type: 21583
      identification_number: "NL123456"
      identification_enddate: "2021-10-01"
      nationality: "NL"
      taxreduction: 20381
      taxreduction_date: "2021-02-02"
      birthcountry: "NL"
      chamber_of_commerce_number: "78789792"
      vat_number: "NL999999299B99"
      domicilyaddress: {
        street: "Testraat "
        housenumber: 1
        housenumberaddition: "BIS"
        postal: "1234 AB"
        city: "Oosterhout"
        country: "NL"
      }
      residentialaddress: {
        street: "Testraat "
        housenumber: 2
        housenumberaddition: "GIS"
        postal: "1234 AB"
        city: "Oosterhout"
        country: "NL"
      }
    
  ) {
    id
    gender
    firstname
    initials
    lastname
    insertion
    email
    phone
    marital_condition
    birthdate
    birthplace
    birthcountry
    bsn
    iban
    bic
    identification_type
    identification_number
    identification_enddate
    nationality
    taxreduction
    taxreduction_date
    chamber_of_commerce_number
    vat_number
    domicilyaddress {
      street
      housenumber
      housenumberaddition
      postal
      city
    }
    residentialaddress {
      street
      housenumber
      housenumberaddition
      postal
      city
    }
  }
}

Response:
{
    "data": {
        "saveCandidate": {
            "id": "909",
            "gender": 20092,
            "firstname": "Johan",
            "initials": "JB",
            "lastname": "Wit",
            "insertion": "de",
            "email": "test@email.nl",
            "phone": "0612345678",
            "marital_condition": 21662,
            "birthdate": "1984-01-01",
            "birthplace": null,
            "birthcountry": "NL",
            "bsn": "252243614",
            "iban": "NL04RABO7070755813",
            "bic": "RABO4U",
            "identification_type": 21583,
            "identification_number": "NL123456",
            "identification_enddate": "2021-10-01",
            "nationality": "NL",
            "taxreduction": 20381,
            "taxreduction_date": "2021-02-02",
            "chamber_of_commerce_number": "78789792",
            "vat_number": "NL999999299B99",
            "domicilyaddress": {
                "street": "Testraat",
                "housenumber": 1,
                "housenumberaddition": "BIS",
                "postal": "1234 AB",
                "city": "Oosterhout"
            },
            "residentialaddress": {
                "street": "Testraat",
                "housenumber": 2,
                "housenumberaddition": "GIS",
                "postal": "1234 AB",
                "city": "Oosterhout"
            }
        }
    }
}

deleteCandidate

Operatie voor het verwijderen van een kandidaat. Als parameter moet hier het ID van de kandidaat in. Dit ID vindt men terug op de detailpagina van de inschrijving onder het kopje flexwerker. De aangegeven retour waardes worden vervolgens nog een “laatste” keer retour gedaan.

Voorbeeld:

Request:
mutation deleteCandidate ($id: ID!) {
    deleteCandidate (id: $id) {
        id
        gender
        firstname
        initials
        lastname
        insertion
        email
        marital_condition
        birthdate
        bsn
        iban
        bic
        phone
        identification_type
        identification_number
        identification_enddate
        nationality
        taxreduction
        taxreduction_date
        domicilyaddress {
            street
            housenumber
            housenumberaddition
            postal
            city
            country
        }
        residentialaddress {
            street
            housenumber
            housenumberaddition
            postal
            city
            country
        }
        birthplace
        birthcountry
        chamber_of_commerce_number
        is_foreign_coc
        vat_number
        remark
        email_sent
        created_at
        updated_at
    }
}

Response:
{
    "data": {
        "deleteCandidate": {
            "id": "909",
            "gender": 20092,
            "firstname": "Johan",
            "initials": "JB",
            "lastname": "Wit",
            "insertion": "de",
            "email": "test@email.nl",
            "marital_condition": 21662,
            "birthdate": "1984-01-01",
            "bsn": "252243614",
            "iban": "NL04RABO7070755813",
            "bic": "RABO4U",
            "phone": "0612345678",
            "identification_type": 21583,
            "identification_number": "NL123456",
            "identification_enddate": "2021-10-01",
            "nationality": "NL",
            "taxreduction": 20381,
            "taxreduction_date": "2021-02-02",
            "domicilyaddress": null,
            "residentialaddress": null,
            "birthplace": null,
            "birthcountry": "NL",
            "chamber_of_commerce_number": "78789792",
            "is_foreign_coc": false,
            "vat_number": "NL999999299B99",
            "remark": null,
            "email_sent": null,
            "created_at": "2021-05-18 12:10:36",
            "updated_at": "2021-05-18 12:10:36"
        }
    }
}

saveCandidateRequest

Operatie voor het opslaan van een inschrijving waarbij de gegevens aangeleverd worden door de flexwerker. In deze operatie zijn de velden; geslacht, voornaam, achternaam, voorletters, e-mail, telefoonnummer, aangeleverd door en e-mailtemplate verplicht. Alle overige velden kunnen optioneel worden meegegeven. De validatieregels voor de velden zijn terug te vinden in het schema.

Voorbeeld:

request:
mutation {
  saveCandidateRequest(
    gender: 20091
    firstname: "Johan"
    lastname: "Wit" 
    initials: "JB"
    insertion: "de" 
    email: "test@email.nl" 
    phone: "0612345678"
    candidateProfileId: 2,
    deliveredBy: 4,
    emailTemplateId: 1,
    preferredLanguageCode: "NL"
  ) {
    id,
    gender
    firstname
    initials
    lastname
    insertion
    email
    phone
    candidate_id
    flexworker_request_id
  }
}

response:
{
    "data": {
        "saveCandidateRequest": {
            "id": "47",
            "gender": 20091,
            "firstname": "Johan",
            "initials": "JB",
            "lastname": "Wit",
            "insertion": "de",
            "email": "test@email.nl",
            "phone": "0612345678",
            "candidate_id": null,
            "flexworker_request_id": null
        }
    }
}

Queries

Met de GraphQL queries is het mogelijk om data op te halen uit EF2GO. De gegeven velden en hun relaties zijn terug te vinden in het GraphQL schema. Alle velden zijn optioneel opvraagbaar alsmede hun relaties.

Candidates

Operatie voor het ophalen van kandidaten. Deze methode werkt met een paginator en retourt maximaal 100 kandidaten. Daarnaast kan er gebruik worden gemaakt van een sortering op achternaam en ID.

Voorbeeld:

query {
  candidates(orderBy: [{ column: ID, order: DESC }] first: 10) {
    data {
        id
        gender
        firstname
        initials
        lastname
        insertion
        email
        marital_condition
        birthdate
        bsn
        iban
        bic
        phone
        identification_type
        identification_number
        identification_enddate
        nationality
        taxreduction
        taxreduction_date
        residentialaddress {
            street
            housenumber
            housenumberaddition
            postal
            city
            country
        }
        birthplace
        birthcountry
        chamber_of_commerce_number
        is_foreign_coc
        vat_number
        remark
        email_sent
        created_at
        updated_at
    }
    paginatorInfo {
        count
        currentPage
        firstItem
        hasMorePages
        lastItem
        lastPage
        perPage
        total
    }
  }
}

Opmerking Postman Candidates methode

Uit ervaring blijkt dat Postman de variabelen niet helemaal correct importeert. Dit is echter eenvoudig aan te passen door ervoor te zorgen dat er een array wordt meegegeven i.p.v. van een object.

Verander:

{
  "orderBy": {
    "column": "LASTNAME",
    "order": "ASC"
  },
  "first": 10,
  "page": 1
}

naar:

{
  "orderBy": [{
    "column": "LASTNAME",
    "order": "ASC"
  }],
  "first": 10,
  "page": 1
}

Candidate

Deze operatie maakt het mogelijk om een enkele kandidaat op te halen op basis van het ID. Deze heeft als parameter ID. En kan mogelijk objecten retouren van het type Candidate (zie het schema voor details.)