DES/Current/Designer/ECMAScript - Revision history

WikiSysop at 17:45, October 11, 2022

2022-10-11T17:45:39Z

WikiSysop at 20:00, April 13, 2022

2022-04-13T20:00:22Z

WikiSysop at 19:15, April 13, 2022

2022-04-13T19:15:22Z

WikiSysop at 19:00, April 13, 2022

2022-04-13T19:00:23Z

Brian.marshall@genesys.com: Published

2021-07-29T12:37:23Z

Published

Brian.marshall@genesys.com: Published

2021-07-09T14:55:19Z

Published

Brian.marshall@genesys.com: Published

2021-07-09T14:48:27Z

Published

New page

{{Article
|Standalone=No
|DisplayName=ECMAScript Expressions
|TocName=Using ECMAScript in Designer
|Context=In certain blocks, you can use ECMAScript expressions to perform dynamic operations while an application is running. For example, you can use ECMAScript expressions to assign values to variables or perform certain functions, like sorting an array.
|ComingSoon=Yes
|Role=Administrator
|Application=Designer
|Section={{Section
|sectionHeading=Before you start
|anchor=overview
|alignment=Vertical
|structuredtext=To use this feature, you must have a basic level of familiarity and understanding of ECMAScript syntax and rules.

Although the terms ECMAScript and JavaScript are often used interchangeably, Designer technically supports ECMAScript and does not support JavaScript functions that are typically used for web-browser based applications, such as pop-up windows, alerts, and so on.

Designer blocks that support the use of ECMAScript expressions include:

*{{Link-SomewhereInThisVersion|manual=Designer|topic=AssignVar|anchor=AdvancedScriptingtab}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=MenuOption|anchor=SetVariablestab}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=Return}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=SharedMod|anchor=Signaturetab}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=DataTables}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=Activity}}
*{{Link-SomewhereInThisVersion|manual=Designer|topic=Milestone}}

In general, block properties do not support ECMAScript expressions unless otherwise stated. If ECMAScript expressions are not supported, you must enter a value (a string that is taken as a ''literal''). This value is not evaluated at runtime. For example, in the {{Link-SomewhereInThisManual|topic=PlayMessage|anchor=top|display text=Play Message block}}, the value of a TTS prompt is interpreted as a literal string.

===A few notes on syntax===
Some rules and guidelines to follow when using ECMAScript in Designer:

*Strings must be quoted (<code>'</code>). For example, <code>'hello'</code> is a string, whereas <code>hello</code> is a reference to a variable called '''hello'''.
*Single quotes (<code>'</code>) are recommended, as opposed to double quotes (<code>"</code>).
*When specifying an object in JSON notation, surround the JSON with parentheses. For example: <code>({'abc': 'def'})</code>.

'''Use caution!''' Any errors in your script can cause erratic behavior, so test your changes to make sure that your script works correctly before running it in your production environment. Designer can check your script for syntax errors, but cannot validate it nor check for runtime errors that might occur when the script is executed. {{NoteFormat|Due to certain platform dependencies and limitations, not all ECMAScript functions are supported when used in Designer. For example, the '''toLocaleString''' function is not supported at this time. |3}}
|Status=No
}}{{Section
|sectionHeading=Examples of how ECMAScript can be used
|anchor=examples
|alignment=Vertical
|structuredtext=Below are examples of how ECMAScript expressions can be used in Designer applications.

===Building a Dynamic TTS Prompt===
You can use the {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign block}} to concatenate a string to be spoken by the application. For example, the expression below reads the caller's phone number or ID:

<code>'You are calling from ' + ANI</code>
===Controlling the Application Flow===
A {{Link-SomewhereInThisManual|topic=Segmentation|anchor=top|display text=Segmentation block}} can take ECMAScript expressions that evaluate to a Boolean value, and thus control the flow of the application.

For example, you might want to inform your customers about upcoming seasonal events and you need a way to determine the current season and whether the event is occurring within the coming week. The expression below determines whether the call was received within seven days of the event, and whether the current season is summer or autumn:

<code>numDays > 7 && (isSummer {{!}} {{!}} isAutumn)</code>
|Status=No
}}{{Section
|sectionHeading=Advanced scripting in Designer
|anchor=advanced
|alignment=Vertical
|structuredtext=In blocks where it is supported, you can use use the '''Advanced Scripting''' tab to compose more complex ECMAScript constructs, such as loops or multiple nested conditions.

Let's take a look at how advanced scripting could be used to assign a value to a variable. Here, some script has been added to the '''Advanced Scripting''' tab of an {{Link-SomewhereInThisVersion|manual=Designer|topic=AssignVar|anchor=AdvancedScriptingtab}}:

[[File:des_assignvar_advanced_ex2.png]]

In this example, the script sets the variable <code>varOrdersPrompt</code> to <code>3 Laptop bags, 2 Phone chargers, 1 Super rare fish</code>.

Here's how it works:

The sample script first initializes JSON data in <code>varOrderDetails</code> so that it becomes an array of three JSON objects. Each JSON object has properties — '''item''', '''quantity''', and '''backordered'''. The script then proceeds to loop through orders and forms a string to play back to the caller to notify them of their order status.

The script uses variables in two scopes:

*A scope exclusive or local to this script itself (<code>i</code>). This variable remains available only while this script runs, and then it disappears.
*Top-level variables that were defined in the '''Initialize''' phase remain available throughout this application flow, but not in any modules this application calls (such as <code>varOrdersPrompt</code>).

{{NoteFormat|Advanced Scripting is an optional feature and might not be enabled on your system. To enable this functionality, contact Genesys.
}}

<br />
|Status=No
}}{{Section
|sectionHeading=Built-in user functions
|anchor=functions
|alignment=Vertical
|structuredtext=Designer also has built-in ECMAScripts that you can invoke from a Designer application, such as from an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign}} or {{Link-SomewhereInThisManual|topic=Segmentation|anchor=top|display text=Segmentation}} block, to perform certain functions at runtime.

===isDataTableValueValid===
You can use this function to determine if a value returned from a data table query is valid. For example, you might use the following function in an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign}} block:

<code>isDataTableValueValid(''value'', ''datatype'')</code>

This function has two arguments:

*''value'' is a single value returned from a data table query
*''datatype'' is the data type of the data table column, such as 'string', 'boolean', 'integer', 'announcement', or 'numeric' (this argument is optional)

If the data table value is valid, the script returns <code>true</code>. Here is a list of values that this function can return:

*<code>isDataTableValueValid(varStr, 'string')</code> on a valid (or empty) string returns <code>true</code>. Anything else returns <code>false</code>.
*<code>isDataTableValueValid(varNum, 'numeric')</code> on a valid number or <code>0</code> returns <code>true</code>. Anything else returns <code>false</code>.
*<code>isDataTableValueValid(varNum, 'integer')</code> on a valid integer or <code>0</code> returns <code>true</code>. Anything else returns <code>false</code>.
*<code>isDataTableValueValid(varBool, 'boolean')</code> on <code>true</code> or <code>false</code> returns <code>true</code>. Anything else returns <code>false</code>.
*<code>isDataTableValueValid(varAudio, 'announcement')</code> on a valid (or null) announcement returns <code>true</code>. Anything else returns <code>false</code>.
|Status=No
}}
}}

@@ Line 85: / Line 85: @@
 |alignment=Vertical
 |structuredtext=Designer also has built-in ECMAScripts that you can invoke from a Designer application, such as from an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign}} or {{Link-SomewhereInThisManual|topic=Segmentation|anchor=top|display text=Segmentation}} block, to perform certain functions at runtime.
+{{AnchorDiv|setAttributes}}
 ===setAttributes===
 You can use this function to add arbitrary key-value pairs to the Session Detail Record (SDR):
@@ Line 91: / Line 91: @@
 <code>setAttributes(''key'', ''value'')</code>
-*If <code>key</code> is a ''string'', a property with <tt>key = value</tt> is added to the attributes object in the SDR.
+*If ''key'' is a string, a property with <code>key = value</code> is added to the attributes object in the SDR.
-*If <code>key</code> is an ''object'', all of its properties are added as individual properties in the attributes object in the SDR. In this case, <code>value</code> is ignored.
+*If ''key'' is an object, all of its properties are added as individual properties in the attributes object in the SDR. In this case, ''value'' is ignored.
 ====Example====
@@ Line 123: / Line 123: @@
 {{NoteFormat|Reading is not supported. Use application variables when both read and write access is required. |3}}
+{{AnchorDiv|isDataTableValueValid}}
 ===isDataTableValueValid===
 You can use this function to determine if a value returned from a data table query is valid. For example, you might use the following function in an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign}} block:

@@ Line 87: / Line 87: @@
 ===setAttributes===
-You can use this function to add arbitrary key/value pairs to the Session Detail Record (SDR):
+You can use this function to add arbitrary key-value pairs to the Session Detail Record (SDR):
-<code>setAttributes (key, value)</code>
+<code>setAttributes(''key'', ''value'')</code>
 *If <code>key</code> is a ''string'', a property with <tt>key = value</tt> is added to the attributes object in the SDR.

@@ Line 26: / Line 26: @@
 *{{Link-SomewhereInThisVersion|manual=Designer|topic=Milestone}}
-In general, block properties do not support ECMAScript expressions unless otherwise stated. If ECMAScript expressions are not supported, you must enter a value (a string that is taken as a ''literal''). This value is not evaluated at runtime. For example, in the {{Link-SomewhereInThisManual|topic=PlayMessage|anchor=top|display text=Play Message block}}, the value of a TTS prompt is interpreted as a literal string. {{NoteFormat|Due to certain platform dependencies and limitations, not all ECMAScript functions are supported when used in Designer. For example, the '''toLocaleString''' function is not supported at this time. |3}}
+In general, block properties do not support ECMAScript expressions unless otherwise stated. If ECMAScript expressions are not supported, you must enter a value (a string that is taken as a ''literal''). This value is not evaluated at runtime. For example, in the {{Link-SomewhereInThisManual|topic=PlayMessage|anchor=top|display text=Play Message block}}, the value of a TTS prompt is interpreted as a literal string.
 ===A few notes on syntax===
@@ Line 35: / Line 38: @@
 *When specifying an object in JSON notation, surround the JSON with parentheses. For example: <code>({'abc': 'def'})</code>.
-'''Use caution!''' Any errors in your script can cause erratic behavior, so test your changes to make sure that your script works correctly before running it in your production environment. Designer can check your script for syntax errors, but cannot validate it nor check for runtime errors that might occur when the script is executed.
+=== General recommendations ===
 |Status=No
 }}{{Section
-|sectionHeading=Examples of how ECMAScript can be used
+|sectionHeading=Scripting examples
 |anchor=examples
 |alignment=Vertical
-|structuredtext=Below are examples of how ECMAScript expressions can be used in Designer applications.
+|structuredtext=Below are examples of how ECMAScript expressions can be used in Designer applications. Some tips and general recommendations are also provided.
 ===Building a Dynamic TTS Prompt===
@@ Line 53: / Line 60: @@
 <code>numDays > 7 && (isSummer {{!}} {{!}} isAutumn)</code>
 |Status=No
 }}{{Section

@@ Line 21: / Line 21: @@
 *{{Link-SomewhereInThisVersion|manual=Designer|topic=MenuOption|anchor=SetVariablestab}}
 *{{Link-SomewhereInThisVersion|manual=Designer|topic=Return}}
-*{{Link-SomewhereInThisVersion|manual=Designer|topic=SharedMod|anchor=Signaturetab}}
+*{{Link-SomewhereInThisVersion|manual=Designer|topic=SharedMod}}
 *{{Link-SomewhereInThisVersion|manual=Designer|topic=DataTables}}
 *{{Link-SomewhereInThisVersion|manual=Designer|topic=Activity}}
@@ Line 85: / Line 85: @@
 |alignment=Vertical
 |structuredtext=Designer also has built-in ECMAScripts that you can invoke from a Designer application, such as from an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign}} or {{Link-SomewhereInThisManual|topic=Segmentation|anchor=top|display text=Segmentation}} block, to perform certain functions at runtime.
 ===isDataTableValueValid===

@@ Line 4: / Line 4: @@
 |TocName=Using ECMAScript in Designer
 |Context=In certain blocks, you can use ECMAScript expressions to perform dynamic operations while an application is running. For example, you can use ECMAScript expressions to assign values to variables or perform certain functions, like sorting an array.
-|ComingSoon=Yes
+|ComingSoon=No
 |Role=Administrator
 |Application=Designer