Self Help Studio Desktop - Les variables et macros

Modifié le 25/07/2023 18:22

Chaque nouveau projet Self Help contient automatiquement une liste de variables et macros prédéfinies.

Chaque rédacteur peut également créer des variables et macros projets en fonction de ses besoins pour son projet Self Help.

Toutes les variables et macros sont stockées dans la librairie du projet Self Help. Elles sont ainsi disponibles à tout moment dans l'ensemble du projet Self Help, sur toutes les étapes des procédures.
 

Spécificités des variables et macros

  • Une variable permet de stocker en mémoire des données de différente nature (booléen, texte, ...).
    • Les variables prédéfinies permettent de récupérer des informations sur l'étape / la procédure en cours d'exécution / l'utilisateur connecté.
    • Une variable projet peut être définie comme une constante à laquelle est attribuée une valeur fixe. Dans ce cas, le contenu de la variable ne peut pas être différent selon le contexte.
  • Une macro est une expression en langage Javascript.
    • Les macros prédéfinies permettent d'effectuer des transformations sur des dates, des nombres et des tableaux.
    • Une macro projet peut être définie comme un script ou comme une condition.
       

Utilisation des variables et macros
Les variables et les macros peuvent être utilisées pour :

  • afficher des données lors du déroulement d'une procédure ;
  • effectuer et afficher les résultats d’un calcul dans une étape de procédure ;
  • définir les conditions d’une branche dans une étape de procédure ;
  • définir les conditions de visibilité d’un contenu dans une étape de procédure ;
  • configurer un connecteur ;
  • définir les paramètres d'entrée / sortie.

Exemples

  • Récupérer et afficher l'adresse e-mail de l'utilisateur qui exécute l'étape en cours ==> Utiliser la variable prédéfinie executionContext.user.email
  • Effectuer des calculs ou de la mise en forme du contenu ==> Utiliser une macro prédéfinie
  • Afficher le libellé d'un bouton d'action en fonction de la langue de l'utilisateur connecté ==> Utiliser une macro projet

