Self Help Desktop Studio - Variables and Macros

Last modified on 2023/07/25 18:22

Each new Self Help project automatically contains a list of predefined variables and macros.

Writers can also create their own project variables and macros based on the requirements for their Self Help project.

Variables and macros are stored in the Self Help project library. They are available to the entire Self Help project, for any step in any procedure.
 

Specific characteristics of variables and macros

  • A variable can store several types of data, i.e. Boolean, text, etc.
    • Predefined variables are used to retrieve information on the current step, the current procedure or the logged-in user.
    • A project variable can be defined as a constant and assigned a fixed value. If this is the case, the variable cannot vary depending on the context.
  • A macro is a JavaScript expression.
    • Predefined macros are used to modify dates, numbers and tables.
    • A project macro can be defined as a script or as a condition.
       

Using variables and macros
You can use variables and macros to:

  • Display data during a procedure.
  • Run calculations and display the results in a procedure step.
  • Define the conditions for a branch in a procedure step.
  • Define the visibility condition for content in a procedure step.
  • Configure a connector.
  • Define input and output parameters.

Examples

  • Retrieve and display the email address of the user running the current step ==> Use the executionContext.user.email predefined variable
  • Run calculations or format content ==> Use a predefined macro
  • Display the label of an action button based on the language of the logged-in user ==> Use a project macro

Notes

  • All variables and macros, both predefined and project, are stored in the Library folder of each Self Help project. As such, they are available to the entire project, for any step in any procedure.
       Predefined variables list.png
  • Predefined variables and macros are provided by EasyVista. You cannot delete or modify an existing one.
  • Project variables and macros can be created as follows:
    • Automatically, after importing or copying any content (e.g. procedure, resource, etc.) associated with one or more variables and/or macros into the Self Help project.
    • Manually, by writers with write access to the Self Help project.
  • Project variables can also be created automatically when designing a form. One project variable will automatically be created for each field in the form.
  • Project macros can also be created in the Macro tab of the Description pane in a procedure step. In this case, the macro will run before the step is displayed and will only be applicable to the current procedure.

Best Practice

  • Create a variable in the project library for items of information that may appear in several procedures of the Self Help project. This way, if you need to update any item of information, you can simply modify the variable in a single place. Your modification will automatically be propagated to all procedures where it is used.

example  Display the virtual agent name in the content of certain procedures

  • Create a variable called CHATBOT_NAME in the library.
  • If you need to update the virtual agent name, modify the content of the variable in the library.

Variables

Different types of variables

Type Description
Boolean The variable can contain the True or False value.
Date The variable can contain a date in the following format, YYYY,MM,DD,HH,MM,SS.
Undefined The variable can contain an expression.
Number The variable can contain a numeric value.
Complex object The variable can contain other variables. It is used to organize the library.
Table The variable can contain a table in the following format, ["Value 1", "Value 2", "Value 3", etc.]. These values can be text or numbers.
Text The variable can contain a string of characters.

List of predefined variables

Variable Type Description

currentNode: Information on the current step

currentNode.automatic Boolean Type of step
  • True ==> Invisible step: No user interaction
  • False ==> Visible step
currentNode.id Text ID of the step
currentNode.name Text Step name
currentNode.procedureName Text Title of the procedure used as the entry point
currentNode.resourcesTab Table List of resources linked to the step, i.e. table with the ID, name and URL of each resource
currentNode.textId Text ID of the Text resource that stores the content of the step
currentNode.type Text Type of step, e.g. Action, Page with Choices, etc.

executionContext: Information on the current procedure instance

executionContext.agentRef Text Reference of the virtual agent calling the procedure
executionContext.channel Text Execution channel of the procedure
  • PORTAL: Procedures called in the portal.
  • APICONTENT: Procedures called via the Content API.
  • MSTEAMS: Procedures called via MS Teams.
  • SERVICEBOTS: Procedures called via a virtual agent.
  • AUTOMATIC: Procedures called via the Portal API.
  • PREVIEW: Procedures called in test mode when writers generate a direct link in the Desktop Studio and click Launch the procedure.
  • DEBUG: Procedures called in debug mode.
executionContext.contextId Text ID of the current step
executionContext.country Fixed length string Code of the country associated with the procedure instance language, e.g. FR, GB, etc.
executionContext.currentNodeTimeOnEnter Integer Execution time of the current step
executionContext.endType Text Way in which the procedure ended
executionContext.expertSessionId Text ID of the expert session when writers generate a direct link in the Desktop Studio and click Launch the procedure
executionContext.instanceId Text ID of the procedure instance
executionContext.isDebug Text Mode for running the procedure
  • True ==> The procedure is run in debug mode
  • False ==> The procedure is run in normal mode
