Wat de TOPdesk-API wel en niet teruggeeft

De TOPdesk-API is netjes gedocumenteerd en doet wat je verwacht. Maar er zitten een paar dingen in die je pas ontdekt als je er een tijdje mee werkt, en die je rapportageplannen kunnen omgooien. Dit kwam naar boven bij het bouwen van een dashboard erop.

Wat er zonder gedoe uit komt

Meldingen zijn het makkelijkst. Je haalt ze op met hun categorie en subcategorie, status, prioriteit, lijn, behandelaarsgroep, behandelaar, aanmelddatum, afhandeldatum en de SLA-gegevens. Genoeg voor instroom, doorlooptijd, SLA-naleving per prioriteit en de vraag hoe lang het oudste openstaande ding al ligt.

Wijzigingen en de onderliggende activiteiten komen er ook uit, net als assets met hun type, locatie en status, en kennisitems met hun status en of ze zichtbaar zijn in de Self Service Portal. Behandelaars kun je opvragen inclusief hun rechtengroepen, wat handiger is dan het klinkt: daarmee zie je welke betaalde accounts al maanden niets doen.

Wat er níet uit komt: de geschiedenis

Dit is de belangrijkste, en degene die de meeste plannen in de war stuurt. De API geeft je de huidige stand van een melding. Welke behandelaarsgroep hem nu heeft, welke status hij nu heeft, bij wie hij nu ligt.

Wat je niet krijgt is het pad ernaartoe. Je kunt niet opvragen dat melding 4711 eerst bij de eerste lijn lag, toen elf dagen bij netwerkbeheer, en daarna terugkwam. Die overdrachten zitten wel in TOPdesk zelf, maar de API levert ze niet uit.

Dat betekent iets vervelends voor je rapportage: de vraag "waar blijft werk hangen" kun je niet beantwoorden met alleen een API-koppeling. En het is meestal wél de vraag waar het management op zit te wachten, want daar zit de doorlooptijd in.

De enige uitweg is zelf bijhouden. Je haalt regelmatig de stand op, vergelijkt met wat je de vorige keer zag, en schrijft de verandering weg. Vanaf dat moment bouw je een tijdlijn op. Het nadeel spreekt voor zich: over de periode vóór je koppeling weet je niets, en die haal je nooit meer in. Wie dit wil, moet dus vroeg beginnen — de waarde groeit met de tijd.

De paden verschillen per licentie en per versie

De meldingen-API is bij iedereen hetzelfde. Daarbuiten wordt het rommeliger. Welke endpoints voor wijzigingen, assets en kennisitems beschikbaar zijn hangt af van welke modules er in je licentie zitten en van je TOPdesk-versie.

In de praktijk betekent dit dat je niet kunt bouwen op aannames. Heeft een omgeving geen Asset Management, dan is dat pad er simpelweg niet, en krijg je geen nette lege lijst maar een foutmelding. Controleer dus altijd eerst de API-referentie van de omgeving zelf, niet de algemene documentatie.

401 en 403 betekenen echt iets anders

Een detail dat je uren kan schelen. Krijg je een 401, dan klopt je inloggegevens niet: verkeerde gebruikersnaam, of een applicatiewachtwoord dat is ingetrokken. Krijg je een 403, dan zijn je gegevens prima maar mag je dit niet: de behandelaar heeft geen leesrechten op die module.

Bij een 403 hoef je dus niet aan het wachtwoord te sleutelen. Ga naar de rechten van die behandelaar en kijk welke module ontbreekt. Die twee zijn tijdens de bouw van AureaDesk een keer verwisseld, goed voor een verspilde middag.

Paginering bij grote omgevingen

Op een omgeving met een paar duizend meldingen merk je hier niets van. Op een omgeving met zestigduizend wel. Grote en drukke omgevingen kunnen anders reageren op paginering dan je op een kleine test zou verwachten, en als je code ervan uitgaat dat elke pagina netjes vol zit tot de laatste, loop je vast of mis je records.

De les: test niet alleen op je eigen omgeving. Wat op een paar honderd meldingen werkt, kan op tienduizenden anders uitpakken, en dat merk je precies op het verkeerde moment.

Reken er ook op dat een eerste volledige ophaalslag zwaarder is dan verwacht. Zestigduizend meldingen ophalen op een kleine server loopt tegen geheugengrenzen aan. Bouw dat dus niet als één grote actie.

Wat je nodig hebt om te koppelen

Je hebt geen speciale integratielicentie nodig. Wat je maakt is een behandelaar die alleen voor de koppeling bestaat, met API-toegang en leesrechten op de modules die je wilt uitlezen. Daarbij genereer je een applicatiewachtwoord, en dat is wat je koppeling gebruikt.

Doe dit met een aparte behandelaar en niet met het account van een collega. Twee redenen. Je ziet in de logs meteen dat het de koppeling was en niet een mens. En je kunt hem uitschakelen wanneer je wilt zonder dat iemand daardoor zijn eigen toegang kwijtraakt.

Houd de rechten zo krap mogelijk. Voor rapportage heb je nooit schrijfrechten nodig, en een koppeling die alleen leest kan per definitie niets kapotmaken in je proces.

Waar het op neerkomt

De API is goed genoeg om een volwaardig dashboard op te bouwen, zolang je twee dingen accepteert. Je moet zelf geschiedenis bijhouden als je wilt weten waar werk blijft liggen, en je moet per omgeving controleren wat er beschikbaar is in plaats van uitgaan van de documentatie.

Dat eerste punt is de reden om niet te wachten. Elke maand dat je nog niet koppelt, is een maand die je later niet kunt terugkijken.