WIKI ITSM-NG

1. Introduction

Ce document a pour but de passer en revue les requêtes API à exécuter en fonction de l’action souhaitée pour interagir avec ITSM-NG. pour cela, il faut bien prendre en compte les remarques générales ci-dessous.

Vous pouvez passer un paramètre supplémentaire « session_write=true » pour contourner ce comportement par défaut.Ce mode en lecture seule permet d’utiliser cette API avec des appels parallèles.

En mode écriture, les sessions sont verrouillées et votre client doit attendre la fin d’un appel avant que le suivant puisse s’exécuter.

2. Activation de l’API

Allez dans Configuration ⇾ Générale, puis dans l’onglet API.

Définissez activer l'API Rest à OUI.

Activer la connexion avec un jeton externe à OUI.

Cliquez sur Sauvegarder.

2.1 Configurer un client API (App-Token)

Cliquez sur le bouton " Ajouter un client de l'API ".

Créez un client API en remplissant les informations suivantes :

Dans la section Filtrer l'accès :

Cliquez sur Regénérer au niveau du champ Jeton d'application (app_token).

Cliquez sur Sauvegarder pour enregistrer les modifications.

Retournez sur le client API que vous venez de générer et copiez le jeton d'application (app_token).

2.2 Générer un token Utilisateur (User-Token)

Allez dans les préférences utilisateur du profil. A la fin de cette page se trouve la section Clefs d'accès distant.

Cochez la case Regénérer qui se trouve à droite du jeton d'API.

Cliquez sur Sauvegarder pour obtenir un nouveau jeton.

ITSM-NG vous a généré un token, copiez-le.

3. Gestion des Sessions

3.1. Initialisation de la session (/initSession)

L’API ITSM-NG requiert une authentification pour être utilisée, il est donc obligatoire de récupérer un jeton de session qui sera à joindre à chaque exécution de requête.

Le temps de validité du jeton de session est de 10 minutes. Une fois ce temps dépassé, il faudra générer un nouveau jeton de session.

Deux paramètres sont requis pour récupérer le jeton de session :

App-Token : chaîne de caractères d’autorisation fournie par la configuration de l’API ITSM-NG.

Authorization : deux options sont possibles :
* Couple identifiant, mot de passe : consiste en une chaîne de caractères Base64 avec l’identifiant et le mot de passe de l’utilisateur séparé par « : »
* Un user_token défini dans les préférences de l’utilisateur. Ces options doivent être configurées par un administrateur ITSM-NG.

Exemple de récupération du jeton de session avec l’option 1 :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Authorization: Basic Z2xwaTpnbHBp" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/initSession'

Exemple de récupération du jeton de session avec l’option 2 :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Authorization: user_token USER_TOKEN" \
    -H "App-Token: APP_TOKEN" \
    ' http://path/to/ITSM-NG/apirest.php/initSession'

Retour dans les deux cas :

< 200 OK
< { "session_token": "83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" }

3.2. Fermeture de la session (/killSession)

Pour des questions de sécurité, la session initiée doit être détruite après utilisation. Cela permet de désactiver le jeton de session.

Deux paramètres sont requis :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/killSession'

Retour

< 200 OK

4. Tickets

4.1. Création d’un ticket (/Ticket/)

Voici les étapes à suivre pour la création d’un nouveau ticket via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il faut construire le JSON qui va être envoyé à ITSM-NG avec les informations du ticket. Ci-dessous un exemple avec les champs principaux :

{
    "name": "Panne sur le réseau 5G", 
    "content": "Ceci est une description", 
    "entities_id": 0,
    "locations_id": 0,
    "itilcategories_id": 0,
    "urgency": 3,
    "impact": 3,
    "priority": 3,
    "status": 1
}

Note : au moment de l’envoi, les données JSON du ticket doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"name": "Panne sur le réseau 5G", "content": "Ceci est une
    description"}}' \
    'http://path/to/ITSM-NG/apirest.php/Ticket/'

Retour succès avec l’ID du ticket créé :

< 201 OK
< Location: http://path/to/ITSM-NG/api/Ticket/15
< {"id": 15}

4.2. Récupération d’un ou plusieurs tickets (/Ticket/)

Voici les étapes à suivre pour récupérer les informations d’un ou plusieurs tickets via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des tickets que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation : Cette exemple montre comment retourner les informations du ticket précédemment créé dans le chapitre 3.1.

$ curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Ticket/? expand_dropdowns=true&searchText[name]=Panne%20sur%20le%20reseau%205G'

