Expression language

We use expression language to work with variables, arrays, functions, objects, and operators in the Convoworks Editor.

For this purpose, we’ve made adjustments to the Symfony Expression Language component to behave more like the Java Expression Language.

Differences from the base Symfony implementation:

• You can reference a non-existing value, which resolves to null.
• You can reference object methods in a shorthand manner: e.g., $request->getPlatformId() can be written as ${request.platformId}; $request->isLaunchRequest() can be written as ${request.launchRequest}.

To evaluate an expression, we use the JUEL syntax. For instance, if you have a variable called service_name, and you want to output its value in the Text response element, use this syntax: ${service_name}.

Alternatively, if you want to evaluate a comparison in the IF element, use: ${result.value > 5}.

 

Setting Variables

In Convoworks, variables enable you to integrate static text with dynamic values for display or speech output, test workflows (using IF conditions), or to dynamically configure component properties.

By default, variable values are strings. If you want to assign a different type to a variable, it needs to be evaluated. Consider the following examples:

• my_var : 1 – interpreted as a string.
• my_var : ${1} – treated as an integer.

When creating a variable, decide if it should be a runtime or service variable.

Service Variables

Service variables are defined on the Variables page. They’re accessible across all service components but can’t be modified during runtime, though they can be shadowed. Use them for constants/configurations such as service names, data source URLs, base paths, and numeric constants like the maximum number of players.

Runtime Variables

Runtime variables are established during service execution. Use the Set parameter element in a service block and specify the name-value in the element’s Properties field. Some components may introduce their runtime variables, such as a LOOP element with a counter or an HTTP client element providing response data. Most of these components allow naming the injected variable. Moreover, when setting variables, some elements let you decide their scope.

Variable Scopes

Scopes determine a variable’s availability duration. There are three scope types:

• Installation – persists until the user reinstalls the app. Retained across sessions.
• Session – exists for a single session. Must be reinitialized in subsequent sessions.
• Request – remains available during one request, typically used by components, e.g., the Loop element for current item information.

Defining multiple variables with identical names but varied scopes results in variable shadowing. A higher priority variable will shadow a lower-priority one. Priorities are as follows:

• Service variables
• Installation scope
• Session scope
• Request scope

Lastly, there’s a built-in third variable type, available either at the block or service level.

System Variables

System variables in Convoworks are built-in variables introduced by executing components, whether they’re on the service or block level. These variables can be accessed similarly to other variables in your system.

PHP Predefined Variables

Convoworks allows access to built-in PHP predefined variables. For instance, to retrieve a value from the POST variable, you would use the syntax ${_POST[“my_var”]}. You can also access other predefined PHP variables like _SERVER, _REQUEST, _POST, _GET, _COOKIE, _SESSION, _FILES, and _ENV.

Service-level Variables

• ${state} – The ID of the currently executing block.
• ${previous_state} – The ID of the previously executed block.
• ${returning} – Returns ‘true’ if the same block is executed consecutively, for example, when invoking a GOTO to the current state during the block’s process phase.
• ${first_call} – Returns ‘true’ only during the initial request in the ongoing session.
• ${request} – Represents the current request object. Notable properties include: ${request.intentName}, ${request.platformData}, ${request.launchRequest}, and ${request.platformId}. Additionally, ${request.isCrossSessionCapable} lets you determine if the service can retain values from past sessions. This is particularly handy for Google Assistant services where persistent storage isn’t possible without voice recognition. For further details, refer to \Convo\Core\Workflow\IIntentAwareRequest.

Block-level Variables

• ${failure_count} – Accessible only during the process phase and within the block’s fallback mechanism. It indicates the number of times the fallback mechanism has been activated (due to no processor match). It initializes at 0.
• ${result} – Accessible exclusively in the process phase. Utilized to retrieve the current filter result stored in filter slots. To fetch slot values, employ either ${result.slotName} or ${result[“slotName”]} syntax.

Working with Arrays

In Convoworks, some components return intricate data structures, including arrays and multidimensional arrays, which can be seamlessly incorporated into your workflow. The Expression language facilitates access to these data structures. For instance, to delve into a sub-array, the syntax ${someArray[“field”][“subfield”]} is used.

Moreover, you have the option to define arrays independently, either as service variables or via the Set parameter element. In both scenarios, the setup revolves around key-value pair definitions.

Below are visual representations illustrating two distinct notations for constructing associative arrays using square and curly brackets:

Observably, the curly bracket notation enables the addition of multiple values concurrently. In contrast, the square bracket notation accommodates one value at a time.

An example of creating indexed arrays is presented below:

Notably, indexed arrays are crafted without the use of curly brackets.

Following is a demonstration of creating and populating values into a multidimensional array:

You also have the flexibility to employ pre-existing variables for defining index numbers or establishing array values:

Important Reminder: Avoid blending JUEL notation with the square brackets notation. For example, given an array of user objects, abstain from using the syntax:

• ${users[1].name}

Rather, consistently employ the square bracket expression, like so:

• ${users[1][“name”]}

Utilizing Functions in Convoworks

Convoworks empowers you with a plethora of functions to manipulate and transform data within your expressions. This suite of functions is comprehensive, encompassing both native PHP functions and bespoke ones unique to Convoworks. An exhaustive list of these functions is accessible at the following link: Functions.

Let’s delve into some illustrative examples:

Example 1: Consider a scenario where we utilize PHP’s is_numeric function combined with the IF element:

In this instance, we deploy the NOT operator in tandem with the is_numeric function to determine if a given slot result is non-numeric.

Example 2: This illustration showcases the amalgamation of two custom functions, ordinal and human_concat, within the Text response element:

The Trivia Scores element yields a Status variable that enumerates player names, their respective rankings, and scores. In the depicted usage, this variable is employed to enunciate the rank and monikers of players who have identical scores. Specifically, the ordinal function metamorphoses a cardinal rank number into its corresponding ordinal form. Concurrently, the human_concat function seamlessly transforms an array of names into a cohesive sentence, punctuating the list with the conjunction ‘and’ before the final name.