Remarques

  • Toutes les variables et macros (prédéfinies et projets) sont stockées dans le dossier Librairie de chaque projet Self Help. Elles sont ainsi disponibles dans tout le projet, sur toutes les étapes des procédures.
        Predefined variables list.png
  • Les macros et les variables prédéfinies sont fournies par EasyVista. Vous ne pouvez pas les modifier ni les supprimer.
  • Les variables et macros projets peuvent être créées :
    • de façon automatique à la suite de l’import ou de la copie dans le projet Self Help d’un contenu quelconque (procédure, ressource) auquel est déjà associé une ou plusieurs variables et/ou macros ;
    • manuellement par un rédacteur ayant les droits d’écriture sur le projet Self Help.
  • Les variables projets peuvent également être créées automatiquement lors de l’élaboration d’un formulaire (création automatique d'une variable projet pour chaque champ du formulaire).
  • Les macros projets peuvent également être créées via l’onglet Macro du volet Description d’une étape de procédure. La macro s’exécute alors en amont de l’affichage de l’étape et son utilisation est limitée à la procédure en cours.

Bonnes pratiques

  • Lorsqu'une information est susceptible d'être affichée sur plusieurs procédures d'un projet Self Help, créez une variable dans la librairie du projet. De cette façon, si le contenu de l'information doit être modifié, il vous suffit de modifier le contenu de la variable en un seul endroit pour que la mise à jour soit répercutée automatiquement sur toutes les procédures.

exemple  Affichage du nom de l'agent virtuel dans le contenu de certaines procédures

  • Créez une variable CHATBOT_NAME dans la librairie.
  • Si le nom de l'agent virtuel doit être modifié, modifiez le contenu de la variable une seule fois dans la librairie.

Les variables

Les différents types de variables

Nature Description
Booléen La variable peut contenir la valeur Vrai (True) ou Faux (False).
Date La variable peut contenir une date au format YYYY,MM,DD,HH,MM,SS.
Indéfini La variable peut contenir une expression.
Nombre La variable peut contenir une valeur numérique.
Objet complexe La variable peut contenir d’autres variables. Elle est utile pour organiser la librairie.
Tableau La variable peut contenir un tableau sous la forme ["Valeur 1", "Valeur 2", "Valeur 3", …]. Les valeurs peuvent être au format texte ou nombre.
Texte La variable peut contenir une chaine de caractères.

Liste des variables prédéfinies

Variable Nature Description

currentNode : Informations liées à l'étape en cours d'exécution

currentNode.automatic Booléen Nature de l'étape
  • True ==> Étape invisible : Sans interaction avec l'utilisateur
  • False ==> Étape visible
currentNode.id Texte Identifiant de l'étape
currentNode.name Texte Titre de l'étape
currentNode.procedureName Texte Titre de la procédure ayant servi de point d’entrée à l’exécution
currentNode.resourcesTab Tableau Liste des ressources liées à l'étape (tableau indiquant l'identifiant, le nom et l'URL de chaque ressource)
currentNode.textId Texte Identifiant de la ressource Texte dans laquelle est stocké le contenu de l'étape
currentNode.type Texte Type d'étape (Action, Page de choix, ...)

executionContext : Informations liées à l’exécution en cours

executionContext.agentRef Texte Référence de l’agent virtuel qui a appelé la procédure
executionContext.channel Texte Canal d'exécution de la procédure
  • PORTAL : procédure appelée dans le portail
  • APICONTENT : procédure appelée via l'API Contenu
  • MSTEAMS : procédure appelée via MS Teams
  • SERVICEBOTS : procédure appelée via un agent virtuel
  • AUTOMATIC : procédure appelée via l'API Portail
  • PREVIEW : procédure appelée en mode Test (le rédacteur génère un lien direct depuis le Studio Desktop et clique sur Lancer la procédure)
  • DEBUG : procédure appelée en mode Debug
executionContext.contextId Texte Identifiant de l’étape en cours d’exécution
executionContext.country Chaîne de caractères figée Code du pays auquel est rattachée la langue d'exécution de la procédure (ex : FR, GB, ...)
executionContext.currentNodeTimeOnEnter Nombre entier Heure d’exécution de l'étape courante
executionContext.endType Texte Façon dont la procédure a été quittée
executionContext.expertSessionId Texte Identifiant de session expert quand le rédacteur génère un lien direct depuis le Studio Desktop et clique sur Lancer la procédure
executionContext.instanceId Texte Identifiant de l’exécution de la procédure
executionContext.isDebug Texte Mode d'exécution de la procédure
  • True ==> Lancement de la procédure en mode Debug
  • False ==> Exécution standard de la procédure
executionContext.isMobile Booléen Procédure lancée depuis un thème destiné à l'affichage sur mobile
executionContext.lang Chaîne de caractères figée Langue d'exécution de la procédure (ex : EN, FR)
executionContext.lastNodeDuration Nombre entier Heure de consultation de la dernière étape (= heure de fin d’exécution de la procédure)
executionContext.log Texte Contenu du rapport d'exécution

Note : Le rapport se crée au fur et à mesure du parcours de l'utilisateur dans la procédure. Il peut être paramétré étape par étape - Open url.png voir onglet Rapport du volet Description dans le Studio Desktop en mode Édition

executionContext.referrer Texte URL d’origine de l'exécution de la procédure
executionContext.server Texte URL du serveur Self Help sur lequel est hébergée la procédure
executionContext.sessionLess Booléen Accès à la procédure en s’identifiant / générant un lien direct
executionContext.startScenarioTime Nombre entier Heure de début de l’exécution de la procédure
executionContext.userAgent Texte Informations sur le navigateur sur lequel est déroulée la procédure
executionContext.userSessionId Texte Identifiant de session utilisateur dans le cas d’une connexion depuis le portail

executionContext.procedure : Informations liées à la procédure courante

executionContext.procedure.category Texte Catégorie de la procédure (contenu de la métadonnée ProcedureCategory)
executionContext.procedure.categoryDescription Texte Description de la catégorie de la procédure (contenu de la métadonnée CategoryDescription)
executionContext.procedure.domain Texte Nom du domaine dans lequel est située la procédure
executionContext.procedure.id Texte Identifiant unique (GUID) de la procédure
executionContext.procedure.isPublished Booléen Statut de publication de la procédure :
  • True ==> La procédure est publiée
  • False ==> La procédure n’est pas publiée (lancement d’une version en édition à partir du Studio Desktop)
executionContext.procedure.metaDescription Texte Balises Html meta associées à la procédure sous forme de chaînes de caractères localisées (contenu de la métadonnée ProcedureMetaDescription)
executionContext.procedure.name Texte Titre de la procédure
executionContext.procedure.project Texte Nom du projet Self Help dans lequel est située la procédure
executionContext.procedure.projectVersion Texte Numéro de version du projet Self Help dans lequel est située la procédure
executionContext.procedure.properties Objet complexe Liste des métadonnées de la procédure (nom et contenu de chaque métadonnée) :
  • executionContext.procedure.properties.agentFlag
  • executionContext.procedure.properties.tags
  • executionContext.procedure.properties.ProcedureViewable
  • executionContext.procedure.properties.ProcedureCategory
  • executionContext.procedure.properties.ProcedureCategoryDescription
  • executionContext.procedure.properties.ProcedureSubCategory
  • executionContext.procedure.properties.ProcedureSubCategoryDescription
  • executionContext.procedure.properties.ProcedureMetaDescription
  • executionContext.procedure.properties.dialogFriendly
executionContext.procedure.subCategory Texte Sous-catégorie de la procédure (contenu de la métadonnée ProcedureSubCategory)
executionContext.procedure.subCategoryDescription Texte Description de la sous-catégorie de la procédure (contenu de la métadonnée ProcedureSubCategoryDescription)
executionContext.procedure.versionId Texte Identifiant de la version de la procédure
executionContext.procedure.viewable Booléen Indique si la procédure doit être indexée par le moteur de recherche (valeur True) ou non (valeur False)

executionContext.user : Informations sur l'utilisateur qui exécute la procédure courante

executionContext.user.email Texte Adresse e-mail de l’utilisateur
executionContext.user.firstName Texte Prénom de l’utilisateur
executionContext.user.groups Tableau de texte Liste des groupes auxquels appartient l’utilisateur
executionContext.user.id Texte Identifiant de l’utilisateur
executionContext.user.lastName Texte Nom de l’utilisateur
executionContext.user.login Texte Login de l’utilisateur (saisi lors de l’identification)
executionContext.user.properties Objet complexe Liste des propriétés utilisateurs supplémentaires renseignées sous la forme d'un tableau indiquant le nom et la valeur de chaque propriété
  • executionContext.user.properties.{nom de la propriété}
executionContext.user.title Texte Civilité de l’identifiant (M / Mme / Mlle)

Autres variables

custom Texte Variable globale générique

Notes :

  • Variable vide par défaut.
  • Variable utilisée dans les versions antérieures à la version 2.6 de Self Help, pour lesquelles le dossier Librairie n'est pas créé automatiquement.
stopMessage Texte Variable dont le contenu s'affiche dans la colonne Message des statistiques disponibles dans le Studio Desktop en mode Publication

Note : Variable vide par défaut.

Description de l'écran Variable projet

          Project variable.png

Nom : Nom de la variable projet.

  • Le nom doit être unique pour le projet Self Help.

Type de données : Type de données contenues dans la variable projet (texte, nombre, date, …).

Constante : Indique si la variable projet est une valeur fixe (case cochée) ou une variable (case non cochée).

  • Si vous créez une constante, vous devez obligatoirement renseigner la valeur par défaut.

Valeur par défaut : Valeur par défaut définie pour la variable projet.

  • Une valeur par défaut est obligatoire pour une constante.
  • Format de la valeur : Indique si la valeur par défaut est une valeur simple ou une expression.

exemple

  • Valeur simple : Variable CHATBOT_NAME contenant le nom de l'agent virtuel
    ==> CHATBOT_NAME = evie
  • Expression : Variable UserName contenant le prénom et le nom de l’utilisateur connecté.
    ==> UserName = executionContext.user.firstName + executionContext.user.lastName

Description : Description de la variable projet.

Procédures

Comment créer une variable projet

Étape 1 : Affichage de la librairie du projet Self Help

1. Sélectionnez le projet Self Help dans l'arborescence du volet Explorateur.

2. Double-cliquez sur le dossier Librairie.

La librairie est ouverte et affiche toutes les variables et macros prédéfinies et projets.
 

Étape 2 : Création de la variable projet dans la librairie

1. Cliquez droit sur l'entrée Variables projets et sélectionnez Nouveau > Variable dans le menu contextuel.

2. Renseignez la nouvelle variable  - Open url.png voir Description

  • Cochez la case Constante si la variable projet est une valeur fixe.
  • Sélectionnez l'option Simple ou Expression suivant le type de format de la valeur par défaut, puis renseignez la valeur par défaut.
  • Si vous créez une constante, vous devez obligatoirement renseigner la valeur par défaut.

3. Cliquez sur Terminer.

La nouvelle variable projet est affichée dans la librairie du projet Self Help et est disponible sur l'ensemble des étapes des procédures.

     Open url.png voir :

Comment afficher une variable dans une étape

Étape 1 : Affichage de l'étape de la procédure

1. Sélectionnez le projet Self Help dans l'arborescence du volet Explorateur.

2. Double-cliquez sur la procédure.

La procédure est affichée dans le volet Conception.

3. Cliquez sur l'étape affichée dans le diagramme.

Le contenu de l'étape est affiché dans le volet Description.

Étape 2 : Insertion de la variable dans le contenu de l'étape

1. Ouvrez l'arborescence du dossier Librairie > Variables prédéfinies via Tree expand icon.png.

2. Cliquez-glissez la variable depuis le volet Explorateur vers le contenu de l'étape dans le volet Description.

La variable est insérée sous la forme d'un cadre gris.
    Predefined variable insertion.png

Étape 3 : Test de l'affichage de la variable lors de l'exécution de la procédure

1. Cliquez sur Launch procedure dropdown list.png dans la barre d'outils puis sur Launch procedure icon.png Lancer la procédure.
L'étape est affichée dans votre navigateur internet.

2. Vérifiez que la variable a été remplacée par son contenu.
    Predefined variable insertion - Result.png

Cas d'utilisation

Utiliser une variable pour faire varier le contenu d'une procédure

Ce cas d'utilisation permet d'indiquer à un utilisateur lançant une procédure avec une étape de choix quelles branches il a déjà parcourues en affichant une icône à la droite de celles-ci.

          Use case - Branches already covered.png

Utiliser une variable dans la condition d'une branche

Ce cas d'utilisation permet de tester si un utilisateur est membre de la compagnie lorsqu'il demande à modifier son mot de passe. Il utilise une condition avec la variable prédéfinie executionContext.user.email pour tester si l'adresse e-mail contient la valeur @company.com et orienter l'utilisateur sur les branches de la procédure suivant le résultat de la condition.

          Use case - Use a variable in a procedure.png

Étape 1 : Création d'une procédure

1. Créez un nouvelle procédure dans votre projet Self Help.

     Open url.png voir Comment créer une procédure Self Help

2. Nommez-la I want to change my password.
 

Étape 2 : Ajout d'une étape de type Action avec conditions

1. Insérez une étape de type Action avec conditions dans votre procédure.

2. Nommez l'étape Email test.

2 branches sont créées.

  • La branche du haut <Condition> traite la réponse à apporter lorsque l'adresse e-mail de l'utilisateur contient @company.com@.
  • La branche du bas Par défaut traite la réponse à apporter dans le cas contraire.
    Use case - Use a variable in a procedure - Condition branch.png

 

Étape 3 : Saisie de la condition pour tester l'adresse e-mail de l'utilisateur

1. Double-cliquez sur la zone <Condition> de la branche du haut.

La fenêtre de saisie de la condition est ouverte.
         Use case - Use a variable in a procedure - Condition branch - Properties.png

2. Renseignez la condition permettant d'indiquer que l'adresse e-mail de l'utilisateur contient @company.com@.

  • Cliquez sur Add variable icon.png en regard du premier champ de la condition.
    La liste des variables disponibles dans le projet Self Help est affichée.
             Use case - Use a variable in a procedure - Condition line - Variable list.png
  • Sélectionnez la variable prédéfinie executionContext.user.email pour récupérer l’adresse e-mail de l’utilisateur connecté.
  • Renseignez les autres champs de la condition.
    • Opérateur = contient (contains)
    • Valeur recherchée = @company.com

          Use case - Use a variable in a procedure - Condition line.png

3. Cliquez sur Terminer.

La condition est mise à jour.
         Use case - Use a variable in a procedure - Condition line entered.png
 

Étape 4 : Saisie des étapes de la procédure

1. Allez sur la branche conditionnelle (branche du haut) et créez les étapes pour accompagner l'utilisateur dans le changement de son mot de passe.

2. Allez sur la branche par défaut (branche du bas activée lorsque la condition n'est pas vérifiée : l'adresse e-mail de l'utilisateur ne contient pas @company.com) et créez une étape invitant l'utilisateur à se rapprocher de sa DSI.

Les macros

Les différents types de macros

Nature Description
Classique La macro est un script renvoyant le résultat de son exécution.
Conditionnelle La macro est une condition renvoyant des valeurs selon le résultat de son exécution (condition vérifiée ou non).

Liste des macros prédéfinies

Macro Nom Description
Date : Modifier date_update Ajoute / supprime des années, mois, jours, heures, minutes et secondes à une date et renvoie la date modifiée.

Syntaxe :

date_update(dateToChange, years, months, days, hours, minutes, seconds)

Paramètres à renseigner :

date à modifier, différence année, différence mois, différence jour, différence heure, différence minute, différence seconde

exemple date_update(myDate, 0, -1, 1, 0, 0, 0)
  • Enlève 1 mois et ajoute 1 jour à la date contenue dans la variable myDate.
  • La nouvelle valeur est retournée.
  • La variable myDate n’est pas modifiée.
Nombre : formater num_format Retourne un nombre au format Texte, arrondi avec le nombre de décimales spécifié.

Syntaxe :

num_format(value, numDecimals)

Paramètres à renseigner :

nombre à formater, nombre de décimales

exemple num_format(0.148632, 2)
  • Arrondit le nombre avec 2 décimales.
  • Retourne la chaîne de caractères 0.14.
Nombre : Arrondir à la décimale num_round Retourne un nombre arrondi avec le nombre de décimales spécifié.

Syntaxe :

num_round(value, numDecimals)

Paramètres à renseigner :

nombre à arrondir, nombre de décimales

exemple num_round(42.7845652, 2)
  • Arrondit le nombre avec 2 décimales.
  • Retourne la valeur 42.78.
Tableau : Ajouter au début tab_addfirst Ajoute un élément au début d’un tableau et renvoie la valeur du tableau modifié.

Syntaxe :

tab_addfirst(table, element)

Paramètres à renseigner :

tableau, élément à ajouter

exemple Le tableau ville contient les éléments [Paris, Nantes, Grenoble]
  • tab_addfirst(ville, "Tampa") ajoute l'élément Tampa au début du tableau.
  • La valeur [Tampa, Paris, Nantes, Grenoble] est retournée.
Tableau : Ajouter à la fin tab_addlast Ajoute un élément à la fin d’un tableau et renvoie la valeur du tableau modifié.

Syntaxe :

tab_addlast(table, element)

Paramètres à renseigner :

tableau, élément à ajouter

exemple Le tableau ville contient les éléments [Paris, Nantes, Grenoble]
  • tab_addlast(ville, "Tampa") ajoute l'élément Tampa à la fin du tableau.
  • La valeur [Paris, Nantes, Grenoble, Tampa] est retournée.
Tableau : Contient l’élément tab_contains Retourne la valeur Vrai (True) si un élément est présent dans un tableau et la valeur Faux (False) s'il est absent.

Syntaxe :

tab_contains(table, element)

Paramètres à renseigner :

tableau, élément à rechercher

exemple Le tableau ville contient les éléments [Paris, Nantes, Grenoble]
  • tab_contains(ville, "Paris") recherche l'élément Paris dans le tableau et retourne la valeur True.
  • tab_contains(ville, "Lyon") recherche l'élément Lyon et retourne la valeur False.
Tableau : Supprime l’élément tab_remove Supprime un élément d’un tableau et renvoie la valeur du tableau modifié.

Syntaxe :

tab_remove(table, element)

Paramètres à renseigner :

tableau, élément à supprimer

exemple Le tableau ville contient les éléments [Paris, Nantes, Grenoble]
  • tab_remove(ville, "Paris") supprime l'élément Paris du tableau.
  • La valeur [Nantes, Grenoble] est retournée.
Tableau : inverser lignes et colonnes tab_swap_row_col Inverse les lignes et les colonnes d’un tableau et renvoie la valeur du tableau modifié.

Syntaxe :

tab_swap_row_col(table)

Paramètres à renseigner :

tableau

exemple Le tableau pays contient les éléments [{Paris, France}, {Londres, Angleterre}]
  • tab_swap_row_col(pays) inverse les lignes et colonnes du tableau.
  • La valeur [{France, Paris}, {Angleterre, Londres}] est retournée.
Texte : Egal ignorant la casse text_equalsIgnoreCase Retourne la valeur Vrai (True) si deux chaînes de caractères sont identiques, en ignorant la casse, et la valeur Faux (False) si elles sont différentes.

Syntaxe :

text_equalsIgnoreCase(string1, string2)

Paramètres à renseigner :

chaîne1, chaîne2

exemple
  • text_equalsIgnoreCase('TeXte', 'texte') compare les 2 chaînes 'TeXte' et 'texte', en ignorant la casse, et retourne la valeur True.
  • text_equalsIgnoreCase('text', 'texte') compare les 2 chaînes 'text' et 'texte' et retourne la valeur False.

Description de l'écran Macro projet

          Project macro.png

Nom : Nom de la macro projet.

  • Le nom doit être unique pour le projet Self Help.

Type de résultat : Type de résultat attendu à la sortie de la macro projet (texte, nombre, date, …).

Paramètres : Liste des paramètres d'entrée de la macro projet.

  • Cliquez sur + Ajouter un paramètre pour renseigner chaque paramètre de la macro projet.

Description : Description de la macro projet.

Type de macro : Indique si la macro est une macro classique (un script est à renseigner dans le champ Contenu de la macro) ou conditionnelle (la condition est à renseigner dans 3 zones SI, ALORS, SINON).

exemple

  • Macro classique : Macro description() mettant en forme le contenu de la variable prédéfinie executionContext.log, en remplaçant les retours à la ligne
    Project macro - Example classic macro.png
  • Macro conditionnelle : Macro info() retournant la valeur Find out more si la langue d’exécution est l’anglais, et la valeur Plus d’informations sur le wiki dans tous les autres cas
    Project macro - Example conditional macro.png

Procédures

Comment créer une macro projet

Étape 1 : Affichage de la librairie du projet Self Help

1. Sélectionnez le projet Self Help dans l'arborescence du volet Explorateur.

2. Double-cliquez sur le dossier Librairie.

La librairie est ouverte et affiche toutes les variables et macros prédéfinies et projets.
 

Étape 2 : Création de la macro projet dans la librairie

1. Cliquez droit sur l'entrée Macros projets et sélectionnez Nouveau > Macro dans le menu contextuel.

2. Renseignez la nouvelle macro  - Open url.png voir Description

  • Sélectionnez l'option Classique ou Conditionnelle suivant le type de macro, puis renseignez le script ou la condition dans les champs affichés.

3. Cliquez sur Terminer.

La nouvelle macro projet est affichée dans la librairie du projet Self Help et est disponible sur l'ensemble des étapes des procédures.  Open url.png voir Procédure Comment afficher une variable dans une étape

Voir les pas à pas détaillés sur le portail Self Help

Ce cas d'utilisation permet d'indiquer à un utilisateur lançant une procédure avec une étape de choix quelles branches il a déjà parcourues en affichant une icône verte à la droite de celles-ci.

Tags :
Powered by XWiki © EasyVista 2024