Cette section décrit l' API Web d'Efecte et les applications externes utilisées pour s'intégrer à Efecte. L' API repose sur le protocole HTTP standard. Les méthodes API Web d'Efecte sont appelées depuis l'URL d'Efecte + /serviceName, où serviceName est le nom du service à appeler. Par exemple : https://localhost:8080/esm/search.ws ou, dans le cloud d'Efecte, https://base_url/api/itsm/search.ws .

Avant d'utiliser API Web, veuillez consulter le chapitre « Authentification », qui décrit l'authentification à API Web et fournit des informations complémentaires sur les rôles et les autorisations. Ce chapitre explique également comment créer un rôle et un utilisateur API Web. L'utilisateur API Web doit être un compte ESM local, et non un compte EIM utilisé pour les connexions à l'environnement cloud.

Certaines opérations peuvent être lentes à traiter. Par exemple, l'importation de références multi-valeurs prend généralement plus de temps que l'importation sans référence. De plus, les expressions complexes dans un modèle peuvent ralentir le traitement des importations. Il est conseillé de toujours filtrer les résultats en utilisant where et, par exemple, templateCode dans search.ws.

Service d'importation de cartes de données

Pour créer une nouvelle carte de données dans Efecte, l'utilisateur doit appeler le service dataCardImport. Ce service utilise le XML de la carte de données comme un corps HTTP ; l'appelant doit donc connaître la syntaxe XML et le schéma Efecte de la carte de données créée. Ce document ne spécifie pas le schéma XML ; consultez la description du schéma XML d'Efecte pour plus d'informations. Le paramètre createDataCards doit être défini sur true lors de la création de nouvelles cartes de données.

Pour modifier une fiche de données existante, au moins un champ de fiche de données doit être défini comme unique dans Efecte dans le XML envoyé. Efecte tente ensuite de faire correspondre les données entrantes à une fiche de données et de mettre à jour la fiche correspondante. Le paramètre updateDataCards doit être défini sur « true » lors de la modification de fiches de données existantes.

Lors de la mise à jour des cartes de données, les valeurs d'attribut XML remplacent les valeurs existantes et les champs inexistants dans XML sont conservés tels quels dans Efecte. Pour supprimer des valeurs d'attribut d'Efecte, laissez l'élément valeur vide dans le XML et utilisez le paramètre removeEmptyValues.
Notez qu'à des fins d'intégration, une bonne façon de gérer les importations est d'importer une seule carte de données à la fois et de maintenir le trafic à un niveau raisonnable pour les raisons suivantes :

• L'inspection des erreurs est plus facile, de cette façon les entités erronées provenant de l'importation peuvent être identifiées immédiatement.
• L'importation d'une quantité importante de cartes de données peut entraîner des délais d'attente.

Paramètres HTTP

Voici une liste des paramètres HTTP possibles qui peuvent être utilisés (paramètres HTTP du service DataCardImport) :

* Soit folderId soit folderCode doit être inclus dans les paramètres

Erreurs dans DataCardImport

