This document provides an introduction and overview of the Service Interaction SLEE (SIS) — Metaswitch’s script-driven, JAIN SLEE compliant, service-interaction engine. The SIS lets developers script service-logic interactions that can handle any application, network service, or protocol — hosted on Rhino as well as other, more traditional platforms.

Topics

This document includes the following topics:

  • The Case for Service Brokers and Service Interaction explains why operators need service brokers and service-interaction technology.

  • About the SIS provides a high-level introduction to the SIS and its model of service interaction, including benefits, architecture, and key features.

  • SIS Components describes the components that are required in a SIS configuration (compositions, triggers, macros, and expressions).

  • SIS Management introduces the SIS MBeans and tools for managing SIS components.

  • SIP Session Replication describes how SIP session state is replicated to make SIP calls fault tolerant.

  • SIS XML Schema is an appendix with links and descriptions of the SIS XML schema definition files.

Audience

This document is aimed at readers who:

  • have a general, high-level understanding of telecommunications networks and IT systems

  • are familiar with the Metaswitch Rhino platform and SLEE concepts

  • wish to understand how SLEE services can be composed to form new services, and how the SIS achieves this.

Scope

This document’s scope is limited to providing an overview of the SIS concepts. Installation and configuration is covered in the SIS Administration Guide. Writing SIS triggers and service compositions is covered by the SIS Visual Interaction Architect (VIA) User Guide.

The Case for Service Brokers and Service Interaction

On the one hand, operators must run multiple networks (2G, 2.5G, 3G, IMS), and somehow have a unified set of service offerings across these networks for their subscribers.

Operators are under pressure

There are also new networks with new capabilities, such as IMS, to consider and challenges from new entrants with new delivery mechanisms (WiMAX, VOIP, and so on).

On the other hand, many services are becoming ubiquitous (Voice, Prepaid, SMS) and ARPU for these services is under attack. So:

  • How does an operator differentiate itself from its competitors?

  • How does an operator encourage subscriber loyalty?

  • How can an operator protect and increase ARPU?

  • How can an operator achieve all of these things in a volatile economic environment?

The service development and delivery mechanisms of the past are not flexible or powerful enough to provide answers to these questions. A new approach is needed.

A new approach to service development and delivery

Operators need to maximise the return on investment in their existing networks and services, whilst at the same time reducing the barriers to future innovation. They need to embrace new networks and technologies, whilst at the same time minimising the impact on their subscribers of migration to these new networks and technologies.

…​there is a forward-looking imperative brewing. In operator surveys, the need to accelerate time-to-market for new services consistently comes out as a top driver for the acquisition of new service creation and delivery technology.
— LIGHTREADING'S Services Software Insider
Vol 4 No 4

Operators need the ability to make new products by re-using existing products (and/or components of products) and augmenting existing products.

In order to bring new products to market more quickly, operators recognize they need service reuse as part of the mix. Operators are interested in new service creation and delivery architectures that support the assembly of telecom products from re-usable service components.
— LIGHTREADING'S Services Software Insider
Vol 4 No 4
Service brokering and service/feature interaction technology is the answer.

Service brokers allow operators to selectively trigger and run multiple services on a single network trigger. Service brokers blend together services, by managing the signaling interactions between the services in a centralised middleware layer, which sits between the network and the services layer.

The Metaswitch Service Interaction SLEE (SIS) provides service brokering and service interaction functionality for SS7 and IMS networks.

Benefits of Using the SIS

Generally, "service logic" and "interaction logic" are intertwined and together provide services. Most operators run many services (sometimes also referred to as "applications"), hosted on multiple Service Control points (SCPs). With operator consolidation and competitive sourcing of SCPs and services, commonly a single network will use both SCPs and services from several vendors.

Why not use "service chaining"?

To combine these disparate services — and get around the SS7 signaling system limitation of only a single service controlling a call — operators often use "service chaining". This method alters telephone numbers in signaling messages, to make a series of services appear as a single service to the switch.

This works, but puts a great load on core network elements. For simple interactions, the core network must trigger the service layer many times, using numbering plans for feature interaction. For example, for a particular service, the switch would call the service layer (the SCP). By reconfiguring the SCP, when the switch gets a resulting message back, the "dialed number" transfers to another number that prompts a look-up, which sends it back to the SCP again, invoking another service (and so on).

The drawbacks to service chaining include:

  • New application insertion is difficult, because it requires re-configuration and feature modification of core networks and any new SCPs.

  • Operators may have difficulty making changes, because interaction requirements mean SCP application logic is tightly coupled.

  • As you have more and more services, and more and more combinations, the whole thing gets harder and harder to change and maintain.

The benefits of Service Interaction

The SIS takes a different approach, separating and structuring application and interaction logic. Using the Service Interaction (SI) model, you can change interaction logic without changing service logic. The benefits include:

  • higher service re-use — services are not contaminated with interaction logic related to their peer services

  • significantly less customisation — instead of requiring separate modifications for every application a service interacts with, you just need write the service once and then add compositions for new applications

  • vendor participation — each vendors' service logic does not need to tie into the others'

  • more prolific service creation — the market can expect more offerings from new compositions of existing (and new) services

  • faster and more cost-efficient development — composition authors don’t need the same knowledge as SCP application developers.

How the SIS Benefits a SLEE

Unfortunately, the benefits of SI don’t extend to a JSLEE hosting multiple services, unless you combine it with a SIS.

The problem: coordinating multiple services processing multiple events

In a conventional SLEE configuration: A resource adaptor gets a request from the network, converts it into a SLEE event, and then fires that event into the SLEE. The SLEE event router then determines which SLEE services are interested in receiving the event, and then passes that event to those services in priority order.

Typically just one service will process an event, but the SLEE model allows more than one service to process the same event. On the surface this sounds like service interaction, given that it allows many services to process the same event. However there are two big problems:

  • The order of event processing is inflexible, depending only on the services' default-priority values — so different scenarios cannot have different priorities.

  • When processing events, services can easily send network messages or change activity states — potentially making those activities unusable to subsequent services.

For example, one service may decide to disconnect a call. The SLEE has no knowledge of the protocol, and will continue passing the event to subsequent services despite the call being disconnected. The subsequent services then fail (because they cannot use a disconnected call).

The solution: controlled service interaction

The SIS solves such problems by managing service interaction intelligently — by letting services operate independently (without concern for what other services are doing). The SIS does this using a combination of the following techniques:

  • taking over some of the SLEE’s event-routing functions, so it can pass events to configurable sets of services, according to parameters in the request

  • understanding particular network protocols, so it can present each service with a virtual view of real network activity, and control whether or not a service can directly affect that real activity

  • intercepting any operations that services perform affecting activity state, and ensuring that subsequent services see any updated states

  • applying all changes to real network activity, and only sending appropriate protocol-specific messages once all interested services have processed an event.

About the SIS

The Metaswitch Service Interaction SLEE (SIS) provides service brokering and service interaction functionality for both SS7 and IMS networks. The Metaswitch SIS is a very powerful, flexible, and extendable, script-driven service-interaction platform that is part of the Metaswitch Rhino product suite. Metaswitch SIS can be used as standalone middleware, or as an integral part of the Metaswitch Rhino platform.

sis archtecture

The SIS builds on the power of the Rhino platform, so it can support local JAIN SLEE services (acting as an IN SCP or a SIP AS). The SIS can trigger and control both local and external services — and let you combine them into more complex services.

With an Metaswitch SIS, developers can:

  • Script service-logic interactions that can handle any application, network service, or protocol — hosted on Rhino or another platform (such as traditional SCPs)

  • Separate the interaction logic (executed in the SIS) from the service code

  • Combine multiple independent services (including a combination of SCP, SIP AS and Rhino-hosted services) to form new services

  • Manage service interaction by isolating and controlling how services interact.

Note
Support for IN and SIP

The Metaswitch SIS supports different network protocols, including:

  • IN protocols ETSI INAP CS1 and CAPv1 through CAPv4 (voice and SMS)

  • SIP and its 3GPP/IMS extensions.

The Metaswitch SIS builds on the Rhino platform, so local services can use all of the Metaswitch resource APIs available (for example, MAP, Diameter, HTTP, SOAP, SMPP, MM7 and so on).

SIS Architecture

Below are details of the role the SIS plays in the network and a high level and more detailed view of the SIS internal architecture.

Role of the SIS in the network architecture

Current networks can be seen as having two layers:

  • The control layer, which includes signaling elements, such as service switching points (SSP) in SS7 networks and CSCF in IMS networks

  • The services layer, which includes signaling control elements triggered by the network on behalf of subscribers, such as service control points (SCP) in SS7 networks and SIP Application Servers in IMS networks.

SIS layers

The Metaswitch SIS interposes a service-interaction layer between the service and control layers. The Metaswitch SIS controls the sequence of services that it invokes, managing and coordinating the interaction between each service. The output from a service may influence the choice of which service the SIS invokes next.

From the perspective of:

  • the control layer — the SIS looks like one service that is interacting with the network

  • each service — the SIS looks like the control layer

  • the service interaction layer — multiple services are being triggered on one session.

Tip Services may be in external network elements such as an SCP or SIP AS, or be deployed with the Metaswitch SIS (as a JAIN SLEE service).

High level SIS architecture

Below is a diagram followed by descriptions of the SIS subsystems.

sis arch option 4a

Scripting

User-provided scripts control the services that the SIS invokes for each call. The SIS defines a script syntax for compositions, which specify a collection of services and the order in which the SIS should invoke them; and triggers, which specify the service compositions the SIS should select in response to individual network triggers.

The SIS also includes a number of pre-defined service-interaction rules, which dictate how the SIS should handle the different outcomes that a service can generate. Composition scripts can influence the behaviour of many pre-defined rules. TIP: Metaswitch’s Visual Interaction Architect (VIA) is a visual design environment with a graphical interface you can use for building and scripting SIS components (triggers, compositions, and macros).

Service-interaction engine

The service-interaction engine is responsible for:

  • evaluating trigger scripts for each call, to select a service composition

  • evaluating the selected composition script

  • managing the protocol state machines, by invoking services at the appropriate time and processing the outcomes services generate

  • considering how the outcomes a service generates affect other services in the composition.

Services

Without services to invoke, the SIS would have an easy life indeed! Local services, implemented as JAIN SLEE services, reside within the local Rhino SLEE. The SIS uses a virtual view of the call, so it receives outcomes for consideration without directly affecting the actual call in the network. The SIS can also invoke services residing in external SIP ASs or IN SCPs by using new network triggers.

Management

You can manage all facets of the SIS (such as trigger and composition deployment, user subscription provisioning, and other administration tasks) using a standard management interface. You can also monitor the SIS through various statistics that it records and reports using Rhino’s statistics monitoring subsystem. And the SIS includes several pre-defined alarm conditions, such as raising an alarm whenever a connection to the network is lost.

SIS internal architecture in more detail

Below is a diagram followed by descriptions of the SIS internal architecture in more detail.

sis arch option 5

SIS management

You can manage all facets of the SIS (such as trigger and composition deployment, user subscription provisioning, and other administration tasks) using a standard management interface. This interface consists of a collection of JMX MBeans and a command-line tool (sis-console). A SIS extension module for the Rhino Element Manager is also available.

SIS monitoring

To support the critical need to monitor SIS behaviour in real time, administrators can:

  • monitor statistics that the SIS defines, using Rhino statistics-monitoring tools

  • augment SIS-specific alarms with Rhino’s threshold-based alarms

  • enable various kinds of detailed tracing on a per-session basis, for example to monitor particular sessions in fine detail without impacting the performance and responsiveness of the entire platform, or quickly and simply focus attention on specific aspects of SIS behaviour, without sifting through large log files.

  • use a SIS audit capability to run a self check and report any issues with the SIS configuration (such as compositions that reference services that are no longer deployed).

Rhino SLEE

The SIS is built on the Rhino SLEE platform. As such it includes all the capabilities of Rhino — all JAIN SLEE features (for example, the JAIN SLEE resource adaptor architecture) and all Rhino features (such as the statistics client, threshold-based alarms, clustering, and so on). The SIS can run JAIN SLEE services, which can any of the resource adaptors in the Metaswitch portfolio (such as SMPP, HTTP, MAP, SOAP, and so on).

Tip You can use any service that runs in the SIS, using IN or SIP, in a service composition.

Service-interaction customisation

While the SIS scripting language is very flexible, some service-interaction scenarios may require further customisation. For those situations, the SIS provides very powerful Java-based extension capabilities.

Service-composition selection Java API

You can use a service-composition selector extension Java component as part of the service-composition selection process. These components can use all capabilities of the Rhino platform (such as any resource adaptor, JDBC, and so on).

A common use case is to query an operator-specific platform, such as a subscriber database, as a part of the service-composition selection process.

Service-composition extension Java API

The SIS service-composition scripts are very powerful, with features such as conditional branching and the ability to adjust signaling parameters. For maximum flexibility and power, you can use a service composition extension Java component as a part of the execution of a service composition. These components can use all the capabilities of the Rhino platform.

A common use-case is to query to an operator specific platform, such as a subscriber database, and adjust signaling parameters based on the query result.

Tip The SIS scripting language is the preferred approach to defining service-interaction logic for the SIS. Each release of the SIS extends it with more capabilities. In particular, Metaswitch actively identifies use cases where customers often have to resort to using the Java extension mechanisms — and we provide equivalent SIS language-level support.

Service-interaction engine

The service-interaction engine is the core of the SIS, that responds to incoming requests, assigns them to a service composition for processing, and then manages and runs the service composition to completion.

Service composition selection

The service-composition selection function evaluates trigger scripts for each new session that reaches the SIS, and determines which service composition should be run. See The SIS Service-Interaction Model for more detail on this process.

Protocol state machines

The SIS service-interaction engine understands the protocol state machines of a number of protocols. It ensures that the signaling between the SIS and the network, and between the SIS and each triggered service, follows these protocol rules. It also ensures that the results of the services that are triggered will result in appropriate interaction with any other service that is part of the service composition. For example, if a service decides to release a call, the SIS will ensure that the other services that were due to be invoked as a part of the service composition will not be invoked.

The scripting language and the extension capabilities can be used to affect, or override, the protocol rules.

Composition executors

The composition executors are the part of the service interaction engine that runs service compositions. The composition executors run the service-composition scripts, invoke extension Java components, and apply the rules of the protocol state machines. The composition executors also include protocol-specific features for invoking services in external platforms (such as a SIP proxy).

Tip The SIS scripting language includes features for controlling the protocol-specific features. For example, a future release of the SIS IN module will allow a service composition script to specify a range of SCCP addresses for a given external service, with guidelines for how the set of SCCP address should be used (for example, active/standby, or round-robin).

The SIS Service-Interaction Model

The service-interaction model defines how the SIS:

Selecting a service composition

Upon receiving a request from the network, the SIS determines the set of services — called a composition — to handle that request. The composition specifies both the services and the order in which the SLEE will invoke them.

finding a composition

When the SIS receives an initial request, it performs some processing to select which composition to execute. This process of selecting the composition is called triggering. The SIS can be configured with many trigger rules, to specify how it selects which compositions to execute for different types of initial requests.

The SIS evaluates each trigger in order, until it finds one that applies to the incoming request. Each trigger has:

  • a trigger condition, that the SIS can evaluate to determine whether the trigger applies

  • a set of service composition selectors, that the trigger uses to select a service composition from the set of service compositions provisioned in the SIS

  • an optional failure clause, for the SIS to execute if trigger doesn’t select a service composition for processing.

Note Triggers and compositions are specified in XML.
See also Triggers.

Including local and external services

A service composition specifies a particular service-combination scenario. For example, a particular user may require PrePay Charging, VPN, and Call Screening functionality. A composition defines which services can be invoked for a given scenario, and the order in which those services can be invoked. A composition can also include branches, so that certain services are only invoked under particular circumstances.

The services in a composition can be any combination of local SLEE services and external services. In the above example, the VPN and Call Screening services might be implemented in external network nodes, while the PrePay Charging service runs as a local service and interacts with a Diameter online charging system. The SIS treats both local and external services the same when it comes to interaction management, as shown below:

sis arch option 4b

Running a service composition

When invoking services in a composition, the SIS passes the request to each service in turn, then waits for the outcome from the service. Each outcome is protocol-specific — it may be a response generated by the service or a new request, depending on the protocol. Once the SIS receives the outcome, it determines which service in the composition to invoke next, and repeats the process, until all necessary services have been invoked. Finally, the SIS sends a response to the original request back to the network (as appropriate for the protocol).

As part of this process, the SIS isolates the services from each other — as far as each service knows, it is the only one handling the request. The SIS ensures each service gets the request in the right order, and any changes the service makes get to the next service according to the network protocol. For example, if a service adds SIP headers to the request, the SIS ensures they are visible to subsequent services in the composition.

SIS service chains

The following diagram shows a service composition, as a directed, a-cyclic graph of services to execute, with branching points that the SIS evaluates as it processes the initial request:

sis composition chains

The righthand side of the diagram shows all the possible service chains that can result from processing an initial request to completion. A service chain is a subset of services in the composition that the SIS has selected to run for a particular request. Once built, the SIS uses the service chain for all subsequent related requests (for example, the SIS uses the same service chain for all messages on an SS7 dialog).

In this particular example, the service composition includes six services (S a, S b, S c, S d, S e, S f), and two decision points (C 1 and C 2) where a different path through the service composition is possible.

Processing initial and subsequent requests

The SIS treats incoming requests as either:

  • an initial request — a request that creates a new protocol-specific activity, such as the InitialDP request on a new CAP dialog, or an INVITE on a new SIP dialog

  • subsequent requests — requests on already-established activities, such as the CAP EventReportBCSM operation, or a mid-dialog SIP NOTIFY request.

Initial requests

When the initial request fires through each service in the composition, the SIS keeps track of which services are interested in receiving future requests on the activity. How it works depends on the network protocol:

  • The SIS for IN tracks the services that want to monitor a dialog, by inspecting the RequestReportBCSMEvent operations that each service emits.

  • The SIS for SIP looks for services that insert Record-Route headers in a dialog-creating request.

An IN example — processing the initial request

The following diagram is an SS7 example based on the service composition in the bxref:#[executing compositions tab.

process initial event

