Variables

Personalize the conversation by capturing user data in variables

Getting started : core usage of variables in the Dydu BMS

Definition of a variable

Whenever a user provides information that needs to be stored somewhere, the BMS saves it in a named variable as its value. The value can be reused later in the conversation or sent to an external API.

To put it simply, a variable is a box that can store things inside.

Different types of variables provided by the Dydu BMS

The BMS provides basically two types of variables according to the use of Dydu’s in-house Natural Language Processing algorithm:

1. Free input variables. They capture and save a piece of information provided directly by the user during the conversation no matter the data format (number, date, text, etc.).

   The NLP algorithm will not match this user input with any item of your knowledge base. One of the common use cases is to capture and send the value to an external API.

2. Predefined default variables. They must be used according to their predefined formats (number, date, text, etc.).

   The NLP algorithm will analyze user information (personal or event data) that is captured in this type of variable to provide the most appropriate answers chosen from your knowledge base.

1.Free input variables

Free input variables allow the bot to capture and save a piece of information provided directly by the user during the conversation.

The NLP algorithm will not match this user input with any item of the knowledge base. One of the everyday use cases is to capture and send the value to an external API.

How to use free input variables?

Consider the following example:

A user wants to declare a sick leave on the RH chatbot. To handle the request, the latter asks for the user’s personal information.

Steps to follow:

1. Create a knowledge item as you would usually do. In the answer, guide the user to provide the information you want the bot to capture. Publish and save the knowledge item.

2. Click on the + (“add an intention”) button under the answer edition box and choose the “capture user input” option.

3. Give a name to the free input variable you just created according to the type of information that needs to be captured.

4. Since we also want to know the social security number of the user, we are going to add another free input variable that we will call “num_secu”.

Attention :

There is no format verification on the value captured.

This means if users make a mistake or provide intentionally wrong information, the data will still be saved in the BMS.

If your use case needs the bot to verify the data format, we advise you to use default variables coupled with a context condition.

During a user input, if the user type "+" in front of his input then the "+" is not kept when restoring the content of the variable.

To keep the "+" used at the beginning of the entry, the variable that stores the entry must contain the term "phone"s

Example :

Given knowledge of a "free entry" branch

If the variable, which stores free input, contains the term "phone"

So when the user goes through this branch and enters "[phone]" the content of the returned variable will be "[phone]"

Otherwise (the variable, which stores free input, does not contain the term "phone") the returned content will be "33679305151" (the "+" is deleted in the restitution :::

5. Lastly, to reassure the user that his/her information has been saved, the bot will summarize the information gathered by displaying the value of the variable in the last interaction.

   To display a captured variable value in an answer, use the syntax ${capture.NameoftheVariable}.

2.Predefined variables

When you edit a knowledge item, you can use predefined variables to capture user information such as name, phone number, age, or date.

The BMS provides the following basic variable types:

• Integer: this variable captures only integer numbers (no decimals). Note that integers written in full words will be understood as numbers (eg: "twenty" will be understood as "20").

• Number: this variable captures numbers. Integers written in full words will be understood as numbers.

• Alphanumeric: this variable captures letters and integer numbers (no decimals).

• Mail: this variable capture an email address according to this format: {address}@{domain}.{com}

• URL: this variable can capture a URL with the following formats: http://url.com / http://www.url.com / www.url.com.

• Date: this variable capture a date with the following formats: 28/07/21 or 28/07/2021.

  You can also capture precise dates thanks to the Date - Precise date group that will let you retrieve the day, month, year... To do so, display captures this way: ${capture.date_dayofmonth} / ${capture.date_month} / ${capture.date_year}

• Phone number: this variable allows to capture the phone number with the following formats: 0601020304 / 06.01.02.03.04. If a figure is missing, the number will not be captured.

How to use them?

Theses variables are accessible in your user question edition box by clicking on and scrolling down to the end of the list until you see the “special” group.

You need to name your variable in order to reuse it in the conversation.

To do so, after choosing the variable type, click on the > symbol in the variable which opens its edition box:

To use the value of a captured variable in an answer, you need to use the syntax ${capture.NameoftheVariable} by respecting the case of the variable name.

Example :

A bank offers its customers a chatbot that answers questions about their bank account such as the account balance at a specific date.The chatbot then fetches this information from the bank’s database and returns the information to the user.In this case, the bot manager can use a variable to capture the date and send it to the bank’s API.

The screenshots below show you how this conversation is configured in the BMS:(To simplify, we do not explain how the API works to fetch the balance data.)

TIPS

• Using a script function on the server side::

    	${displaySlots(capture.filtered_slots)}

In this example we make a js function call that takes a parameter a capture. The ${...} are not needed for the capture.

• For a variable assignment:

    ${mavariable:=....}

  • To assign the value of a variable to another or a constant value the ${...} are not necessary:

      ${mavariable:=capture.autrevariable}
    
      ${mavariable:=valeur constante}

• A variable assignment from a web service return:

    ${service_staff:=${callapi.service_staff.staff}}

We must put ${...} in the call to the web service.

• Variable assignment that uses a server-side javascript function call requiring parameter capture:

    no_tel:=${formatPhoneNumberWS(capture.phone_number)}}