Retour succès avec le ticket recherché :

< 200 OK < [ { "id": 15, "entities_id": "Entité Racine", "name": "Panne sur le réseau 5G", ...}]

Note : si plusieurs tickets correspondent à cette recherche alors l’API retournera la liste de tous les tickets correspondant.

Exemple de recherche en fonction du statut et du lieu :

$ curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Ticket/? expand_dropdowns=true&searchText[status]=1&searchText[locations_id]=0'

Retour succès avec le ou les tickets correspondant à cette recherche :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Panne sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

4.3. Recherche complexe

Il est possible de faire une recherche plus complexe composée d’opérateurs logiques. Cette recherche se fait en deux étapes.

4.3.1. Listage des options de recherche (/listSearchOptions/)

La première étape est de récupérer les ids des champs sur lesquels on souhaite faire la recherche grâce à la route /listSearchOptions/Ticket.

curl -X GET \ -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/listSearchOptions/Ticket'

Le modèle de retour avec les champs les plus pertinents est présent dans la documentation Swagger. Le modèle de retour complet est présent dans le document Ticket_searchoptions.json

4.3.2. Construction de la recherche (/search/Ticket/)

La deuxième étape est de construire notre requête de recherche composée des champs précedemment récupéré.

Dans l’exemple suivant, nous allons rechercher tous les tickets ouverts après le 10/01/2023 avec le statut « En cours (Planifié) ».

Les critères seront construits comme suit :

"criteria": 
    [
        {
            "field": 15, // id de recherche de la date de création du ticket 
            "searchtype": 'morethan',
            "value": '2023-01-10'
        }, {
            "link": 'AND',
            "field": 12, // id de recherche du statut du ticket 
            "searchtype": 'equals',
            "value": 3
        }
    ]

Ce qui nous donnera le requête curl suivante :

curl -g -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: b98leef0urdjjqd7f284med4hj" \
    -H "App-Token: kPo3mTkrvo9J5yDjHgU8xzNszH29IwsTudTq6CBJ" \ 'http://path/to/ITSM-NG/apirest.php/search/Ticket?criteria[0]
    [field]=15&criteria[0][searchtype]=morethan&criteria[0][value]=2023-01-10&criteria[1] [link]=AND&criteria[1][field]=12&criteria[1][searchtype]=equals&criteria[1][value]=3'

Retour succès de la recherche :

< 200 OK 
< [ {"totalcount":1,"count":1,"sort":"1","order":"ASC","data":[{"2":5,"1":"Panne sur le service 5G","12":3,"19":"2023-01-18 14:51:07","15":"2023-01-18 14:43:51","3":4,"4":"10","8":"Support services mobiles","83":"Métropole > Normandie","7":"Service mobiles","76665":"INT-0001","151":"2023-01-19 09:43:51","30":"Urgent"}],"content-range":"0-0/1"}]

Note: le paramètre expand_dropdowns n’est pas disponible pour la route /search. Vous trouverez la correspondance complète entre les ids et les champs dans le fichier Ticket_searchoptions.json.
Il est également possible de récupérer ce modèle via la route /listSearchOptions (cf chapitre 3.3.1).

4.4. Récupération d’un ticket (/Ticket/)

Voici les étapes à suivre pour récupérer les informations d’un ticket en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des informations du ticket que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Ticket/15? expand_dropdowns=true&get_hateoas=false'

Retour succès avec les informations du ticket :

< 200 OK < [ { "id": 15, "entities_id": "Entité Racine", "name": "Panne sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

4.5. Mise à jour d’un ticket (/Ticket/)

Voici les étapes à suivre pour mettre à jour un ticket en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

La prochaine étape est de construire le JSON avec les données du ticket que l’on souhaite mettre à jour.

Dans l’exemple ci-dessous, nous allons mettre à jour le status du ticket :

{
"status": 3
}

Note : au moment de l’envoi, les données JSON du ticket doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X PUT \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"status": 3}}' \
    'http://path/to/ITSM-NG/apirest.php/Ticket/15'

Retour succès :

< 200 OK [{"15":true, "message": ""}]

4.6. Suppression d’un ticket (/Ticket/)

Voici les étapes à suivre pour supprimer un ticket en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Ci-dessous les options disponibles pour la suppression de ticket :

Exemple d’utilisation :

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
'http://path/to/ITSM-NG/apirest.php/Ticket/15?force_purge=true'

Retour succès :

