API des notifications de Workstation
Aperçu général
Avec l'API des notifications de Workstation vous pouvez utiliser des événements dans n'importe quel système (même s'il n'a pas de snippet WalkMe) pour déclencher une notification dans WalkMe et garder automatiquement vos utilisateurs à jour. Déclencher les notifications de Workstation avec un appel REST sur notre Webhook de notification de WalkMe.
Cet article fournira les informations nécessaires pour faire l'appel REST qui nécessite à la fois un jeton d'authentification et une charge utile JSON.
Tout système qui peut appeler une API REST peut être utilisé pour déclencher des notifications dans Workstation.
Avant de commencer...
Appeler l'API nécessite certaines autorisations et une configuration technique. Assurez-vous d'avoir l'accès et de pouvoir faire les opérations suivantes :
- Accès au centre d'administration pour votre système Workstation pour obtenir le jeton d'accès API
- Remarque : si votre organisation a plus d'un système Workstation, vous devrez effectuer des appels API séparés pour chaque système.
- Application pour configurer et exécuter des appels (Zapier ou Postman) à l'API de notification.
- Vous devez avoir une application qui peut faire authentifier des appels API REST sortants. Si vous ne savez pas si votre organisation a une telle application, contactez votre équipe informatique pour discuter des options.
Comment ça marche
Voici ce que vous avez besoin de WalkMe pour que l'API soit déclenchée. Étapes sur la façon de rassembler tout ce qui suit.
- Authentification et création d'un jeton d'accès
- Identifier la notification du centre de communication et l'audience cible
- Créer la charge utile JSON
- Effectuer l'appel
Plus précisément, vous trouverez les informations nécessaires pour utiliser une notification JSON avec les informations suivantes :
- ID du système
- ID du modèle de notification
- ID des utilisateurs finaux ou ID de l'audience
- Type de notification : popup ou push
- Titre de la notification
- Description
- Outrepasser les informations
Authentification et création d'un jeton d'accès
Qu'est-ce qu'un jeton d'accès ?
Un jeton d'accès est un identifiant qui peut être utilisé par une application pour accéder à une API. Ils informent l'API que le porteur du jeton a été autorisé à accéder à une action particulière.
Le jeton d'accès authentifie l'appel d'API, donnant à l'application la permission de transférer les données de son système à Workstation.
Créer un jeton d'accès
- Allez au centre d'administration
- Accédez à l'onglet Clés API : https://admin.walkme.com/account-api-keys
- Cliquez sur Créer une nouvelle clé
À partir du panneau Créer une nouvelle clé :
- Nommez la clé
- Conseil : indiquez l' objectif de la clé dans le nom pour vous aider à vous en souvenir plus tard
- Activez l'API de la notification
- Sélectionnez Écrire dans la liste déroulante
- Cliquez sur Créer
À partir du panneau Détails clés :
- Copiez l'ID du client et le secret du client
Jeton d'authentification
Pour une assistance supplémentaire et pour obtenir le jeton d'autorisation : Page du développeur
Notification du centre de communication et ID de l'audience
Créer un modèle de notification
Allez sur le centre de communication et créez un modèle personnalisé (Apprendre comment créer une notification) Il y a quelques choses à garder à l'esprit pour la notification que vous créez pour l'API :
- La notification ne peut avoir qu'un seul bouton
- L'action du bouton ne peut utiliser que l'action du lien
- Vous pouvez utiliser des liens dynamiques ou des permaliens WalkMe
Facultatif : Ajoutez des règles de remplacement dans le modèle
Dans le cas où vous souhaitez qu'une notification soit personnalisée, soit en fonction de l'utilisateur ou de l'événement qui est déclenché, vous pouvez ajouter des valeurs dynamiques que l'API remplira automatiquement.
Dans l'image, deux exemples de valeurs sont remplacés par un texte dynamique qui sera remplacé en fonction des valeurs l'API déclenche.
C'est un exemple de notification API avec Salesforce qui est déclenché lorsqu'un nouveau prospect a été attribué. Il informera le vendeur du nom de l'opportunité et du lien vers le prospect dans Salesforce.
- ###OPP_NAME_ATTRIBUTE### sera remplacé par le nom de l'opportunité dans Salesforce
- ##URL### sera remplacé par une URL réelle, permettant une action personnalisée pour chaque utilisateur, chaque fois que l'API est déclenchée
Remarque : le nom de la valeur (exemple : OPP_NAME_ATTRIBUTE) doit être copié exactement dans le JSON pour qu'il puisse être remplacé.
Copier les valeurs requises
Les étapes suivantes relieront la notification à l'API.
Copiez l'ID de modèle personnalisé que vous avez créé
- Allez sur CommCenter
- Cliquez sur Nouvelle notification
- Sous Modèles personnalisés > Survolez le coin de la notification
- Cliquez sur l'icône de copie pour copier l'ID dans votre presse-papiers
- Exemple : 75cfcba6-c320-42cb-938e-4c2bd08a43a3
Copiez l'ID du public cible
- Allez sur Audiences
- Survolez l'audience avec la souris > cliquez sur le menu à 3 points sur la droite > cliquez sur Copier l'ID
- Vous pouvez ajouter plusieurs audiences au JSON
- ID de l'exemple : cf0bd4c1-86fd-4c79-a46a-c730d6789e63
Ajouter des informations à l'application de connexion API
Pour une assistance supplémentaire Page du développeur.
Maintenant, il est temps de remplir certaines informations sur votre application de connexion API. Pour plus de clarté, nous utilisons Zapier dans le cadre de nos explications, mais nous ne la recommandons pas plus qu'une autre application. Toute application similaire fonctionnera.
Les informations utilisées ci-dessous sont universellement nécessaires sur toutes les applications :
- URL = https://api.walkme.com/accounts/connect/token
- Type de charge utile = (Content-Type) application/x-www-form-urlencoded
- Données = grant_type → client_credentials
Ajouter l'authentification de base
Lors de l'utilisation de l'Authentification de base, le clientID est le nom d'utilisateur et le secret du client est utilisé comme mot de passe.
- ID du client | Secret du client (copié à partir du centre d'administration)
- Exemple
0o234234234UqD5d7 | JVnD346346346436345asfgasgbPt_4T7h2_
- Exemple
Une fois que vous avez ajouté ces informations, vous recevrez un jeton d'accès.
- Copiez votre jeton d'accès.
Mettre à jour le code JSON
Maintenant, il est temps de remplir les espaces vides et d'utiliser le code JSON qui appellera la notification.
{ "notification": { "systemId" : « <l'ID du système de la station de travail >», //Requis si vous avez plus d'un système de station de travail "templateId" : « <ID du modèle> », //Requise "endUsersIds" : ["<Identifiant d'utilisateur final 1>","<Identifiant d'utilisateur final 2>","<...>"], //Vous avez besoin d'un ID d'utilisateur final ou d'un ID d'audience (vous pouvez utiliser les deux), veuillez supprimer celui que vous n'utilisez pas "audiencesIds" : ["<ID d'audience 1>","<ID d'audience 2>","<...>"], //Vous avez besoin d'un ID d'utilisateur final ou d'un ID d'audience (vous pouvez utiliser les deux), veuillez supprimer celui que vous n'utilisez pas "notificationType" : « <comment la notification s'affichera, push ou popup> », //Facultatif, push par défaut, veuillez la supprimer si elle n'est pas utilisée "title" : "<titre de la notification tel qu'il s'affichera dans le tableau ComCenter>", //Facultatif, veuillez la supprimer si elle n'est pas utilisée "runtimeTitle" : "<ce qui s'affichera pour les utilisateurs finaux dans la liste Workstation et la notification push>", //Facultatif, veuillez la supprimer si elle n'est pas utilisée "runtimeDescription" : "<ce qui s'affichera pour les utilisateurs finaux dans la liste Workstation et le message push>", //Facultatif, veuillez la supprimer si elle n'est pas utilisée « startAt » : « <date de début YYYY-MM-DD hh:mm> », // Facultatif, par défaut en ce moment, le fuseau horaire est UTC, vous pouvez ajouter une date sans heure, l'heure par défaut est 00:00 UTC, supprimez tout ce que vous n'utilisez pas "endAt" : « <date de fin YYYY-MM-DD hh:mm> », // Facultatif, par défaut 30 jours à partir de maintenant, vous pouvez ajouter une date sans heure, l'heure par défaut est 00:00, supprimez tout ce que vous n'utilisez pas "override": [ { // Plus de paires de virgules séparées {key:value}peuvent suivre // Par exemple, la valeur pourrait être une URL qui est passée de ServiceNow pour ouvrir un ticket ] } } |
Voici un exemple de code JSON avec de vraies données et quelques lignes supprimées pour le rendre plus simple.
{ "notification": { "systemId": "bcf4c7f5682b4aa6875a0fc9bdfa21ca", "templateId": "1e5afe51-2d2a-4b22-a60a-cf2d6c01d726", "endUsersIds": ["name@email.com"], "runtimeTitle" : "API Test 3", "notificationType": "Push", “override”: [ {“key”: “URL”, “value”: “www.someurl.com”} ] } } |
Passer l'appel
Maintenant que nous avons les informations dont nous avons besoin, connectons les points. Pour passer l'appel (connecter les systèmes pour créer et publier de nouvelles notifications dans la Workstation de votre organisation), vous aurez besoin de votre JSON et de :
- Méthode : POST
- URL : https://api.walkme.com/public/v1/notifications/send