Becoming expert on variables

Functions

Besides variables, the Dydu BMS also provides several default functions.

Definition

A function is a named piece of computer code that performs a specific task.

Functions usually receive data as input and return the result of the processing performed by the function as output.

Functions can be used as a context condition or directly in an answer. In this case, the syntax to use is slightly different from using variables: ${NameoftheVariable}.

Example:

To use the function UserOS that can retrive user's operating system directly in an anwser, the syntax to use is:

Here is the list of default functions provided by the BMS:

• ComputeDate(date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam]): is used to calculate the date;

• **ComputeDateGetDays(date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam]):**calculate the number of days

• ComputeTime (date_daypart, date_hour, date_minute): allows you to calculate the exact date and time;

• DialogCurrentAnswer (): current bot answer;

• DialogCurrentConsultationSpace(): consultation space of the current dialog;

• DialogCurrentDate(): date of the current dialog;

• DialogCurrentMatches():

• DialogFinished(): dialog completed;

• DialogHistory(): dialog history;

• IsDateBetween('YYYY-MM-DD','YYYY-MM-DD'[, dateToTest]):

• IsDateDayAndHour ('XXXXX--', '----- XXXXXXXXXXXX ----'): means (in this example) from monday to friday, from 8AM to 9PM;

• KnowledgeAskFeedback(): indicates whether satisfaction on a knowledge is requested (true, false);

• UserBrowser(): retrieves the browser used by the user;

• UserBrowserVersion(): retrieves the user's browser version;

• UserLocalization ('AreaCode' | 'City' | 'CountryCode' | 'CountryName' | 'Latitude' | 'Longitude' | 'MetroCode' | 'RegionCode' | 'RegionName' | 'TimeZone' | 'ZipCode'): retrieves one of the following user localization data according to the IP adress: the area code, the city name, the country code or name, the latitude or longitude, the metro code, the region code or name, the time zone and the zip code.

  Use case 1: you can use this variable directly in an answer to tell users their country of residence for example. To do so, use the following syntax in the WYSIWYG ${UserLocalization ('Country')}.

  Use case 2: if you want to send a personalized message to users living in France, create a context condition UserLocalization ('Country') equals France and use it in your knowledge item.

• UserOs(): retrieves the user's operating system AND its version (eg.macOS 10.15);

• UserOsFamily(): retrieves the user's operating system without the version (eg. macOS);

• UserURL(): captures the URL that the user is currently on.

Choice Suites

You can create choice suites, which may be necessary when you want to save several information in a row. You can ask the user for their first choice, their second choice, their third choice, and so on.

When you ask a question that you expect a yes or no answer, you can use the information by inserting a variable and a context condition that you can use later.

1. Create a context condition to use information. Go to Content > Context conditions

2. Edit a knowledge (blue window - user sentence).

3. Click Options then Options again.

4. In the Edition of variables field, insert ${Principle_ok:=yes} for the knowledge "yes" and ${Principle_ok:=no} for the "no" knowledge.

Thus, a first part of the selection sequence is completed.

You can also create multiple-choice knowledge while linking various questions using, for example, GUI actions where you can insert JavaScript code.

"Date" variables