< 200 OK [{"15":true, "message": ""}]

5. Acteurs ticket et notifications courriels

5.1. Ajout d’un acteur (/Ticket_User/)

Voici les étapes à suivre pour ajouter un acteur à un ticket et configurer le suivi courriel via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Pour récupérer l’ID de l’utilisateur, il faut effectuer une recherche avec la route
// en remplaçant {itemtype} par User (cf. chapitre 7.1).

La prochaine étape est de construire le JSON avec les données récupérées pour lier un utilisateur à un ticket.

{
    "tickets_id": 15,
    "users_id": 250,
    "type": 3,
    "use_notification": 1,
    "alternative_email": "mon.utilisateur@mail.fr",
}

Le champ « type » correspond au rôle de l‘acteur du ticket. Il peut être renseigné comme suis :

Le champ « use_notification » permet d’activer ou désactiver le suivi par courriel et peut être renseigné comme suis :

Le champ « alternative_email » permet de renseigner une adresse email alternative. Si le champ est laissé vide, ce sera l’adresse email configurée dans la fiche utilisateur qui sera utilisée.

Note : au moment de l’envoi, les données JSON de la tâche doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"tickets_id": 15, "users_id": 250, "type": 3, "use_notification": 1, "alternative_email": "mon.utilisateur@mail.fr"}}'\
    'http://path/to/ITSM-NG/apirest.php/Ticket_User/'

Retour succès :

< 200 OK 
[{"id": 2, "message": ""}]

5.2. Récupération des acteurs d’un ticket (/Ticket_User/)

Voici les étapes à suivre pour récupérer tous les acteurs d’un ticket via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

L’étape suivante est de construire son URL avec les paramètres de recherche utiles. Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g'http://path/to/ITSM-NG/apirest.php/Ticket_User/? expand_dropdowns=true&searchText[tickets_id]=15'

Retour succès avec la liste de tous les acteurs du ticket :

< 200 OK 
< [ { "id": 2, "tickets_id": "Panne sur le réseau 5G", "users_id":"utilisateur1" }]

Le modèle complet du retour est présent dans la documentation Swagger.

5.3. Mise à jour d’un acteur d’un ticket (/Ticket_User/)

Voici les étapes à suivre pour mettre à jour un acteur d’un ticket en fonction de son ID via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID de Ticket_User en effectuant une recherche avec la route /Ticket_User/ (cf. chapitre 4.2).

La prochaine étape est de construire le JSON avec les données de l’acteur que l’on souhaite mettre à jour.

Dans l’exemple ci-dessous, nous allons mettre à jour le suivi par courriel de l’acteur :

{
    "use_notification": 1,
    "alternative_email": "mon.utilisateur@mail.fr"
}

Note : au moment de l’envoi, les données JSON de Ticket_User doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X PUT \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"use_notification": 1, "alternative_email": "mon.utilsateur@mail.fr"}}'\
    'http://path/to/ITSM-NG/apirest.php/Ticket

Retour succès :

< 200 OK [{"2":true, "message": ""}]

5.4. Suppression d’un acteur d’un ticket (/Ticket_User/)

Voici les étapes à suivre pour supprimer un acteur d’un ticket en fonction de son ID via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID de Ticket_User en effectuant une recherche avec la route /Ticket_User/ (cf. chapitre 4.2).

Ci-dessous les options disponibles pour la suppression de tâche :

Exemple d’utilisation :

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
-H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
'http://path/to/ITSM-NG/apirest.php/Ticket_User/2?force_purge=true'

Retour succès :

< 200 OK [{"2":true, "message": ""}]

6. Tâches

6.1. Création d’une tâche (/TicketTask/)

Voici les étapes à suivre pour créer une tâche dans un ticket via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

La prochaine étape est de construire le JSON avec les données de la tâche que l’on souhaite ajouter au ticket.

{
    "tickets_id": 15,
    "taskcategories_id": 10,
    "users_id": 250,
    "content": "Ceci est une description", "is_private": 0,
    "begin": "2022-12-08 16:30:00 (Y-m-d HH:ii:ss)",
    "end": "2022-12-08 18:10:00 (Y-m-d HH:ii:ss)",
    "state": 1,
    "users_id_tech": 17,
    "groups_id_tech": 57
}

Le champ « state » correspond au statut de la tâche. Il peut être renseigné comme suis :

Note : au moment de l’envoi, les données JSON de la tâche doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"tickets_id": 15, "content": "Ceci est une description"}}' \
    'http://path/to/ITSM-NG/apirest.php/TicketTask/'