executionContext.isMobile Boolean Procedure run in a skin for mobile display
executionContext.lang Fixed length string Language in which the procedure is run, e.g. EN, FR
executionContext.lastNodeDuration Integer Consultation time of the last step (= end time of the procedure instance)
executionContext.log Text Contents of the execution report

Note: The report is created progressively at the same time as the user journey in the procedure. It can be configured step by step. Open url.png See the Report tab in the Description pane of the Desktop Studio in edit mode

executionContext.referrer Text Referrer URL of the procedure instance
executionContext.server Text URL of the Self Help server hosting the procedure
executionContext.sessionLess Boolean Access to the procedure by logging in or by generating a direct link
executionContext.startScenarioTime Integer Start time of the procedure instance
executionContext.userAgent Text Information on the Web browser used by the procedure
executionContext.userSessionId Text ID of the user session for connections via the portal

executionContext.procedure: Information on the current procedure

executionContext.procedure.category Text Category of the procedure, defined in the ProcedureCategory metadata
executionContext.procedure.categoryDescription Text Description of the procedure category, defined in the CategoryDescription metadata
executionContext.procedure.domain Text Domain where the procedure is found
executionContext.procedure.id Text Unique ID (GUID) of the procedure
executionContext.procedure.isPublished Boolean Publication status of the procedure:
  • True ==> The procedure is published
  • False ==> The procedure is not published (the Desktop Studio will open a working version)
executionContext.procedure.metaDescription Text HTML tags associated with the procedure, in a translated string of characters, defined in the ProcedureMetaDescription metadata
executionContext.procedure.name Text Title of the procedure
executionContext.procedure.project Text Name of the Self Help project where the procedure is found
executionContext.procedure.projectVersion Text Version number of the Self Help project where the procedure is found
executionContext.procedure.properties Complex object List of procedure metadata (metadata names and content):
  • 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 Text Sub-category of the procedure, defined in the ProcedureSubCategory metadata
executionContext.procedure.subCategoryDescription Text Description of the procedure sub-category, defined in the ProcedureSubCategoryDescription metadata
executionContext.procedure.versionId Text ID of the procedure version
executionContext.procedure.viewable Boolean Used to indicate if the procedure should be indexed by the search engine (value True) or not (value False)

executionContext.user: Information on the user running the current procedure

executionContext.user.email Text Email address of the user
executionContext.user.firstName Text First name of the user
executionContext.user.groups Plain text table List of groups where the user belongs
executionContext.user.id Text ID of the user
executionContext.user.lastName Text Last name of the user
executionContext.user.login Text User login entered during authentication
executionContext.user.properties Complex object List of additional user properties in a table with the property names and values
  • executionContext.user.properties.{property name}
executionContext.user.title Text Title of the ID, e.g. Mr. or Ms.

Other variables

custom Text Generic global variable

Note:

  • Variable empty by default.
  • Variable used in versions earlier than Self Help version 2.6, when the Library folder was not automatically created.
stopMessage Text Variable whose contents appear in the Message column for statistics available in the Desktop Studio in publish mode

Note: Variable empty by default.

Screen description: Project Variable

          Project variable.png

Name: Name of the project variable.

  • The name must be unique for the Self Help project.

Data type: Type of data in the project variable, e.g. text, number, date, etc.

Constant: Used to specify if the project variable is a fixed value (box is checked) or not (box is not checked).

  • If you create a constant, you must specify its default value.

Default value: Default value defined for a project variable.

  • There must be a default value if the Constant box is checked.
  • Value Format: Used to specify if the default value is a simple value or an expression.

example

  • Simple value: CHATBOT_NAME variable containing the name of the virtual agent
    ==> CHATBOT_NAME = evie
  • Expression: UserName variable containing the first and last names of the logged-in user.
    ==> UserName = executionContext.user.firstName + executionContext.user.lastName

Description: Description of the project variable.

Procedures

How to create a project variable

Step 1: Display the Self Help project library

1. Select the Self Help project in the tree structure of the Explorer pane.

2. Double-click the Library folder.

The library will display predefined variables and macros as well as project variables and macros.
 

Step 2: Create the project variable in the library

