API

Triaspect heeft in december 2022 een API gereleased. Deze API heeft endpoints die gebruikt kunnen worden voor gebruikersbeheer. Dan gaat het om het opvragen, toevoegen, wijzigen en verwijderen van gebruikers en hun relevante kenmerken.

Welke endpoints er zijn en op welke manier je ze kunt gebruiken, kun je vinden in de swaggerdocumentatie: https://swaggerapi-test.triasweb.nl/triaswebapi/index.html

Onderwerpen

Wat is een API?

API staat voor Application Programming Interface. Het zorgt ervoor dat je buiten de schermen van TriasWeb om, toch gegevens kunt uitwisselen met TriasWeb. Een API heeft endpoints. Een endpoint is een webadres waar je alleen bij kunt met een gebruikersnaam, wachtwoord en certificaat. Als je naar dat webadres toegaat (het endpoint aanroept) kun je daarmee gegevens uit TriasWeb ophalen of wijzigen.

Dit kan niet gewoon in Chrome, zoals met andere webadressen. Dit moet via een programma. Dat programma schrijf je zelf, of laat je schrijven door een technische organisatie. Triaspect kan dat niet voor je doen.

Met de TriasWeb API kun je op dit moment (december 2022) gebruikers beheren. Op latere tijdstippen wordt er ook functionaliteit ontsloten om client- en meldingsgegevens uit te wisselen.

Wat kost het?

Het gebruik van de API kost niets. Dat is verwerkt in de licentie die je betaalt voor TriasWeb. Aan het inrichten van de toegang tot de API zijn eenmalige kosten verbonden. Deze kosten betaal je voor het verkrijgen van certificaten voor test-, acceptatie- en productieomgeving en het laten controleren van het ontwerp van het programma. Vooralsnog vallen de kosten in de categorie add-on 1. Je kunt je adviseur vragen wat dat voor jullie organisatie betekent.

Wie bouwt mijn programma?

