Conditions & Variables
On this topic
During a call flow, we usually need to take decisions and do different things depending on different conditions. For example, if a database tells us that a customer ID and PIN are valid, we might need to transfer the call to a specific call queue, and do something else otherwise. Or we might need to let the caller retry entering an ID, iterating a number of times a set of components (User Input, validation, etc.). To do this, we need to use variables, loops and conditions. In this chapter we’ll explain the components available out of the box.
Variables are like “boxes” with a name, in which you can put 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. They are global variables that can be used, for example, to share data between a callflow 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 at the user defined component.
Variables can be read-only (can only be assigned the first time during initialization) or read-write (the value can be changed later during the processing of the call).
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 can’t be seen in call 2, they are independent.
In order to create variables, go to the Project Explorer window, select the project, callflow, dialer or component (depending on the variable level you want to use), and then go to the Properties window, which will show the Variables item. Click on the button on the right to open the Variable Collection Editor.
You can create as many variables as you need.
There are a few session variables that you can use in your callflow for different purposes. These are:
- 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 3CX Call ID. You can use this value to match information in 3CX CDRs.
- session.did: the DID used by the caller to reach 3CX.
- session.dnis: the extension number of the queue where this CFD app is deployed.
- session.queueCallid: a Call ID used by the 3CX Queue Manager service, useful to match log lines for the same call.
- session.transferingExtension: when an extension transfers a call to a CFD app, this variable contains the extension number that transferred the call.
Flow control building blocks
The following are the flow control building blocks available out of the box for your application. You can configure them from the Properties window, or opening the configuration dialog by double clicking the component. When an input property is an expression, 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 variable. The selected variable must be read-write in order to be assigned. The input properties are the following:
- VariableName: The name of the variable. It must be an existing variable defined at Project scope, callflow or dialer scope or a public property of a component. The Variable Selector dialog allows selecting a variable between all the available ones.
- 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 C# Expression, a Variable or an Inbuilt Function, where each parameter is a new expression and can be edited using a new Expression Editor dialog. Variables are selected from a list that shows every available variable in the current scope (read-only and read-write variables). For more details about all the available functions, see The Expression Editor section.
This component allows incrementing an existing numeric variable. The selected variable must have read-write accessibility in order to be incremented. The input properties are the following:
- VariableName: The name of the variable to increment. It must be an existing variable defined at Project scope, callflow or dialer scope or a public property of a component. The Variable Selector dialog allows selecting a variable between all the available ones.
This component allows decrementing an existing numeric variable. The selected variable must have read-write accessibility in order to be decremented. The input properties are the following:
- VariableName: The name of the variable to decrement. It must be an existing variable defined at Project scope, callflow or dialer scope or a public property of a component. The Variable Selector dialog allows selecting a variable between all the available ones.
Create a condition
This component allows selecting a branch for execution when a condition is met.
In order to add a branch, the user must execute the “Add Branch” command from the Properties window or the context menu. Each branch has a Condition input property. That property is an expression that must be evaluated to true in order 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, and it will be the first which has a Condition that evaluates to true. The Condition property for the last branch is optional. If it is set, it must be met in order to execute the branch. If it is not set, the branch is executed when all previous branches didn’t. 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, and also applying DID filters.
In order to add a branch, the user must execute the “Add Branch” command from the Properties window or the context menu. Each branch has 3 input properties:
- DID Filter: allows specifying that this branch will be activated only when the call arrives to 3CX to a specific DID. You can select:
- AllDIDs to allow calls to any DID
- AllDIDsWithExceptions to allow calls to any DID except the ones in the list below (DIDs separated by commas)
- SpecificDIDs to allow calls only to the DIDs in the list below
- DID Filter List: this is a comma separated list of DIDs, which will be considered 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 time conditions that apply to this branch.
Both, the DID and the date and time conditions must be evaluated to true in order 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, and it will be the first which has a both conditions that evaluates to true.
The list of date and time conditions is configured using the Date Time Condition Collection Editor. For example, the following editor shows 2 date and time conditions:
This editor 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. So for example, in the above screenshot, the branch will be executed between 0 and 7, and between 19 and midnight.
The time configured in the From and To fields is included in the range. So in order to configure a time range 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, for example every Monday.
- Specific day: to specify a time range in a specific date, for example a particular holiday.
- Date range: to specify a time range during a date range, for example when an office is closed for 2 weeks for vacations.
- 3CX Office Hours: to activate the branch during global office hours.
- 3CX Out of Office Hours: to activate the branch when we’re out of global office hours.
This component allows executing a group of components while a condition is met. The components contained into 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. The input properties are the following:
- Condition: An expression that must be evaluated to true in order to execute the contained components.
This component allows writing information to the 3CX Queue Manager log file. The input properties are the following:
- Level: the log level (Trace, Info or Error).
- Text: An expression that returns the text to write.
This component allows exiting the current application, also disconnecting the call. This is the last component that will be executed.
- Install the 3CX Call Flow Designer
- Accessing a database from a CFD voice app
- Sending e-mails from a CFD voice app
- How to play a sequence of digits from a 3CX Call Flow Designer voice app
- Creating a Phone Support Portal with the 3CX Call Flow Designer – Part 1, 2, 3, 4
- Routing Calls Based on the Time of Day
- Creating an outbound dialer
- Time-Based Routing without Programming
- Using the Authentication component to validate customers
- Using the Credit Card Component
- Text to Speech with the 3CX Call Flow Designer
- Creating a predictive dialer with the 3CX CFD