In this example the SIS has received an originating InitialDP with calling party A and called party B.

  1. The SIS invokes service SCP A. This service processes this InitialDP and directs the call to a different destination (B2). It does not wish to monitor the call further so does not arm any events. The SIS will not involve this service further in the composition.

  2. The SIS then evaluates condition C 1. In this case the result is that the next service to trigger in the composition is SCP B.

  3. The SIS invokes service SCP B. This service processes the InitialDP, arms some events, and sends a Continue

  4. The SIS then evaluates condition C 2. The next service to trigger in the composition is SCP F.

  5. The SIS invokes service SCP F. This service processes the InitialDP, arms some events, and sends a Continue

  6. The SIS finally sends a final result to the network on behalf of the service composition. In this case the SIS arms some events (based on the events armed by SCP B and SCP F and sends a Connect.

Subsequent requests

When a subsequent request arrives, the SIS passes it to those interested services, in the appropriate order for the protocol. So the initial request for an activity determines the path for subsequent requests on that activity.

Continuing the IN example — processing subsequent requests
process subsequent event

The destination party (B2) answers the call. The SIS has received an EventReportBCSM for O-Answer. The only services that remain in the service composition are SCP B and SCP F. The SIS delivers the EventReportBCSM to services in the reverse direction that the InitialDP was processed, as the reported event relates to the destination party. In this case SCP F is invoked before SCP B.

SIS Features

OpenCloud’s SIS includes the following features:

Tip For details about a particular feature, please see the SIS Administration Guide.

Comprehensive service interaction scripting

The Metaswitch SIS is a very powerful, flexible, and extendable, script-driven service-interaction platform. You can write SIS scripts to:

  • Define trigger rules that control how an incoming request is mapped to a service composition that should be used to process it

  • Combine multiple services (including a combination of SCP, SIP AS and Rhino-hosted services) in a service composition — to form new service offerings

  • Manage service interaction to isolate and control how services interact

  • Adjust signaling parameters before, and after services are invoked

Powerful Java APIs for extending the SIS

Whilst the SIS scripting language is very flexible, some service-interaction scenarios may require further customisation. For maximum power and flexibility, you can augmente the SIS via very powerful Java-based extension capabilities and invoke Java extension components from SIS scripts. For example, you can query an operator specific platform, such as a subscriber database, to adjust signaling parameters based on the query result.

The table below compares the relative capabilities of a composition script versus an extension component:

Composition Script Extension Component

Protocol knowledge

Limited to triggering protocol

Can use any protocol available in the SLEE

Signaling parameters that can be modified

Limited to those provided by SIS variables

Any

Access to provisioned data

None

Any arbitrary internal or external data store

Monitor and change signaling parameters

With SIS extension capabilities, you can inspect and modify call-signaling parameters between the time the SIS decides to invoke a particular composition service and when it actually does. You can use this feature, for example, to select a specific external SCP or AS when triggering an external service, and modify call parameters before the trigger message is sent.

Comprehensive operations and management

You can manage the SIS by:

  • Command-line — sis-console, a command-line console, provides access to almost all SIS configuration functions, and all SIS management and provisioning functions. The sis-console is an extension to the Rhino Command-Line Console (rhino-console), so you can manage both Rhino and SIS from the same session.

or

  • Standard management interfaces  — any external client that can manage Rhino can also manage the SIS using interfaces defined as JMX MBeans, registered with the platform MBean server.

Example sis-console session

Below is an example of a sis-console session:

[admin@localhost (#1)] help
Available command categories:

auditing              Manage Rhino's auditing subsystem
bindings              Manage component bindings
config                Import, export, and manage Rhino configuration
deployment            Install, uninstall, and view SLEE deployable units
general               Rhino console help and features
housekeeping          Housekeeping and maintenance functions
license               Install, remove and view Rhino licenses
limiting              Manage Rhino's limiting subsystem
logging               Configure Rhino's internal logging subsystem
namespaces            Manage namespaces
persistence           Configure Rhino's external database persistence subsystem
profile               Manage profiles and profile tables
resources             Manage resource adaptors
sas                   Manage SAS tracing
security              Manage Rhino security
services              Manage services running in the SLEE
sis                   General SIS management operations
sis-address-subscriptionsManage SIS address subscriptions
sis-compositions      Deploy, undeploy, and view SIS compositions
sis-experimental-featuresManage SIS experimental features
sis-extension-refs    Create, remove, view, and manage SIS extension references
sis-interceptor-refs  Create, remove, view, and manage SIS interceptor references
sis-interceptors      Deploy, undeploy, and view SIS interceptors
sis-macros            Deploy, undeploy, and view SIS macros
sis-networkinterfaces Manage SIS network interfaces
sis-service-refs      Create, remove, view, and manage SIS service references and external platform definitions
sis-triggeraddresstracingManage SIS trigger address tracing
sis-triggers          Deploy, undeploy, view and activate SIS triggers
sleestate             Query and manage Rhino SLEE state
snmp                  Manage Rhino SNMP agent configuration
thresholdrules        Manage threshold alarm rules
trace                 View and set SLEE trace levels using the trace MBean
usage                 View SLEE Service usage statistics
usertransaction       Manage client-demarcated transaction boundaries

Enter help <category name | command name substring> for a list of available commands

[admin@localhost (#2)] listtriggers sis-in
TriggerID[name=CheckParameters,vendor=OpenCloud,version=1.0]
TriggerID[name=O-Trigger Handling,vendor=OpenCloud,version=1.0]
TriggerID[name=T-Trigger Handling,vendor=OpenCloud,version=1.0]
TriggerID[name=Generic Failure Handling,vendor=OpenCloud,version=1.0]

[admin@localhost (#3)] activatetrigger sis-in "name=O-Trigger Handling,vendor=OpenCloud,version=1.0"
Activated trigger TriggerID[name=O-Trigger Handling,vendor=OpenCloud,version=1.0]

[admin@localhost (#4)] installcomposition sis-in composition-7000.xml
Installed composition CompositionID[name=7000,vendor=OpenCloud,version=1.0] from file composition-7000.xml

[admin@localhost (#5)] listservices
ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2]
ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]

[admin@localhost (#6)] activateservice "name=Call Barring Service,vendor=OpenCloud,version=0.2"
Activating service ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2] on node(s) [101]
Service transitioned to the Active state on node 101

Online administration

The SIS supports administration and maintenance while actively processing network traffic. SIS components (such as macros, triggers, and service compositions) can be installed, upgraded, and removed from the SIS, subscribers provisioned, and other administration tasks performed all without loss of service. Moreover, you can use an internal audit-management function to validate the SIS configuration (for example, to find any service composition referencing a SLEE service that has not been activated).

Powerful and flexible fine-grained tracing

Debugging service problems experienced by individual subscribers can be difficult at the best of times. The SIS provides a targeted or fine-grained tracing feature that lets you enable various levels of debugging for specific service compositions or subscribed addresses. This means you do not need to enable debug logging for all calls that pass through the SIS — which can can overwhelmingly degrade performance — when you’re only interested in calls to (or with reference to) particular addresses, or that trigger certain compositions. With fine-grained tracing, you can debug isolated problems easily — without affecting the user experience of all other subscribers (whose calls are routed through the platform).

Example fine-grained tracing

Below are example sis-console commands and Rhino log output using fine-grained tracing.

sis-console commands
[admin@localhost (#1)] setfinegrainedtracingenabled sis-in true
Fine-grained tracing enabled

[admin@localhost (#2)] reload sis-in
Reloaded SIS RA Entity sis-in

[admin@localhost (#3)] updateaddresssubscription sis-in 3460001234 -debuglevel 3
Updated subscription 34600001234
Rhino log output
2011-03-20 15:27:51.843  Info   [trace.sis_in.insis.trigger-handler]  [[sis-featuresdialogID=8]]  dialog debugging triggered for [dialogID=8] at debug level 3 due to a subscription profile
2011-03-20 15:27:51.844  Info   [trace.sis_in.insis.trace.flow]    Cap 0  NW   ---------O_InitialDP clg=600001234 cld=610031274---------> INSIS
2011-03-20 15:27:51.902  Info   [trace.sis_in.insis.trace.detail]    Cap 0   NW -> INSIS(event:InitialDP)
    CCInitialDPRequestEvent[
        dialog=CGIN-Dialog:[dialogID=8]
        invokeId=0
        argument=[
            serviceKey 50
            ...
            ]
        ]

2011-03-20 15:27:51.903  Info   [trace.sis_in.insis.trigger-handler]  [[sis-featuresdialogID=8]]  accepting open request
2011-03-20 15:27:51.948  Info   [trace.sis_in.insis.trace.flow]    Cap 0  NW   <-----------------OpenResponse[accepted]------------------ INSIS
2011-03-20 15:27:51.948  Info   [trace.sis_in.insis.trace.detail]    Cap 0   NW <- INSIS(event:OpenRequest)
    DialogOpenAcceptEvent[
        dialog=CGIN-Dialog:[dialogID=8]
        responder=null
        ]

2011-03-20 15:27:51.949  Info   [trace.sis_in.insis.trigger-handler]  [[sis-featuresdialogID=8]]  setState(SERVICE_COMPOSITION_DISCOVERY -> MONITORING)
2011-03-20 15:27:53.075  Info   [trace.sis_in.insis.virtual-ssf]  [[sis-featuresdialogID=8]]  adding events [OpenRequest, InitialDP, Delimiter] to process queue
2011-03-20 15:27:53.076  Info   [trace.sis_in.insis.virtual-ssf]  [[sis-featuresdialogID=8]]  setFlags(INITIAL: [] -> [BUSY_INPUT])
2011-03-20 15:27:53.154  Info   [trace.sis_in.insis.virtual-ssf]  [[sis-featuresdialogID=8]]  beginning event processing of: [OpenRequest, InitialDP, Delimiter]
2011-03-20 15:27:53.154  Info   [trace.sis_in.insis.model]  [[sis-featuresdialogID=8]]  preprocessing [OpenRequest, InitialDP, Delimiter]
2011-03-20 15:27:53.173  Info   [trace.sis_in.insis.model]  [[sis-featuresdialogID=8]]  current call leg state: [1:{COLLECTED_INFO:[]}]
2011-03-20 15:27:53.173  Info   [trace.sis_in.insis.virtual-ssf]  [[sis-featuresdialogID=8]]  setState(INITIAL -> SERVICE_COMPOSITION_EVALUATION: [BUSY_INPUT])
2011-03-20 15:27:53.216  Info   [trace.sis_in.insis.virtual-ssf]   [[sis-featuresdialogID=8]]  service composition says to invoke ServiceRefID[VPN]
2011-03-20 15:27:53.235  Info   [trace.sis_in.insis.virtual-ssf]   [[sis-featuresdialogID=8]]  entering event processing loop for event(s): [OpenRequest, InitialDP, Delimiter]
...

Auditing

The SIS can keep an audit trail of key decisions made during processing of trigger events. You can enable audit logging for specific service compositions or subscribed addresses, or globally for all calls. The SIS outputs audit logs to their own SLEE tracer, so they can be easily filtered to a separate file log.

Example SIS audit log

Note For brevity, the following example truncates trigger event descriptions — actual audit traces include all event parameters.
2011-03-20 15:49:20.543  Info    [trace.sis_in.insis.audit]  [[sis-featuresdialogID=77]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...610012359... eventType=(o) collected info...calledPartyBCDNumber=...610032089...]
    address 34610012359 matched subscription 34610012359
    matched TriggerID\[name=O-Trigger Handling,vendor=OpenCloud,version=1.0]
    selected CompositionID[name=Originating,vendor=OpenCloud,version=1.0]
    invoking service VPN
    invoking service Call Barring
    invoking service Call Duration Logging
    composition completed
2011-03-20 15:49:20.577  Info    [trace.sis_in.insis.audit]  [[sis-featuresdialogID=78]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...610012359... calledPartyNumber=...610032089...eventType=(t) attempt authorized...]
    address 34610032089 matched subscription 34610032089
    matched TriggerID[name=T-Trigger Handling,vendor=OpenCloud,version=1.0]
    selected CompositionID[name=Terminating,vendor=OpenCloud,version=1.0]
    invoking service Call Barring
    evaluating service-input-interceptor
    service-input-interceptor complete; invoking service
    invoking service Call Forwarding
    invoking service Call Duration Logging
    composition completed
2011-03-20 15:49:21.513  Info    [trace.sis_in.insis.audit]  [[sis-featuresdialogID=79]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...620005076... calledPartyNumber=...610032605...eventType=(t) attempt authorized...]
    address 34610032605 matched subscription 34610032605
    matched TriggerID[name=T-Trigger Handling,vendor=OpenCloud,version=1.0]
    selected CompositionID[name=Terminating,vendor=OpenCloud,version=1.0]
    invoking service Call Barring
    evaluating service-input-interceptor
    service-input-interceptor complete; invoking service
    invoking service Call Forwarding
    invoking service Call Duration Logging
    composition completed
2011-03-20 15:49:22.452  Info    [trace.sis_in.insis.audit]  [[sis-featuresdialogID=80]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...610021092... eventType=(o) collected info...calledPartyBCDNumber=...620002308...]
    address 34610021092 matched subscription 34610021092
    matched TriggerID[name=O-Trigger Handling,vendor=OpenCloud,version=1.0]
    selected CompositionID[name=Originating,vendor=OpenCloud,version=1.0]
    invoking service VPN
    invoking service Call Barring
    invoking service Call Duration Logging
    composition completed

SIS Components

You configure the SIS by installing and activating components, which:

  • define macros, triggers, or service compositions

  • are described by XML files

  • are managed like SLEE components (such as SBBs and services) — uniquely identified by a component identifier (consisting of Name, Vendor and Version strings); and controlled using JMX MBean interfaces, a command-line tool, and Ant tasks that perform operations on the MBeans.

  • can include expressions, which compare the properties of network messages to predefined or computed values.

The following topics describe the SIS components, expressions, and provision for user extensions supported by the SIS:

Triggers

Before the SIS can execute a composition, it must first decide which composition to run. Triggers use rules and conditional logic to define how the SIS selects a composition when it receives an initial request. Multiple triggers may be active at the same time, and the SIS will evaluate them sequentially in order of their priority.

The SIS executes the first composition that a trigger successfully returns (using the initial request as input). If evaluating all triggers returns no compositions, the SIS considers the initial request invalid and replies with a failure response.

What’s in a trigger?

A trigger contains the following information:

  • an optional description

  • name, vendor, and version identifiers

  • a priority, which the SIS uses to determine the order in which it evaluates triggers — ranging from 127 (highest) to -128 (lowest)

  • references to any required macros, compositions, or services

  • a condition expression

  • rules for selecting a composition: zero or more selectors and optional terminate clauses.

Evaluating triggers

The following pseudo-code describes how the SIS evaluates triggers when processing an initial request it receives from the network:

Set T = set of all active triggers
while T is not empty
  remove highest priority trigger from T
  if trigger condition evaluates to true
    // process selectors
    for each selector in the trigger
      invoke selector
      if selector returns a valid composition
        return selected composition as trigger result
      endif
      if selector returns a terminate result
        // a Service Composition Selection event returned a "terminate" result
        return terminate result as trigger result
      endif
    endfor

    // process terminate clause
    if selector contains a terminate clause
      return terminate clause as trigger result
    endif
  endif
endwhile

// no active triggers were satisfied
return SIS generic failure result as trigger result
Note
About the generic failure result

The SIS defines the generic failure result as a last-ditch attempt to return a trigger selection result. OpenCloud highly recommends a set of triggers that provide their own failure handling (rather than relying on the SIS generic failure result) — for example, by using a trigger such as the generic failure handler.

The SIS generic failure result for IN is a UserError response with cause "missing customer record", followed by a user abort of the dialog. The SIP generic failure result is to forward the SIP INVITE request externally.

Trigger conditions

Whether the SIS tries to use a trigger depends on its condition:

  • If the condition evaluates to true, the SIS evaluates the selectors and/or failure clause.

  • If the condition evaluates to false, the SIS disregards the trigger (for that initial request).

The following example has a trigger condition that checks for INVITE messages that correspond to originating access. The trigger condition checks to see that the SIP method is INVITE and also checks for the presence of an orig parameter in the Route uri. If the condition is true (<match> in the diagram), then the SIS will execute the trigger body to select a composition. If the condition is not true, then the SIS will move on to the next trigger (<next-trigger> in the diagram).

trigger condition

Trigger syntax schema

The base XML schema sis-trigger-1.6.xsd defines the basic structure of a trigger. SIS variants extend this base schema with protocol-specific properties.

IN Triggers

Triggers for IN protocols may use the XML schema in-sis-trigger-1.6.xsd to extend the generic schema for SIS triggers. The corresponding schema namespaces used by such triggers is shown below:

<trigger xmlns="http://www.opencloud.com/SIS/Trigger"
    xmlns:in="http://www.opencloud.com/SIS/Trigger/IN"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opencloud.com/SIS/Trigger/IN in-sis-trigger-1.6.xsd http://www.opencloud.com/SIS/Trigger sis-trigger-1.6.xsd">

SIP Triggers

Triggers for SIP may use the XML schema sip-sis-trigger-1.6.xsd to extend the generic schema for SIS triggers. The corresponding schema namespaces used by such triggers is shown below:

<trigger xmlns="http://www.opencloud.com/SIS/Trigger"
    xmlns:sip="http://www.opencloud.com/SIS/Trigger/SIP"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opencloud.com/SIS/Trigger/SIP sip-sis-trigger-1.6.xsd http://www.opencloud.com/SIS/Trigger sis-trigger-1.6.xsd">

Sample trigger: IN trigger-event processing

The following trigger processes originating IN initial requests first by normalising the A party numbers, and then by using the normalised values in a profile selection based on address subscription. If that fails, it tries to select a composition using a service key subscription profile. If that too fails, the trigger returns with a User Error failure response that indicates a missing customer record.

IN example: VIA diagram

In this IN example, the SIS will evaluate the trigger body if it’s part of an originating trigger, and the calling party number can be normalised. If the condition applies, it then try to locate a composition:

  1. by searching the address-subscriptions table for the normalised redirecting-party-id

  2. by searching the address-subscriptions table for the normalised calling-party-number

  3. by searching the service-key-subscriptions table for the service-key.

If none of that works, it terminates with a missing customer record user error, recorded in statistics as a failure.

in trigger example

IN example: trigger XML

<trigger xmlns="http://www.opencloud.com/SIS/Trigger"
   xmlns:in="http://www.opencloud.com/SIS/Trigger/IN"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opencloud.com/SIS/Trigger/IN in-sis-trigger-1.6.xsd http://www.opencloud.com/SIS/Trigger sis-trigger-1.6.xsd">

  <description>
    Handle O triggers by looking for a service composition using the
    RedirectingPartyID, CallingPartyNumber, and ServiceKey (in that order)
  </description>

  <trigger-name>O-Trigger Handling</trigger-name>
  <trigger-vendor>OpenCloud</trigger-vendor>
  <trigger-version>1.0</trigger-version>

  <trigger-priority>99</trigger-priority>

  <macro-ref>
    <macro-name>O-Trigger</macro-name>
    <macro-vendor>OpenCloud</macro-vendor>
    <macro-version>1.0</macro-version>
    <macro-alias>O-Trigger</macro-alias>
  </macro-ref>
  <macro-ref>
    <macro-name>Normalise A-Party Numbers</macro-name>
    <macro-vendor>OpenCloud</macro-vendor>
    <macro-version>1.0</macro-version>
    <macro-alias>Normalise A-Party Numbers</macro-alias>
  </macro-ref>

  <on-condition>
    <and>
      <!-- if the IDP is an O trigger ... -->
      <macro-satisfied macro="O-Trigger"/>
      <!-- ...normalise the A party numbers for the profile lookup -->
      <macro-satisfied macro="Normalise A-Party Numbers"/>
    </and>
  </on-condition>

  <!-- ... try selecting on the redirecting party id, then calling party number, then service key ... -->
  <select>
    <profile-lookup scheme="address-subscriptions" key="${user.normalised-rpi}"/>
  </select>
  <select>
    <profile-lookup scheme="address-subscriptions" key="${user.normalised-cgpn}"/>
  </select>
  <select>
    <profile-lookup scheme="service-key-subscriptions" key="${initial-dp.arg.service-key}"/>
  </select>

  <!-- if none of that worked, fail with a missing customer record user error -->
  <in:terminate record-as-reject="true">
    <in:user-error reason="missing-customer-record" dialog-termination="user-abort"/>
  </in:terminate>
</trigger>

Sample trigger: SIP trigger-event processing

The following trigger matches initial SIP INVITE requests that have the "orig" (originating) parameter set in the Route header. If a request matches, the trigger uses the From header’s URI to select the composition. If the trigger does not find a matching composition, it returns a 404 error response to the client.

SIP example: VIA diagram

In this SIP example, the SIS will evaluate the trigger body if it has received an originating INVITE request. If the condition applies, it tries to locate a composition by searching the originating-address table for the From header’s URI. If that does not work, it fails with a SIP 404 error response.

sip trigger example

SIP example: trigger XML

<trigger xmlns="http://www.opencloud.com/SIS/Trigger"
   xmlns:sip="http://www.opencloud.com/SIS/Trigger/SIP"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opencloud.com/SIS/Trigger/SIP sip-sis-trigger-1.6.xsd http://www.opencloud.com/SIS/Trigger sis-trigger-1.6.xsd">

  <description>
    Runs the originating composition if an originating INVITE request is received.
  </description>

  <trigger-name>Originating</trigger-name>
  <trigger-vendor>OpenCloud</trigger-vendor>
  <trigger-version>1.0</trigger-version>

  <trigger-priority>20</trigger-priority>

  <!-- Trigger on INVITE request with "orig" Route header parameter. -->
  <on-condition>
    <and>
      <equal a="${method}" b="INVITE"/>
      <present variable="${route.param.orig}"/>
    </and>
  </on-condition>

  <select>
    <!-- SIS will lookup the subscriber address in its subscription profiles, and select the originating composition, if available -->
    <profile-lookup scheme="originating-address" key="${from.uri}"/>
  </select>

  <sip:terminate>
    <sip:reject status-code="404"/>
  </sip:terminate>
</trigger>

Sample trigger: generic failure handler

The following trigger illustrates a user-defined generic failure handler for IN. This trigger has the lowest possible priority and a condition that always evaluates to true. If ever evaluated, this trigger causes a User Error with cause unexpected data value returned as the trigger result.

Sample generic failure handler: VIA diagram

in trigger gen failure handler

Sample generic failure handler: trigger XML

<trigger xmlns="http://www.opencloud.com/SIS/Trigger"
   xmlns:in="http://www.opencloud.com/SIS/Trigger/IN"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opencloud.com/SIS/Trigger/IN in-sis-trigger-1.6.xsd http://www.opencloud.com/SIS/Trigger sis-trigger-1.6.xsd">

  <description>Generic catch-all failure handler</description>

  <trigger-name>IN Generic Failure Handler</trigger-name>
  <trigger-vendor>OpenCloud</trigger-vendor>
  <trigger-version>1.0</trigger-version>

  <trigger-priority>-128</trigger-priority>

  <on-condition>
    <true/>
  </on-condition>

  <in:terminate record-as-reject="true">
    <in:user-error reason="unexpected-data-value" dialog-termination="user-abort"/>
  </in:terminate>
</trigger>

Composition Selection

A SIS trigger may contain zero or more selectors, which the SIS evaluates only if the trigger condition evaluates to true. The SIS evaluates the selectors in the order they are declared in the trigger, until one of them finds a valid composition (or an extension component returns a terminate result instead). Below are descriptions of how selectors look for valid compositions by constant value, profile table lookup or extension component.

Constant value

A selector may search for a valid composition using a constant value. In this case, the trigger references and aliases the identity of the composition for the SIS to execute, and the selector’s <composition-alias-ref> element uses that alias name. For example:

VIA notation Script XML
select by name
<trigger ...>
  <trigger-name>...</trigger-name>
  <trigger-vendor>...</trigger-vendor>
  <trigger-version>...</trigger-version>
  <trigger-priority>...</trigger-priority>

  <composition-ref>
    <composition-name>O-Trigger Handling</composition-name>
    <composition-vendor>OpenCloud</composition-vendor>
    <composition-version>1.0</composition-version>
    <composition-alias>O-Trigger</composition-alias>
  </composition-ref>

  <on-condition>...</on-condition>

  <select>
    <composition-alias-ref>O-Trigger</composition-alias-ref>
  </select>
  ...
</trigger>
Warning When the SIS invokes the selector, if the SIS cannot find the composition, the selector fails and the SIS continues rule processing as if the selector did not exist.

Profile table lookup

A profile-lookup selector requests that the SIS search profiles for the identity of a composition for the SIS to execute. These selectors specify a scheme that tells the SIS which profile table contains the profiles to search, and a key that identifies which variable’s value to use to index the profile table.

The SIS performs the following searches for address or service key subscriptions:

Protocol Scheme Searches Key If found…​

IN

 address-subscriptions

address subscriptions

string variable (assumed to be a subscribable address)

…​gets from that profile the component identifier of the relevant composition provisioned for the subscription (originating, terminating, or third-party call, depending on the trigger type).

IN

 service-key-subscriptions

service key subscriptions

integer variable

SIP

 originating-address

address subscriptions

string variable (assumed to be a subscribable address)

…​returns origination composition from that subscription

SIP

 terminating-address

address subscriptions

string variable (assumed to be a subscribable address)

…​returns terminating composition from that subscription

The selector succeeds if:

  • a subscription profile is found

  • a relevant composition is provisioned

  • that composition exists.

The selector fails if:

  • the SIS cannot find a subscription profile with the specified scheme and key

  • the SIS finds a subscription profile, but without a composition provisioned for the relevant trigger type (originating, terminating, or third-party call)

  • the SIS finds a subscription profile with a composition provisioned for the trigger type, but that composition does not exist.

If the selector fails, the SIS continues rule processing as if the selector did not exist.

For example:

VIA notation Script XML
select by lookup
<trigger ...>
  <trigger-name>...</trigger-name>
  <trigger-vendor>...</trigger-vendor>
  <trigger-version>...</trigger-version>
  <trigger-priority>...</trigger-priority>

  <on-condition>...</on-condition>

  <select>
    <profile-lookup scheme="originating-address" key="${from.uri}"/>
  </select>
</trigger>

Extension component

You can invoke an extension component for a composition-selection process more complex than predefined selectors can describe. For example, you might need to interrogate an external subscription database or analyse particular initial request parameters to determine which composition to select.

In this case, the trigger references a extension component of type SCS that has previously been defined in the SIS. For example:

VIA notation Script XML
select by extension
<trigger ...>
  <trigger-name>...</trigger-name>
  <trigger-vendor>...</trigger-vendor>
  <trigger-version>...</trigger-version>
  <trigger-priority>...</trigger-priority>

  <on-condition>...</on-condition>

  <select>
    <extension>Select-via-ldap-lookup</extension>
  </select>
</trigger>

If the extension component does not respond to the selection request within a predefined (configurable) timeout period, or the extension component returns the identity of a composition that does not exist, the SIS assumes the selector failed to find a composition, and continues evaluating any remaining triggers, following the algorithm described in Triggers.

If the extension component returns an error response, trigger processing is aborted immediately with the specified error being returned to the network to terminate call handling, as if a terminate clause had been executed.

Tip Read more about SIS extensions here.

Terminate Clauses

A terminate clause says what to do if no selector in a trigger succeeds in finding a valid composition.

When the SIS encounters a terminate clause it will stop further trigger evaluation, and may send a protocol-specific message to the network to terminate call handling. The base XML schema for triggers defines the simplest terminate clause, the empty <terminate> element. If the SIS encounters this terminate clause, it will perform its default termination action.

For IN, the terminate clause defines whether the termination should be recorded in statistics as a success or failure outcome. Where appropriate, the terminate clause also defines how the SIS terminates the dialog with the dialog-termination parameter. Valid values for this parameter are:

  • none — The SIS will not terminate the dialog

  • close — The SIS sends the response within a TC_END (with basic end)

  • user-abort — The SIS sends the response within a TC_CONTINUE then tears down the dialog with a TC_U_ABORT.

The default terminate action is to respond with a User Error with error code missing-customer-record, and to abort the dialog. This is recorded in statistics as a failure outcome.

For SIP, the default termination action is to send a Forward response, to forward the request to the next hop.

Terminate clauses for IN

The following terminate clauses may be used in an SIS IN trigger definition: User Error, Continue, Release, Connect, ConnectSMS, Redirect, Relay, No Response.

User Error

Description

A User Error response. The error response code may be unexpected-data-value, missing-parameter, or missing-customer-record.

Example: XML

<in:terminate record-as-reject="true">
    <in:user-error reason="missing-customer-record" dialog-termination="user-abort"/>
</in:terminate>

Example: VIA

missing cust record

Continue

Description

A Continue or ContinueSMS response. The SIS resumes the dialog state model and the call or SMS continues in the network using default call handling.

Example: XML

<in:terminate record-as-reject="false">
    <in:continue dialog-termination="close"/>
</in:terminate>

Example: VIA

continue close

Release

Description

A ReleaseCall or ReleaseSMS response. The SIS releases the call or SMS, with the specified cause code.

Example: XML

<in:terminate record-as-reject="true">
    <in:release cause-code="31" dialog-termination="close"/>
</in:terminate>

Example: VIA

release

Connect

Description

A Connect response. The SIS redirects the call to the specified destination routing address, described by an XML <called-party-number> element as specified in [1 Pre-defined Datatypes]. This termination response can only be used with initial triggers on call control dialogs.

Example: XML

<in:terminate record-as-reject="false">
    <in:connect dialog-termination="close">
            <called-party-number
                  nature="NATIONAL"
                  routing-to-internal-network-number="ALLOWED"
                  numbering-plan="ISDN"
                  address="123456789"/>
    </in:connect>
</in:terminate>

Example: VIA

connect

ConnectSMS

Description

A ConnectSMS response. The SIS redirects the SMS to the specified destination subscriber number, described by an XML <called-party-bcd-number> element as specified in [1 Pre-defined Datatypes]. This failure response can only be used with initial triggers on CAPv3 or CAPv4 SMS dialogs.

Example: XML

<in:terminate record-as-reject="false">
    <in:connect-sms dialog-termination="close">
        <called-party-bcd-number
            number-type="NATIONAL"
            numbering-plan="ISDN"
            address="987654321"/>
    </in:connect-sms>
</in:terminate>

Example: VIA

connectsms

Redirect

Description

A Connect or ConnectSMS response. The SIS uses its configured redirect behaviour to redirect the call by issuing a Connect or ConnectSMS with the redirect prefix (from either a specified constant value or a variable) in the destination routing address or destination subscriber number.

Example: XML

<in:terminate record-as-reject="false">
    <in:redirect
        idd-prefix="00"
        country-code="44"
        redirect-prefix="9876"
        dialog-termination="close"/>
</in:terminate>

Example: VIA

in redirect

Relay

Description

A Relay response. A dialog is opened towards the target external platform and the initial request is relayed to it, after which the incoming and relayed dialogs are terminated locally. Further communication on the dialog continues directly between the dialog originator and the external platform. A nested terminate clause must be specified for this option, which is invoked in the event the relay fails (for example, if an outgoing dialog cannot be created, or a TC_CONTINUE has already been sent on the incoming dialog).

Example: XML

<in:terminate record-as-reject="false">
    <in:relay target="some-relay-target">
        <in:on-failure record-as-reject="true">
            <in:release cause-code="31" dialog-termination="close"/>
    </in:on-failure>
    </in:relay>
</in:terminate>

Example: VIA

in relay

No Response

Description

No response is sent. The value of the dialog-termination attribute determines what the SIS will do with the dialog.

Example: XML

<in:terminate record-as-reject="true">
    <in:no-response dialog-termination="user-abort"/>
</in:terminate>

Example: VIA

in no response

Terminate clauses for SIP

The following terminate clauses may be used in an SIS SIP trigger definition: Reject, Forward.

Reject

Description

A Reject response. A reject status code must be specified (in the range 300-699), along with an optional reason phrase. Any number of additional headers may also be included in the response.

Example: XML

<sip:terminate>
    <sip:reject status-code="503" reason-phrase="Service not available">
          <sip:header name="..." value="..."/>
    </sip:reject>
</sip:terminate>

Example: VIA

sip reject

Forward

Description

A Forward response. An optional target URI may be specified. Any number of additional headers may also be included in the response.

Example: XML

<sip:terminate>
    <sip:forward uri="...">
        <sip:header name="..." value="..."/>
    </sip:forward>
</sip:terminate>

Example: VIA

sip forward

Compositions

The main job of the SIS is to evaluate compositions, to control invoking services.

Composition components specify which services to invoke, when. They may include conditional logic, to invoke different services depending on parameters in the request, or the outcome of earlier services in the composition.

Note
What’s in a composition?

A composition contains the following information:

  • an optional description

  • references to any macros the composition requires

  • a script that specifies the services to invoke

  • optional interceptors that can modify signaling parameters in service input or output messages

  • configuration options that can modify SIS behaviour when the composition runs.

Warning Care should be taken to make sure compositions invoke services in a sensible order. For example, services that perform some form of authorization would typically run before the others.
Tip Management operations on the SIS define the services that compositions can use.
See the SIS Administration Guide for more information.

Below is a sample composition, and a description of schema syntax.

Sample composition

The example below shows a simple composition that invokes two services. Its main elements are: composition-name/vendor/version, which defines this composition’s component identity; service-ref, which declares the services that this composition requires; and script, which specifies how to invoke those services.

VIA Diagram Script
simple
Note

When the SIS evaluates this composition, it will:

  • invoke the VPN service

  • wait for the outcome

  • then invoke the Prepay service.

Composition schema syntax

The base XML schema sis-composition-1.8.xsd defines the basic structure of a composition. SIS variants extend this base schema with protocol-specific properties.

IN compositions

Compositions for IN protocols may use the XML schema in-sis-composition-1.8.xsd to extend the generic schema for SIS compositions. IN compositions use the following corresponding schema namespaces:

<composition xmlns="http://www.opencloud.com/SIS/Composition"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:in="http://www.opencloud.com/SIS/Composition/IN"
    xsi:schemaLocation="http://www.opencloud.com/SIS/Composition/IN in-sis-composition-1.8.xsd http://www.opencloud.com/SIS/Composition sis-composition-1.8.xsd">

SIP compositions

Compositions for SIP may use the XML schema sip-sis-composition-1.8.xsd to extend the generic schema for SIS compositions. SIP compositions use the following corresponding schema namespaces:

<composition xmlns="http://www.opencloud.com/SIS/Composition"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:sip="http://www.opencloud.com/SIS/Composition/SIP"
      xsi:schemaLocation="http://www.opencloud.com/SIS/Composition/SIP sip-sis-composition-1.8.xsd http://www.opencloud.com/SIS/Composition sis-composition-1.8.xsd">

Composition Scripts

SIS administrators write a composition script for each combination of services that is appropriate for their network.

A composition script is a set of script statements that the SIS evaluates in the order they appear in the script.

Composition scripts may include the following statements:

  • invoke — to invoke a service

  • parallel — to invoke a number of services in parallel

  • if — to control whether a set of script statements should be executed based on a condition (branching)

  • assign — to assign values to variables

  • delete — to delete values from variables

  • halt — to halt a composition.

Tip Some statements may be nested. For example the body of an if statement may include other if statements.

invoke (composition script)

A composition service is invoked using an <invoke> element.

Below are possible attributes and child elements for an <invoke> element, plus an example script and diagram:

Example

The following script invokes composition services using the <invoke> element with different options. The first service (VPN) will use a timeout value of 1500 ms; the second service (HomeZone) will use all the defaults; and the last service (PrePay) is so important that if it times out, the processing of the service composition will be terminated.

VIA diagram

invoke options

Script XML

<script>
 <invoke service="VPN" timeout="1500"/> <invoke service="HomeZone"/> <invoke service="Prepay" on-timeout="terminate-processing"/>
</script>

Attributes and child elements

Below are possible attributes and child elements for an <invoke> element

Attributes

Name Description Optional?
 service

The service to be invoked. Must refer to a service defined in the SIS (using a service reference).

 timeout

Specifies the timeout period, measured in milliseconds, that the SIS will wait for a response from the service when required. If present, this timeout overrides the default timeout configured for the service.

 on-timeout

Specifies the behaviour the SIS will take if a service response timeout (or other service failure) occurs at any time for the invoked service. The supported values for this attribute are:

  • ignore-service-and-continue — remove the service from further interaction with the composition and continue delivery of any current event to the next service

  • terminate-processing — terminate processing of the current event; if no terminate child element is specified then, if relevant, the SIS will send a response to the network based on event processing thus far, otherwise the SIS will take the action specified by the terminate element.

Warning The behaviour of the terminate-processing action with no terminate child element changed between SIS 2.4.0 and SIS 2.5.0. Please refer to the change log included in the distribution package for information on the previous behaviour and how that behaviour can be specified in the composition.

The default value if this attribute is not specified is ignore-service-and-continue.

Child elements

Name Description Optional?
 service-input-interceptor

A service input interceptor. The SIS evaluates this input interceptor before it delivers any event to the service.

 service-output-interceptor

A service output interceptor. The SIS evaluates this output interceptor whenever the service generates output intended for the network.

 terminate

This element can only be specified if the on-timeout attribute is set to terminate-processing. It specifies a terminate clause that the SIS will use to send a response for the current event.

 message-handling-options

This element specifies configurable options for how the SIS manages specific messages received from the service.

 extension-options

Specifies arbitrary extension options supported by the SIS for service invocation. This is a collection of extension-option elements each with a name and optional value. See the extension options currently supported for <invoke> elements.

Extension options supported by <invoke> elements
Option Description Required Value
 SIP:traffic-reduce

This option can be used if you want to invoke a SIP service, but want to reduce the amount of SIP traffic to that service by only passing it the initial request, then excluding it from the call.

When this option is present, the SIS invokes the service by sending it the initial request. When the service forwards the request, the SIS sends an error response (default: 500) to the service so that it will no longer take part in the call. The request forwarded by the service continues with the remainder of the composition. Responses to the initial request and subsequent requests in the call will not be passed to the service.

The extension-option element may include a <reject> element as seen in terminate clauses for SIP. If present, the status code, reason phrase and headers in the <reject> element will be included in the error response passed to the service. For example, to generate a custom 599 response:

<invoke service="MyService">
  <extension-options>
    <extension-option name="SIP:traffic-reduce">
      <sip:reject status-code="599" reason-phrase="Traffic Reduce">
        <sip:header name="Reason" value="SIP;cause=599;text=&quot;Traffic Reduce&quot;"/>
      </sip:reject>
    </extension-option>
  </extension-options>
</invoke>

n/a

 IN:accept-non-continuing-close

Typically, if the SIS is expecting a response from an IN service and that service just closes the dialog to the SIS without first providing a response, the SIS will regard this as an error condition. However if this extension option is specified, the SIS will instead behave as if the service provided a Continue response before the dialog was closed.

n/a

 IN:proxied-invoke-timer-long

When an operation invoke is sent by an external IN service to the SIS, the timeout period specified for the invoke is not included in the wire protocol message that the SIS receives. When the SIS forwards an operation invoke from an external service to the network, it needs to specify its own invoke timeout period for that operation. The default invoke timeout configured for the SIS or service is adequate for most operations; however operations with "long" timers (Play Announcement, Prompt and Collect User Information) may need longer timeout periods for correct operation. This extension option allows a longer default timeout period to be specified for the service for these long timer operations.

A long integer value greater than or equal to zero specified in millisecond units.

 ECS1:allow-camel-style-apply-charging

The Ericsson INAP CS1 specification states that an Apply Charging request may only be sent by a service if the BCSM is suspended at a detection point. However an operator customisation exists that allows Apply Charging requests to be sent while the BCSM is in any valid state, the same as in CAMEL protocols. This extension option allows the CAMEL behaviour for Apply Charging to be supported for Ericsson INAP protocol dialogs (both CS1 and CS1+).

n/a

Message Handling Options

The SIS has certain default behaviours that it performs when handling messages received from a composition service. Message handling options can be used to alter the default behaviours for specific message types.

Message handling options are specified using the <message-handle-options> element within an or element.

How messaged handling options work

Below is an example of how you might use message handling options:

<invoke service="...">
    <message-handling-options>
        <message-handling-option .../>
        <message-handling-option .../>
        <message-handling-option .../>
    </message-handling-options>
</invoke>

Any number of valid message handling options can be specified for a service or parallel block. The base XML schema for message handling options defines the simplest option, the empty <message-failure-option> element. This option by itself has no effect on the SIS.

For IN, message handling options specify up to three attributes:

Attribute Name Required? Description
 on-message

A message type.

 action

The action to perform if a message of the given type is encountered.

 is-failure

Relevant only for message types that could be considered a service error or failure.

For certain actions, a <terminate> child element may also be included with the <message-handling-option> element. It specifies a terminate clause that the SIS will use to send a response for the current event.

Open Refuse

This option specifies the behaviour of the SIS when it receives an Open Refuse response from a service. The default behaviour, if this option is undeclared, is equivalent to:

<in:message-handling-option on-message="open-refuse" action="ignore-service-and-continue" is-failure="true"/>
Action Failure? Description and example
 ignore-service-and-continue
 true

Initial request service failure handling behaviour is first invoked. For external services this may mean a standby external address is contacted. Assuming a local service, no standby, or the standby also refuses the dialog, service failure statistics are recorded, the service is removed from the composition, and composition evaluation continues for the initial request.

<in:message-handling-option
    on-message="open-refuse"
    action="ignore-service-and-continue"
    is-failure="true"/>
 false

No initial request service failure handling behaviour is invoked, and no service failure statistics are recorded. The service is simply removed from the composition, and composition evaluation continues for the initial request.

<in:message-handling-option
    on-message="open-refuse"
    action="ignore-service-and-continue"
    is-failure="false"/>
 terminate-processing
 true

Processing of the initial request is terminated and service failure statistics are recorded. If no terminate child element is specified then the SIS will send a response for the initial request to the network based on the services that have been successfully invoked thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="open-refuse"
      action="terminate-processing"
      is-failure="true">
    <in:terminate record-as-reject="true">
      <in:release cause-code="21" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>
 false

Processing of the initial request is terminated. No service failure statistics are recorded. If no terminate child element is specified then the SIS will send a response for the initial request to the network based on the services that have been successfully invoked thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="open-refuse"
      action="terminate-processing"
      is-failure="false">
    <in:terminate record-as-reject="true">
      <in:release cause-code="21" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>

User Abort

This option specifies the behaviour of the SIS when it receives a User Abort from a service. The default behaviour, if this option is undeclared, is equivalent to:

<in:message-handling-option on-message="user-abort" action="propagate" is-failure="true"/>
Warning If a service receives an Open Request and responds with a User Abort on that dialog before sending any Delimiter, that User Abort will be handled according to the behaviour defined for Open Refuse.
Action Failure? Description and example
 ignore-service-and-continue
 true

Service failure handling behaviour is first invoked. For external services this may mean a standby external address is contacted if the initial request is still being processed. Assuming a local service, no standby, the standby also aborts the dialog, or the standby cannot be invoked given the current call state, service failure statistics are recorded, the service is removed from the composition, and processing of any current event continues.

<in:message-handling-option
    on-message="user-abort"
    action="ignore-service-and-continue"
    is-failure="true"/>
 false

No service failure handling behaviour is invoked, and no service failure statistics are recorded. The service is simply removed from the composition, and processing of any current event continues.

<in:message-handling-option
    on-message="user-abort"
    action="ignore-service-and-continue"
    is-failure="false"/>
 terminate-processing
 true

Processing of any current event is terminated and service failure statistics are recorded. If no terminate child element is specified then, if relevant, the SIS will send a response for the current event to the network based on event processing thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="user-abort"
      action="terminate-processing"
      is-failure="true">
    <in:terminate record-as-reject="true">
      <in:release cause-code="41" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>
 false

Processing of any current event is terminated. No service failure statistics are recorded. If no terminate child element is specified then, if relevant, the SIS will send a response for the current event to the network based on event processing thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="user-abort"
      action="terminate-processing"
      is-failure="false">
    <in:terminate record-as-reject="true">
      <in:release cause-code="41" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>
 propagate
 true

The user abort is propagated towards the network dialog. Handling of the user abort moves to the next outer level in the SIS; for example, a user abort propagated from an <invoke> within a <parallel> block moves the handling of that abort to the parallel block. If already at the outermost level, the user abort is sent on the network dialog itself. Processing of any current event is terminated and service failure statistics are recorded. Composition services at the same level as the service sending the user abort will be terminated with a user abort.

<in:message-handling-option
    on-message="user-abort"
    action="propagate"
    is-failure="true"/>
</in:message-handling-option>
 false

The user abort is propagated towards the network dialog. Handling of the user abort moves to the next outer level in the SIS; for example, a user abort propagated from an <invoke> within a <parallel> block moves the handling of that abort to the parallel block. If already at the outermost level, the user abort is sent on the network dialog itself. Processing of any current event is terminated. No service failure statistics are recorded. Composition services at the same level as the service sending the user abort will be terminated with a user abort.

<in:message-handling-option
    on-message="user-abort"
    action="propagate"
    is-failure="false"/>
</in:message-handling-option>

Interrupted Event Error

This option specifies the behaviour of the SIS when it receives a User Error response from a service for an event delivered to the service in Interrupted mode — that is, an event such as the initial request, that suspends further call state processing until the service provides a suitable response. The default behaviour, if this option is undeclared, is equivalent to:

<in:message-handling-option on-message="interrupted-event-error" action="propagate" is-failure="true"/>
Action Failure? Description and Example
 ignore-service-and-continue
 true

Service failure handling behaviour is first invoked. For external services this may mean a standby external address is contacted if the initial request is still being processed. Assuming a local service, no standby, the standby also aborts the dialog, or the standby cannot be invoked given the current call state, service failure statistics are recorded, the service is removed from the composition, and processing of any current event continues.

<in:message-handling-option
    on-message="interrupted-event-error"
    action="ignore-service-and-continue"
    is-failure="true"/>
 false

No service failure handling behaviour is invoked, and no service failure statistics are recorded. The service is simply removed from the composition, and processing of any current event continues.

<in:message-handling-option
    on-message="interrupted-event-error"
    action="ignore-service-and-continue"
    is-failure="false"/>
 terminate-processing
 true

Processing of any current event is terminated and service failure statistics are recorded. If no terminate child element is specified then the SIS will send a response for the current event to the network based on event processing thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="interrupted-event-error"
      action="terminate-processing"
      is-failure="true">
    <in:terminate record-as-reject="true">
      <in:release cause-code="41" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>
 false

Processing of any current event is terminated. No service failure statistics are recorded. If no terminate child element is specified then the SIS will send a response for the current event to the network based on event processing thus far, otherwise the SIS will take the action indicated by the terminate element.

<in:message-handling-option
      on-message="interrupted-event-error"
      action="terminate-processing"
      is-failure="false">
    <in:terminate record-as-reject="true">
      <in:release cause-code="41" dialog-termination="close"/>
    </in:terminate>
</in:message-handling-option>
 propagate
 true

The user error is propagated towards the network dialog. Handling of the user error moves to the next outer level in the SIS; for example, a user error propagated from an <invoke> within a <parallel> block moves the handling of that error to the parallel block. If already at the outermost level, the user error is sent on the network dialog itself and the dialog is closed. Processing of any current event is terminated and service failure statistics are recorded. Composition services at the same level as the service sending the user error will be terminated.

<in:message-handling-option
    on-message="interrupted-event-error"
    action="propagate"
    is-failure="true"/>
</in:message-handling-option>
 false

The user error is propagated towards the network dialog. Handling of the user error moves to the next outer level in the SIS; for example, a user error propagated from an <invoke> within a <parallel> block moves the handling of that error to the parallel block. If already at the outermost level, the user error is sent on the network dialog itself and the dialog is closed. Processing of any current event is terminated. No service failure statistics are recorded. Composition services at the same level as the service sending the user error will be terminated.

<in:message-handling-option
    on-message="interrupted-event-error"
    action="propagate"
    is-failure="false"/>
</in:message-handling-option>

O-Trigger Connect

This option specifies the behaviour of the SIS when it receives a valid Connect response from a service while executing the originating call state model for the call. The default behaviour, if this option is undeclared, is equivalent to:

<in:message-handling-option on-message="o-trigger-connect" action="continue"/>

The is-failure attribute cannot be specified for this option.

Action Description and example
 continue

The Connect updates any appropriate parameters of the event it is a response to, and processing of that event continues to the next service in the composition.

<in:message-handling-option
    on-message="o-trigger-connect"
    action="continue"/>
 propagate

The Connect is propagated towards the network dialog. Processing of any current event is terminated and no more services will be invoked at the current level in the SIS.

<in:message-handling-option
    on-message="o-trigger-connect"
    action="propagate"/>
 propagate-on-destination-change

This option provides a conditional response depending on the content of the Connect operation sent by the service. If the Connect received by the SIS contains a Destination Routing Address parameter with an address string that is the same as the address string contained in the Called Party Number that was included in the initial request delivered to the service, this option will behave the same as the continue option. Otherwise, it will behave the same as the propagate option.

<in:message-handling-option
    on-message="o-trigger-connect"
    action="propagate-on-destination-change"/>
 rebranch

If processing the initial request, this option behaves the same as the continue option. Otherwise it will cause the composition script to be re-evaluated again from the current service, possibly causing later services in the composition to be retriggered. The SIS will use the original initial request delivered to the current service, modify it with relevant parameters from the Connect as normal, and use the resulting initial request as the input for the composition re-evaluation. See the section on rebranching for more information.

<in:message-handling-option
    on-message="o-trigger-connect"
    action="rebranch"/>

T-Trigger Connect

This option specifies the behaviour of the SIS when it receives a valid Connect response from a service while executing the terminating call state model for the call. The default behaviour, if this option is undeclared, is equivalent to:

<in:message-handling-option on-message="t-trigger-connect" action="propagate-on-destination-change"/>

The is-failure attribute cannot be specified for this option.

The actions that can be specified for this option are identical in name and behaviour to those defined for o-trigger-connect option.

Rebranching

Rebranching is a message handling option that applies only to Connect operations that a service sends and the SIS processes. The rebranching option lets a service restart composition script evaluation mid-call, so a new initial request can retrigger services that follow the one doing the rebranching.

Tip This is a SIS feature for IN.
Note Rebranching only applies when the SIS sends a Connect response to a leg-terminating event report; for example, "called party busy", "no answer", "disconnect", and so on.

Example

As an example, consider the following call flow:

rebranching call flow example

In this scenario:

  1. The initial request invokes both services.

  2. Service-A responds by arming some BCSM events (including oCalledPartyBusy and sending a Connect).

  3. Service-B simply responds with a Continue and drops out of the dialog interaction.

  4. Some time later, the network reports oCalledPartyBusy, which the SIS delivers to Service-A.

  5. Service-A responds to the event report by sending a second Connect operation to an alternative destination number.

Without the rebranching option, the SIS would simply send the second Connect operation back to the network as a final response to the ERB. However if Service-A’s message handling options specify invoking rebranching, then the SIS behaves as if the Connect operation was a response to the initial request originally sent to the service. This means the SIS:

  • generates a new initial request, based on the original initial request that Service-A received, but modified as necessary by the parameters contained in the new Connect operation

  • restarts composition script evaluation, using the generated initial request as input, at the script statement immediately following the invoke statement for Service-A (that is, at the same point composition evaluation would have continued after the first Connect that the service sent).

How retriggered services affect SIS responses to the network

Retriggered services may affect what final response the SIS sends to the network for the ERB in the same way that would apply during initial composition evaluations. In particular:

  • A Continue response has no effect — the previously stored Connect remains the final response.

  • A Connect response replaces the previously stored Connect response, to be sent as the final response.

  • A Release response overrides any other response. The SIS immediately sends it to the network; terminates composition evaluation; and notifies services still active in the composition of the call termination (as normal).

parallel (composition script)

Two or more services may be invoked in parallel by using the <parallel> element.

Warning Only the initial event is delivered in parallel to services in a parallel block. Subsequent events are delivered in serial to any parallel block services that remain in the call path after the initial event, in the order the services are defined within the parallel block.
Tip

The SIS views a parallel block in the same way it does a regular service — as a black box that accepts input and may generate output. A parallel block is still invoked sequentially with respect to other <invoke> or <parallel> elements within the composition.

The fact that the parallel block actually invokes multiple services is immaterial as far as SIS composition evaluation is concerned.

Example

In the following example, the SIS delivers the initial event to the VPN and Homezone services in parallel, favouring the result of VPN as the primary service. After both services have responded, and assuming neither service releases the call, the SIS proceeds to invoke the Prepay service.

VIA diagram

parallelblock

Script XML

<script>
 <parallel> <invoke service="VPN" primary="true"/> <invoke service="HomeZone"/> </parallel> <invoke service="Prepay"/>
</script>

Attributes and child elements

A <parallel> element has the following possible attributes and child elements.

Attributes

Name Description Optional?
 timeout

Specifies the timeout period, measured in milliseconds, that the SIS will wait for all responses during initial event processing. If present, this timeout overrides the default service timeout configured for the SIS. If the timeout period for the parallel block is less than the timeout period of any individual service within that parallel block, it’s possible for the parallel block as a whole to timeout, in which case the timeout behaviour specified for the parallel block takes precedence over any timeout behaviour specified for individual services within the parallel block.

 on-timeout

Specifies the behaviour the SIS will take if the parallel block fails to obtain a suitable response within its specified timeout period. The supported values for this attribute are:

  • ignore-service-and-continue — remove all services in the parallel block from further interaction with the composition and continue delivery of any current event to the next service

  • terminate-processing — terminate processing of the current event; the SIS will not send any response to the network for this event (if relevant) unless the fail child element is also specified.

The default value if this attribute is not specified is ignore-service-and-continue.

Child elements

Name Description Optional?
 invoke

Indicates a service to be invoked in parallel. Any number of <invoke> elements may be specified. Each <invoke> element has the same syntax as described for regular composition invoke statements, with the addition of an extra boolean primary attribute. Exactly one of the services in the parallel block must be flagged as the primary service. The outcome of a parallel block is determined as follows:

  • if any of the invoked services release the call, the release is the final result and all other services in the parallel block are terminated

  • otherwise, the final response of the primary service is used, and final responses from all other services are discarded.

 service-input-interceptor

A service input interceptor. The SIS evaluates this input interceptor before it delivers any event to services in the parallel block.

 service-output-interceptor

A service output interceptor. The SIS evaluates this output interceptor whenever the parallel block, as a whole, generates output intended for the network.

 terminate

This element can only be specified if the on-timeout attribute is set to terminate-processing. It specifies a terminate clause that the SIS will use to send a response for the current event.

 message-handling-options

This element specifies configurable options for how the SIS manages specific messages received from the parallel block.

 extension-options

Specifies arbitrary extension options supported by the SIS for service invocation. This is a collection of extension-option elements each with a name and optional value. The sole extension option currently supported for parallel blocks is:

Option Description Required Value
 SIP:use-service

Indicates to the SIS that any parallel triggering logic for SIP should be performed by a service, bypassing the default SIS parallel triggering logic. The referenced service must be a local service. If the service is not local or is not present and active in Rhino, the SIS falls back to its default parallel triggering behaviour. See Parallel Triggering Service for information about parallel triggering services.

A service reference name.

if (composition script)

You can add decisions to a composition script using the if statement.

For example, you may want to invoke a particular service only if the called party address starts with a particular prefix.

The <if> statement contains a conditional expression, a <then> element, and optionally <else-if> and <else> elements. The <then> and <else> elements may contain any composition statement for the SIS to evaluate, depending on the outcome of the expression.

The SIS only evaluates conditional expressions in a composition while processing the initial request. While doing this, the SIS implicitly reads variables from the current input request, which is: the initial request the SIS received from the network, if it has not invoked any service before processing the expression; or (if it has invoked a service), the response to a request from the last service the SIS has invoked.

Note After completing initial event processing, the SIS limits the set of services it has invoked for future events on the call to those invoked during initial event processing. If the service selection included conditional logic, the SIS retains decisions made during initial event processing for future events on the same call — it does not re-evaluate conditional expressions for subsequent events.{ocpanel}
Tip
Loop-proof

The composition script language is deliberately constrained so as to make loops impossible — so a badly-written composition will never cause the SIS to enter an infinite loop. (However you can invoke the same service multiple times in the same composition, if necessary).

Initial request

With <if> at the beginning of a script, the SIS evaluates the conditional expression before invoking any services. Therefore, it takes the values of any variables used in the expression from the initial request. The following example shows a script that invokes different services depending on the value of the from.uri.user parameter from the initial request:

VIA diagram

if initial request

Script XML

<script>
 <if><equal a="${from.uri.user}" b="alice"/> <then> <invoke service="AliceSpecial"/> </then> <else-if><equal a="${from.uri.user}" b="bob"/> <then> <invoke service="BobSpecial"/> </then> </else-if> <else> <invoke service="NoSpecial"/> </else> </if>
</script>

Response from service

With <if> after an <invoke> element, the SIS evaluates the conditional expression after invoking and processing the output from the previous service.

In the following example, the SIS invokes the VPN service, and then evaluates the if statement. It will read the variable from.uri.user from the new request that came from invoking the VPN service. If the VPN service changed the value of from.uri.user when it processed the request, the SIS will see that new value here. If the new request matches the condition, the SIS invokes the BobSpecial service. Finally the SIS invokes the Prepay service unconditionally.

VIA diagram Script
if response
<script>
 <invoke service="VPN"/> <if><equal a="${from.uri.user}" b="bob"/> <then> <invoke service="BobSpecial"/> </then> </if> <invoke service="Prepay"/>
</script>

assign (composition script)

You can create new user variables or assign new values to existing variables in a composition using the <assign> element.

The <assign> element used in a composition is identical to that which can be used in an expression, however when used in a composition the SIS disregards the return result of the assignment attempt.

Example

This example shows a composition that invokes one service (VPN), changes the Service Key parameter of the initial event, then invokes two more services (HomeZone and PrePay) with the modified parameter.

VIA diagram

simple assign

Script XML

<script>
 <invoke service="VPN"/> <assign toVariable="${initial-dp.arg.service-key}" value="15"/> <invoke service="HomeZone"/> <invoke service="Prepay"/>
</script>

delete (composition script)

It is possible to delete user variables or the values of some SIS-defined variables in a composition using the <delete> element.

The <delete> element used in a composition is identical to that which can be used in an expression, however when used in a composition the SIS disregards the return result of the deletion attempt.

Warning
  • Deleting a variable representing a SIP header (or header parameter) deletes that header (or header parameter) from the current message.

  • Deleting a user variable removes that user variable from the composition.

Example

The example shows a composition that invokes one service, deletes the orig parameter from the Route header’s URI, then invokes one more service with the modified request.

VIA diagram

delete sip

Script XML

<script>
 <invoke service="VPN"/> <delete variable="${route.uri.param.orig}"/> <invoke service="Prepay"/>
</script>

halt (composition script)

A composition may be stopped at any point using the <halt> element.

This tells the SIS to stop evaluating the composition any further and continue with the current call using only the services invoked so far. A <halt> element may also specify specific response behaviour to perform, as described below for IN and SIP.

IN halt instructions

Note

For IN, if the halt statement includes a response, the response element defines whether or not the response should be recorded in statistics as a success or failure outcome. Where appropriate, the element also defines how the SIS terminates the dialog with the dialog-termination parameter. Valid values for this parameter are:

  • none — The SIS will not terminate the dialog.

  • close — The SIS sends the response within a TC_END (with basic end).

  • user-abort — The SIS sends the response within a TC_CONTINUE, then tears down the dialog with a TC_U_ABORT.

Warning The composition output interceptor (if defined for the composition) processes any response the halt instruction generates, before the SIS sends the final response out on the network.
Halt instruction Description and example
 none

The default halt action for IN is to send a response based on the outcome of any composition services already invoked.

<halt/>
 User Error

Stop further composition evaluation and return a User Error response. The error response code may be unexpected-data-value, missing-parameter, or missing-customer-record.

<in:halt record-as-reject="true">
    <in:user-error reason="missing-customer-record" dialog-termination="user-abort"/>
</in:halt>
 Continue

Stop further composition evaluation and return a Continue or ContinueSMS response. The SIS resumes the dialog state model and the call or SMS continues in the network using default call handling.

<in:halt record-as-reject="false">
    <in:continue dialog-termination="close"/>
</in:halt>
 Release

Stop further composition evaluation and return a ReleaseCall or ReleaseSMS response. The SIS releases the call or SMS, with the specified cause code.

<in:halt record-as-reject="true">
    <in:release cause-code="31" dialog-termination="close"/>
</in:halt>
 Connect

Stop further composition evaluation and return a Connect response. The SIS redirects the call to the specified destination routing address, described by an XML <called-party-number> element as specified in [1 Pre-defined Datatypes]. This halt instruction can only be used with initial triggers on call control dialogs.

<in:halt record-as-reject="false">
    <in:connect dialog-termination="close">
        <called-party-number
            nature="NATIONAL"
            routing-to-internal-network-number="ALLOWED"
            numbering-plan="ISDN"
            address="123456789"/>
    </in:connect>
</in:halt>
 ConnectSMS

Stop further composition evaluation and return a ConnectSMS response. The SIS redirects the SMS to the specified destination subscriber number, described by an XML <called-party-bcd-number> element as specified in [1 Pre-defined Datatypes]. This halt instruction can only be used with initial triggers on CAPv3 or CAPv4 SMS dialogs.

<in:halt record-as-reject="false">
    <in:connect-sms dialog-termination="close">
        <called-party-bcd-number
            number-type="NATIONAL"
            numbering-plan="ISDN"
            address="987654321"/>
    </in:connect-sms>
</in:halt>
 Redirect

Stop further composition evaluation and return a Connect or ConnectSMS response. The SIS uses its configured redirect behaviour to redirect the call by issuing a Connect or ConnectSMS with the redirect prefix (from either a specified constant value or a variable) in the destination routing address or destination subscriber number.

<in:halt record-as-reject="false">
    <in:redirect prefix-value="9876" dialog-termination="close"/>
</in:halt>
 Relay

Stop further composition evaluation and return a Relay response. A dialog is opened towards the target external platform and the initial request is relayed to it, after which the incoming and relayed dialogs are terminated locally. Further communication on the dialog continues directly between the dialog originator and the external platform. A nested terminate clause must be specified for this option which is invoked in the event the relay fails, eg. an outgoing dialog cannot be created, a TC_CONTINUE has already been sent on the incoming dialog, etc.

<in:halt record-as-reject="false">
    <in:relay target="some-relay-target">
        <in:on-failure record-as-reject="true">
            <in:release cause-code="31" dialog-termination="close"/>
        </in:on-failure>
    </in:relay>
</in:halt>
 No Response

Stop further composition evaluation. No response is sent. The value of the dialog-termination attribute determines what the SIS will do with the dialog.

<in:halt record-as-reject="true">
    <in:no-response dialog-termination="user-abort"/>
</in:halt>

SIP halt instructions

Warning If a halt forwards the request (the default halt behaviour), the SIS passes the request to the composition output interceptor (if defined for the composition) before sending it out on the network. The SIS does not invoke the composition output interceptor when the halt rejects the request with an error response.
Halt instruction Description and example
 Reject

Stop further composition evaluation and return a Reject response. A reject status code must be specified (in the range 300-699), along with an optional reason phrase. Any number of additional headers may also be included in the response

<sip:halt>
    <sip:reject status-code="503" reason-phrase="Service not available">
        <sip:header name="..." value="..."/>
    </sip:reject>
</sip:halt>
 Forward

Stop further composition evaluation and return a Forward response. An optional target URI may be specified. Any number of additional headers may also be included in the response

<sip:halt>
    <sip:forward uri="...">
        <sip:header name="..." value="..."/>
    </sip:forward>
</sip:halt>
Note The default halt action for the SIS for SIP is to send a Forward response to forward the request to the next hop.

Example

In the following example, the SIS stops composition evaluation if a certain parameter is present after invoking the CheckUser service. If the parameter is not present, the Prepay service is also invoked.

<script>
 <invoke service="CheckUser"/> <if><present variable="${user.foo}"/> <then> <halt/> </then> </if> <invoke service="Prepay"/>
</script>

Interceptors in Compositions

You can use interceptors in compositions to inspect and manipulate the signaling between services.

This lets you:

  • blend services developed in isolation — by intercepting and changing the signaling, to ensure each can be executed correctly

  • augment the behaviour of services (in ways not imagined when the services were developed).

There are four types of interceptor that can be used within a composition:

Type Invoked when…​
no interceptors

composition input

…​the SIS receives a new message from the network, to deliver to composition services. The SIS invokes the interceptor before delivering the message to the services. (white triangle on the start node in the VIA diagram)

service input

…​the SIS determines a need to deliver a message to an individual composition service. The SIS invokes the interceptor after determining the need, but before actually delivering the message. (white triangle on the top of the VPN/Prepay services in the VIA diagram)

service output

…​a service generates a message it intends for the network. The SIS invokes the interceptor before processing the message. (white triangle on the bottom of the VPN/Prepay services in the VIA diagram)

composition output

…​the SIS determines messages generated by services in the composition should be sent to the network. The SIS invokes the interceptor before writing the messages to the network. (white triangle on the end node in the VIA diagram)

Warning

SIS for IN re-evaluates interceptors in a composition script every time it invokes them — so conditional branches in an interceptor can define behaviour depending on the input messages to the interceptor.

SIS for SIP only evaluates interceptors on the initial request.

Interceptor script blocks

An interceptor script block is written directly inside the composition. The syntax of an interceptor script block in a composition is identical to that of interceptors installed as individual SIS components.

Configurable Options

For compositions in the SIS, you can configure:

Composition debugging

You can assign a fine-grained tracing level to an individual composition in the SIS, to generate extra debugging information for that composition when it is triggered.

To specify the debug level for a composition, use the <debug-level> element. For example:

<composition ...>
    ...
    <debug-level>1</debug-level>
    ...
<composition>
Note
  • For details on the fine-grained tracing debug levels that the SIS supports, and the output that each level produces, see the SIS Administration Guide.

  • If a composition does not specify a debug level, the SIS uses the default level of 0.

  • You can change the debug level for a composition at runtime, after composition installation, using the Composition Management MBean.

Composition auditing

The SIS provides different modes of call audit logging, as described in the SIS Administration Guide. When per-component audit logging is enabled, the SIS includes the audit setting of a triggered composition in its decision whether or not to enable audit logging for each call.

To specify per-component auditing for a composition, use the <audit> element. For example:

<composition ...>
    ...
    <audit>true</audit>
    ...
</composition>
Note
  • If a composition does not specifically enable auditing, the SIS uses a default value of false. The SIS will still generate an audit log for the composition, however, if the audit level has been set to audit all calls.

  • You can change the audit setting for a composition at runtime, after composition installation, using the Composition Management MBean.

Extension options

Specifies arbitrary extension options supported by the SIS for the composition. This is a collection of extension-option elements each with a name and optional value. The extension options currently supported for compositions are:

Option Description Required Value
 IN:proxied-invoke-timer-long

When an operation invoke is sent by an external IN service to the SIS, the timeout period specified for the invoke is not included in the wire protocol message that the SIS receives. When the SIS forwards an operation invoke from an external service to the network, it needs to specify its own invoke timeout period for that operation. The default invoke timeout configured for the SIS or service is adequate for most operations, however operations with "long" timers (Play Announcement, Prompt and Collect User Information) may need longer timeout periods for correct operation. This extension option allows a longer default timeout period to be specified for all services in the composition for these long timer operations.

A long integer value greater than or equal to zero specified in millisecond units.

 ECS1:allow-camel-style-apply-charging

The Ericsson INAP CS1 specification states that an Apply Charging request may only be sent by a service if the BCSM is suspended at a detection point. However an operator customisation exists that allows Apply Charging requests to be sent while the BCSM is in any valid state, the same as in CAMEL protocols. This extension option allows the CAMEL behaviour for Apply Charging to be supported for Ericsson INAP protocol dialogs (both CS1 and CS1+).

 ECS1p:allow-busy-after-alerting

The Ericsson INAP CS1+ specification states that the BCSM event detection point (EDP) indicating the caller is busy is implicitly disarmed if the EDP for alerting is encountered. However some mobile networks use the busy EDP to report a user call rejection, which naturally occurs after the alerting phase of the call has begun. This extension option allows this case to be supported without a service having to explicitly rearm the busy EDP. It suppresses the implicit disarm of the busy EDP in the SIS when the alerting EDP is reported from the MSC. WARNING: This option is only meaningful if the MSC applies the same rules to the BCSM.

n/a

 NCS1:enable-implicit-disarming

By default, the implicit disarming of EDP events is disabled in the SIS for calls received on Nokia INAP CS1 dialogs. This extension option allows the implicit EDP disarming rules to be enabled for Nokia INAP CS1. WARNING: This option is only meaningful if the MSC applies the same rules to the BCSM.

n/a

Event processing optimisations

With IN, the SIS supports optional optimisations that can reduce the overall event processing latency in some cases when using local services.

To specify the optimisations setting in a composition, use the <optimisations-enabled> element. For example:

<composition ...>
    ...
    <in:optimisations-enabled>true</in:optimisations-enabled>
    ...
</composition>
Note
  • Optimisations are typically safe to enable, but should not be used where the local services in a composition share information using transactional state in the SLEE (such as public activity context interface attributes or the activity context naming facility).

  • If a composition does not specifically enable optimisations, they are disabled by default.

  • You can change the optimisations setting for a composition at runtime, after composition installation, using the Composition Management MBean.

Managing FCI requests from multiple services

IN protocols allow services to send charging-related messages to the network. With IN, a composition can specify how the SIS should manage Furnish Charging Information (FCI) requests sent by multiple services in the same composition. The following interaction modes are available:

  • static-service-priorities — Each service in the composition is assigned a static charging priority, using the Service Reference Management MBean. If multiple services send FCI requests while the call state model is suspended, the FCI request sent by the highest priority service "wins" — the SIS sends that FCI request to the network and discards other FCI requests (sent by lower priority services).

  • concatenation — In this mode, the SIS appends the charging characteristics data, that each service sends in an FCI request, to a buffer. The SIS determines the buffer’s size by the maximum data size the FCI request permits for the protocol in use. The SIS can only append charging data while space in the buffer remains. The SIS discards an FCI request if the buffer cannot fit the data it contains. The SIS also appends the charging delimiter specified in the SIS configuration, between each set of charging-characteristics data. The final charging-characteristics data included in the FCI request the SIS sends to the network looks like this:

    <fci#1-data> <delim> <fci#2-data> <delim> ... <fci#n-data>
  • nominated-service — The SIS only sends FCI requests to the network if from the nominated service, as indicated by the associated service reference. The SIS rejects FCI requests sent by any other composition service.

  • pass-through — FCI requests from all services are passed through to the network. No filtering or manipulation of the FCI content is performed by the SIS.

The SIS applies FCI handling anew each time the call state model is suspended at a detection point. While the call state model is suspended, the SIS handles any FCI requests it receives from composition services according to the composition’s FCI interaction mode rules. The SIS determines what FCI request to send to the network when the call state model resumes. As CAPv2 FCI requests include a leg type that identifies which party to charge, the SIS treats FCIs it receives for different call legs separately. In other words, an FCI for the calling party leg will only interact with other FCIs for the same leg. If the SIS receives FCIs for both the calling party and called party legs during processing of a particular initial request, it sends the two FCIs to the network when the call state model resumes.

To specify the FCI interaction mode setting is specified in a composition, use the <fci-interaction> element. For example:

<composition ...>
    ...
    <in:fci-interaction mode="concatenation"/>
    ...
</composition>
Note
  • If a composition does not specify an FCI interaction mode, the SIS uses a default mode of static-service-priorities for that composition.

  • You can change the FCI interaction mode setting for a composition at runtime, after composition installation, using the Composition Management MBean.

Managing online charging requests from multiple services

IN protocols allow services to send charging-related messages to the network. With IN, a composition can specify how the SIS should manage the Apply Charging, Send Charging Information, and Call Information Request online-charging requests sent by multiple services in the same composition.

The following interaction modes are available:

  • static-service-priorities — Each service in the composition is assigned a static charging priority, using the Service Reference Management MBean. If multiple services send any online charging requests while the call state model is suspended, the charging requests sent by the highest priority service "wins" — the SIS sends those charging requests to the network and discards all other online charging requests (sent by lower priority services). If the call state model is not suspended, and the SIS has not yet selected a service for which to send online charging requests to the network, it sends the first service’s online charging requests it receives and discards any subsequent online charging requests from other services (even if they come from a service with a higher priority than the selected service).

  • nominated-service — the SIS only sends online charging requests to the network if from the nominated service, as indicated by the associated service reference. The SIS rejects online charging requests sent by any other service.

To specify the online charging interaction mode setting in a composition, use the <online-charging-interaction> element. For example:

<composition ...>
    ...
    <in:online-charging-interaction mode="nominated-service" service="HomeZone"/>
    ...
</composition>
Note
  • You cannot use this mode to manage FurnishChargingInformation (FCI) requests — instead, manage them separately using the FCI Interaction configuration option.

  • If a composition does not specify an online charging interaction mode, the SIS uses a default mode of static-service-priorities for that composition.

  • You can change the online charging interaction mode setting for a composition at runtime, after composition installation, using the Composition Management MBean.

Interceptors

You can use interceptors to inspect and manipulate the signaling between a service and the SIS, or between the SIS and the network.

This lets you:

  • blend services developed in isolation — by intercepting and changing the signaling, to ensure each can be executed correctly

  • augment the behaviour of services (in ways not imagined when the services were developed)

  • alter messages received from the network before the SIS starts processing them

  • alter messages sent by the SIS, for example to add message fields not set by the SIS.

Note
What is an interceptor?

An interceptor is a set of script elements that may modify the parameters of the messages it intercepts (or may perform some other action). Interceptor scripts are typically embedded directly within a composition. However an interceptor can also be installed as a SIS component in its own right, allowing it to be invoked by SLEE applications or other interceptors.

Below is a sample interceptor and a description of the schema syntax.

Sample interceptor

This example below shows a simple interceptor that modifies the service key of an IN InitialDP operation. Its main elements are: interceptor-name/vendor/version, which define this interceptor’s component identity; and script, which specifies the operations to perform when the interceptor is invoked.

VIA Diagram Script
simple
<interceptor xmlns="http://www.opencloud.com/SIS/Interceptor"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opencloud.com/SIS/Interceptor sis-interceptor-1.2.xsd">

  <interceptor-name>Simple</interceptor-name>
  <interceptor-vendor>ABC</interceptor-vendor>
  <interceptor-version>1.0</interceptor-version>

  <script>
 <if> <present variable="${initial-dp}"/> <then> <assign toVariable="${initial-dp.service-key}" value="100"/> </then> </if>
  </script>
</interceptor>
Note Interceptors may contain conditional branches, and may also invoke interceptor extension components to perform functions that may not be possible using the scripting language.

Interceptor syntax schema

The base XML schema sis-interceptor-1.2.xsd defines the basic structure of an interceptor. SIS variants extend this base schema with protocol-specific properties.

IN interceptors

Interceptors for IN protocols may use the XML schema in-sis-interceptor-1.2.xsd to extend the generic schema for SIS interceptors. IN interceptors use the following corresponding schema namespaces:

<interceptor xmlns="http://www.opencloud.com/SIS/Interceptor"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:in="http://www.opencloud.com/SIS/Interceptor/IN"
  xsi:schemaLocation="http://www.opencloud.com/SIS/Interceptor/IN in-sis-interceptor-1.2.xsd http://www.opencloud.com/SIS/Interceptor sis-interceptor-1.2.xsd">

SIP interceptors

Interceptors for SIP may use the XML schema sip-sis-interceptor-1.2.xsd to extend the generic schema for SIS interceptors. SIP interceptors use the following corresponding schema namespaces:

<composition xmlns="http://www.opencloud.com/SIS/Interceptor"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sip="http://www.opencloud.com/SIS/Interceptor/SIP"
  xsi:schemaLocation="http://www.opencloud.com/SIS/Interceptor/SIP sip-sis-interceptor-1.2.xsd http://www.opencloud.com/SIS/Interceptor sis-interceptor-1.2.xsd">

Interceptor Scripts

An interceptor script is a set of script statements that the SIS evaluates in the order they appear in the script.

The SIS currently supports the following statements in an interceptor:

  • if — to use conditional logic (branching)

  • assign — to assign values to variables

  • delete — to delete values from variables

  • invoke-extension — to invoke an interceptor extension component

  • invoke-interceptor — to invoke an installed interceptor component

  • halt — to halt an interceptor or composition.

Tip Statements may appear in any order within an interceptor, with the exception that no statement may follow a halt. Statements may be nested, for example the if statement may contain other if statements.

if (interceptor)

Branching in an interceptor lets you execute different logic depending on the outcome of some expression.

Example

If the SIS evaluates the following sample composition script for a particular IN call:

  • From the initial request, the SIS will invoke one of either InterceptorComponent1 or InterceptorComponent2, and InterceptorComponent3.

  • For any subsequence call events that Service1 is interested in receiving, the SIS will first invoke the interceptor extension component InterceptorComponent3 only, as the initial-dp variable is only present if the event being delivered is an InitialDP initial request.

VIA diagram

conditions interceptor

Script XML

<script>
 <invoke service="Service1"> <service-input-interceptor> <if> <present variable="${initial-dp}"/> <then> <if> <equal a="${initial-dp.arg.service-key}" b="10"/> <then> <invoke-extension extension="InterceptorComponent1"/> </then> <else> <invoke-extension extension="InterceptorComponent2"/> </else> </if> </then> </if> <invoke-extension extension="InterceptorComponent3"/> </service-input-interceptor> </invoke>
</script>

assign (interceptor)

You can create new user variables or assign new values to existing variables in an interceptor script block, the same way you can for a composition script block — by using the <assign> element.

Tip
Reassigning IN Signaling Parameters

If the value of any IN signaling parameters are changed in a <service-input-interceptor> block, these changes apply to the current composition service only. They do not carry forward to subsequent service invocations, unless the response from the composition service demands it (for example, if the service response is a function of a modified input parameter).
This behaviour does not apply to SIP.

Example

This example shows a script that invokes one service, changes the ServiceKey parameter of the IN InitialDP trigger event for the second service using an interceptor block, then invokes a third service (using the original service key value).

VIA diagrams

interceptor assign comp
interceptor assign

Script XML

<script>
 <invoke service="VPN"/> <invoke service="HomeZone"> <service-input-interceptor> <if> <present variable="${initial-dp}"/> <then> <assign toVariable="${initial-dp.arg.service-key}" value="15"/> </then> </if> </service-input-interceptor> </invoke> <invoke service="Prepay"/>
</script>

delete (interceptor)

You can delete user variables or the values of some SIS-defined variables in an interceptor script block, the same way you can for a composition script block — by using the <delete> element.

Tip
Deleting IN Signaling Parameters

If the values of any IN signaling parameters are changed in a <service-input-interceptor> block, these changes apply to the current composition service only. They do not carry forward to subsequent service invocations, unless the response from the composition service demands it (for example, if the service response is a function of a modified input parameter).
This behaviour does not apply to SIP.

Example

This example shows a composition that invokes a service, after deleting the orig parameter from the Route header’s URI:

<script>
 <invoke service="Prepay"> <service-input-interceptor> <delete variable="${route.uri.param.orig}"/> </service-input-interceptor> </invoke>
</script>

invoke-extension (interceptor)

Any number of interceptor extension components can be invoked sequentially in an interceptor script block.

An extension component is invoked using an <invoke-extension> element and has the following possible attributes:

Type Name Description Optional?

Attribute

 extension

The extension component to be invoked. Must refer to an extension component of type INTERCEPTOR defined in the SIS (using an extension reference)

NO

Attribute

 timeout

Specifies the timeout period, measured in milliseconds, that the SIS will wait for a response from the extension component. If present, this timeout overrides the default timeout configured for the extension component.

YES

Example

Below is an example of a composition that uses a service input interceptor to invoke an interceptor extension component. The service node on the VIA diagram has its input interceptor filled in (indicating the interceptor has been defined). You double-click on the interceptor to open the interceptor diagram.

VIA diagrams

svc input interceptor
interceptor extension

Script XML

<script>
 <invoke service="VPN"> <service-input-interceptor> <invoke-extension extension="InterceptorComponent1"/> </service-input-interceptor> </invoke> ...
</script>

invoke-interceptor (interceptor)

An interceptor script block may invoke another interceptor component.

The current interceptor is suspended while the invoked interceptor is evaluated. If the invoked interceptor completes normally, evaluation of the current interceptor continues. If the invoked interceptor is halted, the current interceptor is also immediately halted with the same halt response.

An interceptor component is invoked using an <invoke-interceptor> element and has the following possible attribute.

Type Name Description Optional?

Attribute

 interceptor

The interceptor component to be invoked. Must refer to an interceptor component defined in the SIS (using an interceptor reference)

NO

Example

Below is an example of an interceptor that invokes another interceptor extension component.

VIA diagram

interceptor

Script XML

<script>
 ... <invoke-interceptor interceptor="Interceptor1"/> ...
</script>

halt (interceptor)

To terminate a composition script evaluation normally during initial event processing, you can include a <halt> element in a service input or output interceptor script block.

This stops the composition from including any more composition services. The SIS will also terminate any further evaluation of the interceptor upon encountering a <halt>.

Warning The <halt> element in a service input interceptor also stops the composition service that is target of the <invoke> element that contains that service input interceptor from being included in the composition.

A <halt> statement will only halt composition evaluation while the SIS is processing the initial event. If the SIS encounters a <halt> while processing a subsequent event, or while evaluating an interceptor invoked directly by a SLEE application, the only effect will be to terminate further interceptor evaluation.

The syntax of a <halt> statement for an interceptor is the same as that for compositions.

Note
  • For IN — the composition output interceptor (if defined for the composition) still processes the response that the halt generates, before the SIS sends the final response out on the network.

  • For SIP — if a halt forwards the request (the default halt behaviour), the SIS passes the request to the composition output interceptor (if defined for the composition) before sending it out on the network. The SIS does not invoke the composition output interceptor when the halt rejects the request with an error response.

Invoking Interceptors from SLEE Applications

A JAIN SLEE service may request that the SIS invoke an interceptor at any time during service execution.

Examples where this can be useful are in proxy or protocol translation services. The SIS already provides support for interceptors on the southbound dialog between the SIS and a service, but it does not impose any specific behaviours onto northbound dialogs created by a service. By coding a service to invoke SIS interceptors at points where messages are sent or received on a northbound dialog, it’s possible to provide pluggable, customisable behaviour without needing to recompile and redeploy the service.

Warning It’s possible for a SLEE service to invoke interceptor components in any SIS instance it has a resource adaptor entity binding to. However, interceptor script variables representing IN signaling parameters are only understood by the SIS for IN. Similarly, script variables representing SIP signaling parameters are only understood by the SIS for SIP. An interceptor that uses protocol-specific script variables therefore needs to be installed into an appropriate SIS instance in order for it to behave as expected when invoked by a service.

The following topics describe how interceptors can be invoked by a service and what the invocation result means:

Invoking an Interceptor

You invoke SIS interceptors using one of the Interceptor Extension Resource Adaptor Types.

There are two Interceptor Extension Resource Adaptor Types, the:

The Interceptor Extensions Provider interface defined by this resource adaptor type provides various methods for invoking interceptors. Invoking an interceptor requires the following parameters:

Parameter Type Description Optional?

Interceptor Reference

 String

The interceptor component to be invoked.

NO

Interceptor Input

 Object

The object that will be provided as input to the interceptor. The interceptor may inspect or modify this object, or may pass it to extension components.

Tip It is not required that an input object be passed to the interceptor; however the interceptor will be very limited in what it can do if it has no input object to operate on.

YES

Activity

 axref:sis-in-interceptors-ratype/com.opencloud.slee.resources.sis.script.interceptors.InterceptorInvocationActivity[InterceptorInvocationActivity]

The interceptor invocation activity on which the interceptor completion callback event will be fired if the interceptor completes asynchronously. If an activity is not provided and the interceptor will complete asynchronously, the SIS will automatically create a new activity for the callback event.

Tip Interceptors that complete synchronously do not require or use an InterceptorInvocationActivity as the interceptor result is passed back to the invoking service in the calling thread.

YES

User Variables

 axref:sis-in-interceptors-ratype/com.opencloud.slee.resources.sis.script.interceptors.UserVariables[UserVariables]

A map containing the names (as map keys) and values (as key values) of any SIS user variables that should be populated in the context the interceptor runs in before the interceptor is evaluated. This parameter can be used, for example, to pass additional information to the interceptor through user variables with predetermined names.

YES

Interceptor Invocation Results

An interceptor invocation can have one of three possible results.

Result Description Result Content
 Completed

The interceptor has completed.

Interceptor output object — may or may not be the same as the original input object provided to the interceptor.
User variables — another UserVariables map. This map contains all user-defined variables that exist in the interceptor context when the interceptor completed and could be used, for example, to pass additional information from the interceptor back to the service.

 In Progress

Interceptor evaluation is in progress and will complete asynchronously at some later point. An Interceptor​Invocation​Completed​Event will be fired on the InterceptorInvocationActivity when the interceptor completes.

Invocation ID — a unique numerical identifier that the service can use to correlate with an InterceptorInvocationCompletedEvent.
Activity — an InterceptorInvocationActivity. If an activity object was provided when the interceptor was invoked, this will be the same object. Otherwise it will represent a new activity created by the SIS. The service should attach to this activity in order to receive the InterceptorInvocationCompletedEvent when the interceptor completes.

 Failed

The interceptor invocation failed. Typically this is because the specified interceptor reference doesn’t exist in the SIS (but could be for other reasons).

Reason — an enumerated value classifying the failure cause.
Cause — a free-format text string providing a human-readable description as to why the invocation failed.

Synchronous vs Asynchronous Interceptors

An interceptor invoked by a SLEE application can complete either synchronously or asynchronously.

Completion Method Description

Synchronous

The SIS completes evaluation of the interceptor script all within the boundary of the calling application thread. The interceptor output is immediately available to the application as a result of the invocation.

Asynchronous

The SIS is required to perform some function of the interceptor script in a separate thread. In the meantime, further evaluation of the interceptor script has been suspended, and control returns to the calling application. At some point in the future, evaluation of the interceptor script will continue and eventually complete. When this happens, the SIS will notify the application asynchronously and provide the interceptor output via an event fired on an InterceptorInvocationActivity.

An interceptor will only complete asynchronously if it invokes an interceptor extension component during evaluation, as doing so requires a SLEE event to be fired to the extension component and the SIS to wait for the response before continuing. An interceptor that performs all processing without invoking an interceptor extension component will always complete synchronously.

Tip Where practical it is recommended to use interceptors that complete synchronously whenever possible. Synchronous interceptors incur lower performance overhead and benefit from simpler application code. However an application that invokes SIS interceptors generally has to be implemented to support both synchronous and asynchronous interceptors, as it’s not typically known during application development what functionality an interceptor may require.

Macros

Macro components specify reusable boolean expressions, for use in trigger, composition, or interceptor components.

Note
What’s in a macro?

A macro contains the following information:

  • an optional description

  • name, vendor and version identifiers

  • references to any other macro used in the expression

  • an expression.

Below is a description of macro schema syntax, and an example.

Macro schema syntax

The XML schema sis-macro-1.6.xsd defines macros, using the following schema namespaces:

<macro xmlns="http://www.opencloud.com/SIS/Macro"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.opencloud.com/SIS/Macro sis-macro-1.6.xsd">

Sample macro

The following sample macro normalises the address contained in the IN InitialDP CallingPartyNumber parameter, according to Spanish network rules. Below are a summary of those rules, and the macro’s pseudo-code, VIA diagram, and script XML.

Rules

  • If the CallingPartyNumber Nature of Address indicator states that the address is nationally formatted, the expression either strips the "00" international direct dialing prefix (if present), or adds the "34" country code if the address is a 9-digit (Spanish national) number. In any other case the address is left unchanged.

  • In the general case this should provide an address starting with "34" followed by a 9-digit national number, such as "34607000001".

  • The macro assigns the normalised address (or the original address if it wasn’t changed) to the user-defined variable user.normalised-cgpn.

  • If the InitialDP does not have a CallingPartyNumber parameter, no user-defined variable is created.

  • This condition always evaluates to true.

Pseudo-code

if (calling-party-number is present) {
    if (calling-party-number.nature == NATIONAL) {
       if (calling-party-number.address starts with "0034") {
          user.normalised-cgpn = (calling-party-number.address without "00" prefix)
          return true
       }
       else if (calling-party-number.address is 9 digits long) {
          user.normalised-cgpn = ("34" + calling-party-number.address)
          return true
       }
    }
    // just use the same value if we can't change it
    user.normalised-cgpn = calling-party-number.address
    return true
 }
 else {
    return true
 }

VIA diagram

Note

The SIS scripting language uses short-circuit boolean evaluation. In this current release of VIA, the order of arguments to AND and OR expressions is based on the order in which they have been associated with the AND or OR symbols.

If you are relying on the behaviour of short-circuit boolean evaluation (for example to guard an ASSIGN or DELETE), then you must take care with the order you define the parameters to AND and OR.

See Macros in the SIS Visual Interaction Architect (VIA) User Guide for information about macros.

complex macro

Script XML

<macro xmlns="http://www.opencloud.com/SIS/Macro"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opencloud.com/SIS/Macro sis-macro-1.6.xsd">

  <description>
Normalise the CallingPartyNumber parameter according to Spanish numbering conventions

This macro always returns true

pseduo-code version:
 if (calling-party-number is present) {
    if (calling-party-number.nature == NATIONAL) {
       if (calling-party-number.address starts with "0034") {
          user.normalised-cgpn = (calling-party-number.address without "00" prefix)
          return true
       }
       else if (calling-party-number.address is 9 digits long) {
          user.normalised-cgpn = ("34" + calling-party-number.address)
          return true
       }
    }
    // just use the same value if we can't change it
    user.normalised-cgpn = calling-party-number.address
    return true
 }
 else {
    return true
 }
  </description>

  <macro-name>Normalise CallingPartyNumber</macro-name>
  <macro-vendor>OpenCloud</macro-vendor>
  <macro-version>1.0</macro-version>

  <macro-expression>
    <or>
      <!-- either (calling-party-number is present and ...) or true -->
      <and>
        <!-- calling-party-number is present and we assign a normalised value -->
        <present variable="${initial-dp.arg.calling-party-number}"/>
        <!-- define the 'normalised' address as equal to the original by default -->
        <assign toVariable="${user.normalised-cgpn}" value="${initial-dp.arg.calling-party-number.address.hex}"/>
        <or>
          <and>
            <equal a="${initial-dp.arg.calling-party-number.nature}" b="NATIONAL"/>
            <or>
              <and>
                <string-starts-with source="${user.normalised-cgpn}" prefix="0034"/>
                <assign toVariable="${user.normalised-cgpn}">
                  <string-substring source="${user.normalised-cgpn}" begin-index="2"/>
                </assign>
              </and>
              <and>
                <equal>
                  <string-length source="${user.normalised-cgpn}"/>
                  <value value="9"/>
                </equal>
                <assign toVariable="${user.normalised-cgpn}">
                  <string-prepend source="${user.normalised-cgpn}" prefix="34"/>
                </assign>
              </and>
            </or>
          </and>
          <!-- force true to be returned in the case no normalisation possible -->
          <true/>
        </or>
      </and>
      <!-- force true to be returned in the case a CallingPartyNumber wasn't present -->
      <true/>
    </or>
  </macro-expression>
</macro>

Expressions

The SIS defines a number of expressions, for use in macros, triggers, compositions, and interceptors.

Expressions can be composed using:


Unless otherwise stated, the parameters to all SIS expression conditions and functions can accept either:

  • a literal constant value — specified using its literal name as the value, for example:

    simple gt
    <greater-than a="10" b="5"/>
  • a variable value — specified by surrounding the variable name with ${…​}, for example:

    simple equal
     <equal a="${initial-dp.arg.service-key}" b="20"/>

Basic Conditions

The XML schema conditions-1.6.xsd defines the testable conditions offered by the SIS. The following tables list the basic conditions, what they compare, and when they evaluate to true or false.

present

Description

Determines if a variable is present in the current request. This condition expects a variable as its parameter, including any surrounding curly braces ${}.

Returns

true if the specified variable exists in the current request

Examples

<present variable="${initial-dp.arg.calling-party-number}"/>
in present
<present variable="${to.uri.user}"/>
sip present

equal

Description

Compares two numeric values. Values may be specified either as element attributes or as nested elements. Nested elements may also be string manipulation functions. If the first value refers to a variable with named values, the second value may be specified in terms of those named values.

Returns

  • true if both values exist and are equal

  • false if either value refers to a variable that does not exist

Examples

<equal a="${initial-dp.arg.event-type-bcsm}" b="collectedInfo"/>
in equal
<equal>
    <value value="${from.uri}"/>
    <value value="sip:alice@foo.com"/>
</equal>
sip equal

not-equal

Description

Equivalent to <not><equal /></not>.

Returns

the inverse of the equivalent <equal> condition

Note This condition will still return true in the case where either value refers to a variable that does not exist such that equality cannot be determined.

Example

<not-equal a="${initial-dp.arg.service-key}" b="50"/>
in not equal

less-than

Description

Compares two numerical values for relative difference. Values may be specified either as element attributes or as nested elements. Nested elements may also be string manipulation functions. If the first value refers to a variable with named values, the second value may be specified in terms of those named values.

Returns

  • true if the first value is less than the second value

  • false if either value refers to a variable that does not exist or is not numeric

Examples

<less-than a="${initial-dp.arg.event-type-bcsm}" b="termAttemptAuthorized"/>
in lessthan
<less-than>
    <string-length source="${from.uri.user}"/>
    <value value="10"/>
</less-than>
sip lessthan

greater-than

Description

Compares two numerical values for relative difference. Values may be specified either as element attributes or as nested elements. Nested elements may also be string manipulation functions. If the first value refers to a variable with named values, the second value may be specified in terms of those named values.

Returns

  • true if the first value is greater than than the second value

  • false if either value refers to a variable that does not exist or is not numeric

Example

<greater-than a="${from.uri.port}" b="1023"/>
sip greater than

macro-satisfied

Description

Evaluates the specified macro and returns the result.

Returns

the result of evaluating the given macro, true or false

Example

<macro-satisfied macro="foo"/>
macro

true

Description

Unconditionally returns true.

Returns

true

Example

<true/>
true

false

Description

Unconditionally returns false.

Returns

false

Example

<false/>
false

assign

Description

Assigns a value to a variable. Can be used to create new user-defined variables. This condition expects a variable name as its parameter, including any surrounding curly braces ${}. Variables may be assigned a literal constant value, or may take their value from any other variable. The value may be specified either as an element attribute or as a nested element. Nested elements may also be string manipulation functions or compound datatypes.

Returns

  • true if the variable was successfully assigned

  • false if the source value refers to a variable that does not exist or a function that returns no value, or if the target variable does not exist and is not a user-defined variable or cannot be assigned for other reasons (for example, attempting to assign a string value to an integer-type variable)

Examples

<assign toVariable="${to.uri.user}" value="bob"/>
sip assign
<assign toVariable="${initial-dp.arg.called-party-number}">
    <called-party-number
        noa="national"
        numbering-plan="isdn"
        allow-inn-routing="true"
        address="1234567890"/>
</assign>

delete

Description

Deletes a variable. Can be use to remove headers from a SIP message or to delete previously created user-defined variables. This condition expects a variable name as its parameter, including any surrounding curly braces ${}.

Returns

true if the variable was successfully deleted

Example

<delete variable="${to.uri.user}"/>
sip delete

Logical Operators

SIS conditions may be combined using the following logical operators.

and

Description

Evaluates to true only if all nested conditions return true. The nested conditions are executed in their defined order. If an executed nested condition evaluates to false, further nested conditions are not evaluated.

Example

<and>
    <equal a="..." b="..."/>
    <equal a="..." b="..."/>
    <equal a="..." b="..."/>
</and>

or

Description

Evaluates to true if at least one nested condition returns true. The nested conditions are executed in their defined order until a condition evaluates to true.

Example

<or>
    <less-than a="..." b="..."/>
    <greater-than a="..." b="..."/>
</or>

not

Description

Negates the value returned by its nested condition.

Example

<not>
    <less-than a="..." b="..."/>
</not>

String Manipulation Functions

The XML schema string-manipulator-datatypes-1.2.xsd defines string manipulation functions that can be used in SIS expressions. Functions that return a Boolean value may also be used as expression conditions in their own right.

The following tables list the string manipulation functions available in the SIS, what they do, and the results they return.

string-prepend

Description

Adds a string prefix to beginning of a string value.

Returns

  • the prefixed value

  • no value, if either parameter cannot be evaluated to a string value

Example

<assign toVariable="user.international-b-party-number">
    <string-prepend source="${user.b-party-number}" prefix="044"/>
</assign>

string-append

Description

Adds a string suffix to the end of a string value.

Returns

  • the suffixed value

  • no value, if either parameter cannot be evaluated to a string value

Example

<assign toVariable="user.foo">
    <string-append source="${user.foo}" suffix="bar"/>
</assign>

string-substring

Description

Extracts a substring from a string value. The begin index specifies the index of the first character to be included. The end index is optional and specifies the index after the last character to be included. If the end index is not specified, it defaults to the length of the source string value.

Returns

  • the specified substring

  • no value, if either index cannot be evaluated to an integer value, is out of bounds of the string length, or the begin index is greater than the end index

Example

<assign toVariable="user.normalised-b-party">
    <string-substring
        source="${initial-dp.arg.called-party-number.address}"
        begin-index="2"/>
</assign>

string-length

Description

Returns the length of a string value.

Returns

  • the string length

  • no value, if the parameter cannot be evaluated to a string value

Example

<assign toVariable="user.from-length">
    <string-length source="${from.uri.user}"/>
</assign>

string-contains

Description

Determines if a string value contains the given substring.

Returns

  • true if the substring exists within the source value

  • false if either parameter cannot be evaluated to a string value

Example

<if>
    <string-contains source="${user.foo}" substring="${user.bar}"/>
    <then> ... </then>
</if>

string-index-of

Description

Returns the index within a string value of the first occurrence of the given substring. The begin index is optional and specifies the index of the first character from where to start the search. If the begin index is not specified, it defaults to 0.

Returns

  • the index within the source value (starting from the given index) of the first occurrence of the substring

  • -1 if the substring does not occur

  • no value, if either the source or substring parameter cannot be evaluated to a string value, or the begin index cannot be evaluated to an integer value

Example

<assign toVariable="user.from-host-index">
    <string-index-of source="${from.uri}" substring="@"/>
</assign>

string-last-index-of

Description

Returns the index within a string value of the last occurrence of the given substring. The begin index is optional and specifies the index of the first character from where to start the search. If the begin index is not specified, it defaults to 0.

Returns

  • the index within the source value (starting from the given index) of the last occurrence of the substring

  • -1 if the substring does not occur

  • no value, if either the source or substring parameter cannot be evaluated to a string value, or the begin index cannot be evaluated to an integer value

Example

<assign toVariable="user.from-root-domain">
    <string-last-index-of source="${from.uri.host}" substring="."/>
</assign>

string-starts-with

Description

Determines if a string value begins with a given prefix. The begin index is optional and specifies the index of the first character from where to start comparing from. If the begin index is not specified, it defaults to 0.

Returns

  • true if the source value (from the given index) starts with the substring

  • false if either the source or substring parameter cannot be evaluated to a string value, or the begin index cannot be evaluated to an integer value

Example

<if>
    <string-starts-with
        source="${initial-dp.arg.calling-party-number.address}"
        substring="00"/>
    <then> ... </then>
</if>

string-ends-with

Description

Determines if a string value ends with a given suffix.

Returns

  • true if the substring is a suffix of the source value

  • false if either parameter cannot be evaluated to a string value

Example

<if>
    <string-ends-with
        source="${from.uri.host}"
        suffix=".net"/>
    <then> ... </then>
</if>

string-matches

Description

Determines if a string value matches a given regular expression.

Returns

  • true if the source value matches the regular expression

  • false if either parameter cannot be evaluated to a string value

Example

<if>
    <not>
        <string-matches
            source="${to.uri}"
            regex="(bxref:[tt[sS][iI][pP][sS]?][eE][lL]):.+"/>
    </not>
    <then> ... </then>
</if>

Array Manipulation Functions

The XML schema array-manipulator-datatypes-1.1.xsd defines array manipulation functions that can be used in SIS expressions.

The following tables list the array manipulation functions available in the SIS, what they do, and the results they return.

array-add-element

Description

Adds a new element value to an existing array. The value may be specified either as an element attribute or as a nested element. Nested elements may also be compound datatype values. The index is optional and specifies the insertion point for the new value. If the index is less than or equal to zero, the new value is inserted at the beginning of the array. If the index is greater than or equal to the current length of the array, the new value is added to the end of the array. Otherwise, the new value is inserted at the specified index. If the index is not specified, the default behaviour is to add the new value to the end of the array.

Returns

  • a new array with the specified value added.

  • no value, if the specified array variable does not exist; its current value is not an array type; the specified value cannot be evaluated, evaluates to null, or evaluates to a value that is not compatible with the array element type; or the index, if specified, cannot be evaluated to a number

Examples

<assign toVariable="${request-report-bcsm-event.bcsm-events}">
    <array-add-element array="${request-report-bcsm-event.arg.bcsm-events}" value="${user.requested-info}"/>
</assign>
<assign toVariable="${request-report-bcsm-event.arg.bcsm-events}">
    <array-add-element array="${request-report-bcsm-event.arg.bcsm-events}">
        <object class="com.opencloud.slee.resources.cgin.callcontrol.CCBCSMEvent">
            <field name="event-type-bcsm" value="oAnswer"/>
            <field name="monitor-mode" value="interrupted"/>
        </object>
    </array-add-element>
</assign>

array-remove-element

Description

Removes an element from an existing array. If an index is specified, the array element at the specified index is removed. Otherwise, a value must be specified either as an element attribute or as a nested element. Nested elements may also be compound datatype values. Array elements are compared to the specified value using normal Java equality tests. If the value appears multiple times in the array, each occurrence will be removed.

Returns

  • a new array with the specified index or value removed

  • no value, if the specified array variable does not exist; its current value is not an array type; the index, if specified, cannot be evaluated to a number or evaluates to a value out of the array bounds; or the value, if specified, cannot be evaluated, evaluates to null, or evaluates to a value that is not compatible with the array element type

Examples

<assign toVariable="${request-report-bcsm-event.arg.bcsm-events}">
    <array-remove-element array="${request-report-bcsm-event.arg.bcsm-events}" index="3"/>
</assign>
<assign toVariable="${request-report-bcsm-event.arg.bcsm-events}">
    <array-remove-element array="${request-report-bcsm-event.arg.bcsm-events}">
        <object class="com.opencloud.slee.resources.cgin.callcontrol.CCBCSMEvent">
            <field name="event-type-bcsm" value="oAnswer"/>
            <field name="monitor-mode" value="interrupted"/>
        </object>
    </array-remove-element>
</assign>

array-length

Description

Returns the length of an array value.

Returns

  • the array length

  • no value, if the parameter cannot be evaluated to an array value

Example

<assign toVariable="user.bcsm-events.length">
    <array-length array="${request-report-bcsm-events.arg.bcsm-events}"/>
</assign>

Compound Datatypes

The XML schema in-sis-datatypes-1.5.xsd defines elements that allow any supported compound datatype value to be constructed and used as values for variable assignment or comparison.

Tip This is a SIS feature for IN.

Compound datatypes are those with a Java type that is not a simple type such as an integer or string but rather is a composite of some number of basic types. For example, the CGIN Call Control InitialDP operation argument is a composite of many sub-parameters including service key, calling party number, called party number, and so on. Values of compound datatypes may be assigned to appropriate variables, or used in conditions such as <equals> or <not-equals> to compare the equality of these variables.

SIS provides elements for a number of predefined datatypes and also defines elements that allow arbitrary datatypes to be constructed.

Pre-defined Datatypes

SIS provides elements for some predefined datatypes. These are shorthand notations for constructing values of a specific type (which you can also specify using the elements for arbitrary datatypes).

Below are descriptions of available parameters, followed by tables showing each datatype with its generated Javatype, parameters, and an example.

Parameters

The following parameters are available. All, with the exception of bytes and the optional digit string codecs, may take their value either from a literal constant or from a script variable.

Parameter Description
 nature

nature of address indicator

 numbering-plan

numbering plan indicator

 number-type

number type indicator

 number-qualifier

number type qualifier indicator

 presentation

address presentation indicator

 screening

screening indicator

 routing-to-internal-network-number

internal network number routing indicator

 address

address digits

 mcc

mobile country code digits

 mnc

mobile national network code digits

 location-area-code

location area code digits

 service-area-code

service area code digits

 cell-id

mobile cell id digits

 number-incomplete

number incomplete indicator

 bytes

comma-separated hexadecimal byte values

 *-codec

optional codec for the digit string corresponding to the prefix

calling-party-number

Generated Javatype

Parameters

nature
number-incomplete
numbering-plan
presentation
screening
address
address-codec

Example

<calling-party-number
    nature="NATIONAL"
    number-incomplete="false"
    numbering-plan="ISDN"
    presentation="ALLOWED"
    screening="NETWORK_PROVIDED"
    address="bd1234567"
    address-codec="hex"/>

called-party-number

Generated Javatype

Parameters

nature
routing-to-internal-network-number
numbering-plan
address
address-codec

Example

<called-party-number
    nature="SUBSCRIBER"
    routing-to-internal-network-number="ALLOWED"
    numbering-plan="ISDN"
    address="${user.short-code}"/>

called-party-bcd-number

Generated Javatype

Parameters

number-type
numbering-plan
address
address-codec

Example

<called-party-bcd-number
      number-type="SHORT_CODE"
      numbering-plan="PRIVATE"
      address="5566"/>

redirecting-party-number

Generated Javatype

Parameters

nature
numbering-plan
presentation
address
address-codec

Example

<redirecting-party-number
    nature="INTERNATIONAL"
    numbering-plan="ISDN"
    presentation="ADDRESS_NOT_AVAILABLE"
    address=""/>

original-called-number

Generated Javatype

Parameters

nature
numbering-plan
presentation
address
address-codec

Example

<original-called-number
    nature="${user.original-noa}"
    numbering-plan="${user.original-numbering}"
    presentation="${user.original-presentation}"
    address="${user.original-address}"/>

generic-number

Generated Javatype

Parameters

number-qualifier
number-incomplete
nature
numbering-plan
presentation
screening
address
address-codec

Example

<generic-number
    number-qualifier="ADDITIONAL_CALLING_PARTY_NUMBER"
    number-incomplete="false"
    nature="NATIONAL"
    numbering-plan="ISDN"
    presentation="ALLOWED"
    screening="NETWORK_PROVIDED"
    address="87654321"/>

location-number

Generated Javatype

Parameters

nature
routing-to-internal-network-number
numbering-plan
presentation
screening
address
address-codec

Example

<location-number
    nature="NATIONAL"
    routing-to-internal-network-number="ALLOWED"
    numbering-plan="ISDN"
    presentation="ALLOWED"
    screening="NETWORK_PROVIDED"
    address="0044acbb098231234567"
    address-codec="hex"/>

address-string

Generated Javatype

Parameters

nature
numbering-plan
address
address-codec

Example

<address-string
    nature="NETWORK_SPECIFIC"
    numbering-plan="LAND_MOBILE"
    address="09831245762123"/>

cell-global-id

Generated Javatype

Parameters

mcc
mnc
location-area-code
cell-id
mcc-codec
mnc-codec

Example

<cell-global-id
    mcc="234"
    mnc="15"
    location-area-code="999999"
    cell-id="12345"/>

service-area-id

Generated Javatype

Parameters

mcc
mnc
location-area-code
service-area-code
mcc-codec
mnc-codec

Example

<service-area-id
    mcc="234"
    mnc="15"
    location-area-code="999999"
    service-area-code="55412"/>

location-area-id

Generated Javatype

Parameters

mcc
mnc
location-area-code
mcc-codec
mnc-codec

Example

<location-area-id
    mcc="234"
    mnc="15"
    location-area-code="999999"/>

imsi

Generated Javatype

Parameters

address
address-codec

Example

<imsi
    address="642112345678"/>

bytes

Generated Javatype

 byte[]

Parameters

bytes

Example

<bytes
    bytes="80,10"/>

Arbitrary Datatypes

SIS defines elements that let you construct arbitrary datatype values.

The set of datatypes that may be constructed is limited to:

  • convenience APIs, such as those defined in the in/datatypes/cc package

  • arguments and field types of all supported protocols, such as those defined in the call control package.

Note

Different SIS packages provide support for different protocols, so the set of supported datatypes varies. See to the documentation included with the SIS package for a complete list of datatypes that may be constructed using this mechanism.

Support for datatypes used in the MAP protocol is limited to only those used by the CAP protocols.

Using these elements you may construct objects, enumerated type values, generic arrays, and byte arrays.

Objects

The <object> element can be used to construct a general object type value.

Note

This element requires the fully qualified class name of the datatype be specified; either values for individual sub-fields of the datatype or a byte array value representing the encoded form of the value can be provided. The set of datatypes that may be constructed is limited to the subset of COMPOUND and BIT_STRING variables of the supported arbitrary datatypes.

If using the encoded byte array form, the specified datatype class must implement a public constructor that takes a single byte[] argument. Otherwise, the specified datatype class must implement a public constructor that takes no arguments. See the CGIN API Javadoc for details on the constructors implemented by each datatype.

The <object> element can also be used to create a new object that is a copy of another object of the same or a related Java type. Extendable types within the CGIN API generally implement a static copyOf method that allows type narrowing. For example the CGIN type CAP4ConnectArg implements a copyOf method that takes an argument of the superclass type CCConnectArg. The method returns a CAP4ConnectArg object populated with the same field values as were set in the input argument. In all respects the returned value is a copy of the input argument; but because the returned value is (potentially) a more specific type than the input argument, it supports all the fields allowed by the CAPv4 protocol. Non-extendable types can also be copied, but for these types the clone() method is used instead, and the class specified in the <object> element must be the same as (or a superclass of) the class of the value copied.

The encoded byte array form and the copy-of form are mutually exclusive and cannot be used together in the same <object> element.

Variables may be used to specify the encoded value, the copied value, or individual field values. Field values can be specified either as element attributes or as nested elements. Nested elements may also be compound datatypes.

General guidelines

Below are general guidelines that apply to all object construction, with examples of how you can construct:

Calling Party Number

There are three possible ways to create a CallingPartyNumber value:

Using an encoded value

Encoded values are a byte array. Encoded byte array values are specified as a comma-separated list of hexadecimal byte values, for example:

<object
    class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber"
    encoded-value="03,13,1b,32,54,76,98,c0"/>

The encoded byte array value can also be provided from some other variable, for example:

<object
    class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber"
    encoded-value="${user.some-encoded-value}"/>
Warning If the specified variable does not exist or its value is not a byte array, then the object construction will fail and produce no result.

Specifying individual field values

A CallingPartyNumber value can be constructed by specifying values for its individual fields, for example:

<object class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber">
    <field name="nature" value="NATIONAL"/>
    <field name="number-incomplete" value="false"/>
    <field name="numbering-plan" value="ISDN"/>
    <field name="presentation" value="ALLOWED"/>
    <field name="screening" value="NETWORK_PROVIDED"/>
    <field name="address" value="*1234567890#"/>
</object>

Variables may also be used to specify the value for any field, for example:

<object class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber">
    ...
    <field name="address" value="${initial-dp.arg.calling-party-number.address}"/>
</object>
Warning The value provided for each field must be a suitable value for that field, otherwise the object construction will fail and produce no result. If a particular field value is obtained from a variable and that variable is determined to have no value, then assignment of that field will be skipped.

Using a pre-defined datatype constructor

SIS includes pre-defined datatype constructors for certain datatypes. The CallingPartyNumber type is one of these datatypes, and such a value can be constructed as shown in the following example:

<calling-party-number
    nature="NATIONAL"
    number-incomplete="false"
    numbering-plan="ISDN"
    presentation="ALLOWED"
    screening="NETWORK_PROVIDED"
    address="*1234567890#"/>
Warning In contrast to specifying individual field values, the pre-defined datatype constructors require that values for all fields be specified. However, the value provided for each field must again be a suitable value for that field, otherwise the object construction will fail and produce no result. When using the pre-defined datatype constructors, if a particular field value is obtained from a variable and that variable is determined to have no value, then object construction will also fail.

CAPv2 IP-SSP Capabilities

The CAP2IPSSPCapabilities class defines IP-SSP capabilities for the CAPv2 protocol. This value may be included in an InitialDP or AssistRequestInstructions operation. The CAP2IPSSPCapabilities class extends ExtendibleOctetString by adding a containedValue field of type CAPIPSSPCapabilities. The CAPIPSSPCapabilities datatype contains the actual structured view of the IP-SSP capabilities.

The following example illustrates how to construct a CAP2IPSSPCapabilities datatype value with a contained value:

<object class="com.opencloud.slee.resources.cgin.cap_v2.CAP2IPSSPCapabilities">
    <field name="contained-value">
        <object class="com.opencloud.slee.resources.in.datatypes.cc.CAPIPSSPCapabilities">
            <field name="ip-routing-address-supported" value="true"/>
            <field name="voice-back-supported" value="false"/>
            <field name="voice-information-via-speech-supported" value="true"/>
            <field name="voice-information-via-voice-supported" value="true"/>
            <field name="voice-generation-from-text-supported" value="false"/>
            <field name="bilateral-part">
                <bytes bytes="55,66,77"/>
            </field>
        </object>
    </field>
</object>

Copying an object

A new object can be created as a copy of another object, possibly with a different type than the original object. This is useful for narrowing type conversions; for example to change the type of an object from a CAPv2 type to a CAPv4 type, and consequently also provide access to all the fields supported by the CAPv4 type that previously weren’t available.

The following example illustrates how to construct a CAP4ConnectArg object from another object and set the CAPv4-specific legToBeConnected field in the new object to indicate leg 3:

<object class="com.opencloud.slee.resources.cgin.cap_v4.CAP4ConnectArg" copy-of="${connect.arg}">
    <field name="leg-to-be-connected">
        <object class="com.opencloud.slee.resources.cgin.callcontrol.CCLegID">
            <field name="sending-side-id">
                <object class="com.opencloud.slee.resources.in.datatypes.cc.LegType">
                    <field name="encoded-value" value="3"/>
                </object>
            </field>
        </object>
    </field>
</object>
Warning If the specified variable to copy does not exist or its value is not compatible with the specified class, then the object construction will fail and produce no result.

Enumerated Type Values

The SIS automatically converts a literal constant value assigned or compared to a enumerated datatype into its enumerated object equivalent.

Consider the following example:

<equal
    a="${initial-dp.arg.event-type-bcsm}"
    b="analyzedInformation"/>

In this case, the SIS knows that the type of the ${initial-dp.arg.event-type-bcsm} variable is the named integer type CCEventTypeBCSM — so it tries to find the enumerated value of that type, with the name analyzedInformation, for the comparison.

When the SIS can’t determine the type

In some cases, however, you may want to assign an enumerated value constant to a variable that the SIS cannot determine a concrete type for. For example, the variable may be defined as a generic NamedInteger type, or the variable may be a user-defined variable. In these situations, the SIS has no way of knowing how to convert a string or numerical constant value for assignment into anything more useful. Consider the example below:

<assign
    toVariable="${user.event-type-bcsm}"
    value="analyzedInformation"/>

Here, the SIS will assign the literal string value “analyzedInformation” to the user variable, rather than the intended enumerated value with that name.

Tip To alleviate this problem, the SIS provides an <enum> object constructor element for ENUMERATED variable types. This element requires the fully-qualified class name of the enumerated datatype and the enumerated value to be specified. The constructor returns the indicated enumerated value. For example:
<assign toVariable="${user.event-type-bcsm}">
    <enum
        class="com.opencloud.slee.resources.cgin.callcontrol.CCEventTypeBCSM"
        value="analyzedInformation"/>
</assign>
Warning If the class is unknown by the SIS, or is not an enumerated type, or the specified value is not a known value for the enumerated type, the constructor will fail.

Creating enumerated values from a constant value

Note that, as enumerated values are just named integer values, it’s also possible to create enumerated values from a constant numerical value rather than a named value. For example, the following produces the same result as the preceding example, since analyzedInformation is the named value for the integer 3 within this datatype:

<assign toVariable="${user.event-type-bcsm}>
    <enum
        class="com.opencloud.slee.resources.cgin.callcontrol.CCEventTypeBCSM"
        value="3"/>
</assign>

Generic Arrays

The <array> element can be used to construct an array of any supported datatype.

As well as arbitrary datatypes, you can make arrays of primitive and simple types such as int, java.lang.Long, and java.lang.String. Arrays can also be copied from other arrays. The <array> element requires that the fully-qualified class name of the array type be specified. The array to copy, array length, or array elements can also be provided during array construction. If none are provided, a zero-length array will be created. If an array to copy and an array length are both specified, then the created array will have a length that is the greater of the length of the array being copied and the specified length.

Array elements are evaluated and assigned to array indexes in the order they are declared. Individual array element values can be specified using either the element attribute or a nested element. The element attribute may contain the special value null to indicate an array element with no value. Nested elements may also be compound datatypes. Variables can also be used as the source of element values.

Warning

The array creation can fail and produce no result if:

  • the specified class is not an array type;

  • an array length is specified but has no value or evaluates to a non-numeric value or a numeric value less that zero;

  • an array to copy is specified but has no value, evaluates to a value that is not an array type, or elements in the array are not compatible with the array type being created;

  • both the array length and array elements are specified, but the specified length is less than the number of declared elements;

  • a specified array element value cannot be evaluated, or evaluates to a value that is not suitable for the array type; or

  • an attempt is made to assign null array elements to an array of a primitive type, such as int or boolean.

Primitive Type Array

You can construct an array of primitive types (such as int) like this:

<array class="int[]">
    <element value="0"/>
    <element value="1"/>
    <element value="${user.int-value-1}"/>
    <element value="7"/>
    <element value="${user.int-value-2}"/>
</array>

Multi-Dimensional Array

Below is a (contrived) example of how a three-dimensional CallingPartyNumber array could be created and populated with various values:

<array class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber[][][]" length="${user.some-length]}">
    <element>
        <array class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber[][]">
            <element>
                <array class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber[]">
                    <element>
                    <!-- concrete value specified using pre-defined datatype constructor -->
                    <calling-party-number
                        nature="NATIONAL"
                        number-incomplete="false"
                        numbering-plan="ISDN"
                        presentation="ALLOWED"
                        screening="NETWORK_PROVIDED"
                        address="12345"/>
                    </element>

                    <!-- an empty element -->
                    <element value="null"/>

                    <element>
                        <!-- concrete value specified using generic object constructor -->
                        <object class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber">
                            <field name="nature" value="INTERNATIONAL"/>
                            <field name="number-incomplete" value="true"/>
                            <field name="numbering-plan" value="ISDN"/>
                            <field name="presentation" value="ALLOWED"/>
                            <field name="screening" value="NETWORK_PROVIDED"/>
                            <field name="address" value="999887"/>
                        </object>
                    </element>

                    <!-- element value from a variable -->
                    <element value="${initial-dp.arg.calling-party-number}"/>
                </array>
            </element>
        </array>
    </element>

    <element>
        <!-- an array with a specified length, but no elements defined -->
        <array class="com.opencloud.slee.resources.in.datatypes.cc.CallingPartyNumber[][]" length="1"/>
    </element>
</array>

Copying an Array

The following example makes a copy of the genericNumbers field in a Connect operation argument:

<array class="com.opencloud.slee.resources.in.datatypes.cc.GenericNumber[]" copy-of="${connect.arg.generic-numbers}"/>

Byte Arrays

Byte arrays may be constructed using either the bytes pre-defined datatype or a generic array construction.

The latter has the advantage that individual array element values may be obtained from script variables (which the pre-defined datatype constructor does not allow).

Pre-defined datatype constructor

Using the pre-defined datatype constructor, the byte array content is specified using a comma-separated list of two-digit hexadecimal values. For example:

<bytes bytes="68,65,6c,6c,6f"/>

Generic array constructor

The same value can be constructed using a generic array constructor, like this:

<array class="byte[]">
    <element value="104"/>
    <element value="101"/>
    <element value="108"/>
    <element value="108"/>
    <element value="111"/>
</array>
Warning The generic array constructor does not support hexadecimal input, so values must be converted to decimal.

Variables

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
 INTEGER

int, long, Integer, Long, or BigInteger

 DECIMAL

float, double, Float, Double, or BigDecimal

 BOOLEAN

boolean or Boolean

 BIT_STRING
 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)

SIS Common Variables

The following variables are available in all SIS expressions, regardless of protocol.

User variables

user.<var-name>

Description

A user-defined variable. User-defined variables may have any name provided the name begins with user.. A user-defined variable converts to the type of the value assigned to it. For example, if a user-defined variable is assigned the value of the calling-party-number.address variable, the user-defined variable effectively becomes a Text variable. A user-defined variable may be reassigned and thus converted from one variable type to another, for example from String to Integer, however type conversion is not recommended (for clarity reasons).

Warning The <var-name> portion of the variable name is case-sensitive. For example, the variable names user.foo and user.FOO refer to two different user-defined variables.

Valid values

Any

Type

User

Assignable?

YES

Array variables

array.current-element

Description

The current element of an array when executing an array index function.

Valid values

Any

Type

Any

Assignable?

NO

array.last-index

The matching index of the last executed array index function. If the last array index function found no matching element, this variable has no value.

Type

Any

Assignable?

NO

IN-Specific Variables

The conditional expressions included in SIS macros, triggers, and compositions may use any of the following variable names to reference parameters of request events or other values computed during the course of call processing.

Protocol variables

Protocol variables are always available to a composition.

protocol

Description

The SS7 protocol of the dialog the initial request was received on.

Valid values

CAP or INAP.

Type

String

Assignable?

NO

protocol.variant

Description

The variant or version of the dialog’s protocol.

Valid values

For the CAP protocol, valid variant values are: v1, v2, and v3 representing the respective CAP protocol phases. For the INAP protocol, the valid variant values are ETSI CS1, Ericsson CS1, Ericsson CS1+, and Nokia CS1.

Type

String

Assignable?

NO

Open Request variables

Variables relating to the Open Request dialog primitive are shown below.

open-request

Description

The Open Request itself.

Valid values

Type

Compound

Assignable?

NO

open-request.application-context

Description

The Open Request’s Application Context parameter.

Valid values

Type

Compound

Assignable?

NO

open-request.application-context.protocol

Description

The name of the protocol, as denoted by CGIN, defining the application context. For example cap_v2 or etsi_inap_cs1.

Valid values

Any network protocol name.

Type

String

Assignable?

NO

open-request.application-context.acn

Description

The application context name. This is the value reference name of the application context as defined by the ASN.1. For example cap-v2-gsmSSF-to-gsmSCF-AC or core-INAP-CS1-SSP-to-SCP-AC.

Valid values

Any application context name.

Type

String

Assignable?

NO

open-request.originating-sccp-address

Description

The Open Request’s Originating SCCP Address parameter.

Valid values

Type

Compound

Assignable?

NO

open-request.originating-sccp-address.type

Description

The Encoding Type of the Open Request’s Originating SCCP Address parameter.

Valid values

C7, A7, J7, or CH7.

Type

String

Assignable?

NO

open-request.originating-sccp-address.routing-indicator

Description

The Routing Indicator of the Open Request’s Originating SCCP Address parameter. The routing indicator is a boolean value indicating "route on PC/SSN?".

Valid values

pcssn/true or gt/false.

Type

Boolean

Assignable?

NO

open-request.originating-sccp-address.point-code

Description

The Point Code of the Open Request’s Originating SCCP Address parameter, expressed as a single integer value.

Valid vlues

Any integer value in the range 0 — 16777215.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.triple

Description

The Point Code of the Open Request’s Originating SCCP Address parameter, expressed as a triplet delimited by forward slash / characters.

If the encoding type of the address is C7, the triplet represents the point code decoded using the zone, area, and signal-point format. Otherwise, the triplet represents the point code decoded using the member, cluster, and network format.

Valid values

A triplet of integer values, delimited by / characters.

Type

String

Assignable?

NO

open-request.originating-sccp-address.point-code.zone

Description

The Zone field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.area

Description

The Area field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.signal-point

Description

The Signal Point field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.member

Description

The Member field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.cluster

Description

The Cluster field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.point-code.network

Description

The Network field of the Point Code of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.ssn

Description

The Subsystem Number of the Open Request’s Originating SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.global-title-indicator

Description

The Global Title indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

0000, 0001, 0010, 0011, 0100 (binary representations of the indicator integer values), or any valid integer value for the indicator.

Type

Enumerated

Assignable?

NO

open-request.originating-sccp-address.address

Description

The Global Title Address digits of the Open Request’s Originating SCCP Address parameter.

Valid values

Any valid network address string.

Type

String

Assignable?

NO

open-request.originating-sccp-address.nature

Description

The Global Title Nature of Address indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

unknown, subscriber, national, international, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.numbering-plan

Description

The Global Title Numbering Plan indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

unknown, isdn, generic, data, telex, maritime-mobile, land-mobile, isdn-mobile, private, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.translation-type

Description

The Global Title Translation Type indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

Any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.encoding-scheme

Description

The Global Title Encoding Scheme indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

bcd-odd, bcd-even, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.originating-sccp-address.national

Description

The Global Title National indicator of the Open Request’s Originating SCCP Address parameter.

Valid values

Any valid boolean value for the indicator.

Type

Boolean

Assignable?

NO

open-request.destination-sccp-address

Description

The Open Request’s Destination SCCP Address parameter.

Valid values

Type

Compound

Assignable?

NO

open-request.destination-sccp-address.type

Description

The Encoding Type of the Open Request’s Destination SCCP Address parameter.

Valid values

C7, A7, J7, or CH7.

Type

String

Assignable?

NO

open-request.destination-sccp-address.routing-indicator

Description

The Routing Iindicator of the Open Request’s Destination SCCP Address parameter. The routing indicator is a boolean value indicating "route on PC/SSN?".

Valid values

pcssn/true or gt/false.

Type

Boolean

Assignable?

NO

open-request.destination-sccp-address.point-code

Description

The Point Code of the Open Request’s Destination SCCP Address parameter, expressed as a single integer value.

Valid values

Any integer value in the range 0 — 16777215.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.triple

Description

The Point Code of the Open Request’s Destination SCCP Address parameter, expressed as a triplet delimited by forward slash / characters.

If the encoding type of the address is C7, the triplet represents the point code decoded using the zone, area, and signal-point format. Otherwise, the triplet represents the point code decoded using the member, cluster, and network format.

Valid values

A triplet of integer values, delimited by / characters.

Type

String

Assignable?

NO

open-request.destination-sccp-address.point-code.zone

Description

The Zone field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.area

Description

The Area field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.signal-point

Description

The Signal Point field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.member

Description

The Member field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.cluster

Description

The Cluster field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.point-code.network

Description

The Network field of the Point Code of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.ssn

Description

The Subsystem Number of the Open Request’s Destination SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.global-title-indicator

Description

The Global Title indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

0000, 0001, 0010, 0011, 0100 (binary representations of the indicator integer values), or any valid integer value for the indicator.

Type

Enumerated

Assignable?

NO

open-request.destination-sccp-address.digits

Description

The Global Title Digits of the Open Request’s Destination SCCP Address parameter.

Valid values

Any valid network address string.

Type

String

Assignable?

NO

open-request.destination-sccp-address.nature

Description

The Global Title Nature of Address indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

unknown, subscriber, national, international, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.numbering-plan

Description

The Global Title Numbering Plan indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

unknown, isdn, generic, data, telex, maritime-mobile, land-mobile, isdn-mobile, private, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.translation-type

Description

The Global Title Translation Type indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

Any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.encoding-scheme

Description

The Global Title Encoding Scheme indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

bcd-odd, bcd-even, or any valid integer value for the indicator.

Type

Integer

Assignable?

NO

open-request.destination-sccp-address.national

Description

The Global Title National indicator of the Open Request’s Destination SCCP Address parameter.

Valid values

Any valid boolean value for the indicator.

Type

Boolean

Assignable?

NO

Open Response variables

Variables relating to the Open Response generated by the SIS for an incoming dialog are shown below.

If the open-response.responder-sccp-address variable is assigned a non-null value during trigger evaluation, either by a trigger condition or by an Service Composition Selection extension component, then this value will be used as the responder SCCP address in the dialog Open Accept sent by the SIS to the network after trigger evaluation completes. This variable has no further meaning to the SIS after the Open Accept has been sent.

open-response.responder-sccp-address

Description

The Open Response’s Responder SCCP Address parameter.

Valid values

This variable may be assigned in XML, for example during trigger evaluation, using an SCCP Address Format string.

Type

Compound

Assignable?

YES

open-response.responder-sccp-address.type

Description

The Encoding Type of the Open Response’s Responder SCCP Address parameter.

Valid values

C7, A7, J7, or CH7.

Type

String

Assignable?

YES

open-response.responder-sccp-address.routing-indicator

Description

The Routing Iindicator of the Open Response’s Responder SCCP Address parameter. The routing indicator is a boolean value indicating "route on PC/SSN?".

Valid values

pcssn/true or gt/false.

Type

Boolean

Assignable?

YES

open-response.responder-sccp-address.point-code

Description

The Point Code of the Open Response’s Responder SCCP Address parameter, expressed as a single integer value.

Valid values

Any integer value in the range 0 — 16777215.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.triple

Description

The Point Code of the Open Response’s Responder SCCP Address parameter, expressed as a triplet delimited by forward slash / characters.

If the encoding type of the address is C7, the triplet represents the point code decoded using the zone, area, and signal-point format. Otherwise, the triplet represents the point code decoded using the member, cluster, and network format.

Valid values

A triplet of integer values, delimited by / characters.

Type

String

Assignable?

YES

open-response.responder-sccp-address.point-code.zone

Description

The Zone field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.area

Description

The Area field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.signal-point

Description

The Signal Point field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 7.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.member

Description

The Member field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.cluster

Description

The Cluster field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.point-code.network

Description

The Network field of the Point Code of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.ssn

Description

The Subsystem Number of the Open Response’s Responder SCCP Address parameter.

Valid values

Any integer value in the range 0 — 255.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.global-title-indicator

Description

The Global Title indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

0000, 0001, 0010, 0011, 0100 (binary representations of the indicator integer values), or any valid integer value for the indicator.

Type

Enumerated

Assignable?

YES

open-response.responder-sccp-address.digits

Description

The Global Title Digits of the Open Response’s Responder SCCP Address parameter.

Valid values

Any valid network address string.

Type

String

Assignable?

YES

open-response.responder-sccp-address.nature

Description

The Global Title Nature of Address indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

unknown, subscriber, national, international, or any valid integer value for the indicator.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.numbering-plan

Description

The Global Title Numbering Plan indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

unknown, isdn, generic, data, telex, maritime-mobile, land-mobile, isdn-mobile, private, or any valid integer value for the indicator.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.translation-type

Description

The Global Title Translation Type indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

Any valid integer value for the indicator.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.encoding-scheme

Description

The Global Title Encoding Scheme indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

bcd-odd, bcd-even, or any valid integer value for the indicator.

Type

Integer

Assignable?

YES

open-response.responder-sccp-address.national

Description

The Global Title National indicator of the Open Response’s Responder SCCP Address parameter.

Valid values

Any valid boolean value for the indicator.

Type

Boolean

Assignable?

YES

Operation variables

The set of operations supported by the SIS on a particular dialog is dependent on the protocol and application context of the dialog, and may vary depending on the set of protocols supported by a particular SIS-IN package.

For a comprehensive list of all the protocol-specific operation variables supported by the SIS, please refer to the documentation included with the SIS-IN package.

SIP-Specific Variables

The conditional expressions included in SIS macros, triggers, and compositions may use any of the following variable names to reference parameters of request events or other values computed during the course of call processing.

Request variables

All requests contain these variables.

method

Description

The SIP method of the request.

Valid values

Any SIP method name, for example INVITE or REGISTER.

Type

String

Assignable?

NO

uri

Description

The Request-URI of the request.
Contains additional URI variables.

Valid values

A valid SIP or TEL URI.

Type

String

Assignable?

YES

<header-name>

Description

Any header name may be used as a variable, for example, From, To, Route, or Call-ID (case-insensitive). This evaluates to the string representation of the first header value.
Contains additional header variables.

Valid values

A valid SIP header (according to the header’s syntax).

Type

String

Assignable?

YES

message-body

Description

The message body of the request, if it has a content-type that can be represented as a string, such as application/sdp or text/plain.

Valid values

Any SDP or text content.

Type

String

Assignable?

NO

Header variables

Header variables may contain the following attributes. For example, route.uri will return the URI in the Route header. The property from.param.tag will return the tag parameter in the From header.

<header-name>.uri

Description

If the header is an address header, then this evaluates to the URI of the header’s address. Examples of address headers are From, To, Route, Contact, and P-Asserted-Identity.
Contains additional URI variables.

Valid values

A valid SIP or TEL URI.

Type

String

Assignable?

YES

<header-name>.display-name

Description

If the header is an address header, then this evaluates to the display-name of the header’s address.

Valid values

Any string.

Type

String

Assignable?

NO

<header-name>.param.<param-name>

Description

If the header contains optional parameters, then this property evaluates to the string value of the named parameter.

Valid values

Any string.

Type

String

Assignable?

YES

<header-name>.count

Description

Returns the number of header values present in the message.

Type

Integer

Assignable?

NO

URI variables

All URI variables may contain the following attributes. For example, uri.host will return the host part of the Request-URI. To extract the user part of the To header, the property used would be to.uri.user.

uri.scheme

Description

The URI scheme.

Valid values

Possible values are sip, sips or tel.

Type

String

Assignable?

NO

uri.user

Description

For SIP URIs, the user part of the URI. For Tel URLs this is undefined.

Valid values

A valid SIP user name.

Type

String

Assignable?

YES

uri.host

Description

For SIP URIs, the host part of the URI. For Tel URLs this is undefined.

Valid values

A host name or IP address.

Type

String

Assignable?

NO

uri.port

Description

For SIP URIs, the port number of the URI. If the URI does not specify a port, the default values are 5060 for UDP and TCP, or 5061 for TLS. For Tel URLs this is undefined.

Valid values

A valid SIP port number.

Type

Integer

Assignable?

YES

uri.tel

Description

For Tel URLs, this is the phone number with visual separators removed. For SIP URIs, this is the value of the user part only if the parameter user=phone is present, otherwise it is not defined.

Valid values

Type

String

Assignable?

YES

uri.param.<param-name>

Description

If the URI contains optional parameters, then this property evaluates to the string value of the named parameter.

Valid values

Any string.

Type

String

Assignable?

YES

Examples

The following table presents examples of using SIP-specific variables, and what they return.

uri.user

Example

 INVITE sip:alice@foo.com SIP/2.0

Returns

alice
the user part of the Request-URI

from.uri.user

Example

 From: <sip:joe@abc.com>

Returns

joe
the user part of the From header’s URI.

to.uri.host

Example

 To: <sip:fred@acme.com>

Returns

acme.com
the host part of the To header’s URI

contact.param.expires

Example

 Contact: sip:bob@10.0.0.1;expires=3600

Returns

3600
the value of the expires parameter in the Contact header

p-asserted-identity.uri

Example

 P-Asserted-Identity: <sip:mary@company.com>

Returns

sip:mary@company.com
the URI in the P-Asserted-Identity header

User Extensions

While the SIS is very flexible, its triggers and service composition scripts cannot do everything. You may want to extend its behaviour by writing extension components, using Java.

The SIS supports two type of extension component:

Service composition selection extension

When trigger composition selection is too complex for predefined SIS composition selectors to describe, you can use a service composition selection (SCS) extension. For example, you might need to interrogate an external subscription database or analyse particular initial request parameters to determine which composition to select.

You implement an SCS extension as a JAIN SLEE service that interacts with the SIS, using either the:

When the SIS evaluates a trigger that contains an extension selector, it fires an event to the extension component specified in the selector. The event that is fired, and the SLEE activity the event is fired on, depends on the context of the call:

Context Activity type Event type

SIP call

IN call

The event object fired to the extension component contains the initial request that the SIS received. The extension component examines the initial request to determine which composition should be selected. The extension component then reports one of three possible outcomes back to the SIS:

  • It has successfully located and selected a composition, and returns that composition’s identifier.

  • It cannot determine a suitable composition.

  • It terminates trigger processing and returns a protocol-specific response (depending on the context of the call). The SIS then behaves the same as when encountering a terminate clause; however the extension component determines whether or not the response counts as an error condition.

Signalling interceptor extension

When manipulating messages flowing in and/or out of a service is too complex for the composition scripting language, you can use an interceptor extension. For example, you might need to interrogate an external network resource to update some signaling parameters.

You implement an interceptor extension as a JAIN SLEE service that interacts with the SIS using either the:

An interceptor extension may be invoked from within any composition interceptor.

To invoke an interceptor extension component, the SIS fires an event to it. The event that is fired, and the SLEE activity the event is fired on, depends on the call protocol:

Protocol Activity type Event type

SIP

varies, depending on the intercepted input or output message

IN

varies, depending on the intercepted input or output message(s)

Note An interceptor extension cannot itself perform call control operations, such as sending messages to the network, on the original call it was invoked for. It can however use any API available to it to create new SLEE activities representing new interactions in the network, for any resource it needs to interact with.

SIS Management

As with Rhino:

  • administrators manage the SIS using Java Management Extensions (JMX) MBeans

  • SIS implementations by default provide a command-line tool and Ant tasks to conveniently access the MBeans. (The command-line client, sis-console, is an extension of the rhino-console that supports a set of SIS commands as well as the normal Rhino commands.)

Tip
See the Admin Guides for details

The SIS Administration Guide describes how to perform various management tasks using command-line tools, Ant tasks, and related MBean operations (for example, for custom JMX clients that need programmatic access to them).

SIS Modules

A SIS module is an optional feature of the SIS that can be installed separately. Each module requires a right-to-use license. A module is packaged as a zip archive that you uncompress from <rhino-home>.
All modules install to:

<rhino-home>/sis/<protocol>/<sis-version>/modules/<module-name>/<module-version>/

Each SIS module includes: a command-line extension library with additional management commands
(beyond sis-console); and an install directory with the software, configuration files, and an installer application.

Installation package

Each module installation package has the following structure:

  • the install directory:

    sis/<protocol>/<sis-version>/modules/<module-name>/<module-version>/install/
  • a shell script that runs the installer application:

    sis/<protocol>/<sis-version>/modules/<module-name>/<module-version>/install/install-module.sh
  • a subdirectory with all deployable units, and any other files and directories required to install the module:

    sis/<protocol>/<sis-version>/modules/<module-name>/<module-version>/install/units

Licensing and activation

The module installation process:

  • checks that module functions are licensed (some module functions may be covered by your SIS license)

  • prompts you to install a license

  • tries to activate the module.

 

Tip
  • You can always install a license for and manually activate a module after installing it.

  • See the SIS Administration Guide for more details about installing and configuring the optional modules available with this release.

SIP Session Replication

As of version 2.6.1, the SIS-SIP EasySIP Resource Adaptor supports session replication. This means that SIP dialogs can be failed over to other cluster nodes if the original node failed.

Overview of Operation

Session replication is disabled by default. It can be enabled for all dialogs, or alternatively an application can specify that a particular dialog must be replicated, using an API call.

In the SIS-SIP EasySIP API, a SIP dialog is represented by the SipSession type.

Normal Operation

When replication is enabled, the SIS initially creates the dialog state in local memory. When the dialog reaches the "Confirmed" state, the SIS writes the dialog state to its replicated store. This is either Rhino’s in-memory database, or an external key-value store, such as Cassandra.

Note Early dialogs (dialogs where the initial request has not yet received a 2xx response) are not replicated.

When the creating node receives mid-dialog requests, it processes the requests normally using the dialog state in local memory. When the SIP transaction completes, the updated dialog state is written to the replicated store.

When a dialog-terminating request such as BYE is processed, the local and replicated dialog state is removed when the transaction completes.

Failover and Recovery

If a node fails, it is assumed that an external mechanism, such as DNS or a load balancer, will direct SIP traffic to the surviving nodes in a cluster.

When a node receives a mid-dialog request for a dialog that does not exist in local memory, it attempts to load the dialog from its replicated state.

  • If the dialog is found, it is copied into local memory and the node can continue processing the mid-dialog request.

  • If the dialog is not found, then the SIS node rejects the request with a 481 Call/Transaction Does Not Exist response.

When the original node recovers, failed-over dialogs do not migrate back to that node. Rather, the dialog remains on the node that last took over ownership of the dialog, as long as that node is alive. This is managed by Session Ownership.

Session Ownership

The SIS uses Rhino’s Session Ownership facility to track which node is currently responsible for a dialog. This is to ensure that requests in a dialog are processed on the same node if possible, for consistency. Otherwise dialog state could be updated by several nodes, leading to errors. In other words, dialogs are "sticky" and will only migrate to another node in the event of a node failure.

When a SIS node receives a mid-dialog request for a dialog that it does not currently own, the request is automatically proxied to the owning node, as determined by the Session Ownership facility. If the owning node is down, then the current node may take over ownership of the dialog and resume processing the request. The Session Ownership facility ensures that subsequent requests for this dialog will be directed to the correct node.

Note Session Ownership records are not automatically created by the SIS; they must be created explicitly by the application processing the initial request. The Sentinel VoLTE session tracking features perform this function.

Configuration for session replication

Enabling Session Replication and Session Ownership requires some configuration changes in the Rhino platform, as well as the SIS instance.

Note Session Replication and Session Ownership are only available in SIS 2.6.1 or later, which requires Rhino 2.6.1 or later.

Replication method

The replication method is determined by the Rhino namespace that the SIS instance is deployed into.

Rhino 2.6.1 and later supports two replication methods:

  • savanna — state is replicated to cluster nodes using Rhino’s Savanna reliable multicast protocol.

  • key-value-store — state is written to an external key-value store database, currently Cassandra.

The key-value-store method is preferred for large clusters.

Session ownership

Rhino’s Session Ownership facility is automatically available to the SIS instance if its namespace has session ownership enabled. This requires configuring a Session Ownership store in Rhino, and creating a namespace with session ownership support.

Session replication mode

The sessionReplicationMode configuration property on the SIS-SIP EasySIP RA determines whether session replication will be used. This property has three values:

  • disabled — no replication will be used.

  • enabled — replication is enabled.

  • automatic — replication is enabled if the replication method is key-value-store.

The default value is automatic.

Replicate by default

When replication is enabled in the SIS, there is also the option to selectively enable it on particular sessions. This is controlled by the replicateByDefault boolean configuration property:

  • If true, and session replication is enabled, all sessions will be replicated.

  • If false, and session replication is enabled, then a session is only replicated on demand, when the application calls SipSession.startReplicating().

The default value is true.

When startReplicating() is called, the SIS replicates the session as soon as it is able to. If the dialog is not yet confirmed, replication will begin when it reaches the confirmed state. If the dialog is already confirmed, replication begins immediately, storing the current dialog state.

Dynamic SRV Name Format

To make use of per-node SRV addresses, the DynamicSRVNameFormat network interface property must be configured.

The value of this property is a string that describes how a DNS SRV name is derived from the node’s IP address. The special token ${IP} is replaced with a DNS-safe encoding of the node’s IP address, that may be used as a domain name component.

For example if DynamicSRVNameFormat is tas-${IP}.site1.home1.net, then the node with IP address 192.168.10.1 will use the hostname tas-192-168-10-1.site1.home1.net in its Contact or Record-Route URIs.

For IPv6 addresses, each 2-octet group is hex-encoded and delimited with a hyphen. For example the address 1080::8:800:200C:417A is encoded as 1080-0000-0000-0000-0008-0800-200c-417a.

Per-node SRV addresses

For dialogs created by the SIS, mid-dialog requests are routed to the SIP URI provided in the Contact or Record-Route headers of the SIS’s dialog-creating request or response. By default this URI will contain the IP address of the SIS node. This means in the event of a node failure, mid-dialog requests cannot fail over to another IP address, so will fail.

The SIS already had the capability to use virtual addresses in its URIs, using the VirtualAddresses network interface property. The virtual address could be a DNS name that resolves to a load balancer address, or it might refer to a DNS NAPTR, SRV or A (address) record.

In the event of a node failure, some load balancers may be able to ensure that subsequent requests in a dialog are routed to the same surviving node. But for sites relying on DNS and SIP’s standard RFC 3263 DNS procedures for locating servers, there is no guarantee that subsequent requests in a dialog will be routed to the same node after a failure — the single virtual address in the SIS’s URI can resolve to any SIS node.

To support DNS failover in a more predictable fashion, the SIS may use per-node SRV addresses in its own SIP URIs. These are DNS SRV names generated from the SIS node’s IP address, so they are specific to that node. The operator can provision corresponding DNS SRV records to specify the primary and backup nodes. Requests will be routed to the given node when it is available, but will fail over to the given backup nodes by the rules of RFC 3263.

The use of this feature requires that the Session Ownership subsystem is available, and that each SIP dialog has a Session Ownership record.

Example

Say we have three SIS nodes, hostnames sis-1.home1.net, sis-2.home1.net and sis-3.home1.net. Their address records in DNS are:

sis-1.home1.net    <ttl> IN    A     192.168.10.1
sis-2.home1.net    <ttl> IN    A     192.168.10.2
sis-3.home1.net    <ttl> IN    A     192.168.10.3

By configuring the DynamicSRVNameFormat network interface property with value ip-${IP}.home1.net, the SIS nodes will use URIs of the form sip:ip-192-168-10-1;lr;transport=tcp.

When DynamicSRVNameFormat is configured, the SIS URIs always specify a transport parameter but do not specify a port. This is to ensure that SIP clients perform a DNS SRV lookup on the host name as per RFC 3263.

The operator provisions the corresponding DNS SRV records:

;; SRV address                                           Priority  Weight  Port   Target
_sip._tcp.ip-192-168-10-1.home1.net.  <ttl> IN    SRV    0         1       5060   sis-1.home1.net.
_sip._tcp.ip-192-168-10-1.home1.net.  <ttl> IN    SRV    10        1       5060   sis-2.home1.net.
_sip._tcp.ip-192-168-10-1.home1.net.  <ttl> IN    SRV    10        1       5060   sis-3.home1.net.

_sip._tcp.ip-192-168-10-2.home1.net.  <ttl> IN    SRV    0         1       5060   sis-2.home1.net.
_sip._tcp.ip-192-168-10-2.home1.net.  <ttl> IN    SRV    10        1       5060   sis-3.home1.net.
_sip._tcp.ip-192-168-10-2.home1.net.  <ttl> IN    SRV    10        1       5060   sis-1.home1.net.

_sip._tcp.ip-192-168-10-3.home1.net.  <ttl> IN    SRV    0         1       5060   sis-3.home1.net.
_sip._tcp.ip-192-168-10-3.home1.net.  <ttl> IN    SRV    10        1       5060   sis-1.home1.net.
_sip._tcp.ip-192-168-10-3.home1.net.  <ttl> IN    SRV    10        1       5060   sis-2.home1.net.
Note Corresponding records would be needed for UDP (_sip._udp) and TLS (_sips._tcp) transports, if used.

For each per-node SRV address, there are 3 records. The first points to the node’s own host name, and the other records point to the 2 other node’s host names. The addresses are always tried in priority order (lowest to highest), by the rules of RFC 3263 and RFC 2782.

If node sis-1 fails, mid-dialog requests routed to sip:ip-192-168-10-1.home1.net will go to either sis-2 or sis-3 - assuming that both are available. This ensures that dialogs are "sticky" to the node that created them and are only sent to other nodes in the presence of a failure. Mid-dialog requests are automatically routed to one of the other nodes, and through the use of the Session Ownership subsystem are proxied to a single node such that requests for the same dialog are always processed on one node.

Initial requests

Initial requests can be directed to a virtual address, DNS NAPTR or SRV address that distributes traffic over all nodes in the cluster. So for the example cluster above, using a DNS SRV address we can say that all nodes have equal priority and weight:

;; SRV address                               Priority  Weight  Port   Target
_sip._tcp.sis.home1.net.  <ttl> IN    SRV    10        1       5060   sis-1.home1.net.
_sip._tcp.sis.home1.net.  <ttl> IN    SRV    10        1       5060   sis-2.home1.net.
_sip._tcp.sis.home1.net.  <ttl> IN    SRV    10        1       5060   sis-3.home1.net.

When a SIP client sends an initial request to the URI sip:sis.home1.net;transport=tcp, it will automatically select one of the three nodes at random as the destination for that request.

The address of the SIS in the network, for example its IMS public service identity (PSI) or the address used in initial filter criteria (iFC), should be a virtual address as above that represents the SIS cluster.

EasySIP API changes

Several enhancements were made to the EasySIP API to support SIP session replication.

Encoding and decoding of SIP messages

SipMessage objects may now be easily encoded to byte streams and back. This makes it easy to store messages in SBB CMP fields, for example. See SipFactory.encodeMessage() and SipFactory.decodeMessage().

Using SipMessages stored in CMP

Using Rhino’s datatype codec support, it is possible to create CMP fields that store a SipMessage directly, rather than as a byte array. Sentinel’s SipMessageCodec class is an example.

If it is a requirement to store an IncomingSipRequest in CMP, and use that request to create responses after it has been stored, then the CMP field must satisfy the following requirements:

For example:

import com.opencloud.rhino.cmp.PassByReference;
import com.opencloud.rhino.cmp.codecs.DatatypeCodecType;
import com.opencloud.sentinel.multileg.SipMessageCodec;
import static com.opencloud.rhino.cmp.PassByReference.Scope.PERMANENT;

@DatatypeCodecType(SipMessageCodec.class)
@PassByReference(scope = PERMANENT)
public abstract SipMessage getInitialRequest();
public abstract void setInitialRequest(SipMessage request);

This will allow the request to create and send responses as long as it is restored on the same node where it was created. Once the request is restored on a different node however, it can no longer be used for creating responses. The request can still be inspected to obtain header and body values.

Replicate sessions on demand

The method SipSession.startReplicating() requests that the session be replicated if possible. It is only meaningful if the replicateByDefault boolean configuration property is false.

The method may be called at any point in the session’s lifetime. The session will not actually be replicated until it reaches the "Confirmed" state. If the session is already in the "Confirmed" state when the method is invoked, replication begins immediately. Multiple invocations of this method have no effect.

Obtain dialog ID for session

The SipSession.getDialogID() method gets the session’s DialogID, consisting of Call-ID, local and remote tags.

The string form of this dialog ID may be used as the tracking key in the Session Ownership facility.

Internal Application Server URI

Each SIS instance has its own unique URI, referred to as the internal application server URI (AS URI). This is a SIP URI used by the SIS for its own communication between SIS nodes. Currently this is used when Session Ownership determines that a mid-dialog request must be handled by another node.

Applications must use the the internal AS URI as the "owner URI" for a session ownership record. The SipFactory methods SipFactory.getInternalASURI() and SipFactory.isInternalASURI() are used to obtain and check these URIs.

Appendix A: SIS XML Schema

Below are the XML schema definition files that make up the SIS XML schema.

File What it defines

common types used by the SIS schema

conditions used in SIS expressions

string-manipulation functions used in SIS expressions

array-manipulation functions used in SIS expressions

the SIS composition component

the SIS trigger component

the SIS macro component

the SIS interceptor component

SIS datatypes specific to IN

IN extensions to the SIS composition component

IN extensions to the SIS trigger component

IN extensions to the SIS interceptor component

SIS datatypes specific to SIP

SIP extensions to the SIS composition component

SIP extensions to the SIS trigger component

SIP extensions to the SIS interceptor component

datatypes-1.3.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:annotation>
    <xs:documentation>
      This no-namespace schema is included by the SIS Trigger, Macro, Composition,
      and Interceptor schemas. It defines types common to all schemas.
    </xs:documentation>
  </xs:annotation>

  <xs:simpleType name="SignificantName">
    <xs:annotation>
      <xs:documentation>
        These names will have all redundant whitespace stripped, and must contain
        at least one non-whitespace character.
      </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:token">
      <xs:minLength value="1"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:group name="ServiceID">
    <xs:sequence>
      <xs:element name="service-name" type="SignificantName"/>
      <xs:element name="service-vendor" type="SignificantName"/>
      <xs:element name="service-version" type="SignificantName"/>
    </xs:sequence>
  </xs:group>

  <xs:group name="TriggerID">
    <xs:sequence>
      <xs:element name="trigger-name" type="SignificantName"/>
      <xs:element name="trigger-vendor" type="SignificantName"/>
      <xs:element name="trigger-version" type="SignificantName"/>
    </xs:sequence>
  </xs:group>

  <xs:group name="MacroID">
    <xs:sequence>
      <xs:element name="macro-name" type="SignificantName"/>
      <xs:element name="macro-vendor" type="SignificantName"/>
      <xs:element name="macro-version" type="SignificantName"/>
    </xs:sequence>
  </xs:group>

  <xs:group name="CompositionID">
    <xs:sequence>
      <xs:element name="composition-name" type="SignificantName"/>
      <xs:element name="composition-vendor" type="SignificantName"/>
      <xs:element name="composition-version" type="SignificantName"/>
    </xs:sequence>
  </xs:group>

  <xs:group name="InterceptorID">
    <xs:sequence>
      <xs:element name="interceptor-name" type="SignificantName"/>
      <xs:element name="interceptor-vendor" type="SignificantName"/>
      <xs:element name="interceptor-version" type="SignificantName"/>
    </xs:sequence>
  </xs:group>

  <xs:complexType name="MacroRefType">
    <xs:sequence>
      <xs:element name="description" minOccurs="0"/>
      <xs:group ref="MacroID"/>
      <xs:element name="macro-alias" type="SignificantName"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="CompositionRefType">
    <xs:sequence>
      <xs:element name="description" minOccurs="0"/>
      <xs:group ref="CompositionID"/>
      <xs:element name="composition-alias" type="SignificantName"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="TerminateType">
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>
</xs:schema>

conditions-1.6.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:include schemaLocation="datatypes-1.3.xsd"/>
  <xs:include schemaLocation="string-manipulator-datatypes-1.2.xsd"/>
  <xs:include schemaLocation="array-manipulator-datatypes-1.1.xsd"/>
  <xs:include schemaLocation="in-sis-datatypes-1.5.xsd"/>

  <xs:annotation>
    <xs:documentation>
      This no-namespace schema is included by the SIS Trigger, Macro and Composition
      schemas. It defines conditions that are used in scripts and macros.
    </xs:documentation>
  </xs:annotation>

  <xs:group name="ConditionGroup">
    <xs:annotation>
      <xs:documentation>
        This choice group defines the elements that may be used in a script
        where a condition is expected.
      </xs:documentation>
    </xs:annotation>
    <xs:choice>
      <xs:element ref="true"/>
      <xs:element ref="false"/>
      <xs:element ref="not"/>
      <xs:element ref="and"/>
      <xs:element ref="or"/>
      <xs:element ref="equal"/>
      <xs:element ref="not-equal"/>
      <xs:element ref="macro-satisfied"/>
      <xs:element ref="assign"/>
      <xs:element ref="delete"/>
      <xs:element ref="less-than"/>
      <xs:element ref="greater-than"/>
      <xs:element ref="present"/>
      <xs:element ref="string-starts-with"/>
      <xs:element ref="string-ends-with"/>
      <xs:element ref="string-contains"/>
      <xs:element ref="string-matches"/>
    </xs:choice>
  </xs:group>

  <xs:element name="true" type="EmptyType"/>
  <xs:element name="false" type="EmptyType"/>
  <xs:element name="not" type="ConditionType"/>
  <xs:element name="and" type="MultiConditionType"/>
  <xs:element name="or" type="MultiConditionType"/>
  <xs:element name="equal" type="CompareType"/>
  <xs:element name="not-equal" type="CompareType"/>
  <xs:element name="less-than" type="CompareType"/>
  <xs:element name="greater-than" type="CompareType"/>
  <xs:element name="macro-satisfied" type="MacroSatisfiedType"/>
  <xs:element name="assign" type="AssignType"/>
  <xs:element name="delete" type="DeleteType"/>
  <xs:element name="present" type="PresentType"/>
  <xs:element name="string-starts-with" type="StringStartsWithType"/>
  <xs:element name="string-ends-with" type="StringEndsWithType"/>
  <xs:element name="string-contains" type="StringContainsType"/>
  <xs:element name="string-matches" type="StringMatchesType"/>

  <xs:complexType name="EmptyType"/>

  <xs:complexType name="PresentType">
    <xs:attribute name="variable" type="SignificantName" use="required"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="CompareType">
    <xs:choice minOccurs="0" maxOccurs="2">
      <xs:element ref="value"/>
      <xs:group ref="StringManipulators"/>
      <xs:element name="array-length" type="ArrayLengthType"/>
      <xs:group ref="INSISDataTypes"/>
    </xs:choice>
    <xs:attribute name="a" type="SignificantName" use="optional"/>
    <xs:attribute name="b" type="SignificantName" use="optional"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="AssignType">
    <xs:choice minOccurs="0" maxOccurs="1">
      <xs:element ref="value"/>
      <xs:group ref="StringManipulators"/>
      <xs:group ref="ArrayManipulators"/>
      <xs:group ref="INSISDataTypes"/>
    </xs:choice>
    <xs:attribute name="toVariable" type="xs:string" use="required"/>
    <xs:attribute name="value" type="xs:string"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="DeleteType">
    <xs:attribute name="variable" type="xs:string" use="required"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="MacroSatisfiedType">
    <xs:attribute name="macro" type="SignificantName"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="ConditionType">
    <xs:choice>
      <xs:group ref="ConditionGroup"/>
    </xs:choice>
  </xs:complexType>

  <xs:complexType name="MultiConditionType">
    <xs:choice maxOccurs="unbounded">
      <xs:group ref="ConditionGroup"/>
    </xs:choice>
  </xs:complexType>

  <xs:element name="value">
    <xs:complexType>
      <xs:attribute name="value" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

string-manipulator-datatypes-1.2.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:annotation>
    <xs:documentation>
      This no-namespace schema is included by the SIS Trigger, Macro and Composition
      schemas. It defines types common to all schemas.
    </xs:documentation>
  </xs:annotation>

  <xs:group name="StringManipulators">
    <xs:choice>
      <xs:element name="string-prepend" type="StringPrependType"/>
      <xs:element name="string-append" type="StringAppendType"/>
      <xs:element name="string-substring" type="StringSubstringType"/>
      <xs:element name="string-length" type="StringLengthType"/>
      <xs:element name="string-contains" type="StringContainsType"/>
      <xs:element name="string-index-of" type="StringIndexOfType"/>
      <xs:element name="string-last-index-of" type="StringLastIndexOfType"/>
      <xs:element name="string-starts-with" type="StringStartsWithType"/>
      <xs:element name="string-ends-with" type="StringEndsWithType"/>
      <xs:element name="string-matches" type="StringMatchesType"/>
    </xs:choice>
  </xs:group>

  <xs:attributeGroup name="source-suffix-attgroup">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="suffix" type="xs:string" use="required"/>
  </xs:attributeGroup>

  <xs:attributeGroup name="source-prefix-attgroup">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="prefix" type="xs:string" use="required"/>
  </xs:attributeGroup>

  <xs:attributeGroup name="source-substring-attgroup">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="substring" type="xs:string" use="required"/>
  </xs:attributeGroup>

  <xs:attributeGroup name="source-substring-begin-index-attgroup">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="substring" type="xs:string" use="required"/>
    <xs:attribute name="begin-index" type="xs:string"/>
  </xs:attributeGroup>

  <xs:complexType name="StringPrependType">
    <xs:attributeGroup ref="source-prefix-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringAppendType">
    <xs:attributeGroup ref="source-suffix-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringSubstringType">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="begin-index" type="xs:string" use="required"/>
    <xs:attribute name="end-index" type="xs:string"/>
  </xs:complexType>

  <xs:complexType name="StringLengthType">
    <xs:attribute name="source" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="StringContainsType">
    <xs:attributeGroup ref="source-substring-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringIndexOfType">
    <xs:attributeGroup ref="source-substring-begin-index-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringLastIndexOfType">
    <xs:attributeGroup ref="source-substring-begin-index-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringStartsWithType">
    <xs:attributeGroup ref="source-prefix-attgroup"/>
    <xs:attribute name="begin-index" type="xs:string"/>
  </xs:complexType>

  <xs:complexType name="StringEndsWithType">
    <xs:attributeGroup ref="source-suffix-attgroup"/>
  </xs:complexType>

  <xs:complexType name="StringMatchesType">
    <xs:attribute name="source" type="xs:string" use="required"/>
    <xs:attribute name="regex" type="xs:string" use="required"/>
  </xs:complexType>
</xs:schema>

array-manipulator-datatypes-1.1.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:include schemaLocation="in-sis-datatypes-1.5.xsd"/>

  <xs:annotation>
    <xs:documentation>
      This no-namespace schema is included by the SIS Trigger, Macro and Composition
      schemas. It defines types common to all schemas.
    </xs:documentation>
  </xs:annotation>

  <xs:group name="ArrayManipulators">
    <xs:choice>
      <xs:element name="array-add-element" type="ArrayAddElementType"/>
      <xs:element name="array-remove-element" type="ArrayRemoveElementType"/>
      <xs:element name="array-length" type="ArrayLengthType"/>
    </xs:choice>
  </xs:group>

  <xs:complexType name="ArrayAddElementType">
    <xs:choice minOccurs="0" maxOccurs="1">
      <xs:element name="value">
        <xs:complexType>
          <xs:attribute name="value" type="xs:string" use="required"/>
        </xs:complexType>
      </xs:element>
      <xs:group ref="INSISDataTypes"/>
    </xs:choice>
    <xs:attribute name="array" type="xs:string" use="required"/>
    <xs:attribute name="index" type="xs:string" use="optional"/>
    <xs:attribute name="value" type="xs:string" use="optional"/>
  </xs:complexType>

  <xs:complexType name="ArrayRemoveElementType">
    <xs:choice minOccurs="0" maxOccurs="1">
      <xs:element name="value">
        <xs:complexType>
          <xs:attribute name="value" type="xs:string" use="required"/>
        </xs:complexType>
      </xs:element>
      <xs:group ref="INSISDataTypes"/>
    </xs:choice>
    <xs:attribute name="array" type="xs:string" use="required"/>
    <xs:attribute name="index" type="xs:string" use="optional"/>
    <xs:attribute name="value" type="xs:string" use="optional"/>
  </xs:complexType>

  <xs:complexType name="ArrayLengthType">
    <xs:attribute name="array" type="xs:string" use="required"/>
  </xs:complexType>
</xs:schema>

sis-composition-1.8.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           targetNamespace="http://www.opencloud.com/SIS/Composition"
           xmlns="http://www.opencloud.com/SIS/Composition"
           xmlns:c="http://www.opencloud.com/SIS/Composition">

  <xs:include schemaLocation="datatypes-1.3.xsd"/>
  <xs:include schemaLocation="conditions-1.6.xsd"/>

  <xs:element name="composition" type="CompositionType">
    <xs:key name="service-key">
      <xs:annotation>
        <xs:documentation>
          The service-alias element in service-ref must be unique.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath="c:service-ref"/>
      <xs:field xpath="c:service-alias"/>
    </xs:key>

    <xs:key name="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro-alias element in macro-ref must be unique.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath="c:macro-ref"/>
      <xs:field xpath="c:macro-alias"/>
    </xs:key>

    <xs:keyref name="macro-keyref" refer="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro attribute of macro-satisfied must refer to a defined macro alias.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath=".//c:macro-satisfied"/>
      <xs:field xpath="@macro"/>
    </xs:keyref>
  </xs:element>

  <xs:complexType name="CompositionType">
    <xs:sequence>
      <xs:element name="description" minOccurs="0"/>
      <xs:group ref="CompositionID"/>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="macro-ref" type="MacroRefType"/>
      </xs:choice>
      <xs:element ref="script"/>
      <xs:element name="debug-level" type="DebugLevelType" minOccurs="0" default="0"/>
      <xs:element name="audit" type="xs:boolean" minOccurs="0" default="false"/>
      <xs:element name="extension-options" type="ExtensionOptionsType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="script" type="TopLevelScriptBlockType"/>

  <xs:simpleType name="DebugLevelType">
    <xs:restriction base="xs:int">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="3"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="ExtensionOptionsType">
    <xs:sequence>
      <xs:element name="extension-option" type="ExtensionOptionType" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ExtensionOptionType">
    <xs:sequence>
      <xs:any namespace="##any" minOccurs="0" maxOccurs="1" processContents="lax">
        <xs:annotation>
          <xs:documentation>
            Allow a single element inside extension-option. Elements that are known in the schema
            will be validated, others will be ignored.
          </xs:documentation>
        </xs:annotation>
      </xs:any>
    </xs:sequence>
    <xs:attribute name="name" use="required"/>
    <xs:attribute name="value" use="optional"/>
  </xs:complexType>

  <xs:complexType name="TopLevelScriptBlockType">
    <xs:sequence>
      <xs:element name="composition-input-interceptor" type="InterceptorBlockType" minOccurs="0"/>
      <xs:group ref="ScriptStatementGroup"/>
      <xs:element name="composition-output-interceptor" type="InterceptorBlockType" minOccurs="0"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:group name="ScriptStatementGroup">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="assign" type="AssignType"/>
        <xs:element name="delete" type="DeleteType"/>
        <xs:element name="if" type="IfType"/>
        <xs:element ref="invoke"/>
        <xs:element ref="parallel"/>
      </xs:choice>
      <xs:element ref="halt" minOccurs="0"/>
    </xs:sequence>
  </xs:group>

  <xs:element name="invoke" type="InvokeServiceType"/>

  <xs:complexType name="InvokeServiceType">
    <xs:sequence>
      <xs:element name="service-input-interceptor" type="InterceptorBlockType" minOccurs="0"/>
      <xs:element name="service-output-interceptor" type="InterceptorBlockType" minOccurs="0"/>
      <xs:element ref="terminate" minOccurs="0"/>
      <xs:element name="message-handling-options" type="MessageHandlingOptionsType" minOccurs="0"/>
      <xs:element name="extension-options" type="ExtensionOptionsType" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="service" type="SignificantName"/>
    <xs:attribute name="timeout" type="xs:long"/>
    <xs:attribute name="on-timeout" type="ServiceTimeoutOptions" default="ignore-service-and-continue"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="terminate" type="TerminateType">
    <xs:annotation>
      <xs:documentation>
        The terminate element can only be used if the parent element's on-timeout attribute equals "terminate-processing".
        It specifies an optional termination response to return to the network.
      </xs:documentation>
    </xs:annotation>
  </xs:element>

  <xs:simpleType name="ServiceTimeoutOptions">
    <xs:restriction base="xs:string">
      <xs:enumeration value="ignore-service-and-continue"/>
      <xs:enumeration value="terminate-processing"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="parallel" type="ParallelBlock"/>

  <xs:complexType name="ParallelBlock">
    <xs:sequence>
      <xs:element name="service-input-interceptor" type="InterceptorBlockType" minOccurs="0"/>
      <xs:element name="invoke" type="ParallelInvokeServiceType" maxOccurs="unbounded"/>
      <xs:element name="service-output-interceptor" type="InterceptorBlockType" minOccurs="0"/>
      <xs:element ref="terminate" minOccurs="0"/>
      <xs:element name="message-handling-options" type="MessageHandlingOptionsType" minOccurs="0"/>
      <xs:element name="extension-options" type="ExtensionOptionsType" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="timeout" type="xs:long"/>
    <xs:attribute name="on-timeout" type="ServiceTimeoutOptions" default="ignore-service-and-continue"/>
  </xs:complexType>

  <xs:complexType name="ParallelInvokeServiceType">
    <xs:complexContent>
      <xs:extension base="InvokeServiceType">
        <xs:attribute name="primary" type="xs:boolean" default="false"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="InterceptorBlockType">
    <xs:sequence>
      <xs:group ref="InterceptorStatementGroup"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:group name="InterceptorStatementGroup">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="assign" type="AssignType"/>
        <xs:element name="delete" type="DeleteType"/>
        <xs:element name="if" type="InterceptorIfType"/>
        <xs:element ref="invoke-extension"/>
        <xs:element ref="invoke-interceptor"/>
      </xs:choice>
      <xs:element ref="halt" minOccurs="0"/>
    </xs:sequence>
  </xs:group>

  <xs:element name="invoke-extension" type="InvokeInterceptorExtensionType"/>

  <xs:complexType name="InvokeInterceptorExtensionType">
    <xs:attribute name="extension" type="SignificantName" use="required"/>
    <xs:attribute name="timeout" type="xs:long"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="invoke-interceptor" type="InvokeInterceptorType"/>

  <xs:complexType name="InvokeInterceptorType">
    <xs:attribute name="interceptor" type="SignificantName" use="required"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="InterceptorIfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="InterceptorBlockType"/>
      <xs:element name="else-if" type="InterceptorElseIfType" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="else" type="InterceptorBlockType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="InterceptorElseIfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="InterceptorBlockType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="IfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="NestedScriptBlockType"/>
      <xs:element name="else-if" type="ElseIfType" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="else" type="NestedScriptBlockType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ElseIfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="NestedScriptBlockType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="NestedScriptBlockType">
    <xs:sequence>
      <xs:group ref="ScriptStatementGroup"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="halt" type="TerminateType"/>

  <xs:complexType name="MessageHandlingOptionsType">
    <xs:sequence>
      <xs:element ref="message-handling-option" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="message-handling-option" type="MessageHandlingOptionType"/>

  <xs:complexType name="MessageHandlingOptionType">
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>
</xs:schema>

sis-trigger-1.6.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           targetNamespace="http://www.opencloud.com/SIS/Trigger"
           xmlns="http://www.opencloud.com/SIS/Trigger"
           xmlns:t="http://www.opencloud.com/SIS/Trigger">

  <xs:include schemaLocation="datatypes-1.3.xsd"/>
  <xs:include schemaLocation="conditions-1.6.xsd"/>

  <xs:element name="trigger">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="description" minOccurs="0"/>
        <xs:group ref="TriggerID"/>
        <xs:element name="trigger-priority" type="xs:int"/>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element name="macro-ref" type="MacroRefType"/>
          <xs:element name="composition-ref" type="CompositionRefType"/>
        </xs:choice>
        <xs:element name="on-condition" type="ConditionType"/>
        <xs:element name="select" type="SelectorType" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="terminate" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>

    <xs:key name="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro-alias element in macro-ref must be unique.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath="t:macro-ref"/>
      <xs:field xpath="t:macro-alias"/>
    </xs:key>

    <xs:keyref name="macro-keyref" refer="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro attribute of macro-satisfied must refer to a defined macro alias.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath=".//t:macro-satisfied"/>
      <xs:field xpath="@macro"/>
    </xs:keyref>

    <xs:key name="composition-key">
      <xs:annotation>
        <xs:documentation>
          The composition-alias element in composition-ref must be unique.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath="t:composition-ref"/>
      <xs:field xpath="t:composition-alias"/>
    </xs:key>

    <xs:keyref name="composition-keyref" refer="composition-key">
      <xs:annotation>
        <xs:documentation>
          The composition-alias-ref element of a select element must refer to a defined composition alias.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath=".//t:select"/>
      <xs:field xpath="t:composition-alias-ref"/>
    </xs:keyref>
  </xs:element>

  <xs:complexType name="SelectorType">
    <xs:annotation>
      <xs:documentation>
        If the select element contains an extension reference, the SIS implementation will
        fire an event to the extension component, using the SCS API to select a composition.
        If the select element contains a composition-alias-ref, the SIS implementation
        will invoke that composition.
        If the select element contains a profile-lookup, the SIS will invoke the
        profile lookup method to find a composition.
      </xs:documentation>
    </xs:annotation>
    <xs:choice>
      <xs:element name="extension" type="SCSServiceType"/>
      <xs:element name="composition-alias-ref" type="SignificantName"/>
      <xs:element name="profile-lookup" type="ProfileLookupType"/>
    </xs:choice>
  </xs:complexType>

  <xs:complexType name="SCSServiceType">
    <xs:simpleContent>
      <xs:extension base="SignificantName">
        <xs:attribute name="timeout" type="xs:long"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:complexType name="ProfileLookupType">
    <xs:annotation>
      <xs:documentation>
        This element specifies an implementation-specific method for looking
        up a composition using profiles.
      </xs:documentation>
    </xs:annotation>
    <xs:attribute name="scheme" type="SignificantName">
      <xs:annotation>
        <xs:documentation>
          The scheme attribute specifies which type of profile lookup will be performed.
          Available schemes must be documented by the SIS implementation.
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="key" type="SignificantName">
    <xs:annotation>
      <xs:documentation>
        The key attribute specifies the name of a field from the initial request.
        The value of this field will be passed to the profile lookup implementation.
      </xs:documentation>
    </xs:annotation>
    </xs:attribute>
  </xs:complexType>

  <xs:element name="terminate" type="TerminateType">
    <xs:annotation>
      <xs:documentation>
        If this terminate element is present in the instance document, the SIS will perform
        the implementation-specific composition termination action.
        Protocol-specific schemas may replace this element with something more useful,
        by defining an element that extends TerminationType and is in the "terminate" substitution group.
      </xs:documentation>
    </xs:annotation>
  </xs:element>
</xs:schema>

sis-macro-1.6.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           targetNamespace="http://www.opencloud.com/SIS/Macro"
           xmlns="http://www.opencloud.com/SIS/Macro"
           xmlns:m="http://www.opencloud.com/SIS/Macro">

  <xs:include schemaLocation="datatypes-1.3.xsd"/>
  <xs:include schemaLocation="conditions-1.6.xsd"/>

  <xs:element name="macro">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="description" type="xs:string" minOccurs="0"/>
        <xs:group ref="MacroID"/>
        <xs:element name="macro-ref" type="MacroRefType" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="macro-expression" type="ConditionType"/>
      </xs:sequence>
    </xs:complexType>

    <xs:key name="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro-alias element in macro-ref must be unique.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath="m:macro-ref"/>
      <xs:field xpath="m:macro-alias"/>
    </xs:key>

    <xs:keyref name="macro-keyref" refer="macro-key">
      <xs:annotation>
        <xs:documentation>
          The macro attribute of macro-satisfied must refer to a defined macro alias.
        </xs:documentation>
      </xs:annotation>
      <xs:selector xpath=".//m:macro-satisfied"/>
      <xs:field xpath="@macro"/>
    </xs:keyref>

  </xs:element>

</xs:schema>

sis-interceptor-1.2.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           targetNamespace="http://www.opencloud.com/SIS/Interceptor"
           xmlns="http://www.opencloud.com/SIS/Interceptor"
           xmlns:i="http://www.opencloud.com/SIS/Interceptor">

  <xs:include schemaLocation="conditions-1.6.xsd"/>

  <xs:element name="interceptor">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="description" minOccurs="0"/>
        <xs:group ref="InterceptorID"/>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element name="macro-ref" type="MacroRefType"/>
        </xs:choice>
        <xs:element name="script" type="InterceptorBlockType"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="InterceptorBlockType">
    <xs:sequence>
      <xs:group ref="InterceptorStatementGroup"/>
    </xs:sequence>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:group name="InterceptorStatementGroup">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="assign" type="AssignType"/>
        <xs:element name="delete" type="DeleteType"/>
        <xs:element name="if" type="InterceptorIfType"/>
        <xs:element ref="invoke-extension"/>
        <xs:element ref="invoke-interceptor"/>
      </xs:choice>
      <xs:element ref="halt" minOccurs="0"/>
    </xs:sequence>
  </xs:group>

  <xs:element name="invoke-extension" type="InvokeInterceptorExtensionType"/>

  <xs:complexType name="InvokeInterceptorExtensionType">
    <xs:attribute name="extension" type="SignificantName"/>
    <xs:attribute name="timeout" type="xs:long"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:element name="invoke-interceptor" type="InvokeInterceptorType"/>

  <xs:complexType name="InvokeInterceptorType">
    <xs:attribute name="interceptor" type="SignificantName" use="required"/>
    <xs:anyAttribute namespace="##any" processContents="lax"/>
  </xs:complexType>

  <xs:complexType name="InterceptorIfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="InterceptorBlockType"/>
      <xs:element name="else-if" type="InterceptorElseIfType" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="else" type="InterceptorBlockType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="InterceptorElseIfType">
    <xs:sequence>
      <xs:group ref="ConditionGroup"/>
      <xs:element name="then" type="InterceptorBlockType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="halt" type="TerminateType"/>
</xs:schema>

in-sis-datatypes-1.5.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:annotation>
    <xs:documentation>
      This no-namespace schema is included by the SIS Trigger, Macro and Composition
      schemas for IN. It defines IN-specific datatypes.
    </xs:documentation>
  </xs:annotation>

  <xs:group name="INSISDataTypes">
    <xs:choice>
      <xs:element name="object" type="ObjectType"/>
      <xs:element name="array" type="ArrayType"/>
      <xs:element name="enum" type="EnumType"/>
      <xs:element name="bytes" type="ByteArrayType"/>
      <xs:element name="calling-party-number" type="CallingPartyNumberType"/>
      <xs:element name="called-party-number" type="CalledPartyNumberType"/>
      <xs:element name="called-party-bcd-number" type="CalledPartyBCDNumberType"/>
      <xs:element