Conditions & Variables

Introduction
Variables
Session Variables
Call Flow Components
Assign a Variable
Increment Variable
Decrement Variable
Create a Condition
Date & Time Condition
Parallel Execution
Loop
Logger
Exit Callflow
See Αlso

Introduction

During a call flow, we usually need to make decisions and do different things depending on different conditions. For example, if we confirm a customer ID and PIN validity via a database, we may need to transfer the call to a specific call queue and perform an action, else perform another action. Or we may need to let the caller retry entering an ID, iterating a number of times a set of components, e.g. “User Input”, validation, etc. To do this, we need to use variables, loops and conditions. This guide describes the relevant components available.

Variables

Variables are like “boxes” with a name that you can store a value and retrieve it later. You can define variables to use in your project, at different levels:

Project level: variables defined at this level can be used across the project by any callflow, dialer or user-defined component. These are global variables that can be used to share data between project objects, e.g. callflows and user-defined components.
Callflow or Dialer level: these variables are visible within the callflow or dialer, but cannot be seen by any child component.
User-defined component level: these variables can be public or private. Public variables are visible by the parent callflow, dialer or user component, and can be used to set parameters and customize the component behavior. Private variables are only visible internally for the user-defined component.

Variables can be read-only, i.e. can only be assigned the first time during initialization, or read-write, i.e. the value can be changed later during call processing.

Variables are not shared between calls. When the system is processing more than 1 call at a time, each call has its own set of variable instances. A value set in call 1 cannot be seen in call 2, as they are independent.

To create variables, go to the “Project Explorer” panel, select the project, callflow, dialer or component, depending on the variable level you want to use, and then go to the “Properties” panel, which shows the Variables item. Click on the button on the right to open the “Variable Collection Editor” and create as many variables as you need.

When creating a variable you need to define:

Name: this is the name you will use to reference this variable along your app.
Accessibility: use ReadWrite if you need to change the value during your callflow, or set it to ReadOnly if the initial value will never be changed.
Initial Value: this is the value that will be assigned to the variable every time a new call is going to be processed. The value is reset to this value every time the callflow starts.
Help Text: this field can be used to explain the purpose of the variable, and will be shown in the Expression Editor when the variable is listed.

Session Variables

These are the session variables that you can use in your callflow for different purposes:

session.ani
: the number of the caller connected to a CFD app.
session.audioFolder
: the path to the folder where the audio for this app is saved.
session.callid
: the unique ID of this call. Please note that the value cannot be matched to the Call ID present in the CDRs or other parts of the 3CX server.
session.did
: the DID used by the caller to reach 3CX.
session.dnis
: the call flow identifier, i.e. the name you need to dial in order to call this callflow.
session.transferingExtension
: when an extension transfers a call to a CFD app, this variable contains the extension number that transferred the call.

Call Flow Components

The available built-in components related to variable management and call flow path execution, can be configured via the “Properties” panel, or by double-clicking the component to open its configuration dialog. For expression input properties, click on the button on the right of the text box to open the Expression Editor.

Assign a Variable

This component allows assigning a new value to an existing read-write variable. The input properties are the following:

VariableName: The name of the variable must refer to an existing variable, defined at Project scope, callflow or dialer scope or a public property of a component. The “Variable Selector” dialog allows selecting an available variable.
Expression: The value to assign to the variable. The “Expression Editor” dialog allows easily creating complex expressions. The user can choose to use a Constant String, a Variable or an Inbuilt Function. Variables are selected from a list that shows every available read-only and read-write variable in the current scope. For more info on the available functions, see The Expression Editor guide.

Increment Variable

This component allows incrementing an existing numeric read-write variable. Its input properties are:

VariableName: The variable name to increment must refer to an existing variable, defined at Project scope, callflow or dialer scope or a public property of a component. The “Variable Selector” dialog allows selecting an available variable.

Decrement Variable

This component allows decrementing an existing numeric read-write variable. Its input properties are:

VariableName: The variable name decrement must refer to an existing variable, defined at Project scope, callflow or dialer scope or a public property of a component. The “Variable Selector” dialog allows selecting an available variable.

Create a Condition

This component allows selecting a branch for execution when a condition is met.

To add a branch, the user needs to use the “Add Branch” command from the “Properties” panel or the context menu. Each branch has a Condition input property, i.e. an expression that must be evaluated to

true

