The conditional expressions, string manipulation functions, array manipulation functions, and compound datatype values included in SIS macros, triggers, and compositions may use variables — to reference parameters of input or output messages or other values computed during the course of call processing. These include:

Below are overviews of how to use SIS variables, and the different variable types supported by SIS.

Using variables

Note All variables names are case-insensitive. An exception to this rule does apply though, to user variables.

Below are details on basic references, dereferencing, array indexes and functions, and combining referencing mechanisms.

Basic variable references

A basic variable reference consists of a name surrounded by curly braces ({ and }), the opening curly brace prefixed with a dollar sign ($). For example:

${initial-dp.arg.service-key}
${connect.arg.destination-routing-address}
${route.param.orig}

A variable name is composed of one or more name components, delimited by a period (.). Each name component typically represents one step in a hierarchical traversal of object fields or attributes, starting from some well-known root object type. For example:

  • The variable name initial-dp.arg.service-key indicates the Service Key field of the IN InitialDP operation argument.

  • The variable name route.param.orig indicates the orig parameter of the SIP route header.

User variables

User variables always start with the name component user. The SIS considers the rest of the variable name to be an atomic name for the user variable, regardless of whether or not the user variable name includes period (.) delimiters; the notion of a hierarchical namespace within a basic reference to a user variable does not apply. For example:

  • The reference ${user.foo} refers to the user variable named foo

  • The reference ${user.foo.bar} refers to the user variable named foo.bar, not the bar field of the user variable named foo

Tip See the next section on dereferencing for details on how to traverse object fields of user variable values.

Dereferencing variables

The SIS maintains a registry of supported datatypes. This registry records the set of sub-fields each of these datatypes has; for example a CCInitialDPArg has sub-fields for service key, calling party number, called party number, and so on.

The SIS uses this registry to allow a value of any supported datatype to be dereferenced. A dereference is simply using the standard .<field-name}> syntax to indicate an object sub-field, but used outside the basic variable reference rather than inside. Dereferences can be chained one after the other to follow a series of sub-fields in the same way as can be used inside a basic variable reference. The variable references given below illustrate the various ways that the Service Key field of an InitialDP operation could be obtained:

<!-- using a basic reference -->
${initial-dp.arg.service-key}
<!-- using a single dereference -->
${initial-dp.arg}.service-key
<!-- using chained dereferences -->
${initial-dp}.arg.service-key

Dereferencing is most useful when applied to user variables. It’s possible to assign any value to a user variable, then use dereferencing to obtain values for its sub-fields. For example:

<!-- save calling party number from InitialDP -->
<assign toVariable="${user.calling-party-number}" value="${initial-dp.arg.calling-party-number}"/>
<!-- compare calling party number adddress with something -->
<if>
    <equal a="${user.calling-party-number}.address" b="..."/>
    <then> ... </then>
</if>
Warning In the above example, you could not use the basic reference ${user.calling-party-number.address}; this would cause the SIS to look for a user variable with the name calling-party-number.address instead.

Array indexing

If the value of a variable is an array type, the value can be indexed to obtain individual elements of the array. An array is indexed by using square brackets ([ and ]) surrounding an index. An index is either a constant numerical value or a reference to a variable that evaluates to a numerical value. An array index can be used after any array-type variable reference. The following example illustrates a variable reference that can be used to obtain the first element of the Destination Routing Address field of a Connect operation:

${connect.arg.destination-routing-address[0]}

An array index only returns a value if the index evaluates to a value greater than or equal to zero and less than the number of elements in the array.

Array functions

The SIS provides a simple array index function that can be used to find an element of an array that matches a given condition. An array index function is a special type of array index "value", and its presence is denoted by surrounding parentheses: ( and ). The function itself is comprised of a condition of the form <a-value>==<b-value>, where <a-value> and <b-value> are either variable references or literal constants that can be compared. A variable reference used for the <a-value> should not include curly braces (${ and }), and typically would be a dereference of the special variable array.current-element. As the SIS iterates through the elements of the array, the array.current-element variable is assigned each element in turn, and then the array index function evaluated. By dereferencing this variable, each array element can be inspected and compared to some condition, in an attempt to find a matching element.