Retour succès :

< 200 OK [{"id": 2, "message": ""}]

6.2. Récupération des tâches d’un ticket (/TicketTask/)

Voici les étapes à suivre pour récupérer toutes les tâches d’un ticket via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

L’étape suivante est de construire son URL avec les paramètres de recherche utiles. Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/TicketTask/? expand_dropdowns=true&searchText[tickets_id]=15'

Retour succès avec la liste de toutes les tâches du ticket :

< 200 OK 
< [ { "id": 2, "content": "Ceci est une description", "tickets_id": "Panne sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger

6.3. Récupération d’une tâche d’un ticket (/TicketTask/)

Voici les étapes à suivre pour récupérer les informations d’une tâche en fonction de son ID via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des informations de la tâche que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/TicketTask/2? expand_dropdowns=true&get_hateoas=false'

Retour succès avec les informations de la tâche :

< 200 OK 
< [ { "id": 2, "content": "Ceci est une description", "tickets_id": "Panne sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

6.4. Mise à jour d’une tâche (/TicketTask/)

Voici les étapes à suivre pour mettre à jour une tâche en fonction de son ID via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID de la tâche en effectuant une recherche avec la route /TicketTask/ (cf. chapitre 5.2).

La prochaine étape est de construire le JSON avec les données de la tâche que l’on souhaite mettre à jour.

Dans l’exemple ci-dessous, nous allons mettre à jour le status de la tâche :

{
    "state": 2
}

Note : au moment de l’envoi, les données JSON de la tâche doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X PUT \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"state": 2}}' \
    'http://path/to/ITSM-NG/apirest.php/TicketTask/2'

Retour succès :

< 200 OK [{"2":true, "message": ""}]

6.5. Suppression d’une tâche (/TicketTask/)

Voici les étapes à suivre pour supprimer une tâche en fonction de son ID via l’API.
La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID de la tâche en effectuant une recherche avec la route /TicketTask/ (cf. chapitre 5.2).

Ci-dessous les options disponibles pour la suppression de tâche :

Exemple d’utilisation :

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/TicketTask/2?force_purge=true'

Retour succès :

< 200 OK [{"2":true, "message": ""}]

7. Changements

7.1. Création d’un changement (/Change/)

Voici les étapes à suivre pour la création d’un nouveau changement via l’API. La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il faut construire le JSON qui va être envoyé à ITSM-NG avec les informations du changement . Ci-dessous un exemple avec les champs principaux :

{
    "name": "Changement sur le réseau 5G", 
    "content": "Ceci est une description", 
    "entities_id": 0,
    "itilcategories_id": 0,
    "urgency": 3,
    "impact": 3,
    "priority": 3,
    "status": 1
}

Note : au moment de l’envoi, les données JSON du changement doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"name": "Changement sur le réseau 5G", "content": "Ceci est une description"}}' \
    'http://path/to/ITSM-NG/apirest.php/Change/'

Retour succès avec l’ID du changement créé :

< 201 OK
 < Location: http://path/to/ITSM-NG/api/changement/15
< {"id": 15}

7.2. Récupération d’un ou plusieurs changements (/Change/)

Voici les étapes à suivre pour récupérer les informations d’un ou plusieurs changements via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des changements que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

Cette exemple montre comment retourner les informations du changement précédemment créé dans le chapitre 1.

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Change/? expand_dropdowns=true&searchText[name]=Changement%20sur%20le%20reseau%205G'

Retour succès avec le changement recherché :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Changement sur le réseau 5G", ...}]

Note : si plusieurs changements correspondent à cette recherche alors l’API retournera la liste de tous les changements correspondant.

Le modèle complet du retour est présent dans la documentation Swagger.

7.3. Récupération d’un changement (/Change/)

Voici les étapes à suivre pour récupérer les informations d’un changement en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des informations du changement que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Change/15?expand_dropdowns=true&get_hateoas=false'

Retour succès avec les informations du changement :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Changement sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

7.4. Mise à jour d’un changement (/Change/)

Voici les étapes à suivre pour mettre à jour un changement en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du changement en effectuant une recherche avec la route /Change/ (cf. chapitre 6.2).

La prochaine étape est de construire le JSON avec les données du changement que l’on souhaite mettre à jour.

Dans l’exemple ci-dessous, nous allons mettre à jour le status du changement :

{
    "status": 9
}

