The evaluate Rule allows an expression to be evaluated and different paths to be followed in the Call Flow based on the result of these. The failure outcome will be followed if none of the designated expressions evaluate as true.

For advanced rules about keypad entries or time, please refer to the dedicated pages.

Structure

As you can see in the XML below, the evaluate Rule has the following elements. All of them are required.

  • eventHandlers: This is the element which will contain the set of possible match events in an evaluate rule**.**
    • matchEvent: This is the condition to evaluate against the leftExpValue in the evaluate rule. It has two attributes:
      • action: The type of action we want to perform in the element. At the moment we only have onMatchCondition.
      • rightExprValue: The right side of the expression that will be compared against the leftExpValue using the defined operator.
      • operator: The operator to use in the expresion. Valid values for operator are: EQUALS,LESS THAN,GREATER THAN,NOT EQUALS,STARTS WITH,ENDS WITH,CONTAINS,LENGTH EQUALS, LENGTH LESS THAN, LENGTH GREATER THAN
    • failure: The default outcome to use if none of the matchEvents are triggered i.e. if none of the expressions evaluate to true.

There are three types of expression values:

  • Fixed value: it is a normal string value.
  • internal variables: : values defined during the Call Flow.
  • Internal functions : Built-in functions that return dynamic values. These may be used as values with the leftExpValue or rightExpValue attributes.

Below is an example structure that can be used:

<evaluate leftExprValue="1" id="evaluate_1" label="evaluate"> 
    <eventHandlers>
        <matchEvent action="onMatchCondition" rightExprValue="val_1" operator="opr_1">
            <!-- Rules -->
        </matchEvent>
        <matchEvent action="onMatchCondition" rightExprValue="val_2" operator="opr_2">
            <!-- Rules -->
        </matchEvent>
        <failure id="failure_1" label="Failure">
            <failureMessage>
                <!-- messageParts -->
            </failureMessage>
            <!-- Rules -->
        </failure>
    </eventHandlers>
</evaluate>

Learn more about the messageParts.

A part of these Elements the rule has one attribute which is described below.

Attribute Description Mandatory Default
leftExpValue This will be the expression we will evaluate in the matchEvent elements. YES

Examples

Basic evaluate with a fix value

The first example is just for checking if a fix value is equal to another one. If so (because 1 = 1) this will play a message saying that both values are equal.

<evaluate leftExprValue="1" id="evaluate_1" label="Is equal?">
    <eventHandlers>
        <matchEvent action="onMatchCondition" rightExprValue="1" operator="EQUALS">
            <play id="play_1" label="Play_1">
                <soundFile soundLabel="Values are the same"/>
            </play>
        </matchEvent>
    </eventHandlers>
</evaluate>

Evaluate with multiple match elements

In this example a function will be used (PhoneNumber:getCountryName) to return the country name based on the caller's number (internal variable $_callOrigin). Different outcomes will be matched based on the country of the caller's number.

<evaluate leftExprValue="=phonenumbers:countryOfCaller($_callOrigin)" id="evaluate_1" label="Is equals?">
    <eventHandlers>
        <matchEvent action="onMatchCondition" rightExprValue="SPAIN" operator="EQUALS">
            <play id="play_1" label="SPANISH">
                <soundFile soundLabel="Bienvenido"/>
            </play>
        </matchEvent>
        <matchEvent action="onMatchCondition" rightExprValue="UNITED KINGDOM" operator="EQUALS">
            <play id="play_2" label="ENGLISH">
                <soundFile soundLabel="Welcome"/>
            </play>
        </matchEvent>
        <matchEvent action="onMatchCondition" rightExprValue="FRANCE" operator="EQUALS">
            <play id="play_3" label="FRENCH">
                <soundFile soundLabel="Bienvenu"/>
            </play>
        </matchEvent>
    </eventHandlers>
</evaluate>

Evaluate with multiple match elements and failure

This example is the same as the above example with the addition of a failure message should none of the conditions (defined in matchEvents) evaluate to true. If this is the case "English Welcome Message" will be played to the caller.

<evaluate leftExprValue="PhoneNumber:countryOfCaller($_callOrigin)" id="evaluate_1" label="Is equals?">
    <eventHandlers>
        <matchEvent action="onMatchCondition" rightExprValue="SPAIN" operator="EQUALS">
            <play id="play_1" label="Play_1">
                <soundFile soundLabel="Bienvenido"/>
            </play>
        </matchEvent>
        <matchEvent action="onMatchCondition" rightExprValue="FRANCE" operator="EQUALS">
            <play id="play_2" label="Play_1">
                <soundFile soundLabel="Bienvenu"/>
            </play>
        </matchEvent>
        <failure id="failure_1" label="Failure">
            <failureMessage>
                <soundFile soundLabel="English Welcome Message"/>
            </failureMessage>
        </failure>
    </eventHandlers>
</evaluate>

Evaluate with internal variables

In this example we play the destination a message advising them that the caller has called during the last hour. If the caller hasn't called previously then no message will be played to the destination.

<evaluate leftExprValue="=calls:countCallersCallsToNode(60)" id="evaluate_1" label="Is equals?">
    <eventHandlers>
        <matchEvent action="onMatchCondition" rightExprValue="0" operator="GREATER THAN">
            <play id="play_1" label="Play_1">
                <call id="call_1" label="Call" record="false" sendCallAlert="NONE" destinationPhoneNumber="447723468855" destinationContactName="Bob Plumbers">
                    <callerMessage>
                        <soundFile soundLabel="This Customer has called you before"/>
                    </callerMessage>
                </call>
            </play>
        </matchEvent>
        <failure id="failure_1" label="Failure">
            <call id="call_1" label="Call" record="false" sendCallAlert="NONE" destinationPhoneNumber="447723468855" destinationContactName="Bob Plumbers"/>
        </failure>
    </eventHandlers>
</evaluate>

Error Result

HTTP Code Error String Resolution
400 Rule ID Empty Set the value of the id attribute
400 Rule ID Not Unique in evaluate The value of the id attribute is used for an other rule, change it to be unique
400 Rule Label Empty Set the value of the label attribute
400 Fixed Value Empty The right or the left expression don't have any value
400 Parameter count is wrong A Internal functions is called with a wrong parameter
400 Parameter is wrong type, needs to be NUMBER A Internal functions is called with a wrong parameter, integer is expected
400 Sound File Does not exist in failureMessage contain a without , it need to be added
400 Function X Not allowed in Interface Y Internal functions called with a wrong name, select an existing one
400 Left Expresion Invalid A internal variables is called with a wrong name, select an existing one
400 Right Expresion Invalid A internal variables is called with a wrong name, select an existing one
400 Interface X Not allowed Internal functions called with a wrong name, select an existing one