En général, si l'un des paramètres obligatoires (listés dans le tableau 7) est manquant ou contient des valeurs non valides, une erreur API Web est renvoyée. C'est également le cas pour les erreurs d'authentification et d'autorisation API Web. (Voir le chapitre 5 « Erreurs API Web » pour plus d'informations sur les erreurs API Web.)

Cependant, si quelque chose d'autre se passe mal lors de l'importation de certaines cartes de données (par exemple, le modèle des cartes importées est mal configuré), le service DataCardImport renvoie contenant des informations sur les cartes de données traitées et sur les erreurs survenues lors de l'importation.

Les valeurs à importer doivent se trouver dans l'élément <value>. Si elles sont importées dans l'élément <reference>, des références erronées à la carte de données seront créées. Si des références sont nécessaires, assurez-vous que l'utilisateur API Web a accès au modèle auquel vous faites référence, sinon la référence ne sera pas créée. Les références doivent cibler la valeur principale du modèle.

Exemple de demande et de réponse

Demande

Service : dataCardImport.ws

Exemple d'URL :
https://localhost:8080/esm/dataCardImport.ws?folderCode=incident_management

Corps du message :

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>Test incident</value>
     </attribute>
     <attribute code="category">
       <value>Testing</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>  
</entityset>

Réponse

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>09.07.2018 09:03:04</start-time>
   <total-time>10,494</total-time>
   <entities-handled-per-second>0,095</entities-handled-per-second>
   <average-entity-handling-time>10,494</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Supprimer le service

Pour supprimer une carte de données existante d'Efecte, l'utilisateur doit appeler le service de suppression. Ce service peut supprimer des cartes de données selon deux critères :

• ID de la carte de données interne (ID d'entité).
• Une requête de recherche ; les cartes de données correspondant à la requête seront supprimées.

Paramètres HTTP

Supprimer les paramètres HTTP du service :

* L'un des deux paramètres (ids, query) est obligatoire. Les paramètres sont traités dans cet ordre, et un seul sera pris en compte lors d'une invocation du service. Si les paramètres ids et query sont tous deux spécifiés, le service ignorera le paramètre query et tentera uniquement de supprimer les cartes de données en fonction du paramètre ids.

Exemple de demande et de réponse : suppression d'une carte de données avec ID d'entité

Demande

Service : delete.ws

Exemple d'URL :
https://localhost:8080/esm/delete.ws?ids=15021

Réponse

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Exemple de requête et de réponse, suppression de données de carte à l'aide EQL

Demande

Service : delete.ws

EQL : SÉLECTIONNEZ $efecte_id$, $subject$, $status$ DE L'entité OÙ entity.template.code = 'incident' ET $efecte_id$='INC-000270'

Exemple d'URL :
https://localhost:8080/esm/delete.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'%20and%20%24efecte_id%24%3D'INC-000270'

Réponse

<?xml version="1.0" encoding="utf-8"?>
<entity-delete-report>
   <successful-deletions count="1"/>
   <failed-deletions count="0"/>
</entity-delete-report>

Service de recherche

Pour rechercher des cartes de données, Efecte propose un service web dataCardSearch qui utilise une requête EQL (Efecte Query Language) et renvoie les résultats au format XML. Consultez le chapitre 2 pour plus d'informations sur la construction de requêtes EQL .

Le XML renvoyé par le service de recherche est dans l’un des trois formats suivants :

• Entité XML
• Modèle XML
• XML « générique »

Les XML d'entité et les XML de modèle sont décrits dans le document de description du schéma XML d'Efecte . Le format XML « générique » est décrit avec des exemples ci-dessous. Notez que le format générique peut inclure des instances complètes de XML d'entité et de XML de modèle, selon la requête EQL .

Les valeurs de date sont toujours renvoyées au format aaaa-MM-jj HH:mm:ss z , conformément à la norme ISO 8601. Notez que le nom du fuseau horaire est inclus à la fin. Le fuseau horaire utilisé est toujours celui par défaut de la JVM ou de la base de données. Notez que si la prise en charge de plusieurs fuseaux horaires est activée, cela peut différer du format Entity XML, où les valeurs datetime sont ajustées selon le fuseau horaire de l'utilisateur du service Web.

Dans les nombres décimaux, le point (.) est utilisé comme séparateur décimal. L'encodage des caractères utilisé dans la réponse XML dépend de la propriété webservice.response.encoding du framework. L'encodage par défaut est UTF-8.

S'il n'est pas nécessaire d'afficher les cartes de données supprimées ou masquées, utilisez entity.deleted=0 ou entity.hidden=0 dans le paramètre de requête.

Résultat XML générique

Éléments de type de données possibles pour les résultats de recherche génériques :

Paramètres HTTP

Paramètres HTTP du service de recherche :

Exemple de requête et de réponse, ne renvoie que les noms des entités

Un document composé de valeurs <string>, directement sous l'élément <result>, est renvoyé en réponse à la requête EQL simple.

Demande

Service : search.ws

EQL : SELECT entity.name FROM entity WHERE entity.folder.name = 'Gestion des incidents'

Exemple d'URL :
https://localhost:8080/esm/search.ws?query=select%20entity.name%20from%20entity%20where%20entity.folder.name%20%3D%20'Gestion des incidents'

Réponse

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <string>Problems in CRM</string>
   <string>Mobile phone not working</string>
   <string>Test incident</string>
   <string>API incident</string>
</result>

Exemple de requête et de réponse, utilisant les codes d'attribut du modèle

Lors de la sélection de plusieurs champs, les résultats sont regroupés à l'aide éléments. Notez que l'ordre des chaînes dans la ligne est le même que l'ordre des attributs dans select (les positions sont liées).

Demande

Service : search.ws

EQL : SÉLECTIONNEZ $efecte_id$, $subject$, $status$ DE l'entité OÙ entity.template.code = 'incident'

Exemple d'URL :
https://localhost:8080/esm/search.ws?query=select%20%24efecte_id%24%20%2C%24subject%24%2C%20%24status%24%20from%20entity%20where%20entity.template.code%20%3D%20'incident'

Réponse

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>INC-000270</string>
       <string> Problems in CRM </string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000273</string>
       <string>Mobile phone not working</string>
       <string>1 - Untouched</string>
   </row>
   <row>
       <string>INC-000272</string>
       <string>Test incident </string>
       <string>2 - Solving</string>
   </row>
</result>

Exemple de demande et de réponse, nom du dossier de retour et cible des données de référence

Dans ce cas, le résultat XML générique inclut des documents XML d'entité complets « intégrés », ainsi que des valeurs <string> simples :
Demande

Service : search.ws

EQL : SÉLECTIONNEZ entity.folder.name, entity.referenceData.target DE entity OÙ entity.templateId = 2597

Exemple d'URL :
https://localhost:8080/esm/search.ws?query= select%20entity.folder.name%2C%20entity.referenceData.target%20from%20entity%20where%20entity.templateId%20%3D%202597

Réponse

<?xml version="1.0" encoding="UTF-8" ?>
<result>
   <row>
       <string>Incident management</string>
       <entity id="14549" name="18.06.2018 09:03">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
   <row>
       <string>Incident management</string>
       <entity id="15066" name="18.06.2018 13:56">
           <template id="5604" name="ValueChange" code="ValueChange"/>
           <group id="834" name="system"/>
           <attribute id="5610" name="Value" code="value">
               <value>1 - Untouched</value>
           </attribute>
           <attribute id="5614" name="Modifier" code="creator">
               <value>webapi</value>
           </attribute>
       </entity>
   </row>
</result>

Exemple de requête et de réponse : renvoyer les attributs donnés à l'aide d'attributeCodes

Les attrbuteCodes définissent les attributs renvoyés dans le message de réponse. Ainsi, API Web ne renvoie pas d'attributs inutiles à l'utilisateur.

Demande

Service : search.ws

EQL : SÉLECTIONNER l'entité À PARTIR DE l'entité OÙ template.code='workstation'

Codes d'attribut : efecte_id,workstation_model,status

Exemple d'URL :
https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,workstation_model,status&query=select%20entity%20from%20entity%20where%20template.code%20%3D%20'workstation'

Réponse

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19103" name="Test User">
       <template id="1622" name="Workstation" code="workstation"/>
       <group code="asset"/>
       <attribute id="1628" name="Device model" code="workstation_model">
           <reference id="19125" name="MacBook Pro 15"/>
       </attribute>
       <attribute id="1380" name="Status" code="status">
           <value>2 - In use</value>
       </attribute>
       <attribute id="1311" name="Efecte ID" code="efecte_id">
           <value>WS-000148</value>
       </attribute>
   </entity>
</entityset>

Service de métadonnées de fichiers

Le service de métadonnées de fichier permet d'obtenir des informations sur les pièces jointes d'une fiche de données. Si la fiche contient plusieurs champs avec pièces jointes, les informations de toutes ces pièces jointes sont renvoyées simultanément. Cela simplifie l' API .

Depuis la version 4.2, le service de métadonnées renvoie non seulement le nom , mais aussi le nom d'affichage pour chaque pièce jointe. Le nom est un nom de fichier interne (par exemple, « 20180717_1.xml ») utilisé comme identifiant lors des requêtes auprès du service de téléchargement de fichiers (voir section suivante). Le nom d'affichage est le nom d'origine de la pièce jointe, généralement plus lisible (par exemple, « readme.txt »).

Paramètres HTTP

Paramètres HTTP du service FileMetaData :

Exemple de demande et de réponse

Demande

Service : fileMetadata.ws

Exemple d'URL :
https://localhost:8080/esm/fileMetadata.ws?entityId=15048

Réponse

<?xml version="1.0" encoding="utf-8"?>
<entity-attachment-metadata>
   <entity id="15048">
       <attribute id="2696" code="file_attachments">
           <attachment>
               <name>20180717_1.xml</name>
               <displayname>test.xml</displayname>
               <size>4871</size>
               <last-modified>2018-07-17 09:35:12 EEST</last-modified>
           </attachment>
       </attribute>
   </entity>
</entity-attachment-metadata>

Service de téléchargement de fichiers

Le service de téléchargement de fichiers permet de télécharger les fichiers joints aux cartes de données hébergées dans Efecte. Les fichiers sont renvoyés dans la réponse HTTP.

Le client doit toujours vérifier d'abord le code d'état HTTP de la réponse. Le corps de la réponse ne peut être interprété comme le fichier demandé que si le code d'état est « 200 OK ». Les autres codes d'état généralement définis par le service sont :

• 400 Bad Request – Si certains des paramètres requis sont manquants.
• 403 Interdit – Si l’utilisateur du service Web n’a aucune autorisation pour l’élément spécifié.
• Carte de données ou attribut.
• 404 Non trouvé – Si le fichier demandé n’est pas trouvé.

Dans ces situations d’erreur, le corps de la réponse HTTP est un message d’erreur XML contenant des informations plus détaillées.

Paramètres HTTP

Paramètres HTTP du service FileDownload :

Exemple de demande et de réponse

Demande

Service : fileDownload.ws

Exemple d'URL :
https://localhost:8080/esm/fileDownload.ws?entityId=15048&attributeId=2696&fileName=20180717_1.xml

Réponse

Dans ce cas, la réponse affiche les données du fichier

<?xml version="1.0" encoding="UTF-8"?>
<inventory>
   <item>
       <title>Computer</title>
       <price>1000</price>
       <company>Customer</company>
   </item>
<inventory>

Service de téléchargement de fichiers

Le service de téléchargement de fichiers permet de télécharger des fichiers sur une carte de données Efecte. Il analyse les requêtes HTTP conformes à la RFC 1867, « Téléchargement de fichiers par formulaire en HTML ». C'est-à-dire si une requête HTTP est soumise via la méthode POST et avec un type de contenu « multipart/form-data ». Il est possible d'envoyer plusieurs fichiers simultanément, si nécessaire.

La carte de données doit être créée avant de pouvoir y importer un fichier ! Le service FileUpload ne crée pas de nouvelle carte de données.

Paramètres HTTP

Paramètres HTTP du service FileUpload :

Exemple de demande et de réponse

Demande

Service : fileUpload.ws

Exemple d'URL :
https://localhost:8080/esm/fileUpload.ws?entityId=14938&attributeId=2696&operationType=set

Type de contenu : multipart/form-data

Réponse

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180717_15.xml</name>
   </attachment>
</attachment-upload-result>

Exemple étape par étape de création d'une carte de données et de téléchargement de fichiers dessus

Cet exemple détaillé illustre toutes les étapes nécessaires au téléchargement d'un fichier à partir de zéro. Les attributs clés sont en gras. Il comprend les étapes suivantes :

1. Importation (création) de la carte de données.
2. Interrogation de l'entityId de la carte de données.
3. Découverte de l'attributId des modèles pour l'attribut de pièce jointe.
4. Téléchargement du fichier sur la carte de données qui a été créée.

La première carte de données doit être créée :

Demande

Service : dataCardImport.ws

Exemple d'URL :
https://localhost:8080/esm/dataCardImport.ws?folderCode=incident_management

Corps du message :

<entityset>
 <entity>
     <template code="incident"/>
     <attribute code="subject">
       <value>File upload test</value>
     </attribute>
     <attribute code="impact">
       <value>3. Low</value>
     </attribute>
     <attribute code="urgency">
       <value>3. Low</value>
     </attribute>
 </entity>
</entityset>

Réponse

<?xml version="1.0" encoding="utf-8"?>
<entity-import-report>
   <start-time>04.09.2018 08:27:29</start-time>
   <total-time>0,602</total-time>
   <entities-handled-per-second>1,661</entities-handled-per-second>
   <average-entity-handling-time>0,602</average-entity-handling-time>
   <user>webapi</user>
   <entities-handled>1</entities-handled>
   <entities-saved>1</entities-saved>
   <entities-updated>0</entities-updated>
   <entities-created>1</entities-created>
</entity-import-report>

Avant de pouvoir téléverser un fichier, les identifiants entityId et attributeId des pièces jointes de la carte de données nouvellement créée doivent être connus. Voici une requête permettant d'obtenir l'identifiant entityId et de valider d'autres données :

Demande

Service : search.ws

EQL : SÉLECTIONNER l'entité À PARTIR DE l'entité OÙ template.code='incident' ET $created$>'NOW-1m' ET $created$<'NOW'
Codes d'attribut : efecte_id,file_attachments,status,subject,description,created

Exemple d'URL :
https://localhost:8080/esm/search.ws?attributeCodes=efecte_id,file_attachments,status,subject,description,created&query=select%20entity%20from%20entity%20where%20template.code%3D'incident'%20and%20%24created%24%3E'NOW-1m'%20and%20%24created%24%3C'NOW'

Réponse

<?xml version="1.0" encoding="UTF-8" ?>
<entityset>
   <entity id="19221" name="File upload test">
       <template id="2597" name="Incident" code="incident"/>
       <group code="incident_management"/>
       <attribute id="2612" name="Incident ID" code="efecte_id">
           <value>INC-000275</value>
       </attribute>
       <attribute id="2623" name="Status" code="status">
           <value>1 - Untouched</value>
       </attribute>
       <attribute id="2632" name="Subject" code="subject">
           <value>File upload test</value>
       </attribute>
       <attribute id="2789" name="Created" code="created">
           <value>04.09.2018 08:27</value>
       </attribute>
   </entity>
</entityset>

AttributeId peut être obtenu, par exemple avec les méthodes suivantes :

Via la page d'administration , sélectionnez le modèle approprié et modifiez l'attribut dont nous avons besoin de l'identifiant. À l'ouverture de l'attribut, l'identifiant correspond aux chiffres après le dernier caractère /, par exemple :
https://localhost:8080/esm/EfecteFrameset.do#/admin/templates/edit/2597/2680/2696

Utilisation du service de recherche pour obtenir le schéma du modèle.

Interrogation du schéma du modèle :

Demande

Service : search.ws

EQL : SÉLECTIONNEZ le modèle À PARTIR DU modèle OÙ template.code='incident'

Exemple d'URL :
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

Réponse
À partir de la réponse, nous devons trouver <attribute> dans lequel <code> est le code d'attribut de l'attribut de pièce jointe et à partir de cet attribut, nous voulons obtenir la valeur de <class-attribute-id> , comme :

…
<attribute>
               <id>2695</id>
               <class-attribute-id>2696</class-attribute-id>
               <code>file_attachments</code>
               <name>File attachments</name>
…

Maintenant que nous avons entityId et attributeId , nous pouvons télécharger le fichier :

Demande

Service : fileUpload.ws

Exemple d'URL :
https://localhost:8080/esm/fileUpload.ws?entityId=19221&attributeId=2696&operationType=set

Type de contenu : multipart/form-data

Réponse

<?xml version="1.0" encoding="utf-8"?>
<attachment-upload-result>
   <attachment>
       <name>20180904_1.xml</name>
   </attachment>
</attachment-upload-result>

Récupération du schéma de la carte de données

Les métadonnées de la carte de données Efecte, c'est-à-dire les informations sur les champs qu'elle peut contenir et leurs propriétés, sont accessibles via le service web dataCardSearch grâce à une requête EQL sur les modèles. Voici un exemple de requête EQL sélectionnant tous les modèles :

SÉLECTIONNER le modèle À PARTIR du modèle

Exemple d'URL :
https://localhost:8080/esm/search.ws?query=select%20template%20from%20template%20where%20template.code='incident'

Sécurité

Cryptage

L'authentification HTTP de base envoie les informations d'identification sous forme de texte brut, il est donc essentiel d'utiliser HTTPS.

Authentification

Les services API Web Efecte sont authentifiés via l'authentification HTTP de base. Vous devez créer les identifiants Efecte pour utiliser les services Web. (Dans l'arborescence des autorisations, créez un rôle autorisé à utiliser les services API Web Efecte et ajoutez-y un ou plusieurs utilisateurs.) Toutes les opérations sont exécutées avec les autorisations de l'utilisateur Efecte authentifié. Ces autorisations définissent les modèles, attributs et dossiers auxquels l'utilisateur du service Web peut accéder.

L'utilisateur root ne doit pas être utilisé comme utilisateur API Web, car il a accès à tout. Son utilisation peut donc être dangereuse. Cependant, lors de l'analyse de problèmes liés à API Web, il peut être utile de promouvoir API utilisateur root pour vérifier s'il existe des problèmes d'autorisations ou si les problèmes sont causés par API requête elle-même.

Création d'un utilisateur API Web

• Créez un rôle et sélectionnez l’autorisation du produit API Web.
• Ajoutez des autorisations de dossier au rôle.
• Ajoutez des autorisations de modèle au rôle.
• Créer un utilisateur API Web.
• Ajouter un utilisateur au rôle précédemment créé.
• Vérifiez que vous pouvez effectuer les opérations souhaitées via API Web. Vous pouvez le faire dans votre navigateur avec la commande /search.ws?query=select count(id) from entity.