Note : au moment de l’envoi, les données JSON du changement doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X PUT \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"status": 9}}' \
    'http://path/to/ITSM-NG/apirest.php/Change/15'

Retour succès :

< 200 OK 
[{"15":true, "message": ""}]

7.5. Suppression d’un changement (/Change/)

Voici les étapes à suivre pour supprimer un changement en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du changement en effectuant une recherche avec la route /Change/ (cf. chapitre 6.2).

Ci-dessous les options disponibles pour la suppression de changement :

Exemple d’utilisation :

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Change/15?force_purge=true'

Retour succès :

< 200 OK 
[{"15":true, "message": ""}]

8. Problèmes

8.1. Création d’un problème (/Problem/)

Voici les étapes à suivre pour la création d’un nouveau problème via l’API.
La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).
Ensuite il faut construire le JSON qui va être envoyé à ITSM-NG avec les informations du problème . Ci-dessous un exemple avec les champs principaux :

{
    "name": "Problème sur le réseau 5G", 
    "content": "Ceci est une description", 
    "entities_id": 0,
    "itilcategories_id": 0,
    "urgency": 3,
    "impact": 3,
    "priority": 3,
    "status": 1
}

Note : au moment de l’envoi, les données JSON du problème doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"name": "Problème sur le réseau 5G", "content": "Ceci est une description"}}' \
    'http://path/to/ITSM-NG/apirest.php/Problem/'

Retour succès avec l’ID du problème créé :

< 201 OK 
< Location: http://path/to/ITSM-NG/api/problem/15
< {"id": 15}

8.2. Récupération d’un ou plusieurs problème (/Problem/)

Voici les étapes à suivre pour récupérer les informations d’un ou plusieurs problèmes via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des problèmes que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation : Cette exemple montre comment retourner les informations du problème précédemment créé dans le chapitre 6.1.

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Problem/?expand_dropdowns=true&searchText[name]=Probleme%20sur%20le%20reseau%205G'

Retour succès avec le problème recherché :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Problème sur le réseau 5G", ...}]

Note : si plusieurs problèmes correspondent à cette recherche alors l’API retournera la liste de tous les problèmes correspondant.

Le modèle complet du retour est présent dans la documentation Swagger.

8.3. Récupération d’un problème (/Problem/)

Voici les étapes à suivre pour récupérer les informations d’un problème en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1)

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des informations du problème que l’on souhaite retourner.
Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Problem/15?expand_dropdowns=true&get_hateoas=false'

Retour succès avec les informations du problème :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Problème sur le réseau 5G", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

8.4. Mise à jour d’un problème (/Problem/)

Voici les étapes à suivre pour mettre à jour un problème en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du problème en effectuant une recherche avec la route /Problem/ (cf. chapitre 7.2).

La prochaine étape est de construire le JSON avec les données du problème que l’on souhaite mettre à jour.

Dans l’exemple ci-dessous, nous allons mettre à jour le status du problème :

{
    "status": 7
}

Note : au moment de l’envoi, les données JSON du problème doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X PUT \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"status": 7}}' \
    'http://path/to/ITSM-NG/apirest.php/Problem/15'

Retour succès :

< 200 OK 
[{"15":true, "message": ""}]

8.5. Suppression d’un problème (/Problem/)

Voici les étapes à suivre pour supprimer un problème en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du problème en effectuant une recherche avec la route /Problem/ (cf. chapitre 7.2).

Ci-dessous les options disponibles pour la suppression de problème :

Exemple d’utilisation :

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Problem/15?force_purge=true'

Retour succès :

< 200 OK .
[{"15":true, "message": ""}]

9. ItemType