Om een programma te maken dat de API aanroept, moet je weten wat de API doet. Dat kun je lezen in de swagger-documentatie (https://swaggerapi-test.triasweb.nl/triaswebapi/index.html).

Het programma moet een certificaat kunnen inlezen en endpoints aanroepen. Als je die kennis niet zelf in huis hebt, zijn er organisaties die dat voor je doen.

Triaspect doet dat zelf niet, en heeft daarvoor ook geen partnerorganisatie gezocht. Mocht je op zoek zijn naar een organisatie die je hierbij kan helpen, dan kunnen we je de namen geven van organisaties die dit ook voor andere klanten doen.

Hoe krijg ik (of mijn leverencier) toegang tot de API?

Om te zorgen dat er op een goede manier gebruik gemaakt wordt van de API, hebben we het volgende proces ingericht.

1. Je vraagt als organisatie via de servicedesk toegang aan tot de API op de testomgeving. Hiervoor moeten de relevante IP-adressen toegevoegd worden aan de Triaspectservers. Je krijgt een certificaat, een gebruikersnaam en een wachtwoord van de SD. Hiermee kun je verbinding maken met de test-omgeving van de API. Op deze testomgeving staan alle tabellen die ook beschikbaar zijn op acceptatie en productie. De data in de tabellen is echter gefingeerd. Je kunt hier dus wel kijken wat de structuur is van de data je terugkrijgt, en je kunt kijken of je überhaupt de data kunt benaderen, en of je kunt data toevoegen.

2. Op basis van je tests schrijf je een ontwerp. Van dat ontwerp maak je een uittreksel van een half a-4tje waarin staat wat je wilt bereiken, welke endpoints je wilt aanroepen en hoe vaak je dat per minuut verwacht te doen. Vooralsnog hebben we een maximum van 50 aanroepen per seconde, met een sliding window. Dit ontwerp wordt gecontroleerd door onze technisch consultants. Zij kijken niet naar de functionaliteit, maar naar de techniek en het aantal aanroepen.

3. Als het ontwerp door Triaspect geaccordeerd is, kan toegang tot de acceptatieomgeving aangevraagd worden, weer via de servicedesk. Hiervoor wordt een nieuw certificaat uitgegeven.

4. Je test je programma op de acceptatieomgeving. Omdat hier jullie eigen data op staat, kan het zijn dat er nog wat aangepast moet worden aan het programma. Dat is geen probleem. Er hoeft niet opnieuw een ontwerp opgeleverd te worden.

5. Ben je tevreden met hoe het programma werkt, dan vraag je toegang aan tot de productiedata. Daarvoor krijg je weer een nieuw certificaat. Voordat dat certificaat wordt uitgegeven, doet een technisch consultant een check op het gebruik van de API op de acceptatieomgeving. Als dat nog iets bijzonders oplevert, dan wordt daarover nog even contact opgenomen.

Kan ik de API tegelijkertijd met cliënt- of medewerkersynchronisatie gebruiken?

Ja, dat kan. De API werkt nu alleen nog maar voor medewerkers (gebruikers), dus de clientsynchronisatie staat er helemaal buiten.

Het gebruik van de medewerkersynchronisatie in combinatie met de API kan heel handig zijn (zie hieronder) maar het is wel zaak om goed op te letten dat ze elkaar niet in de weg lopen. Denk bijvoorbeeld aan dat de synchronisatie alle medewerkers deactiveert die niet in de synchronisatie zitten. Dus als je de API gebruikt om nieuwe medewerkers toe te voegen die niet in de synchronisatie zitten, dan worden die bij de eerstvolgende synchronisatie weer gedeactiveerd.

Wat is het verschil tussen de API en de medewerkersynchronisatie?

De medewerkersynchronisatie is een batchverwerking. Dat betekent dat je niet alleen de verschillende medewerkers verwerkt, maar dat er ook nog zoiets is als álle medewerkers in de synchronisatie. Dat is bijvoorbeeld gebruikt bij het ‘vooraf deactiveren’ waarbij alle medewerkers die niet in de synchronisatie aanwezig zijn, deactief worden.

De API verwerkt 1 medewerker per keer. Je kunt met de API geen verband aanbrengen tussen medewerkers. Dat zou wel kunnen in het programma wat je bouwt om de API aan te roepen, maar er is dus geen functie ‘vooraf deactiveren’ die je kunt aanroepen.

Voor de medewerkersynchronisatie geldt nu dat je er minder mee kunt dan met de API. Met de API kun je bijvoorbeeld een gebruiker als hoofdverantwoordelijke koppelen aan een organisatieonderdeel. Of je kunt een of meerdere rollen koppelen aan een gebruiker. Dat kan in de medewerkersynchronisatie niet, en dat zal ook niet meer ontwikkeld worden door Triaspect.

Welke endpoints moet ik aanroepen om de medewerkersynchronisatie na te bouwen met de API?

De medewerkersynchronisatie heeft een aantal kenmerken.

1. vooraf deactiveren (alleen medewerkers actief die in de synchronisatie zitten)

2. aantal dagen na datum uit dienst (pas deactiveren nadat de medewerker een maand uit dienst is)

3. automatisch activeren (alle medewerkers die in de synchronisatie zitten actief maken)

4. koppelen aan organisatieonderdelen in TriasWeb (ivm autorisatiescope)

Als je al deze dingen wilt doen met je programma met de API, dan kun je zo te werk gaan.

• Zorg dat je een connectie kunt maken met de API. Hiervoor moet je het certificaat meesturen met je aanroepen.

• Haal alle gebruikers individueel uit TriasWeb (op basis van het emailadres).

• Zet ze in het geheugen van je programma. Een endpoint waarmee in 1 keer van alle gebruikers de identificatie kan worden opgehaald wordt nog gemaakt.

• Je moet een lijst hebben met alle medewerkers die actief moeten zijn of worden in TriasWeb. In deze lijst moet al kenmerk 2 opgenomen van hierboven zijn. Deze lijst verwerk je in je programma:

  • Vergelijk de gebruiker uit de lijst met de medewerker in het geheugen.

  • Als er een verschil is, dan roep je het update-endpoint aan voor de gebruiker in TriasWeb. Als je wilt geef je rollen (alleen beschikbaar in API), koppelcodes (kenmerk 4), en hoofdverantwoordelijkheid voor een OE (alleen beschikbaar in API) mee. Activeer de gebruiker om kenmerk 3 te realiseren.

  • Verwijder daarna de medewerker uit het geheugen.

  • Als er geen verschil is, activeer de gebruiker om kenmerk 3 te realiseren. Daarna verwijder je de medewerker uit het geheugen.

  • Als je nog medewerkers in je lijst hebt die je niet in je geheugen hebt, dan maak je een nieuwe gebruiker aan in TriasWeb.

  • Als je alle medewerkers uit de lijst vergeleken hebt met de gebruikers in TriasWeb, dan roep je het verwijder-endpoint aan voor de overgebleven gebruikers in het geheugen (kenmerk 1).

Hoe kan ik de API slim inzetten in combinatie met de medewerkersynchronisatie?

Je kunt tijdelijke accounts voor ZZP-ers aanmaken via de API, terwijl de medewerkersynchronisatie gewoon de ‘normale’ accounts afhandelt. Dat kan bijvoorbeeld zo:

• Zorg voor een lijst met alle actuele ZZP-ers. Deze moet je twee keer verwerken, met (bijvoorbeeld) een week ertussen.

• Per ZZP-er roep je de endpoint GET /api/users?method=email&value=iemand@organisatie.nl op basis van de identificatie (email in dit voorbeeld) aan.

• Als je 404 terugkrijgt is deze persoon niet aanwezig in TriasWeb. Dan roep je de PUT /api/users aan met de relevante parameters in de request body. Zorg ervoor dat handmatig deactiveren aangezet wordt ("isDeactivationManual": true) zodat de medewerkersynchronisatie deze gebruiker niet verwijdert.

• Als de gebruiker bestaat, dan update je indien nodig. Zorg ervoor dat handmatig deactiveren aangezet wordt (zet "isDeactivationManual": true in de request body) zodat de medewerkersynchronisatie deze gebruiker niet verwijdert.

• Na een week (of hoe lang je ook wilt) verwerk je de lijst nogmaals, maar verwijder je de gebruikers die op de lijst staan, uit TriasWeb. Deactiveer de gebruiker met endpoint
  /api/users/close-account?method=email&value=iemand@organisatie.nl

• Voer het programma meteen weer uit met een nieuwe lijst met ZZP-ers.