to execute the branch. Branches are evaluated from left to right, so you can change the evaluation order using the “Move left” and “Move right” commands, shown when a branch is selected.

Only one branch can be possibly executed, i.e. the first with a Condition that evaluates to

true

. The Condition property for the last branch is optional. If it is set, the Condition must be met to execute the branch. If it is not set, the branch is executed when all previous branches did not. If the last branch has a Condition, it is possible that no branch gets executed at all, when every Condition evaluates to

false

Date & Time Condition

This component allows selecting a branch for execution depending on the current date and time, with applicable DID filtering.

To add a branch, the user must execute the “Add Branch” command from the “Properties” panel or the context menu. Each branch has 3 input properties:

DID Filter: allows specifying that this branch is activated only when the call arrives to a specific 3CX DID. You can select:

AllDIDs to allow calls to any DID
AllDIDsWithExceptions to allow calls to any DID, except the ones in the comma-separated list of DIDs
SpecificDIDs to allow calls only to DIDs in the comma-separated list of DIDs

DID Filter List: this is a comma-separated list of DIDs, to be evaluated when “DID Filter” is
AllDIDsWithExceptions
or
SpecificDIDs
. Each DID must be a string, so for example if you want to specify the DIDs 1234567890 and 1234567891, then you need to specify this value to: "1234567890","1234567891"
DateTimeConditions: this is the list of date and time conditions that apply to this branch.

Both, the DID and the date and time conditions must be evaluated to

true

to execute the branch. Branches are evaluated from left to right, so you can change the evaluation order using the “Move left” and “Move right” commands, which are shown when a branch is selected. Only one branch can be possibly executed, i.e. the first with both conditions that evaluate to

true

The list of date and time conditions is configured using the “Date Time Condition Collection Editor”. The editor above shows 2 date and time conditions, but can have as many rows as you need. When 1 row evaluates to true, then the entire date and time condition evaluates to true as well. In the above example screenshot, the branch is executed between 0 and 7, and between 19 and midnight.

The time configured in the “From” and “To” fields is an inclusive range, i.e. to configure a time period between 0 and 7, you need to set it between 0:00 and 6:59.

In this dialog we can specify different date and time conditions:

Day of week: to specify time ranges in specific days of the week, e.g. every Monday.
Specific day: to specify a time range in a specific date, e.g. a particular holiday.
Date range: to specify a time range during a date range, e.g. when an office is closed for a 2-week vacation.
3CX Office Hours: to activate the branch during global office hours.
3CX Out of Office Hours: to activate the branch during global out-of-office hours.
3CX Holidays: to activate the branch during global holidays.

Parallel Execution

This component allows executing many branches at the same time. For example, this component can be used to play a prompt while the app executes a long database query.

To add a branch, the user needs to use the “Add Branch” command from the “Properties” panel or the context menu. Only the first branch can contain call related components, so you can move them to left or right using the “Move left” and “Move right” commands, shown when a branch is selected. All branches are executed at the same time, and the component waits for all of them to finish in order to move to the next component.

💡 Tip: When using the Prompt Playback component in the first branch to play a message while a long operation is executed on other branches, ensure that the Prompt Playback component has the AcceptDtmfInput property set to False. This is because when that property is set to True, the prompt is queued to be played when a DTMF input is required (for example in a Menu component), or when the callflow reaches the end. As a result, the message will not be heard in that case.

Loop

This component allows executing a group of components while a condition is met. The components contained in the “Loop” component are executed from 0 to N times. If the condition is not met the first time, those components are not executed at all. Its input properties are:

Condition: An expression that must evaluate to true to execute the contained components.

Logger

This component writes info to the “3CXCallFlow.log” file. Its input properties are:

Level: the log level, i.e. Trace, Debug, Info, Warn, Error or Critical.
Text: An expression that returns the text to write.

To debug call flow apps via the info written in the “3CXCallFlow.log”, set the log verbosity level to “Medium” or “Verbose” in 3CX “Dashboard” > “Activity Log” > “Settings”:

Off - no messages logged.
Low - log only Error and Critical messages.
Medium - log Info, Error and Critical messages.
Verbose - all messages logged.

Exit Callflow

This component allows exiting the current application, also disconnecting the call. This is the last component that is executed. The “Disconnect Handler” flow is not executed in this case.

See Αlso

Last Updated

This document was last updated 28 November 2023

https://www.3cx.com/docs/manual/cfd-conditions-variables/