9.1. Récupération d’un objet ITSM-NG (//)

La route // est celle actuellement utilisée pour tous les objets ITSM-NG renseignés dans cette documentation (Ticket, TicketTask, Change, Problem, etc ..).

Il est donc possible de réutiliser cette route pour d’autres objets ITSM-NG comme :

Vous trouverez toutes les options de recherches facultatives dans la définition de la route ItemType du Swagger.

9.2. Récupération de la CMDB

L’API permet également de récupérer des informations liées aux actifs (CMDB) ainsi que les relations entre les différents actifs / applicatifs.

Voici une liste des objets faisant référence à la CMDB :

Afin de récupérer les relations entre éléments, il suffit d’utiliser l’objet « ImpactRelation ». Cette route va permettre de voir tout le fil de relation entre éléments, type d’éléments sous le format JSON.

10. Document

10.1. Téléversement d’un document (/Document/)

Voici les étapes à suivre pour téléverser un document via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Le téléversement d'un fichier nécessite l'utilisation du type de contenu « multipart/data ». Les données d'entrée doivent être envoyées dans un paramètre « uploadManifest » et utiliser le format JSON comme ci-dessous :

uploadManifest = {
"input": {
"name": "Document 1",
"_filename": ["file.txt"]
}
};type=application/json 

filename[0]=@file.txt

Exemple d’utilisation :

curl -X POST \ 
    -H 'Content-Type: multipart/form-data' \ 
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \ 
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \ 
    -F 'uploadManifest={"input": {"name": "Uploaded document", "_filename" : ["file.txt"]}};type=application/json' \ 
    -F 'filename[0]=@file.txt' \
'http://path/to/ITSM-NG/apirest.php/Document/'

Retour succès avec l’ID du document téléversé :

< 201 OK 
< Location: http://path/to/ITSM-NG/api/Document/1 
< {"id": 1, "message": "Document move succeeded.", "upload_result": {...}}

10.2. Téléchargement d’un document (/Document/)

Voici les étapes à suivre pour télécharger un document via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Le téléchargement d’un document requiert l’ajout du paramètre Header suivant :
Accept: application/octet-stream

OU du paramètre « alt » dans la requête. Ce dernier doit forcément être renseigné avec la valeur « media ».

Afin de renseigner l’ID du document qui doit être téléchargé, il faut construire le JSON suivant :

{
    "id": 1:
}

Note : au moment de l’envoi, les données JSON du document doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \ 
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \ 
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \ 
    -H "Accept: application/octet-stream" \ 
    -d '{"input": {"id": 1}}' \ 
'http://path/to/ITSM-NG/apirest.php/Document/'

Retour succès (le corps de la réponse contient le fichier brut joint au document) :

< 200 OK

10.3. Récupération des informations d’un document (/Document/)

Voici les étapes à suivre pour récupérer les informations d’un ou plusieurs documents via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des documents que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation : Cette exemple montre comment retourner les informations du problème précédemment créé dans le chapitre 6.1.

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Document/? expand_dropdowns=true&searchText[name]=Document%201'

Retour succès avec le problème recherché :

< 200 OK 
< [ { "id": 15, "entities_id": "Entité Racine", "name": "Document 1", ...}]

Note : si plusieurs documents correspondent à cette recherche alors l’API retournera la liste de tous les documents correspondant.

10.4. Récupération des informations d’un document (/Document/)

Voici les étapes à suivre pour récupérer les informations d’un document en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des informations du document que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Document/1? expand_dropdowns=true&get_hateoas=false'

Retour succès avec les informations du document :

< 200 OK < [ { "id": 1, "entities_id": "Entité Racine", "name": "Document 1", ...}]

Le modèle complet du retour est présent dans la documentation Swagger.

10.5. Suppression d’un document (/Document/)

Voici les étapes à suivre pour supprimer un document en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du document en effectuant une recherche avec la route /Document/ (cf. chapitre 7.2).

Ci-dessous les options disponibles pour la suppression de document :

Exemple d’utilisation :

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Document/1?force_purge=true'

Retour succès :

< 200 OK 
[{"1":true, "message": ""}]

10.6. Liaison d’un document à un ticket (/Document_Item/)

Voici les étapes à suivre pour lier un document à un ticket via l’API.
La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Pour récupérer l’ID du document, il faut effectuer une recherche avec la route /Document/ (cf. chapitre 9.3).

Ensuite il faut construire le JSON qui va être envoyé à ITSM-NG avec les informations de la liaison.

Ci-dessous un exemple avec les champs principaux :

{
    "documents_id": 1,
    "items_id": 15, 
    "itemtype": "Ticket",
}

Note : au moment de l’envoi, les données JSON de la liaison doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"documents_id": 1, "items_id": 15, "itemtype": "Ticket"}}' \
    'http://path/to/ITSM-NG/apirest.php/Document_Item/'

Retour succès avec l’ID du problème créé :

< 201 OK 
< Location: http://path/to/ITSM-NG/api/document_item/15
< {"id": 15}

10.7. Récupération de la liste des documents liés à un ticket (/Document_Item/)

Voici les étapes à suivre pour récupérer les informations d’un ou plusieurs documents liés à un ticket via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1). Il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Ensuite, il faut construire son URL avec les paramètres de recherche utiles en fonction des documents que l’on souhaite retourner.

