Ce que l’API TOPdesk renvoie — et ce qu’elle ne renvoie pas

L’API TOPdesk est correctement documentée et fait ce qu’on en attend. Mais elle recèle quelques particularités que l’on ne découvre qu’après avoir travaillé avec elle un certain temps, et qui peuvent bouleverser vos projets de reporting. Voici ce qui est apparu en construisant un tableau de bord par-dessus.

Ce qui sort sans difficulté

Les incidents sont la partie facile. Vous les obtenez avec leur catégorie et sous-catégorie, statut, priorité, ligne, groupe d’opérateurs (Operator group), opérateur, date de création, date de clôture et les champs SLA. De quoi couvrir le flux entrant, le délai de résolution, le respect des SLA par priorité, et la question de savoir depuis combien de temps le plus ancien élément ouvert traîne.

Les changements et leurs activités sous-jacentes sortent aussi, tout comme les actifs avec leur type, emplacement et statut, et les articles de connaissance (Knowledge items) avec leur statut et leur visibilité dans le portail de self-service. Les opérateurs peuvent être récupérés avec leurs groupes d’autorisations, ce qui est plus utile qu’il n’y paraît : c’est ainsi que vous repérez les comptes payants qui n’ont rien fait depuis des mois.

Ce qui ne sort pas : l’historique

C’est le point important, et celui qui fait dérailler la plupart des projets. L’API vous donne l’état actuel d’un incident. Quel groupe d’opérateurs l’a maintenant, quel statut il a maintenant, chez qui il se trouve maintenant.

Ce que vous n’obtenez pas, c’est le chemin qu’il a parcouru. Vous ne pouvez pas demander à l’API si l’incident 4711 a d’abord été en première ligne, puis onze jours à la gestion du réseau, avant de revenir. Ces transferts sont dans TOPdesk même, mais l’API ne les livre pas.

Cela a une conséquence fâcheuse pour votre reporting : la question « où le travail se bloque-t-il ? » ne peut pas être résolue avec une simple connexion API. Et c’est généralement la question que la direction attend vraiment, car c’est là que se cache le délai de résolution.

La seule issue est de suivre l’historique vous-même. Vous récupérez régulièrement l’état actuel, vous le comparez à ce que vous avez vu la dernière fois et vous notez la différence. À partir de ce moment, vous construisez une chronologie. L’inconvénient est évident : de la période antérieure à la connexion, vous ne savez rien, et vous ne la récupérerez jamais. Quiconque veut cela doit donc commencer tôt — la valeur croît avec le temps.

Les chemins diffèrent selon la licence et la version

L’API des incidents est la même partout. Au-delà, c’est plus désordonné. Les points de terminaison disponibles pour les changements, les actifs et les articles de connaissance dépendent des modules compris dans votre licence et de votre version de TOPdesk.

En pratique, cela signifie que vous ne pouvez pas construire sur des suppositions. Si un environnement n’a pas de Gestion des actifs (Asset Management), ce chemin n’existe tout simplement pas, et vous obtenez une erreur plutôt qu’une liste vide bien propre. Vérifiez donc toujours la référence API de l’environnement lui-même, pas la documentation générale.

401 et 403 signifient vraiment des choses différentes

Un détail qui peut vous faire gagner des heures. Un 401 signifie que vos identifiants sont erronés : mauvais nom d’utilisateur, ou mot de passe d’application révoqué. Un 403 signifie que vos identifiants sont corrects mais que vous n’êtes pas autorisé à faire cela : l’opérateur n’a pas de droits de lecture sur ce module.

Sur un 403, ne touchez donc pas au mot de passe. Allez dans les autorisations de cet opérateur et regardez quel module manque. Ces deux-là ont été confondus une fois lors de la construction d’AureaDesk, de quoi perdre un après-midi.

La pagination dans les grands environnements

Sur un environnement de quelques milliers d’incidents, vous ne remarquez rien. Sur un environnement de soixante mille, si. Les environnements volumineux et très actifs peuvent répondre à la pagination autrement que ne le laisserait penser un petit test, et si votre code suppose que chaque page est bien pleine jusqu’à la dernière, soit vous calez, soit vous perdez des enregistrements sans vous en apercevoir.

La leçon : ne testez pas uniquement sur votre propre environnement. Ce qui fonctionne sur quelques centaines d’incidents peut se comporter autrement sur des dizaines de milliers, et vous le découvrez précisément au mauvais moment.

Comptez aussi sur une première récupération complète plus lourde que prévu. Extraire soixante mille incidents sur un petit serveur se heurte aux limites de mémoire. Ne construisez donc pas cela comme une seule grosse opération.

Ce dont vous avez besoin pour vous connecter

Vous n’avez pas besoin d’une licence d’intégration spéciale. Ce que vous créez, c’est un opérateur qui n’existe que pour la connexion, avec un accès API et des droits de lecture sur les modules que vous voulez lire. Vous générez pour lui un mot de passe d’application, et c’est ce que votre connexion utilise.

Faites-le avec un opérateur distinct, pas avec le compte d’un collègue. Pour deux raisons. Dans les journaux, vous voyez immédiatement que c’était la connexion et non une personne. Et vous pouvez la désactiver quand vous voulez sans priver personne de son propre accès.

Gardez les droits aussi restreints que possible. Le reporting n’a jamais besoin d’un accès en écriture, et une connexion qui ne fait que lire ne peut par définition rien casser dans votre processus.

Ce qu’il faut en retenir

L’API est suffisamment bonne pour y construire un vrai tableau de bord, à condition d’accepter deux choses. Vous devez suivre l’historique vous-même si vous voulez savoir où le travail se bloque, et vous devez vérifier par environnement ce qui est disponible plutôt que de vous fier à la documentation.

Ce premier point est la raison de ne pas attendre. Chaque mois sans connexion est un mois sur lequel vous ne pourrez pas revenir plus tard.