1. Right-click Project Variables and select New > Variable from the contextual menu.

2. Define the new variable. Open url.png See the description

  • Check the Constant box if the project variable is a fixed value.
  • Select the Simple option or the Expression option depending on the format of the default value. Specify the default value.
  • If you create a constant, you must specify its default value.

3. Click Finish.

The new project variable will appear in the Self Help project library and will be available to all procedure steps.

     Open url.png See:

How to display a variable in a step

Step 1: Display the step of the procedure

1. Select the Self Help project in the tree structure of the Explorer pane.

2. Double-click the procedure.

The procedure will appear in the Conception pane.

3. Click the step displayed in the flow chart.

The content of the step will appear in the Description pane.

Step 2: Insert the variable in the content of the step

1. Expand Library > Predefined Variables by clicking Tree expand icon.png.

2. Click and drag the variable from the Explorer pane to the content of the step in the Description pane.

 The inserted variable will appear with a gray outline.
   Predefined variable insertion.png

Step 3: Check that the variable is correctly displayed when the procedure is run

1. Click Launch procedure dropdown list.png in the toolbar and select Launch procedure icon.png Launch the procedure.
The step will appear in your Web browser.

2. Check that the variable has been replaced with the correct content.
   Predefined variable insertion - Result.png

Use cases

Use a variable to vary the content of a procedure

This use case allows you to indicate to a user which branches s/he has already been through by displaying an icon on the right of these branches.

          Use case - Branches already covered.png

Use a variable in a branch condition

This use case explains how to check whether users belong to the company when they submit a request to change their password. It uses a condition with the predefined variable called executionContext.user.email that will check if the user email address contains the value @company.com. Next, based on the results of the condition, it will direct users to the appropriate branch of the procedure.

          Use case - Use a variable in a procedure.png

Step 1: Create the procedure

1. Create a new procedure in your Self Help project.

     Open url.png See How to create a Self Help procedure

2. Name the procedure I want to change my password.
 

Step 2: Add an Action with Switch step

1. Insert an Action with Switch step in your procedure.

2. Name the step Email test.

Two branches will be created.

  • The top branch <Condition> manages the response to be provided if the user email address contains @company.com@.
  • The bottom branch Default manages the response to be provided if it does not contain the value above.
    Use case - Use a variable in a procedure - Condition branch.png

Step 3: Define the condition for checking the user email address

1. Double-click the <Condition> field in the top branch.

The window for defining the condition will appear.
        Use case - Use a variable in a procedure - Condition branch - Properties.png

2. Define the condition for checking that the user email address contains @company.com@.

  • Click Add variable icon.png next to the first field in the condition.
    The list of project variables available in the Self Help project will appear.
            Use case - Use a variable in a procedure - Condition line - Variable list.png
  • Select the predefined value called executionContext.user.email to retrieve the user email address.
  • Specify the other fields in the condition.
    • Operator = contains 
    • Search value = @company.com

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

3. Click Finish.

The condition will be refreshed.
        Use case - Use a variable in a procedure - Condition line entered.png
 

Step 4: Define the procedure steps

1. Go to the Condition branch (top branch) and create the steps that will guide users in changing their password.

2. Go to the Default branch (bottom branch) that will become active when the condition is not satisfied, i.e. the user email address does not contain @company.com. Create a step asking users to contact their IT Department.

Macros

Different types of macros

Type Description
Classic The macro is a script that will return a result when it is run.
Conditional The macro is a condition that will return a value depending on the result obtained, i.e. whether or not its condition is satisfied.

List of predefined macros

Macro Name Description
Date: Update date_update Used to add or subtract years, months, days, hours, minutes and seconds from a date and return the modified date.

Syntax:

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

Specify the following parameters:

date to update, difference in years, difference in months, difference in days, difference in hours, difference in minutes, difference in seconds

example date_update(myDate, 0, -1, 1, 0, 0, 0)
  • Subtract one month and add one day to the date specified in the myDate variable.
  • The new value will be returned.
  • The myDate variable will not be modified.
Number: format num_format Used to return a number in text format, rounded off to the specified number of decimal places.

Syntax:

num_format(value, numDecimals)

Specify the following parameters:

number to format, number of decimals

example num_format(0.148632, 2)
  • The number will be rounded off to two decimal places.
  • This will return the following string of characters, 0.14.
Number: Round off to decimal num_round Used to return a number rounded off to the specified number of decimal places.

Syntax:

num_round(value, numDecimals)

