Document FAQ API Koaly EXP EXP Page: 1 / 52 2005-2015 - - Tous droits réservés
Table des matières Généralités... 4 I.Objectifs du document... 4 II.Présentation de l'api... 4 A.Objectifs et raisons d'être... 4 B.Présentation générale... 5 C.Retours en échec... 6 D.Formatage des dates... 6 Détails de l'api... 7 I.Gestion de l'identification... 7 A.Demande de session... 7 B.Fermeture de session... 9 II.Module Mots de passe... 9 A.Rechercher des mots de passe...10 B.Récupérer un mot de passe...10 III.Module général... 11 A.Recherche de structures... 11 B.Recherche d'équipes... 12 C.Recherche d'applications... 12 D.Gestion des filtres d'affichage...12 IV.Module Accueil... 13 A.Tableau de bord... 13 V.Module Infrastructure... 14 A.Recherche d'équipements... 14 B.Recherche de bases de données...14 C.Recherche d'applications JAVA...15 D.Recherche d'instances SAP...15 E.Recherche de contrats de support...16 F.Recherche de licences... 16 G.Recherche de logiciels... 16 H.Recherche de fournisseurs... 17 VI.Module Main courante... 17 A.Gestion des consignes... 17 B.Recherche d'évènements... 18 C.Recherche d'appels téléphoniques...20 D.Recherche d'arrêts planifiés...20 VII.Module Supervision... 22 A.Recherche de notifications... 22 VIII.Module Rapports... 22 A.Recherche de rapports... 22 IX.Module Tâches... 23 A.Recherche de tâches... 23 B.Recherche de types de tâches...24 X.Module Tickets... 24 A.Recherche de tickets... 24 B.Créer un ticket... 26 C.Modifier un ticket... 28 FAQ... 31 Page: 2 / 52 2005-2015 - - Tous droits réservés
I.Généralités... 31 A.Pourquoi la clé de chiffrement n'est-elle pas plus grande?...31 B.Pourquoi la clé de transaction change t'elle à chaque requête?...31 C.Quel(s) port(s) dois-je ouvrir pour faire fonctionner l'api?...31 D.Comment sécuriser l'accès à l'api?...31 E.Comment déboguer efficacement mon application?...31 II.Connexions à l'api... 32 A.Pourquoi ne puis-je pas me connecter à l'api avec l'utilisateur koalyadm?...32 B.Pourquoi reçois-je l'erreur 501 lorsque je cherche à me connecter?...32 C.Pourquoi l'api m'indique-t-elle que l'utilisateur n'a pas accès à l'api?...32 III.Utilisation de l'api... 32 A.Pourquoi certains champs sont marqués «optionnel»?...32 B.Pourquoi certains champs décrits dans la documentation ne sont pas transférés par l'api?...32 C.Pourquoi n'est-il pas possible d'effectuer [insérer ici le nom d'une action]?...33 D.Comment faire pour changer le format de réponse de l'api?...33 E.Quel format de réponse privilégier?...33 F.Pourquoi l'api me retourne une erreur «Wrong type or wrong value for parameter» alors que j'ai introduis la bonne valeur?... 33 Annexe... 34 I.Code d'erreurs... 34 II.Principaux messages d'erreurs...34 III.Détails des éléments retournés par l'api...36 A.Mots de passe... 36 B.Applications... 37 C.Filtres d'affichage... 37 D.Préférences utilisateurs... 37 E.Structures... 38 F.Équipes... 38 G.Utilisateurs... 38 H.Tableaux d'accueil... 39 I.Contrats de support... 39 J.Bases de données... 39 K.Équipements... 39 L.Applications JAVA... 40 M.Licences... 40 N.Instances SAP... 40 O.Logiciels... 41 P.Fournisseurs... 41 Q.Évènements... 41 R.Types d'évènements... 42 S.Consignes... 42 T.Arrêts planifiés... 42 U.Appels téléphoniques... 43 V.Types d'appels téléphoniques...43 W.Notifications d'alertes de supervision...44 X.Rapports... 44 Y.Fichier de rapport... 45 Z.Tâches... 45 AA.Types de tâches... 46 AB.Tickets... 46 AC.Évolutions d'un ticket... 48 AD.Sous tâches d'un ticket... 49 IV.Exemples... 50 A.Demande de connexion... 50 B.Recherche de rapports entre deux dates...50 C.Récupération des informations d'un rapport trouvé par la requête précédente...50 D.Demande de fermeture de la sessions...52 Page: 3 / 52 2005-2015 - - Tous droits réservés
Généralités I. Objectifs du document Ce document a pour objectif de présenter l'api du portail Koaly EXP de la manière la plus exhaustive qui soit. Il a été étudié pour être à l'usage des développeurs des sociétés clientes de Koaly qui souhaiteraient mettre en place un système de communication entre leurs outils et leur portail Koaly EXP. Ce document se concentre uniquement sur les possibilités offertes par l'api du portail Koaly EXP. Aucune notion de web service ou de développement ne sera abordée. L'auteur conseille aux personnes souhaitant s'initier au développement d'un client d'une API de commencer par étudier les protocoles de communication web tel HTTP et de maitriser au moins un langage de développement (PHP, Java, Python, Ruby, etc.) avant d'entamer la lecture du présent ouvrage. Malgré tous les efforts fournis par la société Koaly, il est possible que ce document ne présente pas la totalité des méthodes disponibles dans l'api, ces dernières pouvant être modifiées ou supprimées, en particulier en fonction de la version du portail Koaly EXP utilisée. En aucun cas la société Koaly ne pourra être tenue responsable des dysfonctionnements des applications externes utilisant son API. Ce document a également pour objectif de servir de référence pour suivre l'évolution de l'api en fonction des versions du portail Koaly EXP. Il s'agit du seul document officiel traitant de l'api du portail Koaly EXP. L'auteur a inclus à ce document un ensemble de questions fréquemment posées. Cette section a pour objectif de répondre au maximum aux questions les plus usuelles des utilisateurs de l'api. II. Présentation de l'api A. Objectifs et raisons d'être Le portail Koaly EXP intègre depuis la version 1.6.0 une API permettant à des développeurs externes d'intégrer les informations et la puissance du portail Koaly EXP au sein d'une autre application. L'API a été créée dans l'objectif de répondre aux besoins croissants des entreprises de réunir en un seul et même endroit diverses informations et données provenant d'outils divers et variés. Elle n'a pas pour vocation de remplacer l'interface standard du portail Koaly EXP accessible par un navigateur internet. De ce fait, certaines fonctionnalités du portail ne seront jamais accessibles au travers de l'api. Page: 4 / 52 2005-2015 - - Tous droits réservés
B. Présentation générale L'API est basée sur le principe de web services utilisant le style d'architecture REST (Representational State Transfer) avec quelques différences notables décrites dans ce document. Comme tout web service, cette API utilise le protocole HTTP pour le transfert des informations. Ce protocole n'étant pas sécurisé par défaut, Koaly recommande l'usage de sa version sécurisée (à l aide du chiffrement SSL ou TLS), plus connue sous l'abréviation HTTPS. Les données sont transférées par la méthode POST ou GET au portail Koaly EXP. Ce dernier répond en envoyant du JSON / JSONP ou du XML en fonction de la demande du client. Quelle que soit la requête exécutée, le premier paramètre contient un booléen permettant de savoir si la requête s'est exécutée avec succès ou non. Pour récupérer une réponse en JSONP (JSON with Padding) au lieu de JSON, il suffit de passer en paramètre le nom de la méthode de callback désirée. Le nom du paramètre à utiliser est «cb». Rappel : l'usage de JSONP ne peut se faire que grâce à la méthode GET. L'API est séparée par module. L'URL pour demander une information sur un ticket est différente de l'url pour demander une information sur un rapport. Cette séparation permet de mettre en place plusieurs instances du portail Koaly et de répartir la charge en fonction, au choix, du module ou du client de manière propre et logique. Afin de sécuriser les échanges, une clé est renvoyée par le portail et sera demandée pour la prochaine requête. Cette clé est unique, valable une seule fois et permet d'identifier rapidement l'utilisateur Koaly associé à la requête dans l'api. Chaque requête à l'api contient un ensemble de paramètres et une URL à laquelle envoyer ces paramètres. Certains paramètres peuvent être optionnels en fonction des cas. Une requête standard à l'api est généralement constituée de la clé de transaction unique, du nom de la méthode à appeler et les paramètres de ladite méthode. L'accès à l'api est soumis à deux restrictions configurables. Il y a tout d'abord un paramètre de configuration du portail (par instance) autorisant ou non l'usage de l'api. Ce paramètre est configurable dans le manageur et toute modification n'est prise en compte qu'après un redémarrage de l'instance concernée. Par défaut, la configuration bloque l'usage de l'api. Il y a également un droit par profil contact et opérateur pour autoriser ou non l'accès à l'api pour les utilisateurs appartenant au profil considéré. Ce droit permet simplement d'autoriser ou non la connexion Page: 5 / 52 2005-2015 - - Tous droits réservés
depuis l'api. Par la suite, toutes les requêtes à l'api sont soumises à la gestion des droits classiques du portail (prenant en compte le profil de l'utilisateur, les équipes dont il est membre et les structures sur lesquelles il a les droits en lecture ou écriture). C. Retours en échec L'API fournit les retours négatifs selon un schéma unique, quelle que soit la requête. Ce message, au format JSON ou XML, contient les données suivantes : success : Vaut toujours «false» en cas d'erreur. errorcode : Contient un nombre qualifiant l'erreur. Le détail des codes d'erreur est disponible dans l'annexe «Code d'erreurs». errormessage : Contient une description, en anglais, de l'erreur. Ce message a pour objectif d'aider le développeur à identifier le problème exact. Il n'a en aucun cas pour vocation d'être affiché à l'utilisateur final. requestkey (optionnel) : La clé de transaction utilisée pour effectuer la requête (le cas échéant). responsekey (optionnel) : La nouvelle clé de transaction à utiliser pour la prochaine requête (le cas échéant). Les paramètres optionnels (requestkey et responsekey) sont toujours inclus dans la réponse sauf pour les cas suivants : (a) Lors de la demande d'identification initiale si elle échoue. (b) Lorsque la clé de transaction n'est pas reçue par le serveur. (c) Lorsque l'erreur empêche la génération d'une nouvelle clé. Attention l'ancienne n'est plus valide, il faut alors procéder à une nouvelle identification. (d) Lors de la demande de déconnexion. (e) Lorsque la session prend fin. Il est alors nécessaire de procéder à une nouvelle identification. D. Formatage des dates Toutes les dates envoyées à l'api doivent respecter un unique format «YYYY-MM-DD hh:mm:ss», où : YYYY : représente l'année du calendrier grégorien sur quatre chiffres. MM : représente le mois du calendrier grégorien sur deux chiffres. DD : représente le jour du calendrier grégorien sur deux chiffres. hh : représente l'heure, au format 24h, sur deux chiffres. mm : représente les minutes, sur deux chiffres. ss : représente les secondes, sur deux chiffres. Exemple de date respectant le format : «2012-12-21 12:11:42». Toutes les dates renvoyées par l'api respectent également ce même format. Page: 6 / 52 2005-2015 - - Tous droits réservés
Détails de l'api I. Gestion de l'identification La grande majorité des requêtes via l'api nécessite une authentification de l'utilisateur. Le système génère une session par utilisateur connecté et utilise les différents systèmes de sécurité internes au portail au même titre qu'une session web standard. Ainsi les droits des opérateurs et des contacts sont les mêmes, quelle que soit la méthode d'accès aux données. A. Demande de session La toute première requête au portail Koaly devrait, en toute logique, être celle de l'identification. Cette étape est nécessaire, car c'est elle qui délivre la toute première clé de transaction nécessaire aux requêtes de l'api. La clé de transaction ainsi récupérée devra être transmise lors de la prochaine requête à l'api. Elle permettra d'identifier l'application cliente et l'utilisateur Koaly associé au client. Cette requête est particulière. Il s'agit de la seule requête qui ne nécessite pas de clé de transaction et dont le délai de réponse peut varier en fonction des paramètres de sécurité du portail. Les paramètres suivants sont à envoyer à l'url [Adresse du portail]/api/login : login (obligatoire) : L'identifiant de l'utilisateur sur le portail Koaly EXP [Chaine de caractères]. password (obligatoire) : Le mot de passe de l'utilisateur sur le portail Koaly EXP après cryptage [Chaine de caractères]. version (obligatoire) : La version de l'api demandée par le logiciel client [Chaine de caractères]. Par exemple : «1.6.0» responseformat : Le format de réponse désiré (XML ou JSON) [Chaine de caractères]. Par défaut la réponse est renvoyée en JSON. cb : Le nom de la méthode de callback du JSONP, le cas échéant [Chaine de caractères]. Le format de réponse est défini au moment de l'identification. Le paramètre est ensuite sauvegardé et utilisé pour toutes les futures transactions depuis l'identification. Cependant, dans certains cas, le format renvoyé peut varier, en particulier lorsqu'aucune clé de transaction n'est transmise (l'api renvoie par défaut du JSON) ou bien lorsque cette dernière n'existe pas. Le mot de passe doit être crypté, via AES en mode CBC avec le padding Pkcs7 (ou Pkcs5), avant d'être envoyé concaténé avec le vecteur d'initialisation choisi aléatoirement. La clé de cryptage à utiliser est la suivante : «K04L1-AESKeyCode». Page: 7 / 52 2005-2015 - - Tous droits réservés
K, la lettre «k» en majuscule. 0, le chiffre «zéro» en chiffre arabe. 4, le chiffre «quatre» en chiffre arabe. L, la lettre «l» en majuscule. 1, le chiffre «un» en chiffre arabe. -, le trait d'union. A, la lettre «a» en majuscule. E, la lettre «e» en majuscule. S, la lettre «s» en majuscule. K, la lettre «k» en majuscule. e, la lettre «e» en minuscule. y, la lettre «y» en minuscule. C, la lettre «c» en majuscule. o, la lettre «o» en minuscule. d, la lettre «d» en minuscule. e, la lettre «e» en minuscule. Par exemple si le mot de passe est «koaly», on génère un vecteur d'initialisation, aléatoirement, de la même taille que la clé de cryptage (16 caractères). Par exemple «SFy69d2Ww2hQcQTE». On chiffre notre mot de passe en AES, en mode CBC, avec le padding Pkcs7 et en utilisant notre vecteur d'initialisation généré précédemment. On obtient ainsi la chaine de caractères suivante : «e5rrm54uqrjw/japtvxnva==». On concatène le vecteur d'initialisation à cette chaine sur le format suivant : Vecteur+mot de passe crypté. On obtient ainsi la chaine suivante : «SFy69d2Ww2hQcQTEe5rrm54UqrJw/JAptVxnvA==». C'est cette chaine de caractères que l'on envoie au portail Koaly EXP. En cas de succès de la requête, une session est créée. La durée de cette dernière est identique à la durée d'une session sur le portail Koaly EXP. Lorsque la session prend fin, il est à nouveau nécessaire de procéder à une demande d'identification afin de régénérer une nouvelle session. La durée de la session est modifiable depuis l'administration du portail, dans les options de sécurités. Le serveur retourne un message indiquant le succès de la demande et contenant la clé de transaction à utiliser pour la prochaine requête ainsi que les principales informations sur l'utilisateur. Les détails sont décrits dans la partie de l'annexe consacrée aux utilisateurs. Si un ou plusieurs paramètres manquent lors de l'appel à cette méthode, l'api retournera un message d'erreur. Il en va de même si la version utilisée est inférieure à la version minimale requise par le serveur pour pouvoir utiliser l'api. Page: 8 / 52 2005-2015 - - Tous droits réservés
En cas d'échec de la requête au niveau de l identification, un système dédié à la protection contre les attaques par force brute se met en place. Ce système se caractérise par une durée d'attente avant la génération de la réponse de plus en plus longue. Il s'agit du même système que celui disponible à la connexion au portail Koaly EXP par l'interface web. De même, il est possible de configurer un blocage du compte à partir d'un certain nombre de tentatives. Ce paramètre est disponible depuis l'administration du portail, dans les options de sécurités. Ce système utilise le même compteur pour les tentatives par l'interface web et par l'api. Lorsque le nombre de tentatives infructueuses dépasse le nombre de tentatives autorisées, le compte est bloqué et il n'est alors plus possible de s'y connecter, que ce soit depuis l'api ou depuis le portail. B. Fermeture de session Il est possible de demander la clôture d'une session ouverte par requête à l'api. Cela permet de clôturer de manière propre une session et ainsi empêcher toute tentative d'intrusion dans le portail par une session laissée ouverte. Les paramètres suivants sont à envoyer à l'url [Adresse du portail]/api/logout : Si la clé transmise est correcte (existe et première utilisation) alors la session est détruite. Le message de retour ne contient pas de nouvelle clé de transaction. Il sera nécessaire d'effectuer à nouveau une demande d'identification pour en récupérer une. En cas d'échec (la clé transmise n'est pas correcte), un message d'erreur est transmis et la session n'est pas fermée. Cependant, aucune nouvelle clé n'est transmise, le système n'ayant pas été en mesure d'identifier la session associée. De manière générale, il est recommandé de demander explicitement la fermeture de la session pour des raisons de sécurité. Cependant, le système ne génère que des sessions ayant une durée de vie réduite (paramétrable depuis le portail) qui se terminent automatiquement une fois le délai passé. II. Module Mots de passe Ce module est accessible à l'adresse [Adresse du portail]/api/access. Voici les différentes méthodes accessibles : Page: 9 / 52 2005-2015 - - Tous droits réservés
A. Rechercher des mots de passe Version requise : 1.6.0 ou ultérieure. Cette fonctionnalité permet d'effectuer des recherches et de lister un ensemble de mots de passe. Voici les paramètres à envoyer via l'api : req (obligatoire) : La valeur suivante : «getpasswords». sid : L'identifiant de la structure dans laquelle doivent se trouver les mots de passe. [Nombre entier]. tid : L'identifiant de l'équipe propriétaire des mots de passe à trouver. [Nombre entier]. cat : Le nom de la catégorie du mot de passe (voir liste des catégories disponibles). [Chaine de caractères]. filter : Booléen indiquant l'usage du filtre d'affichage. Par défaut ce paramètre vaut «false». Le champ «cat» peut prendre une des valeurs suivantes : NETWORK SERVER DISK_BAY EQUIPMENT_BAY SAVE_ROBOT PRINTER POWER HOST_OTHER DB SAP JAVA_APPLICATION SPECIFIC En cas de succès, la réponse prend la forme d'une liste de fiches de mots de passe (voir annexe pour les détails d'un mot de passe). Aucune des fiches ainsi récupérées ne contient le mot de passe en clair. Pour obtenir cette information, il faut utiliser la méthode décrite ci-après. B. Récupérer un mot de passe Version requise : 1.6.0 ou ultérieure. Cette méthode permet de récupérer une fiche contenant son mot de passe en clair. Voici les paramètres à envoyer par l'api : Page: 10 / 52 2005-2015 - - Tous droits réservés
req (obligatoire) : La valeur suivante : «getcleartextpassword». id (obligatoire) : L'identifiant du mot de passe [Nombre entier]. pass : La phrase de chiffrement, le cas échéant [Chaine de caractères]. La phrase de chiffrement est nécessaire pour déchiffrer le mot de passe. Il est recommandé d'utiliser au préalable la méthode «getpasswords» permettant de lister des mots de passe. Dans les fiches retournées, la présence d'une phrase de chiffrement est indiquée. Dans le cas où le système ne peut décrypter le mot de passe, une erreur 501 est retournée. Généralement, cela signifie que la phrase de chiffrement envoyée est erronée. III. Module général Ce module est accessible à l'adresse [Adresse du portail]/api/core. Il permet de récupérer des éléments génériques et utiles dans différents modules. Voici la liste des méthodes disponibles. A. Recherche de structures Version requise : 1.6.0 ou ultérieure. Cette méthode permet de rechercher ou de lister des structures. Voici la liste des paramètres à passer : req (obligatoire) : La valeur suivante : «getstructures». module : Le nom du module dans lequel les structures doivent être actives (voir liste des modules disponibles) [Chaine de caractères]. id : L'identifiant d'une structure (utile si on souhaite récupérer une seule structure) [Nombre entier]. filter : Booléen indiquant l'usage du filtre d'affichage. Par défaut ce paramètre vaut «false». Le champ «module» peut prendre l'une des valeurs suivantes : ACCESS (correspond au module des mots de passe) DOC (correspond au module des documents) HOME (correspond au module d'accueil) INFRASTRUCTURE (correspond au module d'infrastructure) LOGBOOK (correspond au module de main courante) MONITORING (correspond au module de supervision) REPORT (correspond au module des rapports) Page: 11 / 52 2005-2015 - - Tous droits réservés
TASK (correspond au module des tâches) TICKET (correspond au module des tickets) En cas de succès, la réponse prend la forme d'une liste de fiches de structures (voir annexe pour les détails d'une structure). B. Recherche d'équipes Version requise : 1.6.0 ou ultérieure. Cette méthode permet de recherche ou de lister des équipes. Voici la liste des paramètres à passer : req (obligatoire) : La valeur suivante : «getteams». sid : L'identifiant de la structure dans laquelle se trouvent les équipes [Nombre entier]. id : L'identifiant d'une équipe (utile si on souhaite récupérer une seule équipe) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'équipes (voir annexe pour les détails d'une équipe). C. Recherche d'applications Version requise : 1.6.0 ou ultérieure. Cette méthode permet de recherche ou de lister des applications. Voici la liste des paramètres à passer : req (obligatoire) : La valeur suivante : «getapplications». sid : L'identifiant de la structure dans laquelle se trouvent les applications [Nombre entier]. id : L'identifiant d'une application (utile si l on souhaite récupérer une seule application) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'applications (voir annexe pour les détails d'une application). D. Gestion des filtres d'affichage Version requise : 1.6.0 ou ultérieure. Page: 12 / 52 2005-2015 - - Tous droits réservés
Il est possible de récupérer la liste des filtres d'affichage de l'utilisateur courant. Voici la liste des paramètres à passer : req (obligatoire) : La valeur suivante : «getdisplayfilters». id : L'identifiant du filtre d'affichage (utile si on souhaite récupérer un seul filtre d'affichage) [Nombre entier]. En cas de succès, la réponse prend la forme d'une liste de filtres d'affichage (voir annexe pour les détails d'un filtre d'affichage). Il est également possible de sélectionner un filtre d'affichage pour l'utilisateur courant. Voici la liste des paramètres à passer : req (obligatoire) : La valeur suivante : «setactivedisplayfilter». id (obligatoire) : L'identifiant du filtre d'affichage désiré. [Nombre entier]. En cas de succès, la réponse prend la forme d'un simple booléen confirmant le succès de l'opération. Aucune autre information n'est transférée. IV. Module Accueil Ce module est accessible à l'adresse [Adresse du portail]/api/home. Il permet de récupérer les informations du tableau de bord. A. Tableau de bord Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations affichées dans le tableau de bord du portail. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getdashboardinfo». En cas de succès, la réponse prend la forme d'un tableau de données représentant les différentes données du tableau de bord. Page: 13 / 52 2005-2015 - - Tous droits réservés
V. Module Infrastructure Ce module est accessible à l'adresse [Adresse du portail]/api/infrastructure. Il permet de récupérer les données des équipements, des bases de données, des logiciels, etc. A. Recherche d'équipements Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations sur les équipements enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «gethosts». sid : L'identifiant de la structure dans laquelle se trouvent les équipements [Nombre entier]. eid : L'identifiant de l environnement dans lequel se trouvent les équipements [Nombre entier]. id : L'identifiant de l'équipement (utile si l on souhaite récupérer un seul équipement) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'équipements (voir annexe pour les détails d'un équipement). B. Recherche de bases de données Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations sur les bases de données enregistrées dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getdatabases». sid : L'identifiant de la structure dans laquelle se trouvent les bases de données [Nombre entier]. eid : L'identifiant de l environnement dans lequel se trouvent les bases de données [Nombre entier]. hid : L'identifiant de l'équipement sur lequel est installée la base de données [Nombre entier]. id : L'identifiant de la base de donnée (utile si l on souhaite récupérer une seule base de données) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de bases de données (voir annexe pour Page: 14 / 52 2005-2015 - - Tous droits réservés
les détails d'une base de données). C. Recherche d'applications JAVA Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations sur les applications JAVA enregistrées dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getjavaapplications». sid : L'identifiant de la structure dans laquelle se trouvent les applications JAVA [Nombre entier]. eid : L'identifiant de l environnement dans lequel se trouvent les applications JAVA [Nombre entier]. hid : L'identifiant de l'équipement sur lequel est installée l'application JAVA [Nombre entier]. id : L'identifiant de l'application JAVA (utile si l on souhaite récupérer une seule application JAVA) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'applications JAVA (voir annexe pour les détails d'une application JAVA). D. Recherche d'instances SAP Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations sur les instances SAP enregistrées dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getsapinstances». sid : L'identifiant de la structure dans laquelle se trouvent les instances SAP [Nombre entier]. eid : L'identifiant de l environnement dans lequel se trouvent les instances SAP [Nombre entier]. hid : L'identifiant de l'équipement sur lequel est installée l'instance SAP [Nombre entier]. id : L'identifiant de l'instance SAP (utile si l on souhaite récupérer une seule instance SAP) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'instances SAP (voir annexe pour les détails d'une instance SAP). Page: 15 / 52 2005-2015 - - Tous droits réservés
E. Recherche de contrats de support Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations sur les contrats de support enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getcontracts». sid : L'identifiant de la structure dans laquelle se trouvent les contrats de support [Nombre entier]. suppid : L'identifiant du fournisseur associé au contrat de support [Nombre entier]. id : L'identifiant du contrat de support (utile si l on souhaite récupérer un seul contrat de support) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de contrats de support (voir annexe pour les détails d'un contrat de support). F. Recherche de licences Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations des licences enregistrées dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getlicenses». sid : L'identifiant de la structure dans laquelle se trouvent les licences [Nombre entier]. hid : L'identifiant de l'équipement associé à la licence. [Nombre entier]. softid : L'identifiant du logiciel associé à la licence. [Nombre entier]. id : L'identifiant de la licence (utile si l on souhaite récupérer une seule licence) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de licences (voir annexe pour les détails d'une licence). G. Recherche de logiciels Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations des logiciels enregistrés dans le portail Koaly EXP. Voici les Page: 16 / 52 2005-2015 - - Tous droits réservés
paramètres à envoyer par l'api : req (obligatoire) : La valeur «getsoftware». sid : L'identifiant de la structure dans laquelle se trouvent les logiciels [Nombre entier]. hid : L'identifiant de l'équipement sur lequel est installé le logiciel [Nombre entier]. suppid : L'identifiant du fournisseur du logiciel [Nombre entier]. id : L'identifiant du logiciel (utile si l on souhaite récupérer un seul logiciel) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de logiciels (voir annexe pour les détails d'un logiciel). H. Recherche de fournisseurs Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations des fournisseurs enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getsuppliers». sid : L'identifiant de la structure dans laquelle se trouvent les fournisseurs [Nombre entier]. id : L'identifiant du fournisseur (utile si l on souhaite récupérer un seul fournisseur) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de fournisseurs (voir annexe pour les détails d'un fournisseur). VI. Module Main courante Ce module est accessible à l'adresse [Adresse du portail]/api/logbook. Il permet de récupérer les données des arrêts planifiés, des consignes, des évènements et des appels téléphoniques. A. Gestion des consignes Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations des consignes enregistrées dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : Page: 17 / 52 2005-2015 - - Tous droits réservés
req (obligatoire) : La valeur «getinstructions». sid : L'identifiant de la structure dans laquelle se trouvent les consignes [Nombre entier]. tid : L'identifiant de l'équipe propriétaire des consignes [Nombre entier]. readstatus : Le statut de lecture de la consigne vis-à-vis de l'utilisateur courant (voir liste des statuts disponibles) [Chaine de caractères]. latest : Indique si l on souhaite uniquement les consignes du jour. Par défaut la valeur est «false» [Booléen]. startdate : Uniquement si «latest» est à «false». Ce paramètre permet d'indiquer le début de la plage de date de création de la consigne [Date]. enddate : Uniquement si «latest» est à «false». Ce paramètre permet d'indiquer la fin de la plage de date de création de la consigne [Date]. id : L'identifiant de la consigne (utile si l on souhaite récupérer une seule consigne) [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». Le champ «readstatus» peut prendre une des valeurs suivantes : READ (pour ne chercher que les consignes déjà lues par l'utilisateur courant) UNREAD (pour ne chercher que les consignes non lues par l'utilisateur courant) ALL (pour rechercher toutes les consignes) En cas de succès, la réponse prend la forme d'une liste de fiches de consignes (voir annexe pour les détails d'une consigne). Il est également possible de marquer une consigne comme lue par l'utilisateur courant, de la même manière que le fait le portail lorsqu'un opérateur affiche une consigne. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «markinstructionasread». id : L'identifiant de la consigne qui doit être marquée comme lue par l'utilisateur courant [Nombre entier]. En cas de succès, la réponse contient la consigne qui a été marquée comme lue par l'utilisateur courant (voir annexe pour les détails d'une consigne). B. Recherche d'évènements Page: 18 / 52 2005-2015 - - Tous droits réservés
Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les évènements enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getevents». sid : L'identifiant de la structure de l'évènement [Nombre entier]. typeid : L'identifiant du type de l'évènement [Nombre entier]. level : Le niveau d'impact de l'évènement (voir liste des niveaux disponibles) [Chaine de caractères]. startdate : Date de début de la plage de recherche de la date de l'évènement [Date]. enddate : Date de fin de la plage de recherche de la date de l'évènement [Date]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». Le champ «level» peut prendre une des valeurs suivantes : MINOR (évènements dont le niveau d'impact est mineur) MEDIUM (évènements dont le niveau d'impact est moyen) MAJOR (évènements dont le niveau d'impact est majeur) En cas de succès, la réponse prend la forme d'une liste de fiches d'évènements (voir annexe pour les détails d'un évènement). Il est également possible de récupérer les évènements (enregistrés dans le portail Koaly EXP) ayant eu lieu dans les trois derniers mois. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getlatestevents». level : Le niveau d'impact de l'évènement (voir liste des niveaux disponibles) [Chaine de caractères]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches d'évènements (voir annexe pour les détails d'un évènement). Il est également possible de récupérer les types d'évènements enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «geteventtypes». sid : L'identifiant de la structure du type d'évènements [Nombre entier]. Page: 19 / 52 2005-2015 - - Tous droits réservés
filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de types d'évènements (voir annexe pour les détails d'un type d'évènements). C. Recherche d'appels téléphoniques Version requise : 1.6.0 ou ultérieure. Il est possible de récupérer les informations des appels téléphoniques enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getphonecalls». sid : L'identifiant de la structure liée à l'appel téléphonique [Nombre entier]. tid : L'identifiant de l'équipe concernée par l'appel téléphonique [Nombre entier]. typeid : L'identifiant du type de l'appel téléphonique [Nombre entier]. startdate : Date de début de la plage de recherche de l'appel téléphonique [Date]. enddate : Date de fin de la plage de recherche de l'appel téléphonique [Date]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste d'appels téléphoniques (voir annexe pour les détails d'un appel téléphonique). Il est également possible de récupérer les types d'appels téléphoniques enregistrés dans le portail Koaly EXP. Voici les paramètres à envoyer par l'api : req (obligatoire) : La valeur «getphonecalltypes». sid : L'identifiant de la structure du type d'appel téléphonique [Nombre entier]. filter : Booléen indiquant l'usage d'un filtre d'affichage. Par défaut ce paramètre vaut «false». En cas de succès, la réponse prend la forme d'une liste de fiches de types d'appels téléphoniques (voir annexe pour les détails d'un type d'appel téléphonique). D. Recherche d'arrêts planifiés Version requise : 1.6.0 ou ultérieure. Page: 20 / 52 2005-2015 - - Tous droits réservés