Function	Default parameters	Type	Result
ComputeDate	ComputeDate (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Interval	[[2013-03-23 00: 00: 00,2013-03-24 23:59:59]]
			[[2013-04-02 00: 00: 00,2013-04-02 23:59:59], [2013-04-09 00: 00: 00,2013- 04-09 23:59:59], [2013-04-16 00: 00: 00,2013-04-16 23:59:59], [2013-04-23 00: 00: 00,2013-04- 23 23:59:59], [2013-04-30 00: 00: 00,2013-04-30 23:59:59]]
ComputeDateGetDays	ComputeDateGetDays (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Number of days	7
ComputeDateJP	ComputeDateJP (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Date	2013-03-18 20:30:00
ComputeDateJPF	ComputeDateJPF (date_dayofmonth, date_month, date_year, date_dayofweek, date_period, date_daypart, date_hour, date_minute [, date_periodparam])	Date	Wednesday 6th November at 23:30
ComputeTime	ComputeTime (date_daypart, date_hour, date_minute)	Range	[[20: 30: 00,23: 59: 59]]

Thus, the calculation engine uses the specified parameters and calculates the output.

To retrieve the date of the day, insert ${ComputeDateJPF()}

Variables and matching groups

It is possible to insert matching groups as variables. In our example, the goal will be to recover the innovation field the user's idea refers to in order to get this type of knowledge:

To do so, please go through the following steps:

1. Create your matching group. In our example, the matching group is Innovation field.

2. Head to the Knowledge page and create your knowledge like the decision tree in our example.

The knowledge “robotics” is actually just a default label to which you must add a formulation that will integrate your group of formulations.

3. Edit the user phrase for which you wish to add your group of formulations then position yourself on the field for adding a new formulation.

4. Click on the icon and select your previously created group of formulations.
5. Then click on the small white arrow located to the right of your group of formulations

6. Fill in the Variable Name field then click Update. This is the name of this capture that you will then use to retrieve the information in the response window.

7. Complete the response window with the name of the capture corresponding to your formulation group (See previous step).

8. Click Update.

Thus, if the user answers one of the domains integrated into the formulation group, the capture will recover the precise term. Furthermore, if you wish to suggest areas and make clickable links to the “robotics” knowledge, you will first need to modify this knowledge and configure it for direct access. You can also create clickable links to the same knowledge “robotics”. In order to personalize each link and retrieve the correct information, click on the HTML editor button then modify all the titles so that it matches the domain you wish to display.

Variables for web services

This part will cover general information. If you would like to access more concrete cases of using variables for web services, please go to this page.

• Insert a variable into the URL of a web service

You can insert a variable into the URL of your web service like this: http://mon-domaine/abc/${}capture.mavariable/xyz

• Use a web service return as an argument for a server-side script

${arg2:=${callapi.myWS.json}}

${myscript(capture.myvariable,arg2)}

• Calling a server-side script from a web service page

On certain fields, it is possible to enter variables using a server-side script. Go to Contents > Advanced > Variables > Add new Global Variable Configurations

Note that variable assignments with web functions or services do not work. For example: ${myvariable:=JSServerSideFunction(callapi.WebService.Variable)}

In this case, the code will not be executed and the variable will have the value of the character string behind it.

• Insert a variable from a web service into knowledge templates

Variables from web services can also be used in knowledge templates. If a variable returns JSON in the template, you will need to use the JSON.stringify() method otherwise the template will not be applied.

Internet user events

Internet user events allow a variable - typically the occurrence of an event - to be memorized for a duration greater than that of the dialogue (this duration is configurable at the bot level, and is subject to the GDPR).

An event is identified by its name and contains, in addition to its value, the identifiers of the client and the bot as well as its creation date.

To create an internet event, go to Contents > Context conditions > Add

To create an internet event, you can:

• Insert a value directly: ${internaut.myEvent:=eventValue}

• Call another expression: ${internaut.myEvent:=callapi.ws.var} ${internaut.myEvent:=capture.myValue}

• Reading an internet event type variable ${internaut.myEvent}

• Use a user event in a context condition. To use a user event as a context condition, insert it like this: user. myEvent. For example :

  
• Use user events in the chatbox: dydu.chatbox.addInternautEvent('InternautEventName', 'InternautEventValue')

Using server-side JS functions as a parameter:

When using a JS function, it is possible to use character strings, integers, captures or json as parameters.

• Character strings are delimited by double quotes: "example". If a quote is contained in the character string, it must be escaped in this way: ""example"".

• Integers do not need delimiting: 10 or -10 for example. On the other hand, when passing to the JS function, the integers are transformed into a character string: "10" or "-10" will be transformed into the function argument.

• Objects and arrays defined in a valid json format are used as is, as an object. If the json object is not decryptable, it will be considered and used as a character string.

• Captures can be used with the syntax capture.VariableName or just VariableName, without double quotes delimiting the capture name. The capture value will then be used. The rules described previously will be applied to define the type of the variable.

Chatbox variables

Internet users events allow you to keep in memory a variable - typically the occurrence of an event - for a duration greater than the time of the conversation (this duration can be configured at the assistant level, and is subject to the GDPR regulation):

• DYDU_LANGUAGE: corresponds to the language (fr, en, etc.);

• DYDU_CONSULTATION_SPACE: corresponds to the consultation space;

• DYDU_BOT_ID: corresponds to the bot ID;

• DYDU_SERVLET_URL: corresponds to the server with which the bot communicates;

• DYDU_BACKUP_SERVLET_URL: corresponds to the backup server with which the bot communicates;

• DYDU_QUALIFICATION_MODE: corresponds to the qualification mode (true, false) to mark conversations as testing.

Other use cases and general information

• Array variables

${myboard:=["white","black"]}

${capture.mytable[0]} → this displays white

• Alpha variables

This allows you to capture:

• Accents (e.g. tested, haste, etc.);

• Dashes (eg: Jean-Paul);

• Points (eg: jean.paul).

Warning: it is impossible to capture apostrophes (eg: water) as well as spaces (Jean Paul).

• SAML

Variables During SAML authentication, it is possible to save variables on the user. These variables start with “auth_”.