Ci-dessous les paramètres de recherches les plus importants :

Exemple d’utilisation :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Document_Item/? expand_dropdowns=true&searchText[tickets_id]=15'

Retour succès avec le problème recherché :

< 200 OK 
< [ { "id": 1, "entities_id": "Entité Racine", "documents_id": "35", ...}]

Note : si plusieurs documents correspondent à cette recherche alors l’API retournera la liste de tous les documents liés correspondant.

Le modèle complet du retour est présent dans la documentation Swagger.

10.8. Suppression de la liaison entre un document et un ticket (/Document_Item/)

Voici les étapes à suivre pour supprimer une liaison entre un document et un ticket en fonction de son ID via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du document en effectuant une recherche avec la route /Document/ (cf. chapitre 7.2).

Il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Puis nous pouvons récupérer l’ID de la liaison grâce à la requête suivante :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/Document_Item/? expand_dropdowns=true&searchText[tickets_id]=15&searchText[documents_id]=1'

Ci-dessous les options disponibles pour la suppression de la liaison :

Exemple d’utilisation :

curl -X DELETE \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    'http://path/to/ITSM-NG/apirest.php/Document_Item/1?force_purge=true'

Retour succès :

< 200 OK 
[{"1":true, "message": ""}]

11. Référence externe

11.1. Insertion d’une référence externe dans un ticket

Dans ce chapitre, nous partons du principe que le plugin Fields est installé et configuré sur l’applicatif ITSM-NG.

Pour l’exemple, nous avons un bloc appelé « referenceexterne» avec un champ « reference ». Voici les étapes à suivre pour ajouter une valeur à la référence externe d’un ticket via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Pour la suite, nous allons contruire le JSON à envoyer :

{
"items_id": 15, 
"itemtype": "Ticket",
"referencefield": "Ceci est ma valeur",
}

Note : au moment de l’envoi, les données JSON de la référence externe doivent être encapsulées dans un input (cf. exemple d’utilisation)

Exemple d’utilisation :

curl -X POST \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -d '{"input": {"items_id": 15, "itemtype": "Ticket", "referencefield": "Ceci est
    ma valeur"}}' \
    'http://path/to/ITSM-NG/apirest.php/PluginFieldsTicketreferenceexterne/'

Retour succès :

< 200 OK 
[{"id":3, "message": "Elément ajouté : Général- ID 15"}]

11.2. Récupération d’une référence externe

Dans ce chapitre, nous partons du principe que le plugin Fields est installé et configuré sur l’applicatif ITSM-NG.

Pour l’exemple, nous avons un bloc appelé « referenceexterne» avec un champ « reference ».Voici les étapes à suivre pour ajouter une valeur à la référence externe d’un ticket via l’API.

La première étape (si ce n’est pas déjà fait) est de récupérer le jeton de session (cf. chapitre 2.1).

Ensuite il est possible de récupérer l’ID du ticket en effectuant une recherche avec la route /Ticket/ (cf. chapitre 3.2).

Ci-dessous la liste des paramètres de recherche :

Exemple d’utilisation pour retourner toutes les références externes « referenceexterne» :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/PluginFieldsTicketreferenceexterne/? expand_dropdowns=true'

Résultat succès avec toutes les références par ticket :

< 200 OK 
< [ { "itemtype": "Ticket", "referencefield": "Ceci est ma valeur", "items_id": "Panne sur le réseau 5G", ...}]

Exemple d’utilisation pour retourner la référence externe d’un ticket :

curl -X GET \
    -H 'Content-Type: application/json' \
    -H "Session-Token: 83af7e620c83a50a18d3eac2f6ed05a3ca0bea62" \
    -H "App-Token: f7g3csp8mgatg5ebc5elnazakw20i9fyev1qopya7" \
    -g 'http://path/to/ITSM-NG/apirest.php/PluginFieldsTicketreferenceexterne/? expand_dropdowns=true&searchText[items_id]=15’

Résultat succès avec la référence du ticket :

< 200 OK 
< [ { "itemtype": "Ticket", "referencefield": "Ceci est ma valeur", "items_id": "Panne sur le réseau 5G", ...}]

12. Troubleshooting

ERROR_ITEM_NOT_FOUND : La ressource souhaitée (itemtype-id) n'a pas été trouvée dans la base de données ITSM-NG.

ERROR_BAD_ARRAY : Le corps HTTP doit être un tableau d'objets.