As a practical example of where this can be used, say we have a Connect operation and we want to find an Additional Calling Party Number from its array of Generic Numbers. We could do this as given below:

<assign toVariable="${user.acgpn}" value="${connect.arg.generic-numbers[(array.current-element.number-qualifier==ADDITIONAL_CALLING_PARTY_NUMBER)]}"/>

The number-qualifier field of a Generic Number is an enumerated type for which ADDITIONAL_CALLING_PARTY_NUMBER is a named value.

Combining referencing mechanisms

Tip

It’s possible to combine the various variable referencing mechanisms (dereferencing, array indexing, and so on) together into a single reference. The following variable references are all equivalent but use different combinations of referencing mechanisms:

${connect.arg.destination-routing-address[0].address}
${connect.arg.destination-routing-address[0]}.address
${connect.arg.destination-routing-address}[0].address
${connect.arg}.destination-routing-address[0].address
${connect}.arg.destination-routing-address[0].address

Variable types

SIS supports these variable types, representing particular Java types:

Variable type Java types 
 STRING

String

 
 INTEGER

int, long, Integer, Long, or BigInteger

 
 DECIMAL

float, double, Float, Double, or BigDecimal

 
 BOOLEAN

boolean or Boolean

 
 BIT_STRING

BitString

 
 NULL

no type, or ASN1Null

Note

Variables with no type are typically used for flag indicators that are either present or absent but have no assignable value. For these variables, the following rules apply:

  • Checking for the presence of the variable or reading the variable value returns a boolean value indicating whether or not the field is present.

  • An assignment requires a boolean value indicating whether of not the field should be present.

Variable with no type can also be used in some cases for mutually exclusive choices where no additional state is necessary for the choice to be selected — such as the none choice of CCConnectToResourceArg.ResourceAddress. For these variables, the following rules apply:

  • Checking for the presence of the variable always returns true.

  • Reading the variable value returns a boolean value indicating whether of not the choice has been selected.

  • An assignment selects the choice. The value passed to the assignment is ignored and therefore can be any non-null value.

Variables with type ASN1Null behave the same as any other variable with a pre-defined type, however ASN1Null is the only value that can be read from or assigned to a variable of this type.

 
 ENUMERATED

a type that extends Enum or NamedInteger

Note Integer values may be assigned to variables of an enumerated type, in which case the enumerated value with the same ordinal is used. Literal string constants, equal to the named values defined in the corresponding Java API (case sensitive), can also be used, in which case the enumerated value with the same name is used.
Named Integers and subclasses

The NamedInteger type is used for extensible enumerated types. Subclasses of the base enumerated type can be used to define additional named values over and above what the base type defines. For example, the CCEventTypeBCSM class defines the common BCSM event types shared by most IN protocols, and CAP4EventTypeBCSM extends this to add some additional named values.

It is plausible that different subclasses of a named integer type could define different ordinal values with the same name. To handle this issue, SIS allows a literal string constant named value used in an expression to be qualified with the (unqualified) class name of the NamedInteger subclass where it is defined. For example:

<if>
    <or>
        <equal a="${event-report-bcsm.arg.event-type-bcsm}" b="oTermSeized"/>
        <equal a="${event-report-bcsm.arg.event-type-bcsm}" b="oAnswer"/>
    </or>
    <then> ... </then>
</if>

and

<if>
    <or>
        <equal a="${event-report-bcsm.arg.event-type-bcsm}" b="CAP4EventTypeBCSM.oTermSeized"/>
        <equal a="${event-report-bcsm.arg.event-type-bcsm}" b="CCEventTypeBCSM.oAnswer"/>
    </or>
    <then> ... </then>
</if>

are equivalent.

 
 COMPOUND

an aggregate of other datatypes

 
 ARRAY

array of some other type

 
 USER

user-defined (may have any Java type)
Previous page Next page