Specify the following parameters:

number to round off, number of decimals

example num_round(42.7845652, 2)
  • The number will be rounded off to two decimal places.
  • This will return the following value, 42.78.
Table: Add to start tab_addfirst Used to add an element to the start of the table and return the value of the modified table.

Syntax:

tab_addfirst(table, element)

Specify the following parameters:

table, element to add

example The city table contains the following elements, [Paris, Nantes, Grenoble]
  • tab_addfirst(city, "Tampa") will add the element Tampa to the start of the table.
  • The [Tampa, Paris, Nantes, Grenoble] value will be returned.
Table: Add to end tab_addlast Used to add an element to the end of the table and return the value of the modified table.

Syntax:

tab_addlast(table, element)

Specify the following parameters:

table, element to add

example The city table contains the following elements, [Paris, Nantes, Grenoble]
  • tab_addlast(city, "Tampa") will add the element Tampa to the end of the table.
  • The [Paris, Nantes, Grenoble, Tampa] value will be returned.
Table: Contains element tab_contains This will return the True value if an element is present in the table and the False value if it is missing.

Syntax:

tab_contains(table, element)

Specify the following parameters:

table, element to find

example The city table contains the following elements, [Paris, Nantes, Grenoble]
  • tab_contains(city, "Paris") will search the table for the Paris element and return the True value.
  • tab_contains(city, "Lyon") will search the table for the Lyon element and return the False value.
Table: Remove element tab_remove Used to remove an element from the table and return the value of the modified table.

Syntax:

tab_remove(table, element)

Specify the following parameters:

table, element to remove

example The city table contains the following elements, [Paris, Nantes, Grenoble]
  • tab_remove(city, "Paris") will remove the Paris element from the table.
  • The [Nantes, Grenoble] value will be returned.
Table: Swap rows and columns tab_swap_row_col Used to swap the rows and columns of a table and return the value of the modified table.

Syntax:

tab_swap_row_col(table)

Specify the following parameters:

table

example The country table contains the following elements, [{Paris, France}, {London, Great Britain}]
  • tab_swap_row_col(pays) will swap the rows with the columns in the table.
  • The [{France, Paris}, {Great Britain, London}] value will be returned.
Text: Equal non-case-sensitive text_equalsIgnoreCase Used to return the True value if two strings of characters are identical and the False value if they are different, without taking the case into account.

Syntax:

text_equalsIgnoreCase(string1, string2)

Specify the following parameters:

string1, string2

example
  • text_equalsIgnoreCase('TeXt', 'text') will compare the two strings, 'TeXt' and 'text', without taking the case into account, and return the True value.
  • text_equalsIgnoreCase('text', 'texte') will compare the two strings, 'text' and 'texte' and return the False value.

Screen description: Project Macro

          Project macro.png

Name: Name of the project macro.

  • The name must be unique for the Self Help project.

Result type: Type of result expected from the project macro, e.g. text, number, date, etc.

Parameters: List of input parameters for the project macro.

  • Click + Add a parameter to specify each parameter of the project macro.

Description: Description of the project macro.

Type of macro: Used to specify if the macro is a classic or conditional macro. If it is classic, you must define a script in the Macro body field. If it is conditional, you must define the condition in the three following fields, IF, THEN, and ELSE.

example

  • Classic macro: The description() macro will format the contents of the predefined variable, executionContext.log, by replacing line breaks.
    Project macro - Example classic macro.png
  • Conditional macro: The info() macro will return the Find out more value if the procedure instance language is English. If this is not the case, it will return the Plus d’informations sur le wiki value.
    Project macro - Example conditional macro.png

Procedures

How to create a project macro

Step 1: Display the Self Help project library

1. Select the Self Help project in the tree structure of the Explorer pane.

2. Double-click the Library folder.

The library will display predefined variables and macros as well as project variables and macros.
 

Step 2: Create the project macro in the library

1. Right-click Project Macros and select New > Macro from the contextual menu.

2. Define the new macro. Open url.png See the description

  • Select the Classic or Conditional option depending on the type of macro. Next, define the script or the condition in the fields displayed.

3. Click Finish.

The new project macro will appear in the Self Help project library and will be available to all procedure steps.  Open url.png See How to display a variable in a step

See detailed step by step on Self Help portal

This use case allows you to indicate to a user which branches s/he has already been through by displaying an icon on the right of these branches.

Tags:
Powered by XWiki © EasyVista 2024