ERROR_METHOD_NOT_ALLOWED : Vous avez spécifié une ressource inexistante ou non autorisée.

ERROR_RIGHT_MISSING : L'utilisateur actuellement connecté n'a pas les droits dans son profil pour effectuer l'action fournie. Modifiez ce profil ou choisissez-en un nouveau pour l'utilisateur dans l'interface principale de ITSM-NG.

ERROR_SESSION_TOKEN_INVALID : Le jeton de session fourni dans l'en-tête n'est pas valide. Vous devez refaire une demande d'initialisation de session (cf chapitre 2.1).

ERROR_SESSION_TOKEN_MISSING : Le jeton de session est manquant dans la requête HTTP.

ERROR_APP_TOKEN_PARAMETERS_MISSING : L'API actuelle nécessite un en-tête App-Token pour utiliser ses méthodes.

ERROR_WRONG_APP_TOKEN_PARAMETER : Il semble que le jeton d'application fourni n'existe pas dans la configuration de l'API ITSM-NG.

ERROR_NOT_DELETED : L’élément doit être marqué pour suppression avant d’être supprimé réellement.

ERROR_NOT_ALLOWED_IP : Nous ne trouvons pas de client actif défini dans la configuration de votre IP. Allez dans le menu ITSM-NG Configuration > Générale et l'onglet API pour vérifier l'accès IP.

ERROR_LOGIN_PARAMETERS_MISSING : Un de ces paramètre(s) est manquant :
Couple identifiant/mot de passe
user_token

ERROR_LOGIN_WITH_CREDENTIALS_DISABLED : La configuration de ITSM-NG interdit la connexion avec des informations d'identification, vous devez vous connecter avec votre user_token à la place. Consultez votre page de préférences personnelles ou configurez l'accès à l'API dans l'interface principale de ITSM-NG.

ERROR_GLPI_LOGIN_USER_TOKEN : Le user_token fourni semble invalide. Vérifiez votre page de préférences personnelles dans l'interface principale de ITSM-NG.

ERROR_GLPI_LOGIN : Nous ne pouvons pas vous connecter à ITSM-NG. Cette erreur n'est pas relative à l'API mais au coeur de ITSM-NG. Vérifiez l'administration des utilisateurs et les fichiers journaux de ITSM-NG (dans le répertoire files/_logs).

ERROR_ITEMTYPE_NOT_FOUND_NOR_COMMONDBTM : Vous avez demandé une ressource inexistante (endpoint). Ce n'est pas une ressource prédéfinie (initSession, getFullSession, etc.) ni une ressource ITSM-NG CommonDBTM.

ERROR_SQL : Nous soupçonnons une erreur SQL. Cette erreur n'est pas relative à l'API mais au coeur de ITSM-NG. Vérifiez les fichiers journaux de ITSM-NG (dans le répertoire files/_logs).

ERROR_RANGE_EXCEED_TOTAL : Le paramètre de plage que vous avez fourni est supérieur au nombre total de données disponibles.

ERROR_GLPI_ADD : Nous ne pouvons pas ajouter l'objet à ITSM-NG. Cette erreur n'est pas relative à l'API mais au coeur de ITSM-NG. Vérifiez les fichiers journaux de ITSM-NG (dans le répertoire files/_logs).

ERROR_GLPI_PARTIAL_ADD : Certains des objets que vous vouliez ajouter déclenchent une erreur. Peut-être un champ ou des droits manquants. Vous trouverez avec cette erreur une collection de résultats.

ERROR_GLPI_UPDATE : Nous ne pouvons pas mettre à jour l'objet vers ITSM-NG. Cette erreur n'est pas relative à l'API mais au coeur de ITSM-NG. Vérifiez les fichiers journaux de ITSM-NG (dans le répertoire files/_logs).

ERROR_GLPI_PARTIAL_UPDATE : Certains des objets que vous vouliez mettre à jour déclenchent une erreur. Peut-être un champ ou des droits manquants. Vous trouverez avec cette erreur une collection de résultats.

ERROR_GLPI_DELETE : On ne peut pas supprimer l'objet vers ITSM-NG. Cette erreur n'est pas relative à l'API mais au coeur de ITSM-NG. Vérifiez les fichiers journaux de ITSM-NG (dans le répertoire files/_logs).

ERROR_GLPI_PARTIAL_DELETE : Certains des objets que vous souhaitez supprimer déclenchent une erreur, peut-être un champ ou des droits manquants. Vous trouverez avec cette erreur, une collection de résultats.