API de recherche d’intégrations
Aperçu rapide
Afin de fournir plus de flexibilité et d'ouvrir la recherche d'entreprise à de nouvelles capacités, nous avons créé l'API de recherche d'intégrations. L'API d'intégrations est la façon d'intégrer les résultats de recherche tiers dans la recherche d'entreprise Workstation.
L'API de recherche d'intégrations vous permet de connecter des intégrations à la recherche d'entreprise, afin que vous puissiez ajouter des fonctionnalités de recherche pour contrôler l'expérience sur Workstation.
Cet article présente l'API de recherche d'intégrations Workstation.
Les intégrations tierces ajoutent deux capacités principales à WalkMe Workstation-
- Recherche d'entreprise - permet aux utilisateurs de découvrir des applications et des ressources avec une recherche unifiée.
- Widgets d'écran d'accueil - initier des processus directement dans Workstation et rationaliser l'accès aux outils et aux ressources couramment utilisés.
Comment ça marche
Pour créer une nouvelle intégration connectée à l'API d'intégrations, deux étapes sont nécessaires-
- Configuration- créez une nouvelle intégration.
- Exécution- obtenez une demande de l'API (requête de recherche) et fournissez une réponse (résultats de recherche).
Les deux flux seront expliqués dans ce document.
Configuration
Pour créer une nouvelle intégration, il sera nécessaire de fournir à WalkMe les paramètres suivants :
|
Paramètre |
Description |
| apiUrl |
Point de terminaison auquel les services de Workstation enverront la requête de recherche. Requis |
| apiKey |
Votre identifiant unique de service authentifie la source de requête. Requis |
| GUID du système |
Situé dans l'écran Paramètres de l'application >Workstation. Requis |
| appDescription |
Description en une ligne pour l'application, qui apparaîtra aux utilisateurs dans la page Intégrations. Exemple à un format approprié- « Recherche dans les fichiers Google Drive directement à partir de Workstation. » Requis |
| customName |
Nom de l'intégration, qui apparaîtra sur la page Intégrations, les résultats de recherche et le filtre de l'application. Requis |
| customImage |
URL de l'icône qui apparaîtra sur la page Intégrations, les résultats de recherche et le filtre de l'application. Requis |
Pour créer une nouvelle intégration, contactez votre gestionnaire de succès client avec les paramètres répertoriés dans le tableau ci-dessus, et le GUID système concerné.
À l'avenir, cette capacité sera ajoutée à la console WalkMe et sera gérée par l'administrateur du système.
Comme décrit ci-dessous en une Figure ci-dessous, le flux de configuration démarre dans la base de données (à l'avenir, sera fait dans la console). Après avoir fourni les paramètres de configuration, nous testons l'intégration pour nous assurer que nous obtenons une réponse appropriée.
Ce test sera effectué avec un « utilisateur fictif » créé de notre côté. Il ne nécessite aucune configuration du côté du service externe, car il s'agit d'une requête de recherche régulière qui indiquera si le flux a été terminé avec succès.
Exécution
Déclencheur pour le flux est une recherche par l'utilisateur final dans l'application Workstation.
Un appel API sera généré vers le point de terminaison de l'API (URL) avec la clé API fournie, selon les conditions suivantes-
- L'utilisateur saisit 3 caractères ou plus (ou 2 caractères en chinois/japonais).
- Le délai de recherche est de 300 ms (millisecondes) à partir du dernier caractère tapé (également connu sous le nom de Réponse). Cela signifie que l'utilisateur peut taper des lettres à un rythme continu, et chaque lettre ne déclenchera pas la recherche, mais commencera après le délai d'attente.
Une fois cette requête de recherche déclenchée, l'API de recherche d'intégrations enverra une requête de recherche avec les paramètres.
Flux de recherche
Recherche de requête
Envoyé à partir de l'API d'intégrations :
POST <apiURL>/(search)Content-type: application/jsonHeaders:{ Authorization: <apiKey>}Body:{ "user": "user@email.com" "system": "652c91b1ec444c76a313a68f69478b93" "env": "prod" "term": "itay"} |
|
Paramètre |
Description |
| Utilisateur | E-mail de l'utilisateur |
| le système | Système GUID- une chaîne de 32 caractères |
| environnement | Type de l'environnement de Workstation. Valeurs disponibles-
|
| terme | Requête de recherche qui est en train d'être tapée dans l'application Workstation |
Résultats de la recherche
Envoyé à l'API d'intégration (comme appel de POST) :
Body:[{ "id": "b2f8510d-9547-4d53-978f-6fc24371c113", "title": "Creating a user", "description": "WalkMe does not collect personally identifiable information (PII) other than IP addresses in logs for security purposes, end users' approximate geolocation (country and city in which they are located) and masked IP addresses for the ongoing operation of the WalkMe system.", "mimeType": "Answers", "externalType": "Article", "created": "2022-01-30T14:35:16.57Z", "modified": "2022-01-30T14:37:07.40Z", "source": "confluence", "category": "Gitlab Service User creation and configuration", "detail": "Account Management", "relationaltime": "2022-01-30T14:35:16.57Z" }}] |
Référence de l'API
| Attribut | Type | Description |
| Id | Chaîne |
L'identifiant unique de l'élément. Requis |
| titre | Chaîne |
Le nom de l'élément. Requis |
| Description | Chaîne |
La description/résumé de l'élément. Si elle est remplie, le titre de résultat de recherche sera affiché en gras, tandis que la description sera affichée en dessous. Facultatif |
| Lien | URL |
L'URL pour accéder à l'élément une fois que vous avez cliqué sur le résultat de recherche. Requis |
| mimeType | Chaîne |
La catégorie de filtre dans laquelle l'élément devrait être affiché. Elle doit être une correspondance exacte, de l'une des options suivantes apparaissant dans cette liste-
Requis |
| externalType | Chaîne |
Le type d'élément. Par exemple- Article, tableau de bord, cas, etc. S'il est rempli, il sera affiché sur l'élément à côté du nom d'intégration. Facultatif |
| Créé | Date et heure |
L'élément de date et d'heure a été créé. Ce paramètre n'est pas affiché sur l'interface utilisateur, mais est utilisé pour le tri. Facultatif |
| Modifiés | Date et heure |
L'élément de date et d'heure a été récemment mis à jour. Ce paramètre n'est pas affiché sur l'interface utilisateur, mais est utilisé pour le tri. Facultatif |
| Copier | Chaîne |
Si elle est remplie, affichera un bouton de copie sur le résultat de recherche. En cliquant sur ce bouton, il copie le texte fourni (lien d'élément, nom, ID, etc.). Habituellement, il est rempli avec le lien de l'élément. Facultatif |
| confiance | Décimal |
Paramètre à utiliser pour afficher la précision de la réponse (en pourcentage). S'il est rempli, il sera affiché sur l'interface utilisateur de résultat de recherche. Facultatif |
| Source | Chaîne |
Afficher la source de la réponse (par exemple - Confluence). Elle sera affichée sur l'interface utilisateur de résultat de recherche à côté d'une icône de loupe. Facultatif |
| Catégorie | Chaîne |
Paramètre à utiliser par Ask-AI, pour afficher la catégorie de l'article (« miettes de pain »). Si elle est remplie, elle sera affichée sur l'interface utilisateur de résultat de recherche au-dessus du titre. Facultatif |
| poweredBy | Chaîne |
Si elle est remplie, elle affichera une note sur l'interface utilisateur de résultat de recherche en bas à droite. Remarquez que lorsqu'ils sont remplis, le nom d'intégration et l'icône ne seront pas affichés sur le résultat. Facultatif |
| détail | Chaîne |
Si elle est remplie, ces données seront affichées sur l'interface utilisateur de résultat de recherche (après le nom d'intégration et externalType). Facultatif |
| relationalTime | Date et heure |
Si elles sont remplies, ces données seront affichées sur l'interface utilisateur de résultat de recherche, à la fin de celle-ci. Affiche un temps de relationnel en fonction de la date fournie par rapport à l'heure actuelle (par exemple- il y a 3 jours). Facultatif |
Restrictions
Les champs de chaîne sont limités à 255 caractères.
Conception de l'interface utilisateur des paramètres
Traitement des erreurs
Bien que dans la plupart des cas, le flux aboutira à une réponse « HTTP 200 » avec un texte clair ok indiquant que les résultats de recherche ont été affichés avec succès, nous devrons nous préparer à des scénarios où les tentatives d'envoi de résultats de recherche échoueront.
Les erreurs apparaissant dans cette section sont générées du côté de l'API d'intégrations, et devraient indiquer aussi précisément que possible la cause de l'erreur.
La réponse de l'API peut lancer des erreurs (« HTTP 400 ») lors de la réception de requêtes mal formées, lorsqu'elle a utilisé des clés qui se sont plus valides, ou quand quelque chose d'exceptionnel l'empêche de se rendre jusqu'aux résultats de recherche.
|
Erreur |
Description |
| invalid_structure | Indique généralement que la demande reçue est mal formée - peut-être que le JSON est structuré de manière incorrecte, ou que le texte du message n'est pas correctement échappé. La demande ne doit pas être relancée sans correction. |
| api_key_invalid | Indique que la clé d'API en cours d'adressage n'existe pas ou est invalide. La demande ne doit pas être relancée sans modification de la clé API. |
| api_url_invalid | Indique que l'URL de l'API en cours d'adressage est invalide. La demande ne doit pas être relancée sans modification de l'URL de l'API. |
| title_invalid | Indique que le titre, qui est une valeur obligatoire, n'a pas été envoyé ou n'est pas dans les restrictions des caractères. |
| link_invalid | Indique que le lien, qui est une valeur obligatoire, n'a pas été envoyé ou n'est pas dans les restrictions des caractères. |
| mimeType_invalid | Indique que le mimeType, qui est une valeur obligatoire, n'a pas été envoyé ou n'est pas dans les restrictions des caractères. |
| id_invalid | Indique que l'ID, qui est une valeur obligatoire, n'a pas été envoyé ou n'est pas dans les restrictions des caractères. |
Aperçu de la sécurité
La recherche d'entreprise utilise des intégrations tierces pour mettre en œuvre une « recherche fédérale ». Les recherches sur Workstation sont prises en charge par un moteur NLP et une base de données des graphiques qui prend en charge une excellente expérience utilisateur.
La recherche d'entreprise Workstation ne répertorie pas des données tierces sur une base de données indépendante consultable.
Consultez le diagramme de séquence ci-dessous qui décrit l'algorithme de recherche :
Notes techniques
Pour s'assurer que l'intégration de Workstation ServiceNow fonctionne correctement, les clients doivent autoriser les adresses IP suivantes :
- QA : 54.229.168.224
- PROD : 52.53.115.147
- EUPROD : 3.126.219.141