This document details basic procedures for system administrators managing, maintaining, configuring and deploying Metaswitch’s Service Interaction SLEE (SIS) 3.2 with Rhino.

Topics

This document includes the following topics:

  • About the SIS — a brief overview of the SIS and how it provides service interaction, with a focus on its functional description, configuration and subscription data, components and dependencies, and command-line console.

  • Installing and uninstalling the SIS — procedures for installing the SIS automatically and manually, and uninstalling the SIS.

  • Creating, removing, and reconfiguring a SIS instance — procedures for creating a SIS instance automatically and manually, removing a SIS instance, and reconfiguring a SIS instance.

  • Managing the SIS — using console commands, Ant tasks, and MBeans to manage SIS configuration, compositions, triggers, macros, address subscriptions, service key subscriptions, service configurations trigger-address tracing, and fine-grained tracing.

  • Using SIS modules — using and installing optional features available with the SIS.

  • Appendixes — details of SIS XML schema files, the SCCP address format, alarms, and recorded statistics (for network-initiated dialogs, service-initiated dialogs and service statistics).

Audience

This document is for system administrators (and anyone else responsible for) deploying, managing and maintaining the SIS on a Rhino SLEE.

This document assumes a basic knowledge of core concepts about Rhino, SIS, JAIN SLEE, and Java Management Extensions (JMX).

Scope

This document covers procedures for deploying and administering the OpenCloud SIS.

This document does not focus on:

About the SIS

The Rhino Service Interaction SLEE provides service interaction for circuit-switched networks.

Specifically, SIS lets you:

  • run one or more services on a trigger from a Service Switching Function (SSF) or Serving Call Session Control Function
    (S-CSCF). These services may be:

    • local: JAIN SLEE services written using OpenCloud CGIN or EasySIP APIs:

      • SIS supports CGIN APIs for:

        • GSM CAP v1, v2, v3, and v4 (Voice and SMS only)

        • ETSI INAP CS1

        • Ericsson INAP CS1 (optional)

        • Ericsson INAP CS1+ (optional)

        • Nokia INAP CS1 (optional); Siemens INAP 7m+ (optional)

        • GSM MAP v4 (outgoing dialogs only).

      • EasySIP supports SIP (RFC 3261) and ISC (3GPP TS 23.218).

    • external: legacy CAP and INAP services in external network elements, or SIP application servers.

  • fully customise how the SIS selects the service composition (set of services) to run, using initial trigger scripts

  • manage the signaling interactions between the services that the SIS invokes, with powerful and flexible composition scripts

  • enable focused, service-interaction tracing for specific dialogs, without compromising the performance of the SIS, by using fine-grained tracing options for specific service compositions, address or service-key subscriptions, or arbitrary addresses from initial events.

Tip

For more the on SIS generally, see the SIS Overview and Concepts document. For a description of specific SIS features, see the following subtopics:

Functional Description

For SIP and IN, the SIS lets you define complex interactions between services, by applying a composition to each call attempt that it processes.

Note A composition is a pre-tested sequence of services or features that produce added value to a subscriber.

The SIS intelligently manages the interactions between each service and the network dialog.

The SIS FSM

Below is a high-level view of the SIS finite state machine (FSM), followed by descriptions of its three states.

insis highlevel state machine

State A: Inactive

Inactive is the initial and final state of the SIS FSM.

State B: Service Composition Discovery

Service Composition Discovery is the state the SIS FSM enters upon receipt of an initial event. The SIS applies trigger rules that analyse and examine the parameters of the initial event, to select a service composition to run.

If the SIS finds a composition, the SIS FSM transitions to the Monitoring and Event Delivery state. If not, the SIS:

  • sends a configurable "trigger failure" response to the network

  • terminates the network dialog

  • returns the SIS FSM to the Inactive state.

State C: Monitoring and Event Delivery

The Monitoring and Event Delivery state is divided into the following three substates:

  1. Event Delivery,

  2. Waiting for Instructions, and

  3. Monitoring:

insis fsm state c

State C.1: Event Delivery

Event Delivery is the state the SIS FSM enters whenever one or more events are available for potential delivery to one or more services. Typically, the network generates events, but the SIS may also synthesise them as a result of a particular service’s interaction with the network dialog.

insis fsm state c1
Event delivery direction

Events are delivered to the services in a composition in the forward or reverse direction — forward from events associated with the call’s originating party, reverse from events associated with the call’s terminating party. If an event is not associated with either the originating or terminating party, delivery is by default in the forward direction.

Service disposition towards receiving events

Each service may have one of three dispositions towards the receipt of each event:

  • Transparent — The service does not care about the event (will not receive notification).

  • Notify & Continue — The service wants to know but not do anything about the event (will receive notification, but not respond with any specific call-processing functions).

  • Interrupted — The service wants to know about and respond to the event before it goes to another service (will receive notification and may perform some call-processing functions). In this case, the SIS waits for the service to generate a response to the event before continuing with delivery of the event to any other service.

The SIS determines the disposition of a service by considering whether it can receive the event (the event-handler methods defined by the service), and whether it has asked to receive such events in the past (for example, for an IN EventReportBCSM indication event, whether the service has requested interest in its BCSM event type).

The SIS fires an event to the service if the event disposition is not Transparent. If the event disposition was Interrupted, the SIS FSM enters the Waiting for Instructions state.

Transitions to Monitoring or Inactive

After all events have been delivered by the SIS to the services in the service composition (according to the service dispositions) and the SIS has received all required responses from the services (according to the service dispositions), the SIS sends any required response to the network. If the network dialog remains open after this time, the SIS FSM transitions to the Monitoring state. Otherwise, it transitions to the Inactive state.

State C.2: Waiting for Instructions

insis fsm state c2

Waiting for Instructions is the state when the SIS has delivered one or more events to a service with Interrupted event disposition, and it’s waiting for that service to return a response. There are two exit paths from this state: the SIS either receives a response from the service appropriate for the event, or times out.

With a response, the SIS determines whether to continue delivering the event to any remaining services, or abort delivery and send an immediate response to the network. For example, if a service releases the call, the SIS will abort delivery and send the appropriate message to the network. With a timeout, the SIS excludes the non-responding service from further interaction with the network dialog and continues delivering the events to any remaining services.

State C.3: Monitoring

Monitoring is a state where the SIS continues monitoring the network dialog for more events. It also continues to monitor the services where it has delivered events for the composition, so it can respond to any requests they initiate (for example, to terminate the call).

Configuration and Subscription Data

The SIS uses the following ten profile specifications, and root configuration schema, to store its configuration and subscription data.

IN = SIS feature for IN only

Profile specifications

Profile specification What it does

root configuration

Defines basic service-interaction configuration information, and includes the names of other profile tables the SIS needs (see the root configuration schema).

macros

Allows common expressions to be reused multiple times in triggers, compositions or other macros.

triggers

Specifies how the SIS deals with initial events it gets from the network. Includes an expression that the SIS can evaluate against the initial event, composition-selection criteria and failure-handling instructions.

compositions

Prompts the SIS to process an ordered set of services, according to various details, when triggered.

interceptors

Provides custom logic to manipulate the signaling parameters of protocol messages.

extension references

Identifies extension components that can be used in compositions.

service references

Identifies services that can be used in compositions.

interceptor references

Identifies interceptors that can be invoked by SLEE applications or other interceptors.

external platforms

Describes the location of services that are external to the SIS.

network interface definitions

Describes SIS network interfaces and their associated configuration properties.

network routes

Specifies how the SIS selects a network interface for outgoing traffic.

address subscriptions

Defines subscription to compositions using an address. (Address lookup may be based on various addresses present in the initial event.)

service key subscription
IN

Defines subscription to compositions using the mandatory service key parameter of IN initial events.

trigger address tracing

Lets you associate a tracing-debug level with any arbitrary address, so you can enable debug logging for a dialog with a specific address string in one of the initial event’s parameters.

experimental features

Identifies incomplete or untested features that may be enabled in the SIS.

Schema of root configuration profile

The SIS configuration profile specification defines the schema of the root configuration profile for the SIS, as follows:

Attribute

 
 Type

Description

Description

 
 java.lang.String

An optional arbitrary descriptive name for the configuration.

Macro profile table name

 
 java.lang.String

Name of the profile table used to store macro expressions. This profile table must have been created from the SIS macro profile specification.

Trigger profile table name

 
 java.lang.String

Name of the profile table used to store triggers. This profile table must have been created from the SIS trigger profile specification.

Service composition profile table name

 
 java.lang.String

Name of the profile table used to store compositions. This profile table must have been created from the SIS composition profile specification.

Interceptor profile table name

 
 java.lang.String

Name of the profile table used to store interceptors. This profile table must have been created from the SIS interceptor profile specification.

Extension reference profile table name

 
 java.lang.String

Name of the profile table used to store extension references. This profile table must have been created from the SIS extension reference profile specification.

Service reference profile table name

 
 java.lang.String

Name of the profile table used to store service references. This profile table must have been created from the SIS service reference profile specification.

Interceptor reference profile table name

 
 java.lang.String

Name of the profile table used to store interceptor references. This profile table must have been created from the SIS interceptor reference profile specification.

Address subscription profile table name

 
 java.lang.String

Name of the profile table used to store composition provisioning information for triggerable addresses. This profile table must have been created from the SIS address subscription profile specification.

Service key subscription profile table name
IN

 
 java.lang.String

Name of the profile table used to store composition provisioning information for triggerable service keys. This profile table must have been created from the SIS service key subscription profile specification.

External platform profile table name

 
 java.lang.String

Name of the profile table used to store the definitions of external service platforms. This profile table must have been created from the SIS external platform profile specification.

Network interface definitions profile table name

 
 java.lang.String

Name of the profile table used to store the definitions of network interfaces. This profile table must have been created from the SIS network interface definitions profile specification.

Network routes profile table name

 
 java.lang.String

Name of the profile table used to store network routes. This profile table must have been created from the SIS network routes profile specification.

Experimental features profile table name

 
 java.lang.String

Name of the profile table used to store the experimental feature configuration information. This profile table must have been created from the SIS experimental features profile specification.

Trigger address tracing profile table name

 
 java.lang.String

Name of the profile table used to store fine-grained tracing information for arbitrary addresses that may appear in trigger events. This profile table must have been created from the SIS trigger address tracing profile specification.

Originating trigger address tracing selection

 
 com.opencloud.slee.resources.sipsis.management.SipTriggerAddressTracingSelector[] or com.opencloud.slee.resources.insis.management.INTriggerAddressTracingSelector[]

An array of trigger-address-tracing selectors (which specify the initial event parameters to examine for initial events from the originating call state model), to look for a profile in the trigger-address-tracing profile table when fine-grained tracing is enabled. You can select the following parameters: Calling Party Number, Called Party Number, Called Party BCD Number, Redirecting Party ID, Location Number, Original Called Party ID, Additional Calling Party Number, Destination Subscriber Number, SmscAddress, Request-URI, From, To, P-Asserted-Identity, P-Called-Party-ID, and P-Served-User. You can specify zero or more selectors. The SIS searches for profiles in the trigger-address-tracing profile table using the unmodified address from each selected trigger event parameter.

Terminating trigger-address-tracing selection

 
 com.opencloud.slee.resources.sipsis.management.SipTriggerAddressTracingSelector[] or com.opencloud.slee.resources.insis.management.INTriggerAddressTracingSelector[]

Same as the originating trigger-address-tracing selection, except that it applies to initial events from the terminating call state model.

Third-party trigger-address-tracing selection
IN

 
 com.opencloud.slee.resources.insis.management.INTriggerAddressTracingSelector[]

Same as the originating trigger-address-tracing selection, except that it applies to initial events for third-party (network-initiated) calls.

Concatenated FCI interaction mode delimiter
IN

 
 byte[]

Byte array of length zero or more, used as a delimiter between multiple furnish charging information (FCI) requests sent during a particular instance of service interaction. Used only if the concatenated FCI interaction mode has been specified for a service composition.

Fine-grained tracing enabled

 
 boolean

Boolean flag that indicates whether the fine-grained tracing facilities on the SIS are enabled (true) or disabled (false). Checking fine-grained tracing options for an initial event, such as looking up the trigger address tracing profile table, incurs a small additional overhead — so this option lets an administrator eliminate that performance penalty if not needing fine-grained tracing.

Default service timeout

 
 long

The default timeout period, measured in milliseconds, that the SIS uses when waiting for a response to an event from a composition service or an extension component. If it gets no response within the timeout period, the SIS assumes the service or extension component is non-responsive, and if it is a composition service, removes the service from further interaction with the network dialog. The default timeout period is 2s, and the minimum permitted timeout is 100ms.

Audit level

 
 com.opencloud.slee.resources.sis.management.AuditLevel

The SIS audit logging level.

Components and Dependencies

The SIS has the following components and dependences (with links to APIs).

Dependency Description

Rhino SLEE

OpenCloud JAIN SLEE platform.

CGIN Connectivity Pack 3.1

Provides the CGIN APIs, activities, and event types that the IN services use.

IN This is required for SIS-IN only
Component Description

EasySIP resource adaptor type

Provides the EasySIP API, activity, and event types that SIP services use.

SIP This is provided by SIS-SIP only

SIS Common libraries

Provide SIS functionality common to all SIS implementations, including the JMX management API. There is one each for:

SIS Service Composition Selection Extensions resource adaptor types

Provide activity and event types that allow SIS extension components to determine which service composition the SIS should execute for a given initial event. There is one each for:

SIS Interceptor Extension resource adaptor types

Provide activity and event types that:

  • allow SIS extension components to modify signaling parameters in composition service input or output messages

  • allow SLEE services to invoke SIS interceptor components for arbitrary protocol messages.

There is one each for:

SIS Composition Activity Provider resource adaptor type

Provides access to a SIS-managed activity object, related to the underlying network dialog that a service interacts with, through the virtual dialog layer (which the SIS provides, between the network and services, to manage service interaction).

This activity object lets multiple services share state using SLEE-provided features — without the services having to deal with state cleanup on network dialog termination.

Note For a given network dialog, the SIS uses the same activity object to represent service composition selection, interceptor, and composition activities in the SLEE. This means that state can be shared between composition services and SIS extension components if required.

IN This is a SIS feature for IN only

Service Interaction Manager

This component:

  • contains the service-interaction logic of the SIS

  • intelligently manages the delivery of events on a network dialog to multiple services, as well as the responses that it receives from those services

  • is packaged and deployed as a JAIN SLEE resource adaptor, but does not directly provide resource adaption for all resource adaptor types that it implements (a standard SIP or CGIN resource adaptor embedded inside the Service Interaction Manager provides resource adaption functionality for, and implements, the relevant protocol resource adaptor type)

  • injects interaction logic into the events that the embedded resource adaptor passes to it and into the responses that services generate

  • uses relevant protocol resource adaptor type APIs and the SLEE 1.1 specification to interact with the embedded resource adaptor, the SLEE, and composition services.

For IN, the embedded CGIN resource adaptor has two parts:

  • frontend component — a JAIN SLEE resource adaptor (in Java code), implemented according to the SLEE 1.1 specification, to provide functionality defined by the CGIN architecture.

  • backend component — an external TCAP stack which connects to the SS7 network.

See the CGIN documentation for more information on using SS7 networks.

For SIP, the embedded SIP resource adaptor contains the SIP stack and connects directly to the SIP network.

Command-Line Administration Tools

SIS command-line administration tools, in the admin directory of the SIS install, include:

Tool Description 
 install-sis

Installs the SIS into Rhino (or Rhino SDK), and creates profile tables used to store basic configuration data for SIS instances.
See Installing the SIS for details.

 
 create-sis-in-instance
create-sis-sip-instance

Creates a SIS instance for IN or SIP respectively. These tools prompt for configuration parameters necessary to create a SIS instance, then perform the necessary actions in Rhino (or Rhino SDK) to realise the SIS instance.
See Creating a SIS Instance for details.

 
 sis-console

A command-line console that is an extension of rhino-console, that supports the set of SIS commands as well as the normal Rhino commands.
See Managing the SIS for details of console commands specific to the SIS.

 
 sis-export

Extracts the current state of a SIS instance, including macros, triggers, compositions, and so on; and generates an Ant build script that can be used (in conjunction with a standard Rhino state export) to regenerate the SIS instance in another Rhino (or Rhino SDK).
See Exporting SIS State for details.

 
 sis-import

Helper tool to execute an Ant build script generated by sis-export.
See Importing SIS State for details.
Tip SIS administration tools are specific to the type of SIS install they belong to. That is to say the tools included in a SIS-IN install can only operate on SIS-IN SIS instances, and those included with a SIS-SIP install can only operate on SIS-SIP SIS instances.

Installing and Uninstalling the SIS

This section includes the following procedures:

Installing the SIS

Installing the SIS

Below are the steps to install the SIS:

  1. Select SIS package.

  2. Install and start Rhino.

  3. Install the CGIN Connectivity Pack for SIS-IN only.

  4. Unpack the SIS.

  5. Configure the SIS.

  6. Install the SIS.

... plus an example.

1. Select SIS package

The SIS-IN and SIS-SIP packages are completely independent from each other. SIS-IN does not depend on any SIP components and SIS-SIP does not depend on any CGIN components. Both SIS-IN and SIS-SIP may be installed side-by-side in Rhino for those requiring SIS services for both IN and SIP.

2. Install and start Rhino

Rhino (or the Rhino SDK) must be installed and running before anything else can be installed.

Note

The deployable units for both SIS and CGIN include a large number of generated classes. The default MetaspaceSize is 768m in Rhino which is highly above the peak Metaspace usage under load. It is not expected to get seemingly random JVM hangs caused by garbage collection thrashing, out of memory errors, or other related problems that can be attributed to the JVM having to load this quantity of classes.

If it does,

  • For Rhino, you need to edit the read-config-variables file in the ${RHINO_HOME}/etc/defaults directory and each ${RHINO_HOME}/node-XXX directory.

  • For the Rhino SDK, you need to edit the ${RHINO_HOME}/config/jvm_args file.

In each file, search for -XX:MaxMetaspaceSize and -XX:MetaspaceSize and set the value of this option to bigger value than 768m. Rhino (or the Rhino SDK) needs be to restarted for this change to take effect.

3. Install the CGIN Connectivity Pack for SIS-IN only

The SIS-IN 3.2 depends on the CGIN Connectivity Pack 3.1 — you must download and install it before using the SIS-IN package.

Warning

See the SIS Compatibility Guide for further information on using CGIN with the SIS.

Note that the 'trial' version of the SIS can only be used in conjunction with the 'trial' version of the CGIN Connectivity Pack. Similarly, the 'full' version of the SIS can only be used in conjunction with the 'full' version of the CGIN Connectivity Pack.

Typically, the CGIN Connectivity Pack will be extracted directly into the Rhino (or Rhino SDK) directory:

$ cd RhinoSDK
$ unzip ~/downloads/cgin-connectivity-full-3.1.0.zip
Archive:  ~/downloads/cgin-connectivity-full-3.1.0.zip
  creating: cgin-connectivity-full-3.1.0/
  creating: cgin-connectivity-full-3.1.0/du/
  creating: cgin-connectivity-full-3.1.0/examples/
  creating: cgin-connectivity-full-3.1.0/examples/META-INF/
  creating: cgin-connectivity-full-3.1.0/examples/src/
  ...
Tip The third digit of the CGIN Connectivity Pack version indicates the patch release version and may be different from the example shown above.

4. Unpack the SIS

Typically, the SIS should be extracted directly into the Rhino (or Rhino SDK) directory:

$ cd RhinoSDK
$ unzip ~/downloads/sis-in-full-3.2.0.zip
Archive:  ~/downloads/sis-in-full-3.2.0.zip
    creating: sis/
    creating: sis/in/3.2.0/
    creating: sis/in/3.2.0/admin/
    creating: sis/in/3.2.0/admin/common/
    creating: sis/in/3.2.0/admin/etc/
    creating: sis/in/3.2.0/admin/lib/
    creating: sis/in/3.2.0/admin/lib/extensions/
    ...
$ unzip ~/downloads/sis-easysip-full-3.2.0.zip
Archive:  ~/downloads/sis-easysip-full-3.2.0.zip
    creating: sis/
    creating: sis/sip/3.2.0/
    creating: sis/sip/3.2.0/admin/
    creating: sis/sip/3.2.0/admin/common/
    creating: sis/sip/3.2.0/admin/etc/
    creating: sis/sip/3.2.0/admin/lib/
    creating: sis/sip/3.2.0/admin/lib/extensions/
    ...
Tip The third digit of the SIS package version indicates the patch release version and may be different from the example shown above.

5. Configure the SIS

Initial SIS configuration may require modification of the following files:

Directory File What it should contain 
 sis/<protocol>/{product-version}._x_/admin/etc
 
client.ant.properties

and

client.shell.properties

or in Windows:

client.windows.properties.bat

These files each define a property which specifies the path to the client directory of the Rhino (or Rhino SDK) install, as either an absolute or relative path. If relative, must be relative to the sis/<protocol>/3.2.x directory.

If the SIS was extracted into the top-level directory of the Rhino installation, as described in step 4 above, then this file will not need to be modified.

5.1 SIS-IN only

Directory File What it should contain 
 sis/in/{product-version}._x_
 
 cgin-connectivity.properties

This file defines a property which specifies the path to the CGIN Connectivity Pack for the SIS, as either an absolute or relative path. If relative, must be relative to the sis/in/3.2.x directory.

The default value for the path is a relative path to the expected CGIN Connectivity Pack, extracted in the Rhino (or Rhino SDK) directory. For example, the full version of the standard SIS install has a default path value of ../../../cgin-connectivity-full-3.1.x. Note that the path separator character / used in this file will automatically be converted to the local platform path separator when this file is used by the SIS.

If both the CGIN Connectivity Pack and the SIS have been extracted into the same Rhino (or Rhino SDK) directory, then this configuration file only needs to be modified to append the fourth digit of the specific CGIN Connectivity Pack patch release being used. Otherwise, the entire path will need to be modified as necessary.

6. Install the SIS

6.1. SIS-IN

To install the SIS-IN into Rhino, run sis/in/3.2.x/admin/install-sis (or install-sis.bat in Windows).

The SIS installation prompts for the following parameters:

Parameter Description 
 IN Config Profile Table

Name of the profile table to create, to store SIS IN configurations.
Defaults to sis-configs-in

 
 Rhino SIS license

File path to the Rhino license file to use with the SIS (if you have one).

The installer, after confirming values for each parameter, installs the required deployable units from the CGIN Connectivity Pack and the SIS, creates the SIS configuration profile tables, and installs the license file (if specified).

6.2. SIS-SIP

To install the SIS-SIP into Rhino, run sis/sip/3.2.x/admin/install-sis (or install-sis.bat in Windows).

The SIS installation prompts for the following parameters:

Parameter Description 
 SIP Config Profile Table

Name of the profile table to create, to store SIS SIP configurations.
Defaults to sis-configs-sip

 
 Rhino SIS license

File path to the Rhino license file to use with the SIS (if you have one).

The installer, after confirming values for each parameter, installs the required deployable units, creates the SIS configuration profile tables, and installs the license file (if specified).

Example installation of SIS-IN

Below is an example of a SIS installation.

$ cd sis/in/3.2.0/admin
$ ./install-sis
SIS-IN Installer
================

General
=======
General settings

IN Config Profile Table
-----------------------
The name of the profile table used to store basic SIS instance configuration
information for IN.

IN Config Profile Table [sis-configs-in]:

Rhino SIS license
-----------------
A license may already be installed, or you may choose to install a license at
a later point in time.  If you do not want to install a license at this time
provide an empty response.  If no license is present at the time a SIS
instance is created, however, the SIS instance will need to be activated
manually via the console.

Rhino SIS license []:


*** Confirm settings ***

IN Config Profile Table:  sis-configs-in
Rhino SIS license:

Are these settings correct (y/n)? y

Using client base directory: .../client
Installing cgin-connectivity-full-3.1.0/du/oc-common-3.0.0.du.jar as file:cgin/oc-common-3.0.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/cgin-common-3.1.0.du.jar as file:cgin/cgin-common-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/in-datatypes-5.3.1.0.du.jar as file:cgin/in-datatypes-5.3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/callcontrol-3.1.0.du.jar as file:cgin/callcontrol-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/map-3.1.0.du.jar as file:cgin/map-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/cap_v1-3.1.0.du.jar as file:cgin/cap_v1-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/cap_v2-3.1.0.du.jar as file:cgin/cap_v2-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/cap_v3-3.1.0.du.jar as file:cgin/cap_v3-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/cap_v4-3.1.0.du.jar as file:cgin/cap_v4-3.1.0.du.jar...
Installing cgin-connectivity-full-3.1.0/du/etsi_inap_cs1-3.1.0.du.jar as file:cgin/etsi_inap_cs1-3.1.0.du.jar...
Installing sis/in/3.2.0/du/jsip-library-1.2.du.jar as file:sip/jsip-library-1.2.du.jar...
Installing sis/in/3.2.0/du/sis-common-3.2.0.du.jar as file:sis/sis-common-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-scs-ratype-3.2.0.du.jar as file:sis/sis-scs-ratype-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-interceptors-ratype-3.2.0.du.jar as file:sis/sis-interceptors-ratype-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-cap-ratype-3.2.0.du.jar as file:sis/sis-cap-ratype-3.2.0.du.jar...
Installing sis/in/3.2.0/du/cgin-message-utils-common-3.2.0.du.jar as file:sis/cgin-message-utils-common-3.2.0.du.jar...
Installing sis/in/3.2.0/du/cgin-message-utils-voice-ratype-3.2.0.du.jar as file:sis/cgin-message-utils-voice-ratype-3.2.0.du.jar...
Installing sis/in/3.2.0/du/cgin-message-utils-sms-ratype-3.2.0.du.jar as file:sis/cgin-message-utils-sms-ratype-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-in-base-full-3.2.0.du.jar as file:sis/sis-in-base-full-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-cgin-unified-ra-full-3.2.0.du.jar as file:sis/sis-cgin-unified-ra-full-3.2.0.du.jar...
Installing sis/in/3.2.0/du/easysip-ratype-3.2.0.du.jar as file:sip/easysip-ratype-3.2/0.du.jar...
Installing sis/in/3.2.0/du/sis-sip-base-full-3.2.0.du.jar as file:sis/sis-sip-base-full-3.2.0.du.jar...
Installing sis/in/3.2.0/du/sis-easysip-full-3.2.0.du.jar as file:sis/sis-easysip-full-3.2.0.du.jar...
Creating profile table sis-configs-in using ProfileSpecificationID[name=SIS-IN Configuration Profile,vendor=OpenCloud,version=3.0]...
Creating profile table sis-configs-sip using ProfileSpecificationID[name=SIS-SIP Configuration Profile,vendor=OpenCloud,version=3.0]...
Installation successfulInstallation successful

Next Steps:
- Create a SIS instance using create-sis-in-instance
- Use sis-console or Ant to install triggers and compositions into the SIS.
- Visit https://docs.rhino.metaswitch.com/ocdoc/go/product/sis-documentation for further documentation.

Uninstalling the SIS

Below are a note about what the uninstallation removes, instructions for using the cascade-uninstall command, and an example.

What’s uninstalled

Warning

Uninstalling the SIS will also remove from the SLEE:

  • all SIS instances

  • all SIS configuration and subscription information

  • all extension components that depend on the SIS Service Composition Selection resource adaptor type

  • all extension components that depend on the SIS Interceptors resource adaptor type

  • all extension components and services that depend on the SIS Composition Activity Provider resource adaptor type.

Using cascade-uninstall

The quickest and easiest way to uninstall the SIS is by using Rhino’s cascade-uninstall tool, located in the client/bin directory of the Rhino installation. You can specify which deployable units to remove, for example:

To uninstall…​ …​specify:

only the SIS-SIP, while retaining other SIP- and CGIN-related components

file:sis/sis-in-common-3.2.x.du.jar

only the SIS-SIP, while retaining other non sip-related components

file:sis/sis-sip-common-3.2.x.du.jar

all CGIN-related components, including the SIS-IN

file:cgin/cgin-common-3.1.x.du.jar

all SIP-related components, including the SIS-SIP

file:sip/jsip-library-1.2.du.jar and file:sip/easysip-ratype-3.2.x.du.jar

Example cascade-uninstall

Below is an example of using cascade-uninstall to uninstall a SIS-IN:

$ ./client/bin/cascade-uninstall -l
Connecting to localhost:1199
The following deployable units are installed:
  file:cgin/callcontrol-3.1.0.du.jar
  file:cgin/cap_v1-3.1.0.du.jar
  file:cgin/cap_v2-3.1.0.du.jar
  file:cgin/cap_v3-3.1.0.du.jar
  file:cgin/cap_v4-3.1.0.du.jar
  file:cgin/cgin-common-3.1.0.du.jar
  file:cgin/etsi_inap_cs1-3.1.0.du.jar
  file:cgin/in-datatypes-5.3.1.0.du.jar
  file:cgin/map-3.1.0.du.jar
  file:cgin/oc-common-3.0.0.du.jar
  file:javax-slee-standard-types.jar
  file:opencloud/rhino-api-2.6.1.du.jar
  file:opencloud/rhino-api-2.6.du.jar
  file:opencloud/rhino-extension-types.jar
  file:opencloud/session-ownership-resource-adaptor-type.du.jar
  file:sip/easysip-ratype-3.0.0.du.jar
  file:sip/jsip-library-1.2.du.jar
  file:sip/oc-common-3.0.0.du.jar
  file:sis/cgin-message-utils-common-1.1.0.0.du.jar
  file:sis/cgin-message-utils-sms-ratype-3.2.0.du.jar
  file:sis/cgin-message-utils-voice-ratype-3.2.0.du.jar
  file:sis/sis-cgin-unified-ra-full-3.2.0.du.jar
  file:sis/sis-easysip-full-3.2.0.du.jar
  file:sis/sis-in-cap-ratype-3.2.0.du.jar
  file:sis/sis-in-common-3.2.0.du.jar
  file:sis/sis-in-interceptors-ratype-3.2.0.du.jar
  file:sis/sis-in-scs-ratype-3.2.0.du.jar
  file:sis/sis-sip-common-3.2.0.du.jar
  file:sis/sis-sip-interceptors-ratype-3.2.0.du.jar
  file:sis/sis-sip-scs-ratype-3.2.0.du.jar
    ...

$ ./client/bin/cascade-uninstall -d file:sis/sis-in-common-3.2.0.du.jar -y
Connecting to localhost:1199
Uninstalling deployable unit file:sis/sis-cgin-unified-ra-full-3.2.0.du.jar
Uninstalling deployable unit file:sis/sis-in-cap-ratype-3.2.0.du.jar
Uninstalling deployable unit file:sis/sis-in-interceptors-ratype-3.2.0.du.jar
Uninstalling deployable unit file:sis/sis-in-scs-ratype-3.2.0.du.jar
Removing profile table sis-configs-in
Uninstalling deployable unit file:sis/sis-in-common-3.2.0.du.jar

$ ./client/bin/cascade-uninstall -l
Connecting to localhost:1199
The following deployable units are installed:
  file:cgin/callcontrol-3.1.0.du.jar
  file:cgin/cap_v1-3.1.0.du.jar
  file:cgin/cap_v2-3.1.0.du.jar
  file:cgin/cap_v3-3.1.0.du.jar
  file:cgin/cap_v4-3.1.0.du.jar
  file:cgin/cgin-common-3.1.0.du.jar
  file:cgin/etsi_inap_cs1-3.1.0.du.jar
  file:cgin/in-datatypes-5.3.1.0.du.jar
  file:cgin/map-3.1.0.du.jar
  file:cgin/oc-common-3.0.0.du.jar
  file:javax-slee-standard-types.jar
  file:opencloud/rhino-api-2.6.1.du.jar
  file:opencloud/rhino-api-2.6.du.jar
  file:opencloud/rhino-extension-types.jar
  file:opencloud/session-ownership-resource-adaptor-type.du.jar
  file:sip/easysip-ratype-3.0.0.du.jar
  file:sip/jsip-library-1.2.du.jar
  file:sip/oc-common-3.0.0.du.jar
  file:sis/cgin-message-utils-common-1.1.0.0.du.jar
  file:sis/cgin-message-utils-sms-ratype-3.2.0.du.jar
  file:sis/cgin-message-utils-voice-ratype-3.2.0.du.jar
  file:sis/sis-easysip-full-3.2.0.du.jar
  file:sis/sis-sip-common-3.2.0.du.jar
  file:sis/sis-sip-interceptors-ratype-3.2.0.du.jar
  file:sis/sis-sip-scs-ratype-3.2.0.du.jar

Creating, Removing, and Reconfiguring a SIS Instance

Any number of SIS instances may be created in the same Rhino platform. While instances may share the same configuration and provisioning information, they typically each have their own.

This section includes the following procedures:

 

Note
What’s in a SIS instance?

A SIS instance consists of:

  • a root configuration profile

  • a macros profile table

  • a triggers profile table

  • a compositions profile table

  • an interceptors profile table

  • a network interface definitions profile table

  • a network route profile table

  • an extension references profile table

  • a service references profile table

  • an interceptor references profile table

  • an external platform definitions profile table

  • an address subscriptions profile table

  • a service key subscriptions profile table (IN only)

  • a trigger address tracing profile table

  • an experimental features profile table

  • a Service Interaction Manager resource adaptor entity.

Creating a SIS Instance

Below are instructions for creating a SIS instance.

Tip Afterwards, you can provision macros, triggers, compositions, and subscriptions for it — see SIS Management in the SIS Overview and Concepts guide.

Running an -instance tool

You create a SIS instance by running one of the sis/<protocol>/3.2.x/admin/create-sis-<protocol>-instance tools (or create-sis-<protocol>-instance.bat on Windows). There is one tool for each protocol that the SIS supports (SIP or IN). When you execute the tool, it:

  1. asks for configuration parameters

  2. creates the profile tables and profiles it needs

  3. creates the configured SIS instance

  4. prompts you to activate it.

Command-line options

The SIS instance-creation tools accept the following (mutually exclusive) command-line options:

Option Description 
 -h

Displays command-line usage help.

 
 -r

Runs the tool using the settings from a previous run (stored in the etc/last-<protocol>-instance.properties file after the user confirms them).

 
 -u <filename>

Runs the tool using the settings from the specified file (a simple text file containing property variable assignments — see the etc/last-<protocol>-instance.properties file created by the tool after the first successful run for an example of its content).

 
 -y

Runs the tool in non-interactive mode, automatically accepting all settings. This option must be used with either -r or -u <filename> to provide values for properties that have no default.

Configuring SIS Instance Parameters

Creating a SIS instance requires the following parameters — general settings, network settings, default network interface settings, and profile tables — for SIP or IN:

SIP parameters

Below are SIS parameters for SIP general settings, network settings, default network interface settings, and profile tables.

SIP general settings

Parameter Description Example 
 Name

Name of the new SIS instance. This name is used for the Service Interaction Manager resource adaptor entity. Each resource adaptor entity in the SLEE must have a unique name.

 
 sis-sip
 
 Description

An optional arbitrary description for the SIS instance.

 
 My SIP SIS
 
 Default service timeout

Default timeout period, measured in milliseconds, used by the SIS when waiting for a response to an event from a service or extension component.

 
 5000
 
 SIS worker pool size

Number of processing threads available for handling internal SIS tasks.

 
 4
 
 SIS worker queue size

The size of the queue used for tasks awaiting the availability of a processing thread. If the queue is full, a subsequent task will be executed by the thread generating the task. If 0 is specified for the queue size, an unbound queue is used.

 
 50
 
 Maximum compositions

The maximum number concurrent active compositions the SIS will allow. This is to prevent the SIS from consuming excessive memory if composition state is not cleaned up due to an internal error. If the limit is reached, requests that attempt to start new compositions will be rejected with a 503 error response. A value of zero disables limiting.

 
 0
 
 Audit level

SIS auditing level — valid values are ALL, COMPONENT, and NONE

 
 NONE
 
 Fine-grained tracing enabled

Boolean flag indicating whether the fine-grained tracing facilities on the SIS are enabled (true) or disabled (false).

 
 false
 
 Session replication mode

Specifies session replication is enabled. Possible values are disabled, enabled, or automatic. The value automatic means replication is enabled if the SIS’s Rhino namespace supports the key-value store replication method.

 
 automatic
 
 Replicate by default

If true, and session replication is enabled, then all sessions are replicated. If false, and session replication is enabled, then a session is only replicated on demand, when the application calls SipSession.startReplicating().

 
 false

SIP network settings

Parameter Description Example 
 Automatic 100 Trying support

Boolean flag indicating if "100 Trying" responses should be automatically sent whenever an INVITE is received.

 
 true
 
 Automatic 100rel support

Boolean flag indicating if "Supported: 100rel" headers should be automatically added to to outgoing requests in UAC mode.

 
 true
 
 Automatic Dialog ID Rewriting Enabled

Boolean flag indicating if the SIS should rewrite headers that contain embedded dialog IDs, when forwarding requests between dialogs as a B2BUA. This is so that user agents on one side of the B2BUA don’t see Dialog IDs from the other side, which wouldn’t be recognised.

Applies to Target-Dialog and Replaces headers, including Replaces header values inside a Refer-To header.

 
 true
 
 Offset ports

Boolean flag indicating if the SIS should add an offset to its configured SIP ports. Used when there are multiple SIS nodes on the same host.

 
 false
 
 Port offset

If Offset ports is enabled, then the value of Node ID - Port offset is added to the SIS’s SIP port numbers. This value should match the lowest node ID in the cluster.

 
 101
 
 SIP worker pool size

Number of processing threads available to the SIP stack for handling incoming messages.

 
 4
 
 SIP worker queue size

The size of the queue used for tasks awaiting the availability of a processing thread. If the queue is full, the SIP stack will drop the message (UDP) or temporarily suspend reads on the socket (TCP and TLS). If 0 is specified for the queue size, an unbound queue is used.

 
 500
 
 TCP I/O threads

Number of processing threads for handling TCP I/O. TCP connections will be divided between the I/O threads.

 
 1
 
 [[configuring-sis-instance-parametersrate-limited-error-response-status-code]]Rate-limited error response status code

Specifies the status code to be used in an error response sent when an initial request or mid-dialog failover request is rejected due to rate limiting. This must be a 5xx error code.

 
 500
 
 Retry-After period

Specifies the Retry-After header value when an initial request or mid-dialog failover request is rejected due to rate limiting with a 500 or 503 error response. This is an integer value indicating the number of seconds after which the SIS expects to be available again.

If a negative value is specified then a Retry-After header will not be included in relevant responses.

 
 -1
 
 RFC3263 Failover Enabled

Specifies whether to use RFC 3263 failover and load balancing. By default this is disabled, to match existing behaviour. If enabled, the SIS uses RFC 3263 DNS procedures to find possible servers and automatically fails over to backup servers where available. If multiple servers are found in DNS they are sorted and tried according to their SRV priority and weight as per RFC 3263. If disabled, the DNS procedures are still used to find server addresses, but only the first address is used.

 
 false
 
 RFC3263 Failover Timer

Specifies the duration of the failover timer in milliseconds. If RFC 3263 failover is enabled and this timer expires before any responses were received, the SIS treats this as a transport error and tries sending the request to the next available server. This timer should be set to a value smaller than the default Timer B and Timer F timers (32s) so that failures can be detected promptly. A value of zero or less disables this timer.

 
 10000
 
 RFC3263 Blacklist Timer

The duration in milliseconds for which a server will be "blacklisted" after a failure is detected. This avoids the SIS trying to contact the server immediately after a failure, when it is probably just going to fail again. After this time has passed, the failed server may be tried again on subsequent client transactions. If a server specifies a Retry-After duration in a 503 response, that value will be used instead. If this property is zero or less, then no blocking of failed addresses will occur.

 
 300000
 
 UDP Max Request Size

The maximum size, in bytes, of SIP requests that may be sent sent using UDP. Requests larger than this will automatically be sent using TCP, as per RFC3261 §18.1.1. Values of zero or less disable this feature; the SIS will try to send with UDP anyway. This is not recommended as fragmentation and packet loss are more likely with large UDP datagrams.

 
 1300
 
 Reject Invalid Routes

Specifies whether to reject requests that arrive with a Route or Request-URI that the SIS does not recognize as its own address.

If true (default), the SIS rejects these requests with 403 for initial requests and 481 for mid-dialog requests.

If false, the SIS will attempt to forward the request to the next hop, which could cause unexpected behaviour such as routing loops.

 
 true
 
 Non-INVITE Trying Timer

The time (ms) at which an automatic 100 Trying response must be sent for all non-INVITE server transactions, regardless of transport protocol, as per RFC 4320.

Should almost always be left at the default of 3500ms, unless it is known that the network uses T1 and T2 values that differ from SIP defaults.

Non-INVITE server transactions on unreliable transports (UDP) always use this timer value.

A value of zero means the 100 Trying response is sent immediately.

Negative values disable this behaviour, so no automatic 100 Trying responses are sent.

 
 3500
 
 Non-INVITE Trying Timer (TCP)

The time (ms) at which an automatic 100 Trying response is sent for non-INVITE server transactions on TCP and other reliable transports, as per RFC 4320.

A negative value means inherit the configured Non-INVITE Trying Timer value (default 3500), this is the default setting. Otherwise a value between zero and Non-INVITE Trying Timer may be configured.

A value of zero means the 100 Trying response is sent immediately.

If Non-INVITE Trying Timer is disabled, this setting is ignored and no automatic 100 Trying responses are sent.

 
 -1
 
 Redact DTMF signals in SAS traces

Specifies whether to redact DTMF signals in SIP message traces sent to SAS. Applies to INFO requests with the "application/dtmf-relay" Content-Type. If true, SAS traces of these requests will have the DTMF signal characters replaced with "-", to prevent sensitive information leaking via SAS.

 
 false

SIP default network interface settings

Parameter Description Example 
 Virtual addresses

Optional comma-separated list of alternative hostnames that the SIS is known by, such as virtual IP addresses and hostnames in a cluster. When making routing decisions, the SIS will consider these names to be local.

 
 sis1.mydomain.com, sis2.mydomain.com
 
 IP address

The IP address or hostname for the SIS. The SIS will listen on this address. The address "AUTO" will automatically select the node’s primary IP address, for convenience and use in a cluster, where each node has its own IP address.

 
 AUTO
 
 Port

Port that will be used for unencrypted SIP transports (UDP, TCP).

 
 5060
 
 Secure port

Port that will be used for encrypted SIP transports (TLS).

 
 5061
 
 SIP transports

SIP transports to be supported by the SIS. This is a comma-separated list containing one or more of UDP, TCP or TLS.

 
 UDP,TCP
 
 Via sent-by address

Specifies an IP address or hostname that will be used in the "sent-by" field of Via headers added by the SIS. If a value is not specified the SIS will use the local IP address of the node. In some scenarios it may be necessary to specify a value to use a virtual server address.

 
 sis.mydomain.com

SIP profile tables

Parameter Description Example 
 Root configuration profile table name

Name of the root configuration profile table where the root configuration profile will be created. This defaults to the name specified for IN configurations during SIS installation.

 
 sis-configs-sip
 
 Root configuration profile name

Name of the root configuration profile to create for the SIS instance. This defaults to the SIS instance name.

 
 sis-sip
 
 Macros profile table name

Name of the profile table used to store SIS macros.

 
 sis-sip-macros
 
 Triggers profile table name

Name of the profile table used to store SIS triggers.

 
 sis-sip-triggers
 
 Compositions profile table name

Name of the profile table used to store SIS compositions.

 
 sis-sip-compositions
 
 Interceptors profile table name

Name of the profile table used to store SIS interceptors.

 
 sis-sip-interceptors
 
 Network Interface Definitions profile table name

Name of the profile table used to store SIS network interface definitions.

 
 sis-sip-network-interfaces
 
 Network Routes profile table name

Name of the profile table used to store SIS network routes.

 
 sis-sip-network-routes
 
 Extension References profile table name

Name of the profile table used to store SIS extension component references.

 
 sis-sip-extension-refs
 
 Service References profile table name

Name of the profile table used to store SIS service references.

 
 sis-sip-service-refs
 
 Interceptor References profile table name

Name of the profile table used to store SIS interceptor references.

 
 sis-sip-interceptor-refs
 
 External Platform Definitions profile table name

Name of the profile table used to store SIS external platform definitions.

 
 sis-sip-ext-platforms
 
 Address Subscriptions profile table name

Name of the profile table used to store SIS composition-provisioning information for triggerable addresses.

 
 sis-sip-address-subscriptions
 
 Trigger Address Tracing profile table name

Name of the profile table used to store fine-grained tracing information for arbitrary addresses that may appear in initial events.

 
 sis-sip-trigger-address-tracing
 
 Experimental Features profile table name

Name of the profile table used to store experimental feature settings.

 
 sis-sip-experimental-features

IN parameters

Below are SIS parameters for IN general settings, network settings, default network interface settings, and profile tables.

IN general settings

Parameter Description Example 
 Name

Name of the new SIS instance. This name is used for the Service Interaction Manager resource adaptor entity. Each resource adaptor entity in the SLEE must have a unique name.

 
 sis-in
 
 Description

An optional arbitrary description for the SIS instance.

 
 My IN SIS
 
 Default service timeout

Default timeout period, measured in milliseconds, used by the SIS when waiting for a response to an event from a service or extension component.

 
 2000
 
 SIS worker pool size

Number of processing threads available for handling internal SIS tasks.

 
 2
 
 SIS worker queue size

The size of the queue used for tasks awaiting the availability of a processing thread. If the queue is full, a subsequent task will be executed by the thread generating the task. If 0 is specified for the queue size, an unbound queue is used.

 
 5000
 
 Maximum dialogs

Maximum number of concurrent network dialogs the SIS will allow before rejecting new first-party conducted dialogs. A value of zero disables limiting.

Note Assisting and third-party call dialogs are never rejected by the SIS because of maximum dialog limiting, but do contribute towards the total network dialog count. 
 0
 
 Audit level

SIS auditing level — valid values are ALL, COMPONENT, and NONE

 
 NONE
 
 Fine-grained tracing enabled

Boolean flag indicating whether the fine-grained tracing facilities on the SIS are enabled (true) or disabled (false).

 
 false

IN network settings

Parameter Description Example 
 Query-liveness period

The period of inactivity on a dialog, measured in milliseconds, before the SIS will attempt to query the liveness of the dialog, if possible, via the ActivityTest operation or some other means. The minimum period that can be specified is 1000ms. The maximum is 86400000ms (one day). A value of 0 will disable this feature.

 
 180000
 
 ICA proxy SCCP address

SCCP address used by the SIS as the destination for dialog open requests created for third party call setup attempts initiated by services using an InitiateCallAttempt request. This setting is optional but must be specified in order for third-party call support to be enabled in the SIS. See also SCCP Address Format.

 
 type=C7,ri=pcssn,pc=201,ssn=100

IN default network interface settings

Below are general default network interface settings, followed by those specific to the ocss7, signalware, and tcapsim stacks.

Note
Using TCAP stacks
IN general default network interface settings
Parameter Description Example 
 Local SCCP address

SCCP address assigned to the SIS instance, included in dialog open requests sent by the SIS instance to the network. TIP: See also SCCP Address Format and Administering the CGIN Resource Adaptor Entity.

 
 type=C7,ri=pcssn,pc=202,ssn=101
 
 Responder SCCP address

SCCP address used by the SIS when sending responses to received dialog open requests. This setting is optional and only needs to be specified if an address different to that filled in by the TCAP stack when sending open responses is required. See also SCCP Address Format.

 
 type=C7,ri=pcssn,pc=202,ssn=101
 
 Default TCAP invoke timeout

The timeout period, measure in milliseconds, the SIS uses whenever it needs to send invoke requests to the network.

 
 5000
 
 Default dialog activity timeout

The default timeout period, measured in milliseconds, for dialogs with no activity before they are terminated.

 
 1800000
 
 TCAP fibers maximum pool size

The maximum number of threads in the TCAP layer fiber pool. If zero, then a pool is not used: work is done directly in the I/O thread.

 
 4
 
 TCAP fibers queue size

The maximum number of waiting fibers in the TCAP layer fiber pool.

If the queue becomes full and there are less than the maximum number of worker threads, a new thread is started. If the queue is full and no more threads are permitted, then subsequent fiber tasks are executed directly by the calling thread (usually the I/O thread).

A zero-sized queue is possible and implies that work is either immediately assigned an idle thread, or the work is done by the calling thread.

 
 250
 
 Inbound ACN mappings

Activity Context Name mappings for inbound dialogs: a comma-separated list of values in <external OID>:<internal ASN.1 or interceptor> format. Allows the SIS to be reconfigured to accept the external application context name as a synonym for the internal application context name. An external ACN can be mapped to only one internal ACN. Several external ACNs can be mapped to the same internal ACN. The righthand side of each mapping can either name an application context valueref (such as etsi_inap_cs1.core-INAP-CS1-SSP-to-SCP-AC, or it can name the interceptor to use to determine the AC to use (such as map.phase-1).

 
 1.2.34.567.8.9.0.1:etsi_inap_cs1.core-INAP-CS1-IP-to-SCP-AC
 
 Outbound ACN mappings

Activity Context Name mappings for outbound dialogs: a comma-separated list of values in <internal ASN.1>:<external OID> format. Allows the SIS to be reconfigured to write the external application context name in place of the internal application context name. An internal ACN can be mapped to only one external ACN. Multiple internal ACNs can be mapped to the same external ACN.

 
 etsi_inap_cs1.core-INAP-CS1-IP-to-SCP-AC:1.2.34.567.8.9.0.1
 
 Relaxed BER decoding rules

Specifies whether or not to relax the BER decoding rules to allow certain types of malformed data. If false, then the BER rules are strictly enforced and malformed data will be rejected.

 
 false
 
 TCAP stack

Name of the TCAP stack for the SIS to use. Three stacks are currently supported: ocss7, a TCAP stack that connects to one or more TCAP Manager (SGC) processes, signalware, a TCAP stack that connects to one or more backend processes running on Mavenir Signalware, and tcapsim, a simulated TCAP stack that does not require any specific hardware.

 
 ocss7
IN default network interface settings specific to the OC SS7 stack
Note

  • These parameters only need valid values if using the ocss7 TCAP stack.
Parameter Description Example 
 SGCs

Comma-separated list of host:port OC SGC data ports which the TCAP stack will connect to. The TCAP stack will attempt to establish a connection to all of the configured host:port pairs. For use with OCSS7 1.1.0 and newer.

 
 ocss71:8081,ocss72:8081
 
 URL List

Comma-separated list of host:port locations where the SIS instance can expect to find OC SS7 SGC TCAP Manager processes running and listening for connections from the SLEE. The TCAP stack will attempt to establish a connection to one of the configured TCAP managers on a round robin basis. For use with OCSS7 1.0.1 and older.

 
 ocss71:8080,ocss72:8080
 
 URL List Retry Interval

The wait interval in milliseconds between subsequent connection attempts to the TCAP Managers. This value applies to all TCAP manager connections.

 
 1000
 
 Local SSN

The subsystem number used when the Local SCCP Address property does not provide one, for example in the case when it is set to "auto".

 
 -1
 
 Open Transactions Capacity

The maximum number of open transactions (dialogs) at any moment in time.

 
 100000
 
 Max Scheduler Threads

The maximum number of threads used by the scheduler.

 
 10
 
 Scheduler Node List Size

The number of events that may be scheduled on a single scheduler thread. This value multiplied with the value for Max Scheduler Threads should be directly proportional to Open Transactions Capacity. 0 = autosize.

 
 0
 
 Waiting Tasks Capacity

The maximum number of inbound messages and timeout events that may be waiting to be processed at any moment in time. This value should be directly proportional to Open Transactions Capacity. 0 = autosize.

 
 0
 
 Worker Group Queues

The number of threads used by the worker group to process timeout events and inbound messages.

 
 100
 
 Worker Queue Size

The maximum number of tasks in one worker queue. This value multiplied with the value for Worker Group Queues should be directly proportional to (2 * Waiting Tasks Capacity). 0 = autosize.

 
 0
 
 Sender Queue Size

The maximum number of outbound messages in the sender queue. This value is directly proportional to Open Transactions Capacity. 0 = autosize.

 
 0
 
 Heartbeat Enabled

Enables the heartbeat between the TCAP stack and the SGC.

 
 true
 
 Heartbeat Period

The interval, in seconds, between successive heartbeat sends.

 
 5
IN network interface parameters specific to the Signalware stack
Note These parameters only need valid values if using the signalware TCAP stack.
Parameter Description Example 
 Backends

Comma-separated list of host:port locations where the SIS instance can expect to find Signalware backend processes running and listening for connections from the SLEE.

 
 signalware1:10001,signalware2:10001
 
 Base weight

Base incoming traffic weight advertised to backends.

This property is a comma-separated list that must include at least one numeric item — the weight value used by any node that does not explicitly specify a weight. Additional items may specify weights for particular nodes, using the form {nodeid,nodeid,…​}weight.

For example, the value 100,{101}50,{102,103}75 specifies a weight of 50 for node 101, a weight of 75 for nodes 102 and 103, and a default weight of 100 for all other nodes.

Each weight is a positive integer used to balance load between nodes. The values have no particular unit other than relative to each other. A node will receive new dialogs in proportion to its weight; for example, two nodes with weights of 10 will receive about the same number of dialogs each, and a node with a weight of 20 will receive twice as many as a node with a weight of 10.

Tip One approach is to treat them as percentages and assign 100 to the busiest node, with smaller values for nodes that take less load.

The actual weight used for a particular node is the base weight specified here, modified by the function defined by weight function below, based on the amount of traffic that node has processed.

 
 100
 
 Weight function

Definition of the weight function applied to "full-rate" weights to find the actual rate to use. This is used to gradually increase load on a newly-joined cluster node, so as not to immediately swamp it with traffic.

The function is specified as a series of comma-separated values S(1),T(1),S(2),T(2),…​,S(N-1),T(N-1),S(N) where:

  • S(i) is the multiplier (in the range [0.0 .. 1.0]) of the "full-rate" weight to use in state (i)

  • T(i) is the total number of dialogs that must be received on a particular node before moving to state (i+1).

 
 0.01,10,0.10,1000,0.50,5000,1.00
 
 Fiber map size

The number of fibers in the fixed-size fiber map used to process incoming traffic. This value must be at least as large as the value of the TCAP Fibers Queue Size property.

 
 256
 
 Dialog allocation timeout

The maximum time, in milliseconds, to block while waiting to allocate a new dialog before returning an error to the calling service code.

 
 5000
 
 Dialog pool size

The size of the pre-allocation pool for outgoing dialogs. This pool is used to satisfy requests for new outgoing dialogs, and is refilled asynchronously. If the pool becomes empty due to a high rate of dialog creation, outgoing dialogs must wait for the backend to allocate a new dialog, increasing latency.

One pool is maintained per backend connection.

 
 100
IN network interface parameters specific to the tcapsim stack
Note These parameters only need valid values if using the tcapsim TCAP stack.
Parameter Description Example 
 Global title translation table

Path to the file containing the global translation table description

 
 ${rhino.dir.home}${/}config${/}tcapsim-gt-table.txt
 
 Listen addresses

Comma-separated list of {nodeid,…​}host:port addresses to listen on for incoming connections from other Sim TCAP stacks.

 
 localhost:10100
 
 Remote addresses

Comma-separated list of {nodeid,…​}host:port addresses of other Sim TCAP stacks that should be connected to.

 
 localhost:10150
 
 Maximum dialogs

Maximum number of concurrent dialogs the stack can support.

 
 10000
 
 Base transport layer

Base transport layer used to carry SUA messages. Valid values are: tcp, sctp and auto. Default is tcp.

 
 tcp

IN profile tables

Parameter Description Example 
 Root configuration profile table name

Name of the root configuration profile table where the root configuration profile will be created. This defaults to the name specified for IN configurations during SIS installation.

 
 sis-configs-in
 
 Root configuration profile name

Name of the root configuration profile to create for the SIS instance. This defaults to the SIS instance name.

 
 sis-in
 
 Macros profile table name

Name of the profile table used to store SIS macros.

 
 sis-in-macros
 
 Triggers profile table name

Name of the profile table used to store SIS triggers.

 
 sis-in-triggers
 
 Compositions profile table name

Name of the profile table used to store SIS compositions.

 
 sis-in-compositions
 
 Interceptors profile table name

Name of the profile table used to store SIS interceptors.

 
 sis-in-interceptors
 
 Network Interface Definitions profile table name

Name of the profile table used to store SIS network interface definitions.

 
 sis-in-network-interfaces
 
 Network Routes profile table name

Name of the profile table used to store SIS network routes.

 
 sis-in-network-routes
 
 Extension References profile table name

Name of the profile table used to store SIS extension component references.

 
 sis-in-extension-refs
 
 Service References profile table name

Name of the profile table used to store SIS service references.

 
 sis-in-service-refs
 
 Interceptor References profile table name

Name of the profile table used to store SIS interceptor references.

 
 sis-in-interceptor-refs
 
 External Platforms profile table name

Name of the profile table used to store SIS external platform definitions.

 
 sis-in-ext-platforms
 
 Address Subscriptions profile table name

Name of the profile table used to store SIS composition-provisioning information for triggerable addresses.

 
 sis-in-address-subscriptions
 
 Service Key Subscriptions profile table name

Name of the profile table used to store SIS composition-provisioning information for triggerable service keys.

 
 sis-in-service-key-subscriptions
 
 Service Configuration profile table name

Name of the profile table used to store configuration information for services that the SIS fires events to.

 
 sis-in-service-configs
 
 Trigger Address Tracing profile table name

Name of the profile table used to store fine-grained tracing information for arbitrary addresses that may appear in initial events.

 
 sis-in-trigger-address-tracing
 
 Experimental Features profile table name

Name of the profile table used to store experimental feature settings.

 
 sis-in-experimental-features

Activating a SIS Instance

As part of the installation, you can activate a SIS instance (if licensed).

Activation

To activate a SIS instance during installation, answer the following prompt from the create-sis-<protocol>-instance tool:

  Activate the instance?
  ----------------------
  Should the new SIS instance be activated once it has been successfully
  created?
  Valid values are: true, false

  Activate the instance? [true]:

Licensing

You cannot activate a SIS instance unless a suitable license is installed in Rhino. License files can be obtained from Metaswitch.

Tip The SIS installation process includes an option to install a license file.

Removing a SIS Instance

Note There is currently no automated method for removing a SIS instance.

To remove a SIS instance:

1
Deactivate the SIS Service Interaction Manager resource adaptor entity

The first step to removing a SIS instance from the SLEE is to remove its SIS Service Interaction Manager resource adaptor entity. To be removed, the entity must be in the INACTIVE state. To let it return to that state, deactivate it — that will put it in the STOPPING state, and when no more activities it owns are in the SLEE, the SLEE will move it to the INACTIVE state.

For example, to deactivate the SIS resource adaptor entity called sis-in:

$ ./rhino-console deactivateRAEntity sis-in
Deactivating resource adaptor entity sis-in on node(s) [101]
Resource adaptor entity transitioned to the Stopping state on node 101

2
Remove the SIS Service Interaction Manager resource adaptor entity

Once the resource adaptor entity is in the INACTIVE state, you can remove it from the SLEE using the removeRAEntity command of the command-line management client. For example, to remove an inactive IN Service Interaction Manager resource adaptor entity called sis-in:

$ ./rhino-console listraentities
sis-in
...
$ ./rhino-console removeraentity sis-in
Removed resource adaptor entity sis-in

3
Remove the root configuration profile

To remove the root configuration profile for a SIS instance, use the removeprofile command. For example, to remove the profile named sis-in from the sis-configs profile table:

$ ./rhino-console listprofiles sis-configs
sis-in
...
$ ./rhino-console removeprofile sis-configs sis-in
Removed profile sis-configs/myconfig

4
Remove the profile tables

To remove the profile tables containing configuration information for a SIS instance, you can use the listprofiletables command to list them, and then removeprofiletable commands to remove them. For example:

$ ./rhino-console listprofiletables
sis-in-address-subscriptions
sis-in-compositions
sis-in-experimental-features
sis-in-ext-platforms
sis-in-extension-refs
sis-in-interceptor-refs
sis-in-interceptors
sis-in-macros
sis-in-network-interfaces
sis-in-network-routes
sis-in-service-key-subscriptions
sis-in-service-refs
sis-in-trigger-address-tracing
sis-in-triggers
sis-configs-in
sis-configs-sip
...
$ ./rhino-console removeprofiletable sis-in-address-subscriptions
Removed profile table sis-in-address-subscriptions
$ ./rhino-console removeprofiletable sis-in-service-key-subscriptions
Removed profile table sis-in-service-key-subscriptions
$ ./rhino-console removeprofiletable sis-in-trigger-address-tracing
Removed profile table sis-in-trigger-address-tracing
$ ./rhino-console removeprofiletable sis-in-interceptors
Removed profile table sis-in-interceptors
$ ./rhino-console removeprofiletable sis-in-compositions
Removed profile table sis-in-compositions
$ ./rhino-console removeprofiletable sis-in-macros
Removed profile table sis-in-macros
$ ./rhino-console removeprofiletable sis-in-triggers
Removed profile table sis-in-triggers
$ ./rhino-console removeprofiletable sis-in-network-interfaces
Removed profile table sis-in-network-interfaces
$ ./rhino-console removeprofiletable sis-in-network-routes
Removed profile table sis-in-triggers
$ ./rhino-console removeprofiletable sis-in-interceptor-refs
Removed profile table sis-in-interceptor-refs
$ ./rhino-console removeprofiletable sis-in-service-refs
Removed profile table sis-in-service-refs
$ ./rhino-console removeprofiletable sis-in-extension-refs
Removed profile table sis-in-extension-refs
$ ./rhino-console removeprofiletable sis-in-ext-platforms
Removed profile table sis-in-ext-platforms
$ ./rhino-console removeprofiletable sis-in-experimental-features
Removed profile table sis-in-experimental-features

Removal of the SIS instance is now complete.

Tip The SIS uninstallation process also automatically removes all SIS instances.

Reconfiguring a SIS Instance

You can reconfigure a SIS instance by:

  • changing its resource adaptor entity configuration properties using the SLEE’s ResourceManagementMBean or

  • changing any other configuration property managed using a SIS MBean interface.

Changing resource adaptor entity configuration properties

The SIS supports limited active reconfiguration (see section 15.4.2 of the JAIN SLEE 1.1 specification). Changes to some configuration properties while the SIS instance is ACTIVE will not take effect until you deactivate and reactivate the SIS instance (see below).

Warning

A SIS IN instance raises an alarm if it’s in the ACTIVE state and you try to change any configuration property that does not support active reconfiguration.

SIP network interfaces and network routes do not support active reconfiguration. IN network interfaces and network routes support active reconfiguration.

Active reconfiguration with SIP

Property ACTIVE reconfiguration? 
 configurationProfileID

YES

 
 SISWorkerPoolSize

YES

 
 SISWorkerQueueSize

YES

 
 automatic100TryingSupport

YES

 
 automaticRel100Support

YES

 
 WorkerPoolSize

NO

 
 WorkerQueueSize

NO

 
 TCPIOThreads

NO

 
 sessionReplicationMode

NO

 
 replicateByDefault

NO

 
 max-compositions

YES

 
 rateLimitedResponseCode

YES

 
 retryAfterPeriod

YES

Active reconfiguration with IN

Property ACTIVE reconfiguration? 
 configurationProfileID

YES

 
 enabledProtocols

NO

 
 SISWorkerPoolSize

YES

 
 SISWorkerQueueSize

YES

 
 icaProxySccpAddress

YES

 
 iddPrefix

YES

 
 countryCode

YES

 
 max-dialogs

YES

Changing MBean-managed configuration properties

If you change any MBean-managed configuration property of a SIS instance, generally before those changes take effect you must tell the instance to reload its configuration. The exceptions, when a forced configuration reload is not necessary, are:

  • any address or service key subscription provisioning changes (excluding changing the configured subscription profile table names)

  • any IN trigger address tracing provisioning changes (excluding changing the configured trigger address tracing profile table name)

  • changing any fine-grained tracing debug levels or component audit level settings.

Rate Limiting

SIS provides two ways for managing network traffic overload conditions:

  • Limiter endpoints — for connecting with the standard Rhino platform rate limiter functionality

  • SIP overload control — an API allowing custom SIP network traffic management using user-defined plugin logic.

Limiter Endpoints

A SIS instance provides the following limiter endpoints for Rhino platform rate limiting:

 inbound

This limiter endpoint can be used to control the rate that incoming initial requests received from the network are accepted for processing by the SIS.

The SIS requests one unit of work from this limiter endpoint for each initial request that it receives. If the request is granted then initial request processing proceeds normally. If, however, the work request is rejected by a rate limiter connected to the endpoint, then the SIS stops processing the initial request and returns an error response determined by the rate-limited error response status code and Retry-After period configuration properties.

 
 inbound_invites

(SIP only)
This limiter endpoint can be used to control the rate that incoming initial INVITE requests received from the network are accepted for processing by the SIS.

This limiter endpoint is a "sub-endpoint" of the inbound endpoint. For each initial INVITE, the SIS requests one unit of work from the inbound endpoint, and if that is granted, another unit of work is requested from the inbound_invites endpoint. By configuring the inbound endpoint with a rate limiter of higher capacity than inbound_invites, the SIS can throttle initial INVITEs while still allowing other initial requests to proceed.

If the initial INVITE is rejected by a rate limiter connected to the endpoint, then the SIS stops processing the INVITE and returns an error response determined by the rate-limited error response status code and Retry-After period configuration properties.

 
 failover

(SIP only)
This limiter endpoint is used by the SIS when Rhino key/value store replication is in use and the SIS receives a mid-dialog request on a dialog that it has no local state for.

Before querying the Session Ownership Facility in an attempt to retrieve the state for the dialog, the SIS requests one unit of work from this limiter endpoint. If the request is granted then the Session Ownership Facility is queried normally. If, however, the work request is rejected by a rate limiter connected to the endpoint, then the SIS stops processing the mid-dialog request and returns an error response determined by the rate-limited error response status code and Retry-After period configuration properties.

In summary, the purpose of this limiter endpoint is to limit the number of queries made to the key/value store backend database (typically Cassandra) under failover conditions.

SIP Overload Control

In addition to limiter endpoints for platform rate limiting, the SIP SIS also provides a Java API allowing the implementation of custom overload control plugins. Overload control plugins are invoked by the SIS for every request received from the network prior to the application of regular endpoint rate limiting.

Overload Control Plugin Registration

An overload control plugin is registered with a SIS instance using the SipFactory.registerOverloadControlPlugin(SipOverloadControlPlugin) operation. At most one plugin may be registered with each SIS instance in each JVM at any one time. Attempting to register a plugin while one is already registered will replace the existing registration with the new one.

Overload control plugins are expected to be registered with the SIS by an SBB. For example, the root SBB of a service may respond to a ServiceNodeStartedEvent by instantiating a plugin implementation object and registering that with the SIS when the service is activated. Later, when the service is deactivated and the ServiceNodeActivity ends, the SBB would deregister the plugin from the SIS.

Overload Control Plugin API

The Java API for the overload control plugin is given here. The interface contains only a single operation - invoke(SipRequest) - which the SIS invokes when it needs an overload control instruction for an inbound network request. An overload control plugin may return one of four instructions for each request it considers:

 accept

The request is accepted by the overload control plugin and should be passed up the software stack as a normal request. If the request is an initial request, this means it is subject to regular SIS rate limiting.

 
 exempt

The request is accepted by the overload control plugin is considered exempt from regular SIS rate limiting. This means it must be passed up the software stack into the Session and Application layers.

 
 reject

The request has been rejected by the overload control plugin and a SIP error response should be returned to the network. The overload control plugin may provide the response to use for the request, otherwise the SIS will use its default rate limiting error response instead.

Caution must be used when rejecting requests, as doing so may break various call flows and application state machines. As a rule of thumb, mid-dialog requests should not be rejected, and careful consideration should be given to which initial requests should be exempt from overload control.

 
 discard

The request and any associated server transaction state should be discarded with no SIP response sent. Discarded requests may be observable through side effects such as statistics, TCP sequence numbers, etc.

Extreme caution must be used when discarding requests. The specific algorithm must be very well thought through. If in doubt, never discard a request.

Example Overload Control Plugin

A simple overload control plugin example is provided in the Appendix.

Exporting SIS State

The SIS exporter tool sis-export exports the state of a SIS instance as an Ant script. The script, when executed with Ant, invokes a series of management commands to restore the state of that SIS instance into Rhino.

Warning The SIS exporter is not a standalone tool for generating an export image of a SIS instance in a Rhino SLEE. sis-export only exports the configuration state of a SIS instance, under the assumption that when the export script is run the SIS will have already been installed into Rhino and the SIS instance being configured recreated.

Below are details of what sis-export exports, instructions for using sis-export, a sample export, and list of files exported.

What does the SIS exporter export?

Below are listings of what sis-export does and does not export.

The SIS exporter exports from a SIS instance: The SIS exporter does not export:

  • deployable units installed in the SLEE, including:

    • deployable units for SIS and its dependencies

    • deployable units for any extension components or services used by their respective references in the SIS instance

  • profile tables used by the SIS instance

  • resource adaptor configuration properties used to recreate the SIS instance

  • SIS address or service key subscription information

    • subscription information may be too numerous to generate individual management operations for

  • SIS trigger address tracing information.

Tip You can export these items using the rhino-export shell script.

Export instructions

To export a SIS instance, use the sis-export tool in the SIS admin directory.

Warning You cannot run sis-export unless the Rhino SLEE is available and ready to accept management commands, and you include at least two arguments — the name of the SIS instance to export and the directory to write the export image to.

Command-line arguments

You can include the following command-line arguments with sis-export:

$ cd sis/<protocol>/<version>/admin
$ ./sis-export
Valid command line options are:
-h <host>            - The hostname to connect to.
-p <port>            - The port to connect to.
-u <username>        - The user to authenticate as.
-w <password>        - The password used for authentication.
-D                   - Display connection debugging messages.
-l                   - List SIS instances found in the Rhino connected to.
-f                   - Removes the output directory if it exists.
<sis-name>           - The name of the SIS instance to export.
<output-directory>   - The destination directory for the export.

Usually, only the <sis-name> and <output-directory> arguments must be
specified.
All other arguments will be read from 'client.properties' in the Rhino client
directory.

Sample SIS export

For example, an export might run as follows:

$ cd sis/<protocol>/<version>/admin
$ ./sis-export sis ../../../../sis_export
Connecting to localhost:1199
Export complete

Exported files

The SIS exporter creates:

  • a new sub-directory, such as sis_export (as specified by the command-line parameter)

  • all macro, trigger, composition, and interceptor files that are installed in the SIS instance

  • an Ant script called build.xml, which can be used later to initiate the import process.

For example:

$ cd ../../../../sis_export
$ ls
build.xml
compositions
import.properties
interceptors
macros
triggers

Exported files and directories include:

File or directory Description 
 build.xml

The main Ant build file, which gives Ant the information it needs to import all the macros, triggers, compositions, and configuration state of this export directory into the SLEE.

 
 import.properties

A file with configuration information that includes the location of the SIS directory containing the required Java libraries.

 
 macros

A directory containing the macros installed in the SIS instance.

 
 triggers

A directory containing the triggers installed in the SIS instance.

 
 compositions

A directory containing the compositions installed in the SIS instance.

 
 interceptors

A directory containing the interceptors installed in the SIS instance.

Importing SIS State

Below are instructions and an example of using sis-import to import an exported SIS instance.

Instructions

To import an exported SIS instance:

1

First, set up prerequisites for importing the exported SIS instance:

  • Install the SIS.

  • Create the SIS instance.

  • Install any services or extension components the SIS instance will depend on.

2

Then verify properties and run the import:

  • First check the import.properties file in the SIS export directory,
    and update it if necessary.

    This file defines a value for the sis.home property, which indicates the SIS install that will be used for the import (and consequently the Rhino SLEE that will be connected to).

  • To import the state of a SIS export directory into a Rhino SLEE, run the sis-import tool in the SIS admin directory, passing as a parameter the path of the SIS export directory.

    (You can also manually run Ant directly, specifying the build.xml file in the export directory as the Ant build file to run.)

Example

Below is a sample import of an exported SIS instance:

$ cd sis/in/3.2.0/admin
$ ./sis-import ../../../sis_export
Buildfile: ../../../build.xml
     [echo] Loading properties from /home/user/rhino/sis/in/3.2.0/admin/etc/client.ant.properties...
     [echo] Loading properties from /home/user/rhino/sis/in/3.2.0/admin/etc/common.ant.properties...
     [echo] Loading properties from /home/user/rhino/sis/in/3.2.0/admin/etc/in.ant.properties...

management-init:
     [echo] Open Cloud Rhino SLEE Management tasks defined

login:
[slee-management] Establishing new connection to localhost:1199
[slee-management] Connected to localhost:1199 (101) [Rhino-SDK (version='3.0', release='0.2', build='201911180954', revision='1c064dc')]

configure-sis:
[sis-in-management] Connected to admin@localhost:1199/sis-in
[sis-in-management] [Failed] Network interface definition already exists: sis-in-default
[sis-in-management] [Failed] Network interface sis-in-default is already enabled
[sis-in-management] [Failed] A default route is already specified for this SIS instance
[sis-in-management] Fine-grained tracing disabled
[sis-in-management] Audit level set to NONE
[sis-in-management] Default service timeout set to 2000ms
[sis-in-management] Reloaded SIS RA Entity sis-in

BUILD SUCCESSFUL
Total time: 1 second

Managing the SIS

You can manage the SIS using console commands, Ant tasks, and MBean operations.

MBean interfaces

The following topics cover JMX MBean interfaces for SIS management:

To get the object name of these MBeans, there’s another MBean interface: the SIS Management MBean. The object name of this MBean is equal to the string: com.opencloud.SIS:name=<sis-instance-name>,type=SISManagement.

Other management functions

Additionally, the SIS provides management functions for:

Managing SIS Configuration

The Configuration Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Get and set the SIS instance description

 
 getdescription
setdescription
 
 Configuration Management &rarr; getDescription
Configuration Management &rarr; setDescription

Procedure: Get and set the global default service timeout

 
 getDefaultServiceTimeout
setDefaultServiceTimeout
 
 Configuration Management &rarr; getDefaultServiceTimeout
Configuration Management &rarr; setDefaultServiceTimeout

Procedure: Get and set the "concatenated" FCI interaction mode delimiter

 
 getConcatenatedFCIInteractionModeDelimiter
setConcatenatedFCIInteractionModeDelimiter
 
 Configuration Management &rarr; getConcatenatedFCIInteractionModeDelimiter
Configuration Management &rarr; setConcatenatedFCIInteractionModeDelimiter

Procedure: Get and set the flag indicating if fine-grained tracing is enabled

 
 isfinegrainedtracingenabled
setfinegrainedtracingenabled
 
 Configuration Management &rarr; getFineGrainedTracingEnabled
Configuration Management &rarr; setFineGrainedTracingEnabled

Procedure: Get and set the audit level for the SIS instance

 
 getauditlevel
setauditlevel
 
 Configuration Management &rarr; getAuditLevel
Configuration Management &rarr; setAuditLevel

Procedure: Get and set the macro that tells whether a SIP request is originating

 
 getoriginatingmacro
setoriginatingmacro
 
 SIP Configuration Management &rarr; getOriginatingMacro
SIP Configuration Management &rarr; setOriginatingMacro

Procedure: Reload the SIS configuration

 
 reload
 
 _(none)_

Procedure: Audit the SIS configuration

 
 audit
 
 SIS Management &rarr; audit

Getting and Setting the Description

To get or set the description of a SIS instance, use the following sis-console commands or related MBean operations.

Warning The SIS description is an arbitrary descriptive string for the SIS instance — for human consumption only. Its value has no bearing whatsoever on the operation of the SIS.

Console commands

getDescription

Command

 
getdescription <ra-entity>
    Get SIS description

Example

To get the description of the SIS instance named sis-cap1:

$ ./sis-console getdescription sis-cap1
Current description: Configuration for 1st SIS RA Entity (composition selection by XML)

setDescription

Command

 
setdescription <ra-entity> <description>
    Set SIS description

Example

To set the description of the SIS instance named sis-cap2 to the string Configuration for 2nd SIS RA Entity:

$ ./sis-console setdescription sis-cap2 "Configuration for 2nd SIS RA Entity"
Description set to Configuration for 2nd SIS RA Entity

MBean operations

MBean

Configuration Management

getDescription

operation

 
public String getDescription()
    throws ManagementException;

setDescription

operation

 
public void setDescription(String desc)
    throws ManagementException;

Getting and Setting the Global Default Service Timeout

To get or set the default service timeout of a SIS instance, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getSisDefaultServiceTimeout

Command

 
getsisdefaultservicetimeout <ra-entity>
    Get default service timeout

Example

To get the default service timeout of the SIS instance named sis:

$ ./sis-console getsisdefaultservicetimeout sis
Default service timeout is 2000ms

setSisDefaultServiceTimeout

Command

 
setsisdefaultservicetimeout <ra-entity> <timeout>
    Set default service timeout, measured in milliseconds

Example

To set the default service timeout of the SIS instance named sis to 5000ms:

$ ./sis-console setsisdefaultservicetimeout sis 5000
Default service timeout set to 5000ms

Ant task

setDefaultServiceTimeout

Task

 
<setdefaultservicetimeout timeout="..."/>

Example

 
<sis-in-management>
  <setdefaultservicetimeout timeout="5000"/>
</sis-in-management>

or

<sis-sip-management>
  <setdefaultservicetimeout timeout="5000"/>
</sis-sip-management>

MBean operations

MBean

Configuration Management

getDefaultServiceTimeout

Operation

 
public long getDefaultServiceTimeout()
    throws ManagementException;

setDefaultServiceTimeout

Operation

 
public void setDefaultServiceTimeout(long timeout)
    throws IllegalArgumentException, ManagementException;
Warning The timeout argument must be at least 100.

Getting and Setting the Concatenated FCI Interaction Mode Delimiter

To get or set the "concatenated" FCI interaction mode delimiter, use the following sis-console commands, Ant task, or related MBean operations.

Tip This is a SIS feature for IN

Console commands

getConcatenatedFCIInteractionModeDelimiter

Command

 
getconcatenatedfciinteractionmodedelimiter <ra-entity>
   Get delimiter used for a composition when its FCI Interaction mode is set to
   'concatenation'

Example

To get the concatenated FCI interaction delimiter for the SIS instance named sis:

$ ./sis-console getconcatenatedfciinteractionmodedelimiter sis
Current delimiter is [0x5e]

setConcatenatedFCIInteractionModeDelimiter

Command

 
setconcatenatedfciinteractionmodedelimiter <ra-entity> <delimiter>
   Set delimiter used for a composition when its FCI Interaction mode is set to
   'concatenation'. Delimiter is a comma-separated list of hexadecimal byte values,
   eg. '00,0f,ff'

Example

To set the delimiter for the SIS instance named sis to the bytes 0x5c,0x5c:

$ ./sis-console setconcatenatedfciinteractionmodedelimiter sis 5c,5c
Delimiter set to [0x5c,0x5c]

Ant task

setConcatenatedFCIInteractionModeDelimiter

Task

 
<setconcatenatedfciinteractionmodedelimiter delimiter="..."/>

Example

 
<sis-in-management>
    <setconcatenatedfciinteractionmodedelimiter delimiter="5c,5c"/>
</sis-in-management>

MBean operations

MBean

Configuration Management

getConcatenatedFCIInteractionModeDelimiter

operation

 
public byte[] getConcatenatedFCIInteractionModeDelimiter()
        throws ManagementException;

setConcatenatedFCIInteractionModeDelimiter

operation

 
public void setConcatenatedFCIInteractionModeDelimiter(byte[] delimiter)
        throws ManagementException;

Getting and Setting the Fine-Grained Tracing Enabled Flag

To get or set the fine-grained tracing enabled flag, use the following sis-console commands, Ant task, or related MBean operations:

Console commands

isFineGrainedTracingEnabled

Command

 
isfinegrainedtracingenabled <ra-entity>
     Determine if fine-grained tracing is enabled in the SIS

Example

To determine if fine-grained tracing is enabled for the SIS instance named sis:

$ ./sis-console isfinegrainedtracingenabled sis
Fine-grained tracing is currently disabled

setFineGrainedTracingEnabled

Command

 
setfinegrainedtracingenabled <ra-entity> <boolean>
    Enable/disable SIS fine-grained tracing

Example

To enable fine-grained tracing for the SIS instance named sis:

$ ./sis-console setfinegrainedtracingenabled sis true
Fine-grained tracing enabled

Ant task

setFineGrainedTracingEnabled

Task

 
<setfinegrainedtracing enabled="..."/>

Example

 
<sis-in-management>
    <setfinegrainedtracing enabled="true"/>
</sis-in-management>

or

<sis-sip-management>
    <setfinegrainedtracing enabled="true"/>
</sis-sip-management>

MBean operations

MBean

Configuration Management

getFineGrainedTracingEnabled

Operation

 
public boolean getFineGrainedTracingEnabled()
    throws ManagementException;

setFineGrainedTracingEnabled

Operation

 
public void setFineGrainedTracingEnabled(boolean enabled)
    throws ManagementException;

Getting and Setting the Audit Level

To get and set the level at which the SIS performs audit logging use the following sis-console commands, Ant task, or related MBean operations:

Console commands

getAuditLevel

Command

 
getauditlevel <ra-entity>
    Get the SIS audit logging level

Example

To get the audit logging level for the SIS instance named sis:

$ ./sis-console getauditlevel sis
Audit level is NONE

setAuditLevel

Command

 
setauditlevel <ra-entity> <boolean>
    Set the SIS audit logging level: ALL, COMPONENT or NONE

Example

To set the audit logging level for the SIS instance named sis to ALL:

$ ./sis-console setauditlevel sis ALL
Audit level set to ALL

Ant task

setAuditLevel

Task

 
<setauditlevel level="..."/>

Example

 
<sis-in-management>
    <setauditlevel level="ALL"/>
</sis-in-management>

or

<sis-sip-management>
    <setauditlevel level="ALL"/>
</sis-sip-management>

MBean operations

MBean

Configuration Management

getAuditLevel

Operation

 
public AuditLevel getAuditLevel()
    throws ManagementException;

setAuditLevel

Operation

 
public void setAuditLevel(AuditLevel level)
    throws ManagementException;

Getting and Setting the SIP Originating Macro

To get or set the SIP originating macro, use the following sis-console command, Ant task, or related MBean operation:

Note
About the SIP Originating Macro

Unlike IN protocols, SIP has no standard for determining whether an initial request is as an "originating" or "terminating" trigger. This is network-specific.

The SIS needs to know whether the request is originating or terminating when it determines the trigger address tracing selectors for an initial request. The SIS uses a user-defined macro to do this for SIP.

This macro is specified using the commands below. It must return true if an initial request is an originating trigger. If the macro returns false, the SIS treats the request as if it was a terminating trigger. If no originating macro is configured, the SIS treats all initial requests as originating, for the purposes of trigger address tracing.
Tip This is a SIS feature for SIP.

Console commands

getSIPOriginatingMacro

Command

 
getsiporiginatingmacro <ra-entity>
    Get the currently configured SIP originating macro.

Example

 
$ sis-console getsiporiginatingmacro sipsis
Current originating macro is MacroID[name=IsOriginating,vendor=OpenCloud,version=1.0]

setSIPOriginatingMacro

Command

 
setsiporiginatingmacro <ra-entity> <macro-id>
    Set the macro used by trigger address tracing to determine if an initial
    SIP request is originating or terminating.

Example

 
$ sis-console setsiporiginatingmacro sipsis name=IsOriginating,vendor=OpenCloud,version=1.0
Originating macro set to MacroID[name=IsOriginating,vendor=OpenCloud,version=1.0]

Ant task

setSIPOriginatingMacro

Task

 
<setsiporiginatingmacro>
    <macro name="..." vendor="..." version="..."/>
</setsiporiginatingmacro>

Example

 
<sis-sip-management>
    ...
    <setsiporiginatingmacro>
        <macro name="Originating" vendor="XYZ" version="1.1"/>
    </setsiporiginatingmacro>
</sis-sip-management>

MBean operations

MBean

SIP Configuration Management

getOriginatingMacro

Operation

 
public MacroID getOriginatingMacro() throws ManagementException;

setOriginatingMacro

Operation

 
public void setOriginatingMacro(MacroID id) throws ManagementException;

Reloading SIS Configuration

To reload the SIS configuration, use the following sis-console command, Ant task, or related MBean operation.

Warning The SIS caches its configuration for performance reasons. Changes to SIS components, such as installing, uninstalling or activating components, do not take effect immediately. The SIS must explicitly reload its components to apply any changes.

Console command

reload

Command

 
reload <ra-entity>
    Reload SIS configuration, required for changes to take effect.
Note This command tells the SIS to reload all cached configuration data.

Example

To reload the configuration for the SIS instance named sis:

$ ./sis-console reload sis
Reloaded SIS RA Entity sis

Ant task

reload

Command

 
<reload/>

Example

 
<sis-in-management>
    <reload/>
</sis-in-management>

or

<sis-sip-management>
    <reload/>
</sis-sip-management>

MBean operation

MBean

No SIS MBean is required.

updateConfigurationProperties

Operation

The reload command calls the standard SLEE 1.1 MBean operation: ResourceManagementMBean.updateConfigurationProperties.

Auditing SIS Configuration

To audit the SIS configuration, use the following sis-console command or related MBean operation.

Note

The SIS audit function verifies, for the current configuration, that the following referenced components exist:

  • macros referenced by other macros

  • macros, services, and compositions referenced by triggers

  • macros and services referenced by compositions

  • services referenced by extension references

  • services and external platform definitions referenced by service references

  • compositions referenced by address and service key subscriptions.

If the audit finds any of these missing, the SIS logs a warning message and raises an alarm

Console command

audit

Command

 
audit <ra-entity>
    Audit the SIS configuration, checking for missing components.
Note This command asks the SIS to audit configuration data.

Example

To audit the configuration for the SIS instance named sis:

$ ./sis-console audit sis
Audit completed successfully

MBean operation

MBean

SIS Management

audit

Operation

 
public void audit()
    throws AuditFailedException, ManagementException;

Managing Macros

The Macro Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Managing reusable expressions

A macro is an expression that can be reused multiple times in other SIS macros, triggers, and compositions.
sis-console command(s) MBean(s) → Operation

Procedure: Install a macro

 
 installmacro
 
 Macro Management &rarr; install

Procedure: Replace an existing macro

 
 replacemacro
 
 Macro Management &rarr; replace

Procedure: Uninstall a macro

 
 uninstallmacro
 
 Macro Management &rarr; uninstall

Procedure: View a macro

 
 listmacros
dumpmacro
 
 Macro Management &rarr; getMacros
Macro Management &rarr; getMacro

Installing Macros

To install a macro, use the following sis-console command, Ant task, or related MBean operations.

Console command

installmacro

Command

 
installmacro <ra-entity> <file>
    Installs a macro component from a file.
Warning This command installs in the SIS a macro XML file — which must be on the local filesystem of the management client.

Example

To install macro example-macro.xml from the local filesystem of the management client into the SIS instance named sis:

$ ./sis-console installmacro sis example-macro.xml
Installed macro MacroID[name=Example,vendor=ABC,version=1.0] from file example-macro.xml

Ant task

installmacro

Task

 
<installmacro file="..."/>

Example

 
<sis-in-management>
    <installmacro file="example-macro.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <installmacro file="example-macro.xml"/>
</sis-sip-management>

MBean operations

MBean

Macro Management

install

Operation

To install a macro from a URL:

public MacroID install(String url)
    throws NullPointerException, MalformedURLException,
           AlreadyDeployedException, DeploymentException,
           ManagementException;
Warning The SIS retrieves the macro XML file using the specified URL — which must be resolvable from the Rhino node.

install

Operation

To install a macro from a byte array:

public MacroID install(byte[] content)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;
Note The SIS reads the macro XML data from the specified byte array.

Replacing Existing Macros

To replace an existing macro with a new macro, use the following sis-console command, Ant task, or related MBean operations.

Console command

replacemacro

Command

 
replacemacro <ra-entity> <file>
    Replace a previously installed macro component with new content from a file
Warning This command installs in the SIS the macro XML file — which must be on the local filesystem of the management client.
Note If a macro with same identity as that denoted in the file does not exist, this command behaves the same as installmacro.

Example

To replace an existing macro with macro example-macro.xml from the local filesystem of the management client, into the SIS instance named sis:

$ ./sis-console replacemacro sis example-macro.xml
Replaced macro MacroID[name=Example,vendor=ABC,version=1.0] from file example-macro.xml

Ant task

replacemacro

Task

 
<replacemacro file="..."/>

Example

To replace an existing macro with macro example-macro.xml from the local filesystem of the management client:

<sis-in-management>
    <replacemacro file="example-macro.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <replacemacro file="example-macro.xml"/>
</sis-sip-management>

MBean operations

MBean

Macro Management

replace

Operation

To replace a macro from a URL:

public MacroID replace(String url)
    throws NullPointerException, MalformedURLException,
           DeploymentException, ManagementException;
Warning The SIS retrieves the macro XML file using the specified URL — which must be resolvable from the Rhino node.

replace

Operation

To replace a macro from a byte array:

public MacroID replace(byte[] content)
    throws NullPointerException, DeploymentException, ManagementException;
Note The SIS reads the macro XML data from the specified byte array.

Uninstalling Macros

To uninstall a macro, use the following sis-console command, Ant task, or related MBean operation.

Console command

uninstallmacro

Command

 
uninstallmacro <ra-entity> <macro-id>
    Uninstall a macro component.

Example

To uninstall the macro component with identifier MacroID[name=Example,vendor=ABC,version=1.0] from the SIS instance named sis:

$ ./sis-console uninstallmacro sis name=Example,vendor=ABC,version=1.0
Uninstalled macro MacroID[name=Example,vendor=ABC,version=1.0]

Ant task

uninstallmacro

Task

 
<uninstallmacro>
    <macro name="..." vendor="..." version="..."/>
</uninstallmacro>

Example

 
<sis-in-management>
    <uninstallmacro>
        <macro name="Example" vendor="ABC" version="1.0"/>
    </uninstallmacro>
</sis-in-management>

or

<sis-sip-management>
    <uninstallmacro>
        <macro name="Example" vendor="ABC" version="1.0"/>
    </uninstallmacro>
</sis-sip-management>

MBean operation

MBean

Macro Management

uninstall

Operation

 
public void uninstall(MacroID id)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Viewing Macros

To list or display macros, use the following sis-console commands or related MBean operations:

Console commands

listmacros

Command

 
listmacros <ra-entity>
    List installed macros.
Note This command lists the IDs of all macros installed in the SIS.

Example

To list macros installed in the SIS instance named sis:

$ ./sis-console listmacros sis
MacroID[name=Example,vendor=ABC,version=1.0]
MacroID[name=IsOriginating,vendor=ABC,version=1.0]
MacroID[name=IsTerminating,vendor=ABC,version=1.0]

dumpmacro

Command

 
dumpmacro <ra-entity> <composition-id> [file]
    Dumps a macro to screen [or file].
Note This command displays the XML source of a macro, and if given a filename writes the XML to that file.

Example

To dump the macro component with identifier MacroID[name=Example,vendor=ABC,version=1.0] installed in the SIS instance named sis to the file foo.xml:

$ ./sis-console dumpmacro sis name=Example,vendor=ABC,version=1.0 foo.xml
Wrote macro MacroID[name=Example,vendor=ABC,version=1.0] to file foo.xml

MBean operations

MBean

Macro Management

getMacros

Operation

 
public MacroID[] getMacros()
    throws ManagementException;
Note This operation returns the identifiers of all macros installed in the SIS.

getMacro

Operation

 
public String getMacro(MacroID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note This operation returns the specified macro, in the form of an XML string.

Managing Triggers

The Trigger Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Selecting compositions

A trigger is used to select a composition for execution for each call received by the SIS.
sis-console command(s) MBean(s) → Operation

Procedure: Install a trigger

 
 installtrigger
 
 Trigger Management &rarr; install

Procedure: Replace an existing trigger

 
 replacetrigger
 
 Trigger Management &rarr; replace

Procedure: Uninstall a trigger

 
 uninstalltrigger
 
 Trigger Management &rarr; uninstall

Procedure: Activate or deactivate a trigger

 
 activatetrigger
deactivatetrigger
 
 Trigger Management &rarr; activatetrigger
Trigger Management &rarr; deactivatetrigger

Procedure: View a trigger

 
 listtriggers
listactivetriggers
gettriggerstate
dumptrigger
 
 Trigger Management &rarr; getTriggers
Trigger Management &rarr; getActiveTriggers
Trigger Management &rarr; isActivated
Trigger Management &rarr; getTrigger

Installing Triggers

To install a trigger component from a local file, use the following sis-console command, Ant task, or related MBean operations.

Console command

installtrigger

Command

 
installtrigger <ra-entity> <file>
    Installs a trigger component from a file.
Warning This command installs in the SIS a trigger XML file — which must be on the local filesystem of the management client.

Example

To install trigger example-trigger.xml from the local filesystem of the management client into the SIS instance named sis:

$ ./sis-console installtrigger sis example-trigger.xml
Installed trigger TriggerID[name=Example,vendor=ABC,version=1.0] from file example-trigger.xml

Ant task

installtrigger

Task

 
<installtrigger file="..."/>

Example

 
<sis-in-management>
    <installtrigger file="example-trigger.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <installtrigger file="example-trigger.xml"/>
</sis-sip-management>

MBean operations

MBean

Trigger Management

install

Operation

To install a trigger from a URL:

public TriggerID install(String url)
    throws NullPointerException, MalformedURLException,
           AlreadyDeployedException, DeploymentException,
           ManagementException;
Warning The SIS retrieves the trigger XML file by using the specified URL — which must be resolvable from the Rhino node.

install

Operation

To install a trigger from a byte array:

public TriggerID install(byte[] content)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;
Note The SIS reads the trigger XML data from the specified byte array.

Replacing Existing Triggers

To replace an existing trigger with a new trigger, use the following sis-console command, Ant task, or related MBean operations.

Console command

replacetrigger

Command

 
replacetrigger <ra-entity> <file>
    Replace a previously installed trigger component with new content from a file
Warning This command installs in the SIS the trigger XML file — which must be on the local filesystem of the management client.
Note If a trigger with same identity as that denoted in the file does not exist, this command behaves the same as installtrigger.

Example

To replace an existing trigger with trigger example-trigger.xml from the local filesystem of the management client, into the SIS instance named sis:

$ ./sis-console replacetrigger sis example-trigger.xml
Replaced trigger TriggerID[name=Example,vendor=ABC,version=1.0] from file example-trigger.xml

Ant task

replacetrigger

Task

 
<replacetrigger file="..."/>

Example

To replace an existing trigger with trigger example-trigger.xml from the local filesystem of the management client:

<sis-in-management>
    <replacetrigger file="example-trigger.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <replacetrigger file="example-trigger.xml"/>
</sis-sip-management>

MBean operations

MBean

Trigger Management

replace

Operation

To replace a trigger from a URL:

public TriggerID replace(String url)
    throws NullPointerException, MalformedURLException,
           DeploymentException, ManagementException;
Warning The SIS retrieves the trigger XML file using the specified URL — which must be resolvable from the Rhino node.

replace

Operation

To replace a trigger from a byte array:

public TriggerID replace(byte[] content)
    throws NullPointerException, DeploymentException, ManagementException;
Note The SIS reads the trigger XML data from the specified byte array.

Uninstalling Triggers

To uninstall a trigger component from the SIS, use the following sis-console command, Ant task, or related MBean operation:

Console command

uninstalltrigger

Command

 
uninstalltrigger <ra-entity> <trigger-id>
    Uninstall a trigger component.

Example

 
$ ./sis-console uninstalltrigger sis name=Example,vendor=ABC,version=1.0
Uninstalled trigger TriggerID[name=Example,vendor=ABC,version=1.0]

Ant task

uninstalltrigger

Task

 
<uninstalltrigger>
    <trigger name="..." vendor="..." version="..."/>
</uninstalltrigger>

Example

 
<sis-in-management>
    <uninstalltrigger>
        <trigger name="Example" vendor="ABC" version="1.0"/>
    </uninstalltrigger>
</sis-in-management>

or

<sis-sip-management>
    <uninstalltrigger>
          <trigger name="Example" vendor="ABC" version="1.0"/>
    </uninstalltrigger>
</sis-sip-management>

MBean operation

MBean

Trigger Management

uninstall

Operation

 
public void uninstall(TriggerID id)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, DependencyException,
           ManagementException;

Activating and Deactivating Triggers

To activate and deactivate triggers, use the following sis-console commands, Ant tasks, or related MBean operations.

Warning When processing an initial request, the SIS evaluates only activated triggers.

Console commands

activatetrigger

Command

 
activatetrigger <ra-entity> <trigger-id>
    Activates the specified trigger.

Example

 
$ ./sis-console activatetrigger sis name=Example,vendor=ABC,version=1.0
Activated trigger TriggerID[name=Example,vendor=ABC,version=1.0]

deactivatetrigger

Command

 
deactivatetrigger <ra-entity> <trigger-id>
    Deactivates the specified trigger.

Example

 
$ ./sis-console deactivatetrigger sis name=Example,vendor=ABC,version=1.0
Deactivated trigger TriggerID[name=Example,vendor=ABC,version=1.0]

Ant tasks

activatetrigger

Task

 
<activatetrigger>
    <trigger name="..." vendor="..." version="..."/>
</activatetrigger>

Example

 
<sis-in-management>
    <activatetrigger>
        <trigger name="Example" vendor="ABC" version="1.0"/>
    </activatetrigger>
</sis-in-management>

or

<sis-sip-management>
    <activatetrigger>
          <trigger name="Example" vendor="ABC" version="1.0"/>
    </activatetrigger>
</sis-sip-management>

deactivatetrigger

Task

 
<deactivatetrigger>
    <trigger name="..." vendor="..." version="..."/>
</deactivatetrigger>

Example

 
<sis-in-management>
    <deactivatetrigger>
          <trigger name="Example" vendor="ABC" version="1.0"/>
    </deactivatetrigger>
</sis-in-management>

or

<sis-sip-management>
    <deactivatetrigger>
        <trigger name="Example" vendor="ABC" version="1.0"/>
    </deactivatetrigger>
</sis-sip-management>

MBean operations

MBean

Trigger Management

activate

Operation

 
public void activate(TriggerID id)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, ManagementException;

deactivate

Operation

 
public void deactivate(TriggerID id)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, ManagementException;

Viewing Triggers

To list installed triggers, list active triggers, get trigger state, or display a trigger, use the following sis-console commands or related MBean operations.

Console commands

listtriggers

Command

 
listtriggers <ra-entity>
    List installed triggers.
Note This command lists the IDs of all triggers installed in the SIS.

Example

To list installed triggers:

$ ./sis-console listtriggers sis
TriggerID[name=Example,vendor=ABC,version=1.0]
TriggerID[name=Originating,vendor=ABC,version=1.0]
TriggerID[name=Terminating,vendor=ABC,version=1.0]

listactivetriggers

Command

 
listactivetriggers <ra-entity>
    Lists active triggers in order of priority.
Note This command lists the IDs of all active triggers, in order of their priority (highest to lowest).

Example

To list active triggers:

$ ./sis-console listactivetriggers sis
TriggerID[name=Originating,vendor=ABC,version=1.0]
TriggerID[name=Terminating,vendor=ABC,version=1.0]

gettriggerstate

Command

 
gettriggerstate <ra-entity> <trigger-id>
    Get the state of a trigger.
Note Displays the trigger state, either ACTIVE or INACTIVE.

Example

To get trigger state:

$ ./sis-console gettriggerstate sis name=Originating,vendor=ABC,version=1.0
ACTIVE

dumptrigger

Command

 
dumptrigger <ra-entity> <trigger-id> [file]
    Dumps a trigger to screen [or file].
Note This command displays the XML source of a trigger, and if given a filename writes the XML to that file.

Example

To dump a trigger to a file:

$ ./sis-console dumptrigger sis name=Example,vendor=ABC,version=1.0 foo.xml
Wrote trigger TriggerID[name=Example,vendor=ABC,version=1.0] to file foo.xml

MBean operations

MBean

Trigger Management

getTriggers

Operation

 
public TriggerID[] getTriggers()
    throws ManagementException;
Note Returns the identifiers of all triggers installed in the SIS.

getActiveTriggers

Operation

 
public TriggerID[] getActiveTriggers()
    throws ManagementException;
Note Returns the identifiers of all activated trigger components in the SIS, in order of priority (highest to lowest).

isActivated

Operation

 
public boolean isActivated(TriggerID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns true if the specified trigger is active, otherwise false.

getTrigger

Operation

 
public String getTrigger(TriggerID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the trigger, in the form of an XML string.

Managing Compositions

The Composition Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Executing services

A composition describes the services to be invoked for a particular call and the order the services should be invoked.
sis-console command(s) MBean(s) → Operation

Procedure: Install a composition

 
 installcomposition
 
 Composition Management &rarr; install

Procedure: Replace an existing composition

 
 replacecomposition
 
 Composition Management &rarr; replace

Procedure: Uninstall a composition

 
 uninstallcomposition
 
 Composition Management &rarr; uninstall

Procedure: Viewing a composition

 
 listcompositions
dumpcomposition
 
 Composition Management &rarr; getCompositions
Composition Management &rarr; getComposition

Procedure: Get and set the optimisations enabling flag

 
 isoptimsationsenabled
setoptimsationsenabled
 
 Composition Management &rarr; getOptimisationsEnabled
Composition Management &rarr; setOptimisationsEnabled

Procedure: Get and set the FCI interaction mode

 
 getfciinteraction
setfciinteraction
 
 Composition Management &rarr; getFCIInteraction
Composition Management &rarr; setFCIInteraction

Procedure: Get and set the Online Charging interaction mode

 
 getonlinecharginginteraction
setonlinecharginginteraction
 
 Composition Management &rarr; getOnlineChargingInteraction
Composition Management &rarr; setOnlineChargingInteraction

Procedure: Get and set a composition’s debug level

 
 getdebuglevel
setdebuglevel
 
 Composition Management &rarr; getDebugLevel
Composition Management &rarr; setDebugLevel

Procedure: Get and set a composition’s audit logging

 
 getcompositionauditlogging
setcompositionauditlogging
 
 Composition Management &rarr; isAuditLoggingEnabled
Composition Management &rarr; setAuditLoggingEnabled

Installing Compositions

To install a composition from a local file, use the following sis-console command, Ant task, or related MBean operations.

Console command

installcomposition

Command

 
installcomposition <ra-entity> <file>
    Install a composition component from a file.
Warning This command installs in the SIS the composition XML file — which must be on the local filesystem of the management client.

Example

To install composition example-composition.xml from the local filesystem of the management client into the SIS instance named sis:

$ ./sis-console installcomposition sis example-composition.xml
Installed composition CompositionID[name=Example,vendor=ABC,version=1.0] from file example-composition.xml

Ant task

installcomposition

Task

 
<installcomposition file="..."/>

Example

To install composition example-composition.xml from the local filesystem of the management client:

<sis-in-management>
    <installcomposition file="example-composition.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <installcomposition file="example-composition.xml"/>
</sis-sip-management>

MBean operations

MBean

Composition Management

install

Operation

To install a composition from a URL:

public CompositionID install(String url)
    throws NullPointerException, MalformedURLException,
           AlreadyDeployedException, DeploymentException,
           ManagementException;
Warning The SIS retrieves the composition XML file using the specified URL — which must be resolvable from the Rhino node.

install

Operation

To install a composition from a byte array:

public CompositionID install(byte[] content)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;
Note The SIS reads the composition XML data from the specified byte array.

Replacing Existing Compositions

To replace an existing composition with a new composition, use the following sis-console command, Ant task, or related MBean operation.

Console command

replacecomposition

Command

 
replacecomposition <ra-entity> <file>
    Replace a previously installed composition component with new content from a
    file
Warning This command installs in the SIS the composition XML file — which must be on the local filesystem of the management client.
Note If a composition with same identity as that denoted in the file does not exist, this command behaves the same as installcomposition.

Example

To replace an existing composition with composition example-composition.xml from the local filesystem of the management client, into the SIS instance named sis:

$ ./sis-console replacecomposition sis example-composition.xml
Replaced composition CompositionID[name=Example,vendor=ABC,version=1.0] from file example-composition.xml

Ant task

replacecomposition

Task

 
<replacecomposition file="..."/>

Example

To replace an existing composition with composition example-composition.xml from the local filesystem of the management client:

<sis-in-management>
    <replacecomposition file="example-composition.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <replacecomposition file="example-composition.xml"/>
</sis-sip-management>

MBean operation

MBean

Composition Management

replace

Operation

To replace a composition from a URL:

public CompositionID replace(String url)
    throws NullPointerException, MalformedURLException,
           DeploymentException, ManagementException;
Warning The SIS retrieves the composition XML file using the specified URL — which must be resolvable from the Rhino node.

replace

Operation

To replace a composition from a byte array:

public CompositionID replace(byte[] content)
    throws NullPointerException, DeploymentException, ManagementException;
Note The SIS reads the composition XML data from the specified byte array.

Uninstalling Compositions

To uninstall a composition component from the SIS, use the following sis-console command, Ant task, or related MBean operation.

Console command

uninstallcomposition

Command

 
uninstallcomposition <ra-entity> <composition-id>
    Uninstall a composition component.

Example

To uninstall the composition component with identifier CompositionID[name=Example,vendor=ABC,version=1.0] from the SIS instance named sis:

$ ./sis-console uninstallcomposition sis name=Example,vendor=ABC,version=1.0
Uninstalled composition CompositionID[name=Example,vendor=ABC,version=1.0]

Ant task

uninstallcomposition

Task

 
<uninstallcomposition>
    <composition name="..." vendor="..." version="..."/>
</uninstallcomposition>

Example

 
<sis-in-management>
    <uninstallcomposition>
        <composition name="Example" vendor="ABC" version="1.0"/>
    </uninstallcomposition>
</sis-in-management>

or

<sis-sip-management>
    <uninstallcomposition>
        <composition name="Example" vendor="ABC" version="1.0"/>
    </uninstallcomposition>
</sis-sip-management>

MBean operation

MBean

Composition Management

uninstall

Operation

 
public void uninstall(CompositionID id)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Viewing Compositions

To list or display installed compositions, use the following sis-console commands or related MBean operations.

Console commands

listcompositions

Command

 
listcompositions <ra-entity>
    List installed compositions.
Note This command lists the component identifiers of all compositions installed in the SIS.

Example

 
$ ./sis-console listcompositions sis
CompositionID[name=Example,vendor=ABC,version=1.0]
CompositionID[name=OriginatingServices,vendor=ABC,version=1.0]
CompositionID[name=TerminatingServices,vendor=ABC,version=1.0]

dumpcomposition

Command

 
dumpcomposition <ra-entity> <composition-id> [file]
    Dumps a composition to screen [or file].
Note This command displays the XML source of a composition, and if given a filename writes the XML to that file.

Example

 
$ ./sis-console dumpcomposition sis name=Example,vendor=ABC,version=1.0 foo.xml
Wrote composition CompositionID[name=Example,vendor=ABC,version=1.0] to file foo.xml

MBean operations

MBean

Composition Management

getCompositions

Operation

 
public CompositionID[] getCompositions()
    throws ManagementException;
Note Returns the identifiers of all compositions installed in the SIS.

getComposition

Operation

 
public String getComposition(CompositionID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the composition, in the form of an XML string.

Getting and Setting Composition Optimisations

To get or set the optimisations enabled flag for a composition, use the following sis-console commands, Ant task, or related MBean operations.

Tip This is a SIS feature for IN.

Console commands

isOptimisationsEnabled

Command

 
isoptimisationsenabled <ra-entity> <composition-id>
    Determine if processing optimisations are enabled for a composition

Example

To determine if optimisations are enabled for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console isoptimisationsenabled sis name=4000,vendor=OpenCloud,version=1.0
Optimisations for CompositionID[name=4000,vendor=OpenCloud,version=1.0] are disabled

setOptimisationsEnabled

Command

 
setoptimisationsenabled <ra-entity> <composition-id> <boolean>
    Enable/disable processing optimisations for a composition

Example

To enable optimisations for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console setoptimsationsenabled sis name=4000,vendor=OpenCloud,version=1.0 true
Optimisations for CompositionID[name=4000,vendor=OpenCloud,version=1.0] enabled

Ant task

updateincomposition

Task

 
<updateincomposition optimisationsEnabled="...">
    <composition name="..." vendor="..." version="..."/>
</updateincomposition>

Example

To enable optimisations for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0]:

<sis-in-management>
    <updateincomposition optimisationsEnabled="true">
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
    </updateincomposition>
</sis-in-management>

MBean operations

MBean

IN Composition Management

getOptimisationsEnabled

Operation

 
public boolean getOptimisationsEnabled(CompositionID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setOptimisationsEnabled

Operation

 
public void setOptimisationsEnabled(CompositionID id, boolean enabled)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Getting and Setting Composition FCI Interaction Mode

To get or set the FCI Interaction mode for a composition, use the following sis-console commands, Ant task, or related MBean operations.

Tip This is a SIS feature for IN.

Console commands

getFCIInteraction

Command

 
getfciinteraction <ra-entity> <composition-id>
    Get the FCI interaction mode for a composition

Example

To determine the current FCI interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console getfciinteraction sis name=4000,vendor=OpenCloud,version=1.0
FCI interaction mode for CompositionID[name=4000,vendor=OpenCloud,version=1.0] is
FCIInteraction[mode=static-service-priorities]

setFCIInteraction

Command

 
setfciinteraction <ra-entity> <composition-id> <mode> [<service-alias>]
    Set the FCI interaction mode for a composition. Mode must be
    'static-service-priorities', 'nominated-service', 'concatenation', or
    'pass-through'. The service-alias argument is required if the
    'nominated-service' mode is selected.

Example

To set the FCI interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis to nominated-service, nominating the service with alias SERVICE1:

$ ./sis-console setfciinteraction sis name=4000,vendor=OpenCloud,version=1.0 nominated-service SERVICE1
FCI interaction mode for CompositionID[name=4000,vendor=OpenCloud,version=1.0] set to
FCIInteraction[mode=nominated-service,nominated-service-alias=SERVICE1]
Tip To display the service aliases used in a composition, and what service each alias maps to, use the dumpComposition command.

Ant task

updateincomposition

Task

 
<updateincomposition>
    <composition name="..." vendor="..." version="..."/>
    <fciInteraction mode="..." serviceref="..."/>
</updateincomposition>

Example

To set the FCI interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] to nominated-service, nominating the service with alias SERVICE1:

<sis-in-management>
    <updateincomposition>
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
        <fciInteraction mode="nominated-service" serviceref="SERVICE1"/>
    </updateincomposition>
</sis-in-management>

MBean operations

MBean

IN Composition Management

getFCIInteraction

Operation

 
public FCIInteraction getFCIInteraction(CompositionID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setFCIInteraction

Operation

 
public void setFCIInteraction(CompositionID id, FCIInteraction fciInteraction)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidArgumentException, ManagementException;

Getting and Setting Composition Online Charging Interaction Mode

To get or set the Online Charging Interaction mode for a composition, use the following sis-console commands, Ant task, or related MBean operations.

Tip This is a SIS feature for IN.

Console commands

getOnlineChargingInteraction

Command

 
getonlinecharginginteraction <ra-entity> <composition-id>
   Get the online charging interaction mode for a composition

Example

To determine the current online charging interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console getonlinecharginginteraction sis name=4000,vendor=OpenCloud,version=1.0
Online charging interaction mode for CompositionID[name=4000,vendor=OpenCloud,version=1.0] is
OnlineChargingInteraction[mode=static-service-priorities]

setOnlineChargingInteraction

Command

 
setonlinecharginginteraction <ra-entity> <composition-id> <mode> [<service-alias>]
   Set the online charging interaction mode for a composition. Mode must be
   'static-service-priorities' or 'nominated-service'. The service-alias argument
   is required if the 'nominated-service' mode is selected.

Example

To set the online charging interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis to nominated-service, nominating the service with alias SERVICE1:

$ ./sis-console setonlinecharginginteraction sis name=4000,vendor=OpenCloud,version=1.0 nominated-service SERVICE1
Online charging interaction mode for CompositionID[name=4000,vendor=OpenCloud,version=1.0] set to
OnlineChargingInteraction[mode=nominated-service,nominated-service-alias=SERVICE1]
Tip To display the service aliases used in a composition, and what service each alias maps to, use the dumpComposition command.

Ant task

updateincomposition

Task

 
<updateincomposition>
    <composition name="..." vendor="..." version="..."/>
    <onlineChargingInteraction mode="..." serviceref="..."/>
</updateincomposition>

Example

To set the online charging interaction mode for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] to nominated-service, nominating the service with alias SERVICE1:

<sis-in-management>
    <updateincomposition>
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
        <onlineChargingInteraction mode="nominated-service" serviceref="SERVICE1"/>
    </updateincomposition>
</sis-in-management>

MBean operations

MBean

IN Composition Management

getOnlineChargingInteraction

Operation

 
public OnlineChargingInteraction getOnlineChargingInteraction(CompositionID id)
        throws NullPointerException, UnrecognizedComponentException,
               ManagementException;

setOnlineChargingInteraction

Operation

 
public void setOnlineChargingInteraction(CompositionID id, OnlineChargingInteraction interaction)
        throws NullPointerException, UnrecognizedComponentException,
               InvalidArgumentException, ManagementException;

Getting and Setting Composition Debug Level

To get or set the fine-grained tracing debug level for a composition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getDebugLevel

Command

 
getdebuglevel <ra-entity> <CompositionID>
    Get current fine-grained tracing debug level for a composition

Example

To get the debug level for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console getdebuglevel sis name=4000,vendor=OpenCloud,version=1.0
Debug level for CompositionID[name=4000,vendor=OpenCloud,version=1.0]=0

setDebugLevel

Command

 
setdebuglevel <ra-entity> <CompositionID> <debugLevel>
    Set fine-grained tracing debug level for a composition

Example

To set the debug level for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis to 2:

$ ./sis-console setdebuglevel sis name=4000,vendor=OpenCloud,version=1.0 2
Debug level for CompositionID[name=4000,vendor=OpenCloud,version=1.0] set to 2

Ant task

updatecomposition

Task

 
<updatecomposition audit="..." debuglevel="..." >
    <composition name="..." vendor="..." version="..."/>
</updatecomposition>

Example

To set the debug level for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] to 2:

<sis-in-management>
    <updatecomposition debuglevel="2">
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
    </updatecomposition>
</sis-in-management>

or

<sis-sip-management>
    <updatecomposition debuglevel="2">
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
    </updatecomposition>
</sis-sip-management>

MBean operations

MBean

Composition Management

getDebugLevel

Operation

 
public int getDebugLevel(CompositionID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setDebugLevel

Operation

 
public void setDebugLevel(CompositionID id, int debugLevel)
    throws NullPointerException, UnrecognizedComponentException,
           IllegalArgumentException, ManagementException;

Getting and Setting Composition Audit Logging

To get or set audit logging for a composition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getCompositionAuditLogging

Command

 
getcompositionauditlogging <ra-entity> <CompositionID>
    Determine if audit logging is enabled for a composition

Example

To determine if audit logging is enabled for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console getcompositionauditlogging sis name=4000,vendor=OpenCloud,version=1.0
Audit logging for CompositionID[name=4000,vendor=OpenCloud,version=1.0] is disabled

setCompositionAuditLogging

Command

 
setcompositionauditlogging <ra-entity> <CompositionID> <boolean>
    Enable/disable audit logging for a composition

Example

To enable audit logging for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0] in the SIS instance named sis:

$ ./sis-console setcompositionauditlogging sis name=4000,vendor=OpenCloud,version=1.0 true
Audit logging for CompositionID[name=4000,vendor=OpenCloud,version=1.0] enabled

Ant task

updatecomposition

Task

 
<updatecomposition audit="..." debuglevel="..." >
    <composition name="..." vendor="..." version="..."/>
</updatecomposition>

Example

To enable audit logging for the composition with identifier CompositionID[name=4000,vendor=OpenCloud,version=1.0]:

<sis-in-management>
    <updatecomposition audit="true">
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
    </updatecomposition>
</sis-in-management>

or

<sis-sip-management>
    <updatecomposition audit="true">
        <composition name="4000" vendor="OpenCloud" version="1.0"/>
    </updatecomposition>
</sis-sip-management>

MBean operations

MBean

Composition Management

isAuditLoggingEnabled

Operation

 
public boolean isAuditLoggingEnabled(CompositionID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setAuditLoggingEnabled

Operation

 
public void setAuditLoggingEnabled(CompositionID id, boolean enabled)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Managing Interceptors

The Interceptor Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Signaling interceptors

An interceptor can be used to inspect and manipulate the signaling between a service and the SIS, or between the SIS and the network.

An interceptor reference identifies an interceptor component to SIS compositions or other interceptors.
sis-console command(s) MBean(s) → Operation

Procedure: Install an interceptor

 
 installinterceptor
 
 Interceptor Management &rarr; install

Procedure: Replace an existing interceptor

 
 replaceinterceptor
 
 Interceptor Management &rarr; replace

Procedure: Uninstall a interceptor

 
 uninstallinterceptor
 
 Interceptor Management &rarr; uninstall

Procedure: View a interceptor

 
 listinterceptors
dumpinterceptor
 
 Interceptor Management &rarr; getInterceptors
Interceptor Management &rarr; getInterceptor

Procedure: Create an interceptor reference

 
 createinterceptorref
 
  Interceptor Management &rarr; createServiceInterceptorRef

Procedure: Replace an existing interceptor reference

 
 replaceinterceptorref
 
  Interceptor Management &rarr; replaceInterceptorRef

Procedure: Remove an interceptor reference

 
 removeinterceptorref
 
  Interceptor Management &rarr; removeInterceptorRef

Procedure: View an interceptor reference

 
 listinterceptorrefs
dumpinterceptorref
 
  Interceptor Management &rarr; getInterceptorRefs
Interceptor Management &rarr; getDescriptor

Installing Interceptors

To install an interceptor from a local file, use the following sis-console command, Ant task, or related MBean operations.

Console command

installinterceptor

Command

 
installinterceptor <ra-entity> <file>
    Install an interceptor component from a file.
Warning This command installs in the SIS the interceptor XML file — which must be on the local filesystem of the management client.

Example

To install interceptor example-interceptor.xml from the local filesystem of the management client into the SIS instance named sis:

$ ./sis-console installinterceptor sis example-interceptor.xml
Installed interceptor InterceptorID[name=Example,vendor=ABC,version=1.0] from file example-interceptor.xml

Ant task

installinterceptor

Task

 
<installinterceptor file="..."/>

Example

To install interceptor example-interceptor.xml from the local filesystem of the management client:

<sis-in-management>
    <installinterceptor file="example-interceptor.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <installinterceptor file="example-interceptor.xml"/>
</sis-sip-management>

MBean operations

MBean

Interceptor Management

install

Operation

To install a interceptor from a URL:

public InterceptorID install(String url)
    throws NullPointerException, MalformedURLException,
           AlreadyDeployedException, DeploymentException,
           ManagementException;
Warning The SIS retrieves the interceptor XML file using the specified URL — which must be resolvable from the Rhino node.

install

Operation

To install a interceptor from a byte array:

public InterceptorID install(byte[] content)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;
Note The SIS reads the interceptor XML data from the specified byte array.

Replacing Existing Interceptors

To replace an existing interceptor with a new interceptor, use the following sis-console command, Ant task, or related MBean operations.

Console command

replaceinterceptors

Command

 
replaceinterceptor <ra-entity> <file>
    Replace a previously installed interceptor component with new content from a
    file
Warning This command installs in the SIS the interceptor XML file — which must be on the local filesystem of the management client.
Note If an interceptor with same identity as that denoted in the file does not exist, this command behaves the same as installinterceptor.

Example

To replace an existing interceptor with interceptor example-interceptor.xml from the local filesystem of the management client, into the SIS instance named sis:

$ ./sis-console replaceinterceptor sis example-interceptor.xml
Replaced interceptor InterceptorID[name=Example,vendor=ABC,version=1.0] from file example-interceptor.xml

Ant task

replaceinterceptor

Task

 
<replaceinterceptor file="..."/>

Example

To replace an existing interceptor with interceptor example-interceptor.xml from the local filesystem of the management client:

<sis-in-management>
    <replaceinterceptor file="example-interceptor.xml"/>
</sis-in-management>

or

<sis-sip-management>
    <replaceinterceptor file="example-interceptor.xml"/>
</sis-sip-management>

MBean operations

MBean

Interceptor Management

replace

Operation

To replace an interceptor from a URL:

public InterceptorID replace(String url)
    throws NullPointerException, MalformedURLException,
           DeploymentException, ManagementException;
Warning The SIS retrieves the interceptor XML file using the specified URL — which must be resolvable from the Rhino node.

replace

Operation

To replace an interceptor from a byte array:

public InterceptorID replace(byte[] content)
    throws NullPointerException, DeploymentException, ManagementException;
Note The SIS reads the interceptor XML data from the specified byte array.

Uninstalling Interceptors

To uninstall an interceptor component from the SIS, use the following sis-console command, Ant task, or related MBean operation.

Console command

uninstallinterceptor

Command

 
uninstallinterceptor <ra-entity> <interceptor-id>
    Uninstall an interceptor component.

Example

To uninstall the interceptor component with identifier InterceptorID[name=Example,vendor=ABC,version=1.0] from the SIS instance named sis:

$ ./sis-console uninstallinterceptor sis name=Example,vendor=ABC,version=1.0
Uninstalled interceptor InterceptorID[name=Example,vendor=ABC,version=1.0]

Ant task

uninstallinterceptor

Task

 
<uninstallinterceptor>
    <interceptor name="..." vendor="..." version="..."/>
</uninstallinterceptor>

Example

 
<sis-in-management>
    <uninstallinterceptor>
        <interceptor name="Example" vendor="ABC" version="1.0"/>
    </uninstallinterceptor>
</sis-in-management>

or

<sis-sip-management>
    <uninstallinterceptor>
        <interceptor name="Example" vendor="ABC" version="1.0"/>
    </uninstallinterceptor>
</sis-sip-management>

MBean operation

MBean

Interceptor Management

uninstall

Operation

 
public void uninstall(InterceptorID id)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Viewing Interceptors

To list or display installed interceptors, use the following sis-console commands or related MBean operations.

Console commands

listinterceptors

Command

 
listinterceptors <ra-entity>
    Lists installed interceptors.
Note This command lists the component identifiers of all interceptors installed in the SIS.

Example

 
$ ./sis-console listinterceptors sis
InterceptorID[name=Example,vendor=ABC,version=1.0]

dumpinterceptor

Command

 
dumpinterceptor <ra-entity> <interceptor-id> [file]
    Dumps an interceptor to screen [or file].
Note This command displays the XML source of an interceptor, and if given a filename writes the XML to that file.

Example

 
$ ./sis-console dumpinterceptor sis name=Example,vendor=ABC,version=1.0 foo.xml
Wrote interceptor InterceptorID[name=Example,vendor=ABC,version=1.0] to file foo.xml

MBean operations

MBean

Interceptor Management

getInterceptors

Operation

 
public InterceptorID[] getInterceptors()
    throws ManagementException;
Note Returns the identifiers of all interceptors installed in the SIS.

getInterceptor

Operation

 
public String getInterceptor(InterceptorID id)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the interceptor, in the form of an XML string.

Creating Interceptor References

To create an interceptor reference to an interceptor component, use the following sis-console command, Ant task, or related MBean operation.

Console command

createinterceptorref

Command

 
createinterceptorref <ra-entity> <name> <interceptor-id>
    Create an interceptor reference

Example

To create an interceptor reference called Example in the SIS instance named sis which references the SIS interceptor with identifier InterceptorID[name=name=Example,vendor=ABC,version=1.0]:

$ ./sis-console createinterceptorref sis Example "name=Example,vendor=ABC,version=1.0"
Created interceptor reference Example for interceptor InterceptorID[name=Example,vendor=ABC,version=1.0]

Ant task

createinterceptorref

Task

 
<createinterceptorref name="...">
    <interceptor name="..." vendor="..." version="..."/>
</createinterceptorref>

Example

To create an interceptor reference called Example which references the SIS interceptor with identifier InterceptorID[name=Example,vendor=ABC,version=1.0]:

<sis-in-management>
    <createinterceptorref name="Example">
        <interceptor name="Example" vendor="ABC" version="1.0"/>
    </createinterceptorref>
</sis-in-management>

or

<sis-sip-management>
    <createinterceptorref name="Example">
        <interceptor name="Example" vendor="ABC" version="1.0"/>
    </createinterceptorref>
</sis-sip-management>

MBean operation

MBean

Interceptor Management

createInterceptorRef

Operation

To create an interceptor reference that references a SIS interceptor:

public void createInterceptorRef(String name, InterceptorID interceptorID)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Replacing Existing Interceptor References

To replace an existing interceptor reference with a reference to a new interceptor, use the following sis-console command, Ant task, or related MBean operation.

Console command

replaceinterceptorref

Command

 
replaceinterceptorref <ra-entity> <name> <interceptor-id>
    Replace an interceptor reference with a binding to a new interceptor
Warning If the named interceptor reference does not exist, this command will fail.

Example

To replace an existing interceptor reference called Example in the SIS instance named sis with a reference to the interceptor component with identifier InterceptorID[name=Example,vendor=ABC,version=2.0]:

$ ./sis-console replaceinterceptorref sis Example "name=Example,vendor=ABC,version=2.0"
Replaced interceptor reference Example with reference to interceptor InterceptorID[name=Example,vendor=ABC,version=2.0]

Ant task

replaceinterceptorref

Task

 
<replaceinterceptorref name="...">
    <interceptor name="..." vendor="..." version="..."/>
</replaceinterceptorref>

Example

To replace an interceptor reference called Example with a new reference to the interceptor with identifier InterceptorID[name=Example,vendor=ABC,version=2.0]:

<sis-in-management>
    <replaceinterceptorref name="Example">
        <interceptor name="Example" vendor="ABC" version="2.0"/>
    </replaceinterceptorref>
</sis-in-management>

or

<sis-sip-management>
    <replaceinterceptorref name="Example">
        <interceptor name="Example" vendor="ABC" version="2.0"/>
    </replaceinterceptorref>
</sis-sip-management>

MBean operation

MBean

Interceptor Management

replaceInterceptorRef

Operation

To replace an interceptor reference with a new reference to a SIS interceptor:

public void replaceInterceptorRef(InterceptorRefID interceptorRefID, InterceptorID serviceID)
    throws NullPointerException, UnrecognizedComponentException,
           DeploymentException, ManagementException;

Removing Interceptor References

To remove an interceptor reference from the SIS, use the following sis-console command, Ant task, or related MBean operation.

Console command

removeinterceptorref

Command

 
removeinterceptorref <ra-entity> <name>
    Remove an interceptor reference

Example

To remove an interceptor reference called Example in the SIS instance named sis:

$ ./sis-console removeinterceptorref sis Example
Removed interceptor reference Example

Ant task

removeinterceptorref

Task

 
<removeinterceptorref name="..."/>

Example

To remove an interceptor reference called Example:

<sis-in-management>
    <removeinterceptorref name="Example"/>
</sis-in-management>

or

<sis-sip-management>
    <removeinterceptorref name="Example"/>
</sis-sip-management>

MBean operation

MBean

Interceptor Management

removeInterceptorRef

Operation

To remove an interceptor reference:

public void removeInterceptorRef(InterceptorRefID interceptorRefID)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Viewing Interceptor References

To list or display interceptor references, use the following sis-console commands or related MBean operations.

Console commands

listinterceptorrefs

Command

 
listinterceptorrefs <ra-entity>
    List interceptor references
Note This command lists the interceptor reference identifiers of all interceptor references created in the SIS.

Example

 
$ ./sis-console listinterceptorrefs sis
InterceptorRefID[Example]

dumpinterceptorref

Command

 
dumpinterceptorref <ra-entity> <name>
    Display an interceptor reference
Note This command displays the properties of the interceptor reference.

Example

 
$ ./sis-console dumpinterceptorref sis "Example"
interceptorName    : Example
interceptorVendor  : ABC
interceptorVersion : 1.0
name               : Example

MBean operations

MBean

Interceptor Management

getInterceptorRefs

Operation

 
public InterceptorRefID[] getInterceptorRefs()
    throws ManagementException;
Note Returns the identifiers of all interceptor references in the SIS.

getDescriptor

Operation

 
public CompositeData getDescriptor(InterceptorRefID interceptorRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the interceptor reference descriptor in the form of an MBean CompositeData object.

Managing Service References

The Service Reference Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Identifying composition services

A service reference identifies a service that can be invoked from a composition. Services may be either:

  • local — JAIN SLEE services deployed in the same Rhino instance; identified to the SIS by their SLEE service-component identifiers

  • external — services running on other network nodes; represented in the SIS by an external platform definition.
sis-console command(s) MBean(s) → Operation

Procedure: Create a local service reference

 
 createlocalserviceref
 
  Service Reference Management &rarr; createLocalServiceRef

Procedure: Create an external service reference

 
 createexternalserviceref
 
  Service Reference Management &rarr; createExternalServiceRef

Procedure: View a service reference

 
 listservicerefs
dumpserviceref
 
  Service Reference Management &rarr; getServiceRefs
Service Reference Management &rarr; getDescriptor

Procedure: Replace an existing service reference with a new local service reference

 
 replacelocalserviceref
 
  Service Reference Management &rarr; replaceServiceRef

Procedure: Replace an existing service reference with a new external service reference

 
 replaceexternalserviceref
 
  Service Reference Management &rarr; replaceServiceRef

Procedure: Get and set the global default service timeout

 
 getservicetimeout
setservicetimeout
 
 Service Reference Management &rarr; getDefaultTimeout
Service Reference Management &rarr; setDefaultTimeout

Procedure: Get and set the static charging priority

 
 getstaticchargingpriority
setstaticchargingpriority
 
 Service Reference Management &rarr; getStaticChargingPriority
Service Reference Management &rarr; setStaticChargingPriority

Procedure: Get and set the service application context override

 
 getapplicationcontext
setapplicationcontext
listsupportedapplicationcontexts
 
 Service Reference Management &rarr; getApplicationContext
Service Reference Management &rarr; setApplicationContext
Service Reference Management &rarr; listSupportedApplicationContexts

Procedure: Get and set the service assisting dialog application context override

 
 getassistingdialogapplicationcontext
setassistingdialogapplicationcontext
listsupportedapplicationcontexts
 
 Service Reference Management &rarr; getAssistingDialogApplicationContext
Service Reference Management &rarr; setAssistingDialogApplicationContext
Service Reference Management &rarr; listSupportedApplicationContexts

Procedure: Remove a service reference

 
 removeserviceref
 
  Service Reference Management &rarr; removeServiceRef

Creating Local Service References

To create a service reference to a local JAIN SLEE service, use the following sis-console command, Ant task, or related MBean operation.

Console command

createlocalserviceref

Command

 
createlocalserviceref <ra-entity> <name> <service-id>
    Create a service reference bound to a local SLEE service

Example

To create a service reference called VPN in the SIS instance named sis which references a local SLEE service with identifier ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2]:

$ ./sis-console createlocalserviceref sis VPN "name=VPN Service,vendor=OpenCloud,version=0.2"
Created service reference VPN for local SLEE service ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2]

Ant task

SIP

createserviceref

Task

 
<createserviceref name="..." type="local">
    <service name="..." vendor="..." version="..."/>
</createserviceref>

Example

To create a service reference called VPN which references a local SLEE service with identifier ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2]:

<sis-sip-management>
    <createserviceref name="VPN" type="local">
        <service name="VPN Service" vendor="OpenCloud" version="0.2"/>
    </createserviceref>
</sis-sip-management>

IN

createserviceref

Task

 
<createserviceref name="..." type="local">
    <service name="..." vendor="..." version="..."/>
</createserviceref>

The IN version of this task has additional optional parameters.

Example

To create a service reference called VPN which references a local SLEE service with identifier ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2]:

<sis-in-management>
    <createserviceref name="VPN" type="local">
        <service name="VPN Service" vendor="OpenCloud" version="0.2"/>
    </createserviceref>
</sis-in-management>

MBean operation

MBean

Service Reference Management

createLocalServiceRef

Operation

To create a service reference that references a local JAIN SLEE service:

public void createLocalServiceRef(String name, ServiceID serviceID)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Creating External Service References

To create a service reference to an external platform, use the following sis-console command, Ant task, or related MBean operation.

Console command

createexternalserviceref

Command

 
createexternalserviceref <ra-entity> <name> <external-platform-name>
    Create a service reference bound to an external platform definition

Example

To create a service reference called VPN in the SIS instance named sis which references an external platform definition with the name VPN-External:

$ ./sis-console createexternalserviceref sis VPN VPN-External
Created service reference VPN for external platform VPN-External

Ant task

SIP

createserviceref

Task

 
<createserviceref name="..." type="external" extPlatformName="..."/>

Example

To create a service reference called VPN which references an external platform definition with the name VPN-External:

<sis-sip-management>
    <createserviceref name="VPN" type="external" extPlatformName="VPN-External"/>
</sis-sip-management>

IN

createserviceref

Task

 
<createserviceref name="..." type="external" extPlatformName="..."/>

The IN version of this task has additional optional parameters.

Example

To create a service reference called VPN which references an external platform definition with the name VPN-External:

<sis-in-management>
    <createserviceref name="VPN" type="external" extPlatformName="VPN-External"/>
</sis-in-management>

MBean operation

MBean

Service Reference Management

createExternalServiceRef

Operation

To create a service reference that references an external platform definition:

public void createExternalServiceRef(String name, ExternalPlatformID extPlatformID)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Viewing Service References

To list or display service references, use the following sis-console commands or related MBean operations.

Console commands

listservicerefs

Command

 
listservicerefs <ra-entity>
    List service references
Note This command lists the service reference identifiers of all service references created in the SIS.

Example

 
$ ./sis-console listservicerefs sis
ServiceRefID[Call Barring]
ServiceRefID[Call Forwarding]
ServiceRefID[VPN]

dumpserviceref

Command

 
dumpserviceref <ra-entity> <name>
    Display a service reference
Note This command displays the properties of the service reference. The output depends on whether the referenced service is local or external.

Examples

 
$ ./sis-console dumpserviceref sis VPN
chargingPriority : 0
defaultTimeout   : 1500
name             : VPN
serviceName      : VPN Service
serviceVendor    : OpenCloud
serviceVersion   : 0.2
type             : local

$ ./sis-console dumpserviceref sis "Call Barring"
chargingPriority : -20
defaultTimeout   : 0
extPlatformName  : Call Barring
name             : Call Barring
type             : external

MBean operations

MBean

Service Reference Management

getServiceRefs

Operation

 
public ServiceRefID[] getServiceRefs()
    throws ManagementException;
Note Returns the identifiers of all service references in the SIS.

getDescriptor

Operation

 
public CompositeData getDescriptor(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the service reference descriptor in the form of an MBean CompositeData object.

Replacing Existing Service References with Local Service References

To replace an existing service reference with a reference to a local JAIN SLEE service, use the following sis-console command, Ant task, or related MBean operation.

Console command

replacelocalserviceref

Command

 
replacelocalserviceref <ra-entity> <name> <service-id>
    Replace a service reference with a binding to a local SLEE service
Note If the named service reference does not exist, this command behaves the same as createlocalserviceref.

Example

To replace an existing service reference called VPN in the SIS instance named sis with a reference to a local SLEE service with identifier ServiceID[name=iVPN Service,vendor=OpenCloud,version=1.0]:

$ ./sis-console replacelocalserviceref sis VPN "name=iVPN Service,vendor=OpenCloud,version=1.0"
Replaced service reference VPN with reference to local SLEE service ServiceID[name=iVPN Service,vendor=OpenCloud,version=1.0]

Ant task

replaceserviceref

Task

 
<replaceserviceref name="..." type="local">
    <service name="..." vendor="..." version="..."/>
</replaceserviceref>

Example

To replace a service reference called VPN with a new reference to a local SLEE service with identifier ServiceID[name=iVPN Service,vendor=OpenCloud,version=1.0]:

<sis-in-management>
    <replaceserviceref name="VPN" type="local">
        <service name="iVPN Service" vendor="OpenCloud" version="1.0"/>
    </replaceserviceref>
</sis-in-management>

or

<sis-sip-management>
    <replaceserviceref name="VPN" type="local">
        <service name="iVPN Service" vendor="OpenCloud" version="1.0"/>
    </replaceserviceref>
</sis-sip-management>

MBean operation

MBean

Service Reference Management

replaceServiceRef

Operation

To replace a service reference with a new reference to a local JAIN SLEE service:

public void replaceServiceRef(String name, ServiceID serviceID)
    throws NullPointerException, DeploymentException, ManagementException;

Replacing Existing Service References with External Service References

To replace an existing service reference with a reference to an external platform, use the following sis-console command, Ant task, or related MBean operation.

Console command

replaceexternalserviceref

Command

 
replaceexternalserviceref <ra-entity> <name> <external-platform-name>
  Replace a service reference with a binding to an external platform definition
Note If the named service reference does not exist, this command behaves the same as createexternalserviceref.

Example

To replace an existing service reference called VPN in the SIS instance named sis with a reference to an external platform definition with the name iVPN-External:

$ ./sis-console replaceexternalserviceref sis VPN iVPN-External
Replaced service reference VPN with reference to external platform iVPN-External

Ant task

replaceserviceref

Task

 
<replaceserviceref name="..." type="external" extPlatformName="..."/>

Example

To replace a service reference called VPN with a new reference to an external platform definition with the name iVPN-External:

<sis-in-management>
    <replaceserviceref name="VPN" type="external" extPlatformName="iVPN-External"/>
</sis-in-management>

or

<sis-sip-management>
    <replaceserviceref name="VPN" type="external" extPlatformName="iVPN-External"/>
</sis-sip-management>

MBean operation

MBean

Service Reference Management

replaceServiceRef

Operation

To replace a service reference with a new reference to an external platform definition:

public void replaceServiceRef(String name, ExternalPlatformID extPlatformID)
    throws NullPointerException, DeploymentException,
           ManagementException;

Getting and Setting the Default Service Timeout for a Service

To get or set the default invocation timeout for a service, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getDefaultServiceTimeout

Command

 
getdefaultservicetimeout <ra-entity> <name>
    Get default timeout for a service

Example

To get the default timeout for a service with reference name VPN in the SIS instance named sis:

$ ./sis-console getdefaultservicetimeout sis VPN
Default timeout for service reference VPN is 2000ms

setDefaultServiceTimeout

Command

 
setdefaultservicetimeout <ra-entity> <name> <timeout>
    Set default timeout for a service. Timeout, measured in milliseconds, must be at least 100, or specify 0 to use the global default service timeout configured in the SIS for this service

Example

To set the default timeout for a service with reference name VPN in the SIS instance named sis to 5000ms:

$ ./sis-console setdefaultservicetimeout sis VPN 5000
Default timeout for service reference VPN set to 5000ms

Ant task

updateserviceref

Task

 
<updateserviceref name="..." defaulttimeout="..."/>

Example

 
<sis-in-management>
    <updateserviceref name="VPN" timeout="5000"/>
</sis-in-management>

or

<sis-sip-management>
    <updateserviceref name="VPN" timeout="5000"/>
</sis-sip-management>

MBean operations

MBean

Service Reference Management

getDefaultTimeout

Operation

 
public long getDefaultTimeout(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setDefaultTimeout

Operation

 
public void setDefaultTimeout(ServiceRefID serviceRefID, long timeout)
    throws NullPointerException, IllegalArgumentException,
           UnrecognizedComponentException, ManagementException;
Warning The timeout argument must be at least 100, or specify 0 to use the global default service timeout configured in the SIS for this service.

Getting and Setting the Static Charging Priority

To get or set the static charging priority for a service, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getStaticChargingPriority

Command

 
getstaticchargingpriority <ra-entity> <name>
    Get static charging priority for a service

Example

To get the static charging priority for a service with reference name VPN in the SIS instance named sis:

$ ./sis-console getstaticchargingpriority sis VPN
Static charging priority for service reference VPN is 0

setStaticChargingPriority

Command

 
setstaticchargingpriority <ra-entity> <name> <priority>
    Set static charging priority for a service. More positive number means
    higher priority

Example

To set the static charging priority for a service with reference name VPN in the SIS instance named sis to -10:

$ ./sis-console setstaticchargingpriority sis VPN -10
Set static charging priority for service reference VPN to -10

Ant task

updateserviceref

Task

 
<updateserviceref name="..." staticchargingpriority="..."/>

Example

 
<sis-in-management>
    <updateserviceref name="VPN" staticchargingpriority="-10"/>
</sis-in-management>

or

<sis-sip-management>
    <updateserviceref name="VPN" staticchargingpriority="-10"/>
</sis-sip-management>

MBean operations

MBean

Service Reference Management

getStaticChargingPriority

Operation

 
public int getStaticChargingPriority(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setStaticChargingPriority

Operation

 
public void setStaticChargingPriority(ServiceRefID serviceRefID, int priorty)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Getting and Setting the Service Application Context Override

To get or set the application context override for a service, use the following sis-console commands, Ant task, or related MBean operations:

Tip This is a SIS feature for IN.
Note The default behaviour of the SIS is to trigger composition services using a dialog of the same application context as the network dialog. The application context override option allows a service to be instead triggered with a specific application context, typically different to the expected network dialog application context. For example, the service may only support a particular protocol.
Warning This option does not provide protocol translation. If protocol translation is required between the network dialog application context and the service dialog application context, then this must be provided via SIS interceptor components.

Console commands

getApplicationContext

Command

 
getapplicationcontext <ra-entity> <name>
    Get IN application context that the service will be invoked with

Example

To get the application context override for a service with reference name VPN in the SIS instance named sis:

$ ./sis-console getapplicationcontext sis VPN
IN application context for service reference VPN is cap_v2:cap-v2-gsmSSF-to-gsmSCF-AC

setApplicationContext

Command

 
setapplicationcontext <ra-entity> <name> <app-context>
    Set IN application context that the service will be invoked with. Use - to
    clear an existing setting

The list of supported application context names that can be used by this command is obtainable using the listSupportedApplicationContexts command as shown below.

Example

To set the application context override for a service with reference name VPN in the SIS instance named sis to cap_v3:capssf-scfGenericAC:

$ ./sis-console setapplicationcontext sis VPN cap_v3:capssf-scfGenericAC
Set IN application context for service reference VPN to cap_v3:capssf-scfGenericAC

To remove an existing application context override for the same service:

$ ./sis-console setapplicationcontext sis VPN -
Cleared IN application context for service reference VPN

listSupportedApplicationContexts

Command

 
listsupportedapplicationcontexts <ra-entity>
    List the set of supported application contexts that a service can be invoked
    with

Example

To list the application contexts supported by the SIS instance named sis:

$ ./sis-console listsupportedapplicationcontexts sis
The following application contexts are supported:
cap_v1:cap-v1-gsmSSF-to-gsmSCF-AC
cap_v2:cap-v2-assist-gsmSSF-to-gsmSCF-AC
cap_v2:cap-v2-gsmSRF-to-gsmSCF-AC
cap_v2:cap-v2-gsmSSF-to-gsmSCF-AC
cap_v3:cap3-sms-AC
cap_v3:capssf-scfAssistHandoffAC
cap_v3:capssf-scfGenericAC
cap_v3:gsmSRF-gsmSCF-ac
cap_v4:cap4-sms-AC
cap_v4:capssf-scfAssistHandoffAC
cap_v4:capssf-scfGenericAC
cap_v4:gsmSRF-gsmSCF-ac
etsi_inap_cs1:core-INAP-CS1-IP-to-SCP-AC
etsi_inap_cs1:core-INAP-CS1-SCP-to-SSP-AC
etsi_inap_cs1:core-INAP-CS1-SSP-to-SCP-AC
etsi_inap_cs1:core-INAP-CS1-assist-handoff-SSP-to-SCP-AC

Ant task

updateserviceref

Task

 
<updateserviceref name="..." inServiceApplicationContext="..."/>

Example

 
<sis-in-management>
    <updateserviceref name="VPN" inServiceApplicationContext="cap_v3:capssf-scfGenericAC"/>
</sis-in-management>

MBean operations

MBean

IN Service Reference Management

getApplicationContext

Operation

 
public String getApplicationContext(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException, ManagementException;

setApplicationContext

Operation

 
public void setApplicationContext(ServiceRefID serviceRefID, String appContextName)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidArgumentException, ManagementException;

getSupportedApplicationContexts

Operation

 
public String[] getSupportedApplicationContexts()
    throws ManagementException;

Getting and Setting the Assisting Dialog Application Context Override

To get or set the assisting dialog application context override for a service, use the following sis-console commands, Ant task, or related MBean operations:

Tip This is a SIS feature for IN only.
Note This option provides the same function and capability as that described in Getting and Setting the Service Application Context Override except that it applies to assisting dialogs used for user interaction.

Console commands

getAssistingDialogApplicationContext

Command

 
getassistingdialogapplicationcontext <ra-entity> <name>
    Get IN application context that the service will be invoked with for assisting
    dialogs

Example

To get the assisting dialog application context override for a service with reference name VPN in the SIS instance named sis:

$ ./sis-console getassistingdialogapplicationcontext sis VPN
IN assisting dialog application context for service reference VPN is cap_v2:cap-v2-assist-gsmSSF-to-gsmSCF-AC

setAssistingDialogApplicationContext

Command

 
setassistingdialogapplicationcontext <ra-entity> <name> <app-context>
    Set IN application context that the service will be invoked with for assisting
    dialogs. Use - to clear an existing setting

The list of supported application context names that can be used by this command is obtainable using the listSupportedApplicationContexts command as shown below.

Example

To set the assisting dialog application context override for a service with reference name VPN in the SIS instance named sis to cap_v3:capssf-scfAssistHandoffAC:

$ ./sis-console setassistingdialogapplicationcontext sis VPN cap_v3:capssf-scfAssistHandoffAC
Set IN assisting dialog application context for service reference VPN to cap_v3:capssf-scfAssistHandoffAC

To remove an existing assisting dialog application context override for the same service:

$ ./sis-console setassistingdialogapplicationcontext sis VPN -
Cleared IN assisting dialog application context for service reference VPN

listSupportedApplicationContexts

Command

 
listsupportedapplicationcontexts <ra-entity>
    List the set of supported application contexts that a service can be invoked
    with

Example

To list the application contexts supported by the SIS instance named sis:

$ ./sis-console listsupportedapplicationcontexts sis
The following application contexts are supported:
  cap_v1:cap-v1-gsmSSF-to-gsmSCF-AC
  cap_v2:cap-v2-assist-gsmSSF-to-gsmSCF-AC
  cap_v2:cap-v2-gsmSRF-to-gsmSCF-AC
  cap_v2:cap-v2-gsmSSF-to-gsmSCF-AC
  cap_v3:cap3-sms-AC
  cap_v3:capssf-scfAssistHandoffAC
  cap_v3:capssf-scfGenericAC
  cap_v3:gsmSRF-gsmSCF-ac
  cap_v4:cap4-sms-AC
  cap_v4:capssf-scfAssistHandoffAC
  cap_v4:capssf-scfGenericAC
  cap_v4:gsmSRF-gsmSCF-ac
  etsi_inap_cs1:core-INAP-CS1-IP-to-SCP-AC
  etsi_inap_cs1:core-INAP-CS1-SCP-to-SSP-AC
  etsi_inap_cs1:core-INAP-CS1-SSP-to-SCP-AC
  etsi_inap_cs1:core-INAP-CS1-assist-handoff-SSP-to-SCP-AC

Ant task

updateserviceref

Task

 
<updateserviceref name="..." inAssistingDialogApplicationContext="..."/>

Example

 
<sis-in-management>
    <updateserviceref name="VPN" inAssistingDialogApplicationContext="cap_v3:capssf-scfGenericAC"/>
</sis-in-management>

MBean operations

MBean

IN Service Reference Management

getAssistingDialogApplicationContext

Operation

 
public String getAssistingDialogApplicationContext(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setAssistingDialogApplicationContext

Operation

 
public void setAssistingDialogApplicationContext(ServiceRefID serviceRefID, String appContextName)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidArgumentException, ManagementException;

getSupportedApplicationContexts

Operation

 
public String[] getSupportedApplicationContexts()
    throws ManagementException;

Removing Service References

To remove a service reference from the SIS, use the following sis-console command, Ant task, or related MBean operation.

Console command

removeserviceref

Command

 
removeserviceref <ra-entity> <name>
    Remove a service reference

Example

To remove a service reference called VPN in the SIS instance named sis:

$ ./sis-console removeserviceref sis VPN
Removed service reference VPN

Ant task

removeserviceref

Task

 
<removeserviceref name="..."/>

Example

To remove a service reference called VPN:

<sis-in-management>
    <removeserviceref name="VPN"/>
</sis-in-management>

or

<sis-sip-management>
    <removeserviceref name="VPN"/>
</sis-sip-management>

MBean operation

MBean

Service Reference Management

removeServiceRef

Operation

To remove a service reference:

public void removeServiceRef(ServiceRefID serviceRefID)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Managing External Platforms

An external platform definition describes the properties of an external service usable in a SIS composition.

Note
Describing external services

An external platform definition includes:

  • a name, used as a unique identifier for the external platform definition

  • zero or more IN SCCP addresses, providing the network address of IN nodes where the service can be found

  • zero or more SIP URI addresses, providing the network address of IP nodes where the service can be found

  • an address selection mode (round-robin, load-share, or active-standby), which indicates how multiple addresses should be used by the SIS.

The Service Reference Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Create an external platform definition

 
 createexternalplatform
 
 Service Reference Management &rarr; createExternalPlatform

Procedure: Remove an external platform definition

 
 removeexternalplatform
 
 Service Reference Management &rarr; removeExternalPlatform

The External Platform Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Update the configuration of an external platform definition

 
 updateexternalplatform
 
 External Platform Management &rarr; setPlatformConfig

Procedure: Add an external address to an external platform definition

 
 addexternalplatformsipaddress
addexternalplatforminaddress
 
 External Platform Management &rarr; addSIPAddress
External Platform Management &rarr; addINAddress

Procedure: Activate an address in an external platform definition

 
 activateexternalplatformsipaddress
activateexternalplatforminaddress
 
 External Platform Management &rarr; activateSIPAddress
External Platform Management &rarr; activateINAddress

Procedure: Deactivate an address in an external platform definition

 
 deactivateexternalplatformsipaddress
deactivateexternalplatforminaddress
 
 External Platform Management &rarr; deactivateSIPAddress
External Platform Management &rarr; deactivateINAddress

Procedure: Remove an address from an external platform definition

 
 removeexternalplatformsipaddress
removeexternalplatforminaddress
 
 External Platform Management &rarr; removeSIPAddress
External Platform Management &rarr; removeINAddress

Procedure: Remove an external platform definition

 
 removeexternalplatform
 
 External Platform Management &rarr; remove

Procedure: View an external platform definition

 
 listexternalplatforms
dumpexternalplatform
 
 Service Reference Management &rarr; getExternalPlatforms
External Platform Management &rarr; getDescriptor

Procedure: Repair a failed address in an external platform definition

 
 repairexternalplatformsipaddress
repairexternalplatforminaddress
 
 External Platform Management &rarr; repairSIPAddress
External Platform Management &rarr; repairINAddress

Creating External Platform Definitions

To create an external platform definition, use the following sis-console command, Ant task, or related MBean operation.

Console command

createexternalplatform

Command

 
createexternalplatform <ra-entity> <name> <address-selection-mode>
    Create an external platform definition, address selection mode is
    ACTIVE_STANDBY, LOAD_SHARE, or ROUND_ROBIN

Example

To create an external platform definition called VPN-External using the address selection mode LOAD_SHARE in the SIS instance named sis:

$ ./sis-console createexternalplatform sis VPN-External load_share
Created external platform VPN-External using address selection mode LOAD_SHARE

Ant task

createexternalplatform

Task

 
<createexternalplatform extPlatformName="..." selectionMode="..."/>

Example

To create an external platform definition called VPN-External using the address selection mode LOAD_SHARE:

<sis-in-management>
    <createexternalplatform extPlatformName="VPN-External" selectionMode="load_share"/>
</sis-in-management>

or

<sis-sip-management>
    <createexternalplatform extPlatformName="VPN-External" selectionMode="load_share"/>
</sis-sip-management>

MBean operation

MBean

Service Reference Management

createExternalPlatform

Operation

To create an external platform definition:

public ObjectName createExternalPlatform(String name, ExternalAddressSelectionMode selectionMode)
    throws NullPointerException, AlreadyDeployedException,
           ManagementException;

Updating External Platform Definitions

To update an external platform definition, use the following sis-console command, Ant task, or related MBean operation.

Note See Detecting Failed External Addresses for descriptions of the parameters.

Console command

updateexternalplatform

Command

 
updateexternalplatform <ra-entity> <name> [selectionMode <mode>] [detectInterval <ms>] [detectThreshold <p>] [retryInterval <ms>] [retryAttempts <n>]
    Update the configuration of an external platform definition

Examples

To update an external platform definition called VPN-External to use a detect interval of 10000ms and a detect threshold of 0.5:

$ ./sis-console updateexternalplatform sis VPN-External detectInterval 10000 detectThreshold 0.5
Updated external platform VPN-External

To update an external platform definition called IM-SSF to use a retry interval of 60000ms:

$ ./sis-console updateexternalplatform sis IM-SSF retryInterval 60000
Updated external platform IM-SSF

Ant task

updateexternalplatform

Task

 
<updateexternalplatform extPlatformName="..." selectionMode="..." detectInterval="..." detectThreshold="..." retryInterval="..." retryAttempts="..."/>

Examples

To update the external platform definition VPN-External to use a detect interval of 10000ms and a retry interval of 20000ms:

<sis-in-management>
    <updateexternalplatform extPlatformName="VPN-External" detectInterval="10000" retryInterval="20000"/>
</sis-in-management>

or

<sis-sip-management>
    <updateexternalplatform extPlatformName="VPN-External" detectInterval="10000" retryInterval="20000"/>
</sis-sip-management>

To update the external platform definition VPN-External to use the LOAD_SHARE address selection mode:

<sis-in-management>
    <updateexternalplatform extPlatformName="VPN-External" selectionMode="LOAD_SHARE"/>
</sis-in-management>

or

<sis-sip-management>
    <updateexternalplatform extPlatformName="VPN-External" detectInterval="10000" retryInterval="20000"/>
</sis-sip-management>

MBean operations

MBean

External Platform Management

setPlatformConfig

Operation

To update the configuration of an external platform definition:

public void setPlatformConfig(ExternalPlatformConfig config)
    throws InvalidArgumentException, ManagementException;

Adding External Addresses to External Platform Definitions

To add an external address to an external platform definition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

addexternalplatformaddress

Command

 
addexternalplatformaddress <ra-entity> <platform-name> <address> [insert-pos]

Add an address to an external platform definition, optionally inserting the address at a specified position

Note The address must be a valid SIP URI string or IN SCCP address described using the correct format.

Example

To add the external address sip:vpn2.mycompany.com:5060;transport=tcp at position 1 for the external platform definition named VPN-External in the SIS instance named sis:

$ ./sis-console addexternalplatformaddress sis VPN-External sip:vpn2.mycompany.com:5060;transport=tcp 1
Added address sip:vpn2.mycompany.com:5060;transport=tcp to external platform definition VPN-External at position 1

To add the external address type=c7,ri=pcssn,pc=7,ssn=146 to the end of the current list of IN addresses for the external platform definition named VPN-External in the SIS instance named sis:

$ ./sis-console addexternalplatformaddress sis VPN-External type=c7,ri=pcssn,pc=7,ssn=146
Added address type=c7,ri=pcssn,pc=7,ssn=146 to external platform definition VPN-External

Ant task

addexternalplatformaddress

Task

 
<addexternalplatformaddress extPlatformName="..." type="..." address="..." position="..."/>

Example

To add the external address sip:vpn2.mycompany.com:5060;transport=tcp at position 1 for the external platform definition named VPN-External:

<sis-sip-management>
    <addexternalplatformaddress
          extPlatformName="VPN-External"
          address="sip:vpn2.mycompany.com:5060;transport=tcp"
          position="1"/>
</sis-sip-management>

To add the external address type=c7,ri=pcssn,pc=7,ssn=146 to the end of the current list of IN addresses for the external platform definition named VPN-External:

<sis-in-management>
    <addexternalplatformaddress
        extPlatformName="VPN-External"
        address="type=c7,ri=pcssn,pc=7,ssn=146"/>
</sis-in-management>

Mbean operations

MBean

External Platform Management

addAddress

Operations

 
public void addAddress(String address)
    throws NullPointerException, InvalidArgumentException,
           DuplicateAddressException, ManagementException;
Note This operation adds the new address to the end of the current list of the addresses.

addAddress

Operations

 
public void addAddress(String address, int position)
    throws NullPointerException, InvalidArgumentException,
           DuplicateAddressException, ManagementException;
Note This operation adds the new address to the current list of the addresses at the specified position.

Activating External Addresses in External Platform Definitions

To activate an external address in an external platform definition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

activateexternalplatformaddress

Command

 
activateexternalplatformaddress <ra-entity> <platform-name> <position>

Activate an address at specified position in an external platform definition

Example

 
To activate the address at position `1` in the external platform definition named `VPN-External` in the SIS instance named `sis`:
$ ./sis-console activateexternalplatformaddress sis VPN-External 1
Activated address at position 1 in external platform definition VPN-External

Ant task

activateexternalplatformaddress

Task

 
<activateexternalplatformaddress extPlatformName="..." position="..."/>

Examples

To activate the SIP address at position 1 in the external platform definition named VPN-External:

<sis-sip-management>
    <activateexternalplatformaddress extPlatformName="VPN-External" position="1"/>
</sis-sip-management>

To activate the IN address at position 0 in the external platform definition named VPN-External:

<sis-in-management>
    <activateexternalplatformaddress extPlatformName="VPN-External" position="0"/>
</sis-in-management>

MBean operations

MBean

External Platform Management

activateAddress

Operations

To activate the address at the specified position in an external platform definition:

public void activateAddress(int position)
    throws InvalidArgumentException, InvalidStateException, ManagementException;

Deactivating External Addresses in External Platform Definitions

To deactivate an external address in an external platform definition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

deactivateexternalplatformaddress

Command

 
deactivateexternalplatformaddress <ra-entity> <platform-name> <position>

Deactivate an address at specified position in an external platform definition

Example

To deactivate the address at position 1 in the external platform definition named VPN-External in the SIS instance named sis:

$ ./sis-console deactivateexternalplatformaddress sis VPN-External 1
Deactivated address at position 1 in external platform definition VPN-External

Ant task

deactivateexternalplatformaddress

Task

 
<deactivateexternalplatformaddress extPlatformName="..." position="..."/>

Examples

To deactivate the SIP address at position 1 in the external platform definition named VPN-External:

<sis-sip-management>
    <deactivateexternalplatformaddress extPlatformName="VPN-External" position="1"/>
</sis-sip-management>

To deactivate the IN address at position 0 in the external platform definition named VPN-External:

<sis-in-management>
    <deactivateexternalplatformaddress extPlatformName="VPN-External" position="0"/>
</sis-in-management>

MBean operations

MBean

External Platform Management

deactivateAddress

Operations

To deactivate the address at the specified position in an external platform definition:

public void deactivateAddress(int position)
    throws InvalidArgumentException, InvalidStateException, ManagementException;

Removing External Addresses from External Platform Definitions

To remove an external address from an external platform definition, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

removeexternalplatformaddress

Command

 
removeexternalplatformaddress <ra-entity> <platform-name> <position>

Remove the address at specified position from an external platform definition

Example

To remove the address at position 1 from the external platform definition named VPN-External in the SIS instance named sis:

$ ./sis-console removeexternalplatformaddress sis VPN-External 1
Removed address at position 1 from external platform definition VPN-External

Ant task

removeexternalplatformaddress

Task

 
<removeexternalplatformaddress extPlatformName="..." position="..."/>

Examples

To remove the SIP address at position 1 from the external platform definition named VPN-External:

<sis-sip-management>
    <removeexternalplatformaddress extPlatformName="VPN-External" position="1"/>
</sis-sip-management>

To remove the IN address at position 0 from the external platform definition named VPN-External:

<sis-in-management>
    <removeexternalplatformaddress extPlatformName="VPN-External" position="0"/>
</sis-in-management>

MBean operations

MBean

External Platform Management

removeAddress

Operations

To remove the address at the specified position from an external platform definition:

public void removeAddress(int position)
    throws InvalidArgumentException, ManagementException;

Removing External Platform Definitions

To remove an external platform definition from the SIS, use the following sis-console command, Ant task, or related MBean operations.

Console command

removeexternalplatform

Command

 
removeexternalplatform <ra-entity> <name>
    Remove an external platform definition

Example

To remove an external platform definition called VPN-External in the SIS instance named sis:

$ ./sis-console removeexternalplatform sis VPN-External
Removed external platform VPN-External

Ant task

removeexternalplatform

Task

 
<removeexternalplatform extPlatformName="..."/>

Example

To remove an external platform definition called VPN-External:

<sis-in-management>
    <removeexternalplatform extPlatformName="VPN-External"/>
</sis-in-management>

or

<sis-sip-management>
    <removeexternalplatform extPlatformName="VPN-External"/>
</sis-sip-management>

MBean operations

MBean

Service Reference Management

removeExternalPlatform

Operation

To remove an external platform definition:

public void removeExternalPlatform(ExternalPlatformID extPlatformID)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

MBean

External Platform Management

remove

Operation

To remove an external platform definition:

public void remove()
      throws DependencyException, ManagementException;
Note This is an alternative method to remove an external platform definition, using the MBean for the external platform definition directly.

Viewing External Platform Definitions

To list or display external platform definitions, use the following sis-console commands or related MBean operations.

Console commands

listexternalplatforms

Command

 
listexternalplatforms <ra-entity>
    List external platform definitions
Note This command lists the identifiers of all external platform definitions created in the SIS.

Example

 
$ ./sis-console listexternalplatforms sis
ExternalPlatformID[Call Forwarding-External]
ExternalPlatformID[VPN-External]

dumpexternalplatform

Command

 
dumpexternalplatform <ra-entity> <name>
    Display an external platform definition
Note This command displays the properties of the external platform definition.

Examples

 
$ ./sis-console dumpexternalplatform sis VPN-External
detectInterval : 10000
detectThreshold : 0.5
name          : VPN-External
retryAttempts : 3
retryInterval : 30000
selectionMode : LOAD_SHARE
inAddresses   : no rows
sipAddresses  :
       > position   address                                     state
       > ---------  ------------------------------------------  ---------
       >         0   sip:vpn1.mycompany.com:5060;transport=tcp   INACTIVE
       >         1   sip:vpn2.mycompany.com:5060;transport=tcp   INACTIVE

MBean operations

MBean

Service Reference Management

getExternalPlatforms

Operation

 
public ExternalPlatformID[] getExternalPlatforms()
    throws ManagementException;
Note This operation returns the identifiers of all external platform definitions in the SIS.

MBean

External Platform Management

getDescriptor

Operation

 
public CompositeData getDescriptor()
    throws ManagementException;
Note This operation returns the external platform descriptor in the form of an MBean CompositeData object.

Detecting Failed External Addresses

The SIS can automatically detect when an external address has failed, and when it becomes available again. This page describes the possible states of an external address, how the SIS performs automatic failure detection and repair, and the configuration parameters that control this behaviour.

How the SIS views the state of external addresses

External addresses in the SIS may be in one of three states:

State Description 
 INACTIVE

The external address has been deactivated, and the SIS will not direct calls to it.

 
 ACTIVE

The external address has been activated and the SIS may direct calls to it, according to the external platform’s address selection policy.

 
 FAILED

The external address was active, but the SIS has detected a failure, and will not direct calls to the address.
Note You can view the current state of an external platform definition’s external addresses by using the dumpexternalplatform sis-console command.

How the SIS detects failed addresses

The SIS detects failed addresses by monitoring the outcome of calls to each address. When a call attempt fails (for example due to a service timeout), the SIS records that failure. If too many failures occur in a given interval, the SIS marks the address as FAILED and raises an alarm.

Several things can cause an external address failure, such as: the external server being offline; a network problem between the SIS and the external server; a SIS configuration error (for example, an incorrect address).

When the SIS detects an external address failure, it automatically:

  • raises an alarm to inform the operator

  • stops directing calls to the failed address (changes its state to FAILED)

  • monitors the address, to detect when it becomes available again.

Note Automatic failure detection can be disabled by setting the external platform’s detectInterval parameter to 0. In this case, the address will remain in the ACTIVE state indefinitely, until it is deactivated. The SIS will continue trying to use the address even if it has failed.

How the SIS detects when failed addresses are repaired

The SIS can optionally monitor failed addresses to automatically detect when they have been repaired. The SIS does this by periodically trying the failed address in an actual call, when the external platform is invoked in a service composition. The SIS records the outcome of the call, and if enough of these periodic call attempts succeed, the SIS makes the address available again.

When an external address has been repaired, the SIS automatically:

  • clears the alarm that was raised when the address failed

  • resumes directing calls to the address (changes its state to ACTIVE)

  • monitors the address to detect if it fails.

Note Automatic repair of failed addresses can be disabled by setting the external platform’s retryInterval parameter to 0. In this case, the address will remain in the FAILED state indefinitely, until an administrator manually repairs the address.

External platform definition parameters for failure detection and recovery

The parameters below are configured by updating the external platform definition. The parameters apply to all external addresses in the external platform definition.

Parameter Description Default 
 detectInterval

The interval (ms) between checking the proportion of failed calls for each of this platform’s active addresses.
Set to 0 to disable automatic failure detection.

 
 5000
 
 detectThreshold

The proportion of failed calls (between 0.0 and 1.0) occurring in a detection interval. If this threshold is exceeded in a detection interval, the SIS marks the address as failed.

 
0.5

(50%)

 
 retryInterval

The interval (ms) between attempts to retry a failed address, to see if it has recovered.
Set to 0 to disable automatic repair of failed addresses.

 
 30000
 
 retryAttempts

The number of consecutive retry attempts that must succeed before the SIS will begin using a failed address again.

 
 3

Repairing Failed External Addresses

To repair failed addresses in an external platform definition, use the following sis-console commands or related MBean operations.

Warning An external address that has failed must be repaired before the SIS can resume using it.
Note

The SIS can repair addresses automatically (see Detecting Failed External Addresses). However it may be necessary to repair addresses manually if:

  • automatic repair has been disabled in the external platform definition

  • the administrator wants to immediately resume using the address, rather than waiting for automatic repair.

Console commands

repairexternalplatformaddress

Command

 
repairexternalplatformaddress <ra-entity> <name> <position>

Repair a failed address at the specified position in an external platform definition

Note This command clears any alarms that were raised when the external address failed.

Example

To repair the failed address at position 0 in an external platform definition called Prepaid-External:

$ ./sis-console repairexternalplatformsipaddress sis Prepaid-External 0
Repaired failed address at position 0 in external platform definition Prepaid-External

MBean operations

MBean

External Platform Management

repairAddress

Operation

To repair a failed address in an external platform definition:

public void repairAddress(int position)
    throws InvalidArgumentException, InvalidStateException, ManagementException;

Managing Extension References

An extension reference identifies an extension component.

Note

There are two types of extension component supported by the SIS:

  • service composition selection extension component, used during the triggering phase

  • interceptor extension component, used in composition interceptors.

SIS extension components are implemented as JAIN SLEE services, and an extension reference identifies an extension component using its SLEE service component identifier.

The Extension Reference Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Create an extension reference

 
 createextensionref
 
 Extension Reference Management &rarr; createServiceExtensionRef

Procedure: View an extension reference

 
 listextensionrefs
dumpextensionref
 
 Extension Reference Management &rarr; getExtensionRefs
Extension Reference Management &rarr; getDescriptor

Procedure: Replace an existing extension reference

 
 replaceextensionref
 
 Extension Reference Management &rarr; replaceExtensionRef

Procedure: Get and set the default extension component timeout

 
 getextensiontimeout
setextensiontimeout
 
 Extension Reference Management &rarr; getDefaultTimeout
Extension Reference Management &rarr; setDefaultTimeout

Procedure: Remove an extension reference

 
 removeextensionref
 
 Extension Reference Management &rarr; removeExtensionRef

Creating Extension References

To create an extension reference to an extension component implemented as a JAIN SLEE service, use the following sis-console command, Ant task, or related MBean operation:

Console command

createextensionref

Command

 
createextensionref <ra-entity> <name> <extension-type> <service-id>
    Create an extension reference, extension type is SCS or INTERCEPTOR

Example

To create an extension reference called External DB Selector of extension type SCS in the SIS instance named sis which references a SLEE service with identifier ServiceID[name=External DB Selector Service,vendor=OpenCloud,version=1.0]:

$ ./sis-console createextensionref sis "External DB Selector" scs "name=External DB Selector Service,vendor=OpenCloud,version=1.0"
Created extension reference External DB Selector of type SCS for SLEE service ServiceID[name=External DB Selector Service,vendor=OpenCloud,version=1.0]

Ant task

createextensionref

Task

 
<createextensionref name="..." type="service">
    <service name="..." vendor="..." version="..."/>
</createextensionref>

Example

To create an extension reference called External DB Selector which references a SLEE service with identifier ServiceID[name=External DB Selector Service,vendor=OpenCloud,version=1.0]:

<sis-in-management>
    <createextensionref name="External DB Selector" type="service">
        <service name="External DB Selector Service" vendor="OpenCloud" version="1.0"/>
    </createextensionref>
</sis-in-management>

or

<sis-sip-management>
    <createextensionref name="External DB Selector" type="service">
        <service name="External DB Selector Service" vendor="OpenCloud" version="1.0"/>
    </createextensionref>
</sis-sip-management>

MBean operation

MBean

Extension Reference Management

createServiceExtensionRef

Operation

To create an extension reference that references a JAIN SLEE service:

public void createServiceExtensionRef(String name, ExtensionType extensionType, ServiceID serviceID)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Viewing Extension References

To list or display extension references, use the following sis-console commands or related MBean operations.

Console commands

listextensionrefs

Command

 
listextensionrefs <ra-entity>
    List extension references
Note This command lists the extension reference identifiers of all extension references created in the SIS.

Example

 
$ ./sis-console listextensionrefs sis
ExtensionRefID[External DB Selector]
ExtensionRefID[Update Service Key Interceptor]

dumpextensionref

Command

 
dumpextensionref <ra-entity>
    Display an extension reference
Note This command displays the properties of the extension reference.

Example

 
$ ./sis-console dumpextensionref sis "External DB Selector"
defaultTimeout : 0
extension-type : SCS
name           : External DB Selector
ref-type       : service
serviceName    : External DB Selector Service
serviceVendor  : OpenCloud
serviceVersion : 1.0

Mbean operations

MBean

Extension Reference Management

getExtensionRefs

Operation

 
public ExtensionRefID[] getExtensionRefs()
    throws ManagementException;
Note Returns the identifiers of all extension references in the SIS.

getDescriptor

Operation

 
public CompositeData getDescriptor(ExtensionRefID extensionRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note Returns the extension reference descriptor in the form of an MBean CompositeData object.

Replacing Existing Extension References

To replace an existing extension reference with a reference to a new JAIN SLEE service, use the following sis-console command, Ant task, or related MBean operation:

Console command

replaceextensionref

Command

 
replaceextensionref <ra-entity> <name> <service-id>
    Replace an extension reference with a binding to a SLEE service
Warning If the named extension reference does not exist, this command will fail. It is not possible to change the type of extension referenced (SCS or INTERCEPTOR) using this command.

Example

To replace an existing extension reference called External DB Selector in the SIS instance named sis with a reference to a SLEE service with identifier ServiceID[name=External DB Selector Service,vendor=OpenCloud,version=2.0]:

$ ./sis-console replaceextensionref sis "External DB Selector" "name=External DB Selector Service,vendor=OpenCloud,version=2.0"
Replaced extension reference External DB Selector with reference to SLEE service ServiceID[name=External DB Selector Service,vendor=OpenCloud,version=2.0]

Ant task

replaceextensionref

Task

 
<replaceextensionref name="..." type="service">
    <service name="..." vendor="..." version="..."/>
</replaceextensionref>

Example

To replace an extension reference called External DB Selector with a new reference to a SLEE service with identifier ServiceID[name=External DB Selector,vendor=OpenCloud,version=2.0]:

<sis-in-management>
    <replaceextensionref name="External DB Selector" type="service">
        <service name="External DB Selector Service" vendor="OpenCloud" version="2.0"/>
    </replaceextensionref>
</sis-in-management>

or

<sis-sip-management>
    <replaceextensionref name="External DB Selector" type="service">
        <service name="External DB Selector Service" vendor="OpenCloud" version="2.0"/>
    </replaceextensionref>
</sis-sip-management>

MBean operation

MBean

Extension Reference Management

replaceExtensionRef

Operation

To replace a service reference with a new reference to a local JAIN SLEE service:

public void replaceExtensionRef(ExtensionRefID extensionRefID, ServiceID serviceID)
    throws NullPointerException, UnrecognizedComponentException,
           DeploymentException, ManagementException;

Getting and Setting the Default Extension Component Timeout

To get or set the default invocation timeout for an extension component, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getExtensionTimeout

Command

 
getextensiontimeout <ra-entity> <name>
    Get default timeout for an extension component

Example

To get the default timeout for an extension component with reference name External DB Selector in the SIS instance named sis:

$ ./sis-console getextensiontimeout sis "External DB Selector"
No default timeout set for extension reference External DB Selector

setExtensionTimeout

Command

 
setextensiontimeout <ra-entity> <name> <timeout>
    Set default timeout for an extension component. Timeout, measured in
    milliseconds, must be at least 100, or specify 0 to use the global default
    service timeout configured in the SIS for this extension component

Example

To set the default timeout for an extension component with reference name External DB Selector in the SIS instance named sis to 1000ms:

$ ./sis-console setextensiontimeout sis "External DB Selector" 1000
Default timeout for extension reference External DB Selector set to 1000ms

Ant task

updateextensionref

Task

 
<updateextensionref name="..." defaulttimeout="..."/>

Example

 
<sis-in-management>
    <updateextensionref name="External DB Selector" timeout="1000"/>
</sis-in-management>

or

<sis-sip-management>
    <updateextensionref name="External DB Selector" timeout="1000"/>
</sis-sip-management>

Mbean operations

MBean

Extension Reference Management

getDefaultTimeout

Operation

 
public long getDefaultTimeout(ExtensionRefID extensionRefID)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

setDefaultTimeout

Operation

 
public void setDefaultTimeout(ExtensionRefID extensionRefID, long timeout)
    throws NullPointerException, IllegalArgumentException,
           UnrecognizedComponentException, ManagementException;
Warning The timeout argument must be at least 100.

Removing Extension References

To remove an extension reference from the SIS, use the following sis-console command, Ant task, or related MBean operation:

Console command

removeextensionref

Command

 
removeextensionref <ra-entity> <name>
    Remove an extension reference

Example

To remove an extension reference called External DB Selector in the SIS instance named sis:

$ ./sis-console removeextensionref sis "External DB Selector"
Removed extension reference External DB Selector

Ant task

removeextensionref

Task

 
<removeextensionref name="..."/>

Example

To remove an extension reference called External DB Selector:

<sis-in-management>
    <removeextensionref name="External DB Selector"/>
</sis-in-management>

or

<sis-sip-management>
    <removeextensionref name="External DB Selector"/>
</sis-sip-management>

MBean operation

MBean

Extension Reference Management

removeExtensionRef

Operation

To remove an extension reference:

public void removeExtensionRef(ExtensionRefID extensionRefID)
    throws NullPointerException, UnrecognizedComponentException,
           DependencyException, ManagementException;

Managing Address Subscriptions

Address subscriptions can be used by triggers during composition selection to select a composition based on an address contained in the initial event.

The Address Subscription Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Get and set the name of the profile table used to store address subscriptions

 
 getAddressSubscriptionsProfileTableName
setAddressSubscriptionsProfileTableName
 
 Address Subscription Management &rarr; getAddressSubscriptionsProfileTableName
Address Subscription Management &rarr; setAddressSubscriptionsProfileTableName

Procedure: Install an address subscription

 
 installAddressSubscription
 
 Address Subscription Management &rarr; installAddressSubscription

Procedure: Uninstall an address subscription

 
 uninstallAddressSubscription
 
 Address Subscription Management &rarr; uninstallAddressSubscription

Procedure: View address subscriptions

 
 listAddressSubscriptions
getAddressSubscription
getSubscriptionByAddress
 
 Address Subscription Management &rarr; getSubscriptions
Address Subscription Management &rarr; getSubscription
Address Subscription Management &rarr; getSubscriptionByAddress

Procedure: Update an address subscription

 
 updateAddressSubscription
 
 Address Subscription Management &rarr; updateAddressSubscription

Getting and Setting Address Subscriptions Profile Table Name

To get or set the address subscriptions profile table name, use the following sis-console commands or related MBean operations.

Console commands

getAddressSubscriptionsProfileTableName

Command

 
getaddresssubscriptionsprofiletablename <ra-entity>
    Get the current configured address subscriptions profile table name

Example

To get the address subscriptions profile table name for the SIS instance named sis:

$ ./sis-console getaddresssubscriptionsprofiletablename sis
Address subscriptions profile table name=sis-address-subscriptions

setAddressSubscriptionsProfileTableName

Command

 
setaddresssubscriptionsprofiletablename <ra-entity> <table-name>
    Set the configured address subscriptions profile table name. To remove the
    table name, specify 'null' as the argument

Example

To set the address subscriptions profile table name for the SIS instance named sis to sis-address-subscriptions:

$ ./sis-console setaddresssubscriptionsprofiletablename sis sis-address-subscriptions

Ant task

setaddresssubscriptionsprofiletablename

Task

 
<setaddresssubscriptionsprofiletablename tablename="..."/>

Example

 
<sis-in-management>
    <setaddresssubscriptionsprofiletablename tablename="sis-address-subscriptions"/>
</sis-in-management>

or

<sis-sip-management>
    <setaddresssubscriptionsprofiletablename tablename="sis-address-subscriptions"/>
</sis-sip-management>

MBean operations

MBean

Address Subscription Management

getAddressSubscriptionsProfileTableName

Operation

 
public String getAddressSubscriptionsProfileTableName()
    throws ManagementException;

setAddressSubscriptionsProfileTableName

Operation

 
public void setAddressSubscriptionsProfileTableName(String tableName)
    throws ManagementException;

Installing Address Subscriptions

To install an address subscription, use the following sis-console command, Ant task, or related MBean operation.

Console command

installAddressSubscription

Command

 
installaddresssubscription <ra-entity> <name> <address>
                          [-orig <CompositionID>] [-term <CompositionID>]
                          [-desc <description>] [-debuglevel <level>]
                          [-audit <boolean>]
      Install an address subscription with originating and/or terminating compositions

Example

To install an address subscription with attributes:

  • name = Bob

  • address = 34607000123

  • originating composition = CompositionID[name=4000,vendor=OpenCloud,version=1.0]

  • terminating composition = CompositionID[name=4001,vendor=OpenCloud,version=1.0]

into the SIS instance named sis:

$ ./sis-console installaddresssubscription sis Bob 34607000123 \
    -orig name=4000,vendor=OpenCloud,version=1.0 \
    -term name=4001,vendor=OpenCloud,version=1.0
Installed subscription Bob

Ant task

installAddressSubscription

Task

 
<installaddresssubscription name="..." address="..." description="..." debuglevel="..." audit="...">
    <originatingcomposition name="..." vendor="..." version="..."/>
    <terminatingcomposition name="..." vendor="..." version="..."/>
</installaddresssubscription>

Example

 
<sis-in-management>
    <installaddresssubscription name="Bob" address="34607000123">
          <originatingcomposition name="4000" vendor="OpenCloud" version="1.0"/>
          <terminatingcomposition name="4001" vendor="OpenCloud" version="1.0"/>
    </installaddresssubscription>
</sis-in-management>

or

<sis-sip-management>
    <installaddresssubscription name="Bob" address="34607000123">
          <originatingcomposition name="4000" vendor="OpenCloud" version="1.0"/>
          <terminatingcomposition name="4001" vendor="OpenCloud" version="1.0"/>
    </installaddresssubscription>
</sis-sip-management>

MBean operation

MBean

Address Subscription Management

installSubscription

Operation

 
public void installSubscription(AddressSubscription subscription)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Uninstalling Address Subscriptions

To uninstall an address subscription, use the following sis-console command, Ant task, or related MBean operation.

Console command

uninstallAddressSubscription

Command

 
uninstalladdresssubscription <ra-entity> <name>
    Uninstall an address subscription

Example

To uninstall the address subscription with name "Bob" from the SIS instance named sis:

$ ./sis-console uninstalladdresssubscription sis Bob
Uninstalled subscription Bob

Ant task

uninstallAddressSubscription

Task

 
<uninstalladdresssubscription name="..."/>

Example

 
<sis-in-management>
    <uninstalladdresssubscription name="Bob"/>
</sis-in-management>

or

<sis-sip-management>
    <uninstalladdresssubscription name="Bob"/>
</sis-sip-management>

MBean operation

MBean

Address Subscription Management

uninstallSubscription

Operation

 
public void uninstallSubscription(String name)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Viewing Address Subscriptions

To list and get address subscriptions (by name or address), use the following sis-console commands or related MBean operations.

Console commands

listAddressSubscriptions

Command

 
listaddresssubscriptions <ra-entity>
    List all address subscriptions

Example

To list all address subscription for the SIS instance named sis:

$ ./sis-console listaddresssubscriptions sis
AddressSubscription[name=Bob,
                    address=34607000123,
                    orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                    term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                    debugLevel=0, audit=false]
AddressSubscription[name=34610004000,
                    address=34610004000,
                    orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                    term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                    debugLevel=0, audit=false]

getAddressSubscription

Command

 
getaddresssubscription <ra-entity> <name>
    Retrieve an address subscription by name

Example

To get the address subscription for the subscription named Bob in the SIS instance named sis:

$ ./sis-console getaddresssubscription sis Bob
AddressSubscription[name=Bob,
                    address=34607000123,
                    orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                    term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                    debugLevel=0, audit=false]

getSubscriptionByAddress

Command

 
getsubscriptionbyaddress <ra-entity> <address>
    Retrieve a subscription by address

Example

To get the address subscription for the subscribed address 34607000123 in the SIS instance named sis:

$ ./sis-console getsubscriptionbyaddress sis 34607000123
AddressSubscription[name=Bob,
                    address=34607000123,
                    orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                    term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                    debugLevel=0, audit=false]

MBean operations

MBean

Address Subscription Management

getSubscriptions

Operation

To get the list of all address subscriptions:

public AddressSubscription[] getSubscriptions()
    throws ManagementException;

getSubscription

Operation

To get a subscription by name:

public AddressSubscription getSubscription(String name)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

getSubscriptionByAddress

Operation

To get a subscription by subscribed address:

public AddressSubscription getSubscriptionByAddress(String address)
    throws NullPointerException, ManagementException;

Updating Address Subscriptions

To update an address subscription, use the following sis-console command, Ant task, or related MBean operation.

Console command

updateAddressSubscription

Command

 
updateaddresssubscription <ra-entity> <name> [-address <address>]
                          [-orig <CompositionID>] [-term <CompositionID>]
                          [-desc <description>] [-debuglevel <level>]
                          [-audit <boolean>]
Update an existing address subscription

Example

To update the address subscription for Bob with new attributes:

  • address = 34607000999

  • debug level = 2

in the SIS instance named sis:

$ ./sis-console updateaddresssubscription sis Bob -address 34607000999 -debuglevel 2
Updated subscription Bob

Ant task

updateAddressSubscription

Task

 
<updateaddresssubscription name="..." address="..." description="..." debuglevel="..." audit="...">
    <originatingcomposition name="..." vendor="..." version="..."/>
    <terminatingcomposition name="..." vendor="..." version="..."/>
</updateaddresssubscription>

Example

 
<sis-in-management>
    <updateaddresssubscription name="Bob" address="34607000999" debuglevel="2"/>
</sis-in-management>

or

<sis-sip-management>
    <updateaddresssubscription name="Bob" address="34607000999" debuglevel="2"/>
</sis-sip-management>

MBean operation

MBean

Address Subscription Management

updateSubscription

Operation

 
public void updateSubscription(AddressSubscription subscription)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Managing Service Key Subscriptions

Service key subscriptions can be used by triggers during composition selection to select a composition based on the service key contained in the initial event.

The Service Key Subscription Management MBean includes operations for performing the following procedures on a SIS instance:

Tip This is a SIS feature for IN.
sis-console command(s) MBean(s) → Operation

Procedure: Get and set the name of the profile table used to store service key subscriptions

 
 getServiceKeySubscriptionsProfileTableName
setServiceKeySubscriptionsProfileTableName
 
 Service Key Subscription Management &rarr; getServiceKeySubscriptionsProfileTableName
Service Key Subscription Management &rarr; setServiceKeySubscriptionsProfileTableName

Procedure: Install a service key subscription

 
 installServiceKeySubscription
 
 Service Key Subscription Management &rarr; installServiceKeySubscription

Procedure: Uninstall a service key subscription

 
 uninstallServiceKeySubscription
 
 Service Key Subscription Management &rarr; uninstallServiceKeySubscription

Procedure: View service key subscriptions

 
 listServiceKeySubscriptions
getServiceKeySubscription
getSubscriptionByServiceKey
 
 Service Key Subscription Management &rarr; getSubscriptions
Service Key Subscription Management &rarr; getSubscription
Service Key Subscription Management &rarr; getSubscriptionByServiceKey

Procedure: Update a service key subscription

 
 updateServiceKeySubscription
 
 Service Key Subscription Management &rarr; updateServiceKeySubscription

Getting and Setting Service Key Subscriptions Profile Table Name

To get or set the service key subscriptions profile table name, use the following sis-console commands or related MBean operations.

Tip This is a SIS feature for IN.

Console commands

getServiceKeySubscriptionsProfileTableName

Command

 
getservicekeysubscriptionsprofiletablename <ra-entity>
    Get the current configured service key subscriptions profile table name

Example

To get the service key subscriptions profile table name for the SIS instance named sis:

$ ./sis-console getservicekeysubscriptionsprofiletablename sis
Service key subscriptions profile table name=sis-servicekey-subscriptions

setServiceKeySubscriptionsProfileTableName

Command

 
setservicekeysubscriptionsprofiletablename <ra-entity> <table-name>
    Set the configured service key subscriptions profile table name. To remove the
    table name, specify 'null' as the argument

Example

To set the service key subscriptions profile table name for the SIS instance named sis to sis-servicekey-subscriptions:

$ ./sis-console setservicekeysubscriptionsprofiletablename sis sis-servicekey-subscriptions

MBean operations

MBean

Service Key Subscription Management

getServiceKeySubscriptionsProfileTableName

Operation

 
public String getServiceKeySubscriptionsProfileTableName()
    throws ManagementException;

setServiceKeySubscriptionsProfileTableName

Operation

 
public void setServiceKeySubscriptionsProfileTableName(String tableName)
    throws ManagementException;

Installing Service Key Subscriptions

To install a service key subscription, use the following sis-console command, Ant task, or related MBean operation.

Tip This is a SIS feature for IN.

Console command

installServiceKeySubscription

Command

 
installservicekeysubscription <ra-entity> <name> [-servicekey <service-key>]
                              [-orig <composition-id>] [-term <composition-id>]
                              [-thirdparty <composition-id>] [-desc <description>]
                              [-debuglevel <level>] [-audit <boolean>]
    Install a service key subscription with originating, terminating, and/or
    third-party call compositions

Example

To install a service key subscription with attributes:

  • name = VPN

  • service key = 50

  • originating composition = CompositionID[name=4000,vendor=OpenCloud,version=1.0]

  • terminating composition = CompositionID[name=4001,vendor=OpenCloud,version=1.0]

into the SIS instance named sis:

$ ./sis-console installservicekeysubscription sis VPN 50 \
    -orig name=4000,vendor=OpenCloud,version=1.0 \
    -term name=4001,vendor=OpenCloud,version=1.0
Installed subscription VPN

Ant task

installServiceKeySubscription

Task

 
<installservicekeysubscription name="..." servicekey="..." description="..." debuglevel="..." audit="...">
    <originatingcomposition name="..." vendor="..." version="..."/>
    <terminatingcomposition name="..." vendor="..." version="..."/>
</installservicekeysubscription>

Example

 
<sis-in-management>
    <installservicekeysubscription name="VPN" servicekey="50">
        <originatingcomposition name="4000" vendor="OpenCloud" version="1.0"/>
        <terminatingcomposition name="4001" vendor="OpenCloud" version="1.0"/>
    </installservicekeysubscription>
</sis-in-management>

MBean operation

MBean

Service Key Subscription Management

installSubscription

Operation

 
public void installSubscription(ServiceKeySubscription subscription)
    throws NullPointerException, AlreadyDeployedException,
           DeploymentException, ManagementException;

Uninstalling Service Key Subscriptions

To uninstall a service key subscription, use the following sis-console command, Ant task, or related MBean operation.

Tip This is a SIS feature for IN.

Console command

uninstallServiceKeySubscription

Command

 
uninstallservicekeysubscription <ra-entity> <name>
    Uninstall a service key subscription

Example

To uninstall the service key subscription with name VPN from the SIS instance named sis:

$ ./sis-console uninstallservicekeysubscription sis VPN
Uninstalled subscription VPN

Ant task

uninstallServiceKeySubscription

Task

 
<uninstallservicekeysubscription name="..."/>

Example

 
<sis-in-management>
    <uninstallservicekeysubscription name="Bob"/>
</sis-in-management>

MBean operation

MBean

Service Key Subscription Management

uninstallSubscription

Operation

 
public void uninstallSubscription(String name)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Viewing Service Key Subscriptions

To list and get service key subscriptions (by name or service key), use the following sis-console commands or related MBean operations.

Tip This is a SIS feature for IN.

Console commands

listServiceKeySubscriptions

Command

 
listservicekeysubscriptions <ra-entity>
    List all service key subscriptions

Example

To list all service key subscription for the SIS instance named sis:

$ ./sis-console listservicekeysubscriptions sis
ServiceKeySubscription[name=11, service key=11, debugLevel=0, audit=false]
ServiceKeySubscription[name=12, service key=12,
                       orig=CompositionID[name=1,vendor=OpenCloud,version=1.0],
                       term=CompositionID[name=1,vendor=OpenCloud,version=1.0],
                       debugLevel=0, audit=false]
ServiceKeySubscription[name=VPN, service key=50,
                       orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                       term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                       debugLevel=0, audit=false]

getServiceKeySubscription

Command

 
getservicekeysubscription <ra-entity> <name>
    Retrieve a service key subscription by name

Example

To get the service key subscription for the subscription named VPN in the SIS instance named sis:

$ ./sis-console getservicekeysubscription sis VPN
ServiceKeySubscription[name=VPN, service key=50,
                       orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                       term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                       debugLevel=0, audit=false]

getSubscriptionByServiceKey

Command

 
getsubscriptionbyservicekey <ra-entity> <service-key>
    Retrieve a subscription by service key

Example

To get the service key subscription for the subscribed service key 50 in the SIS instance named sis:

$ ./sis-console getsubscriptionbyservicekey sis 50
ServiceKeySubscription[name=Bob, service key=50,
                       orig=CompositionID[name=4000,vendor=OpenCloud,version=1.0],
                       term=CompositionID[name=4001,vendor=OpenCloud,version=1.0],
                       debugLevel=0, audit=false]

MBean operations

MBean

Service Key Subscription Management

getSubscriptions

Operation

To get the list of all service key subscriptions:

public ServiceKeySubscription[] getSubscriptions()
    throws ManagementException;

getSubscription

Operation

To get a subscription by name:

public ServiceKeySubscription getSubscription(String name)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

getSubscriptionByServiceKey

Operation

To get a subscription by subscribed service key:

public ServiceKeySubscription getSubscriptionByServiceKey(int serviceKey)
    throws NullPointerException, ManagementException;

Updating Service Key Subscriptions

To update a service key subscription, use the following sis-console command, Ant task, or related MBean operation.

Tip This is a SIS feature for IN.

Console command

updateServiceKeySubscription

Command

 
updateservicekeysubscription <ra-entity> <name> [-servicekey <service-key>]
                            [-orig <composition-id>] [-term <composition-id>]
                            [-thirdparty <composition-id>] [-desc <description>]
                            [-debuglevel <level>] [-audit <boolean>]
Update an existing service key subscription

Example

To update the service key subscription for VPN with new attributes:

  • service key = 60

  • debug level = 2

in the SIS instance named sis:

$ ./sis-console updateservicekeysubscription sis VPN -servicekey 60 -debuglevel 2
Updated subscription VPN

Ant task

updateServiceKeySubscription

Task

 
<updateservicekeysubscription name="..." servicekey="..." description="..." debuglevel="..." audit="...">
    <originatingcomposition name="..." vendor="..." version="..."/>
    <terminatingcomposition name="..." vendor="..." version="..."/>
    <thirdpartycomposition name="..." vendor="..." version="..."/>
</updateservicekeysubscription>

Example

 
<sis-in-management>
    <updateservicekeysubscription name="VPN" servicekey="60" debuglevel="2"/>
</sis-in-management>

MBean operation

MBean

Service Key Subscription Management

updateSubscription

Operation

 
public void updateSubscription(ServiceKeySubscription subscription)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Managing Network Interfaces

This section includes procedures for managing network interfaces using the Network Interface Management and Network Interface Definition MBeans.

Note
What’s in a network interface definition?

A network interface definition describes the properties of a network connection point. It includes:

  • a name, used as a unique identifier for the network interface

  • zero or more configuration properties

  • the current state of the network interface, either ENABLED or DISABLED.

Network Interface Management MBeans

The Network Interface Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Create a network interface definition

 
 createnetworkinterface
 
  Network Interface Management &rarr; createNetworkInterfaceDefinition

Procedure: Remove a network interface definition

 
 removenetworkinterface
 
  Network Interface Management &rarr; removeNetworkInterfaceDefinition

Procedure: Enable a network interface

 
 enablenetworkinterface
 
  Network Interface Management &rarr; enableNetworkInterface

Procedure: Disable a network interface

 
 disablenetworkinterface
 
  Network Interface Management &rarr; disableNetworkInterface

Procedure: View a network interface definition

 
 listnetworkinterfaces
listenablednetworkinterfaces{ctd]
 
  Network Interface Management &rarr; getNetworkInterfaces
Network Interface Management &rarr; getEnabledNetworkInterfaces{ctd]

Network Interface Definition MBean

The Network Interface Definition MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Update the configuration properties of a network interface definition

 
 updatenetworkinterface
 
  Network Interface Definition &rarr; updateProperties

Procedure: Remove a network interface definition

 
 removenetworkinterface
 
  Network Interface Definition &rarr; remove

Procedure: View a network interface definition

 
 dumpnetworkinterface
 
  Network Interface Definition &rarr; getDescriptor

Network Interface Properties

SIS supports both SIP and IN network interface types. Each type of network interface supports a number of mandatory and optional configuration properties. Below are the configuration parameters for SIP and IN network interface definitions.

SIP network interface definition parameters

Parameter Description Default

IP address
IPAddress

The IP address or hostname for the SIS. The SIS will listen on this address. The address AUTO will automatically select the node’s primary IP address, for convenience and use in a cluster, where each node has its own IP address.

An IP address range may also be used, using address/mask notation; for example, 192.168.0.0/24. This will select the matching IP address on the node, if one exists. This may be useful in a cluster where nodes have IP addresses on the same subnet.

Example: sis.mydomain.com
Example: 192.168.5.0/24

none

Virtual addresses
VirtualAddresses

Optional comma-separated list of alternative addresses that the SIS is known by, such as virtual addresses provided by an external load balancer. DNS NAPTR or SRV names for the SIS should also be specified here. The SIS treats requests that are routed to these addresses as destined for the SIS; they must be processed by the SIS before forwarding.

Addresses may also include a port number, which would specify the load balancer port, if an external load balancer provides the virtual address on a different port to the SIS. If no port is specified then the SIS will match the virtual address on any port. If the literal string <local-port> is used instead of a port number, an address will match if its port matches the SIS’s port.

If this property is set, and the UseVirtualAddressInURIs property is set to true, the first name in the list will be used in SIP URIs generated by the SIS, so that mid-dialog requests are routed back to the virtual address, not a specific node. The first name should be the fully-qualified hostname that corresponds to the virtual address.

Example: sis1.mydomain.com, sis2.mydomain.com:5090
Example: tas.home1.net:<local-port>

an empty list

Dynamic SRV name format
DynamicSRVNameFormat

Format for generating a DNS SRV name from either the interface’s IP address ${IP} or the environment variable SRV_INSTANCE_ID which is set in a startup script, .bashrc, etc.

See Per-node SRV addresses.

If the format string is 'mmtel-${IP}.home1.net' then this will generate names like 'mmtel-10-0-0-1.home1.net'.

If the format string is 'mmtel-${SRV_INSTANCE_ID}.home1.net', and the environment variable SRV_INSTANCE_ID has been set to node101 then this will generate the name 'mmtel-node101.home1.net'. If the SRV_INSTANCE_ID value is not a valid FQDN label then a RA configuration alarm will be raised, and the network interface will not enter active state.

If defined, the SIS will use the generated SRV name in its own Contact and Record-Route headers. Corresponding SRV records must be provisioned in the DNS, which favour the given node’s IP address, but allow failover to backup addresses if the primary address fails.

Either ${IP} or ${SRV_INSTANCE_ID} can be used in the format string, not both.

Default: none (no SRV name will be generated).

Example: , mmtel-${IP}.home1.net generates names like mmtel-10-0-0-1.home1.net.

none

Use virtual address in URIs
UseVirtualAddressInURIs

If true, the first virtual address (if defined) is used in SIP URIs.

 
 false

Port
Port

Port that will be used for unencrypted SIP transports (UDP, TCP).

 
 5060

Secure port
SecurePort

Port that will be used for encrypted SIP transports (TLS).

 
 5061

SIP transports
Transports

SIP transports to be supported by the SIS. This is a comma-separated list containing one or more of UDP, TCP or TLS.

 
 UDP
TCP

Via sent-by address
ViaSentByAddress

Specifies an IP address or hostname that will be used in the "sent-by" field of Via headers added by the SIS. If a value is not specified the SIS will use the local IP address of the node. In some scenarios it may be necessary to specify a value to use a virtual server address. Example: sis.mydomain.com

null

IN network interface definition parameters

Below are general default network interface settings, followed by those specific to the OCSS7, Signalware, and simulated TCAP stacks.

Note
Using TCAP stacks

General settings

Parameter Description Default

Local SCCP address
local-sccp-address

SCCP address assigned to the SIS instance, included in dialog open requests sent by the SIS instance to the network. See also SCCP Address Format and Administering the CGIN Resource Adaptor Entity.

Example: type=C7,ri=pcssn,pc=202,ssn=101

 
 _none_

Responder SCCP address
responder-sccp-address

SCCP address used by the SIS when sending responses to received dialog open requests. This setting is optional and only needs to be specified if an address different to that filled in by the TCAP stack when sending open responses is required. See also SCCP Address Format.

Example: type=C7,ri=pcssn,pc=202,ssn=101

auto

Default TCAP invoke timeout
default-invoke-timeout

The timeout period, measure in milliseconds, the SIS uses whenever it needs to send non-service-specified invoke requests to the network.

 
 5000

Default dialog activity timeout
default-activity-timeout

The default timeout period, measured in milliseconds, for dialogs with no activity before they are terminated.

 
 1800000

TCAP fibers maximum pool size
tcap-fibers.max-pool-size

The maximum number of threads in the TCAP layer fiber pool. If zero, then a pool is not used: work is done directly in the I/O thread.

 
 4

TCAP fibers queue size
tcap-fibers.queue-size

The maximum number of waiting fibers in the TCAP layer fiber pool.

If the queue becomes full and there are less than the maximum number of worker threads, a new thread is started. If the queue is full and no more threads are permitted, then subsequent fiber tasks are executed directly by the calling thread (usually the I/O thread).

A zero-sized queue is possible and implies that work is either immediately assigned an idle thread, or the work is done by the calling thread.

 
 250

Inbound ACN aliases
acn-inbound-aliases

Comma-separated list of values in <external OID>:<internal ASN.1> format. It allows the SIS to be configured to accept the external application context name as a synonym for the internal application context name. An external ACN can be mapped to only one internal ACN. Several external ACNs can be mapped to the same internal ACN. The right-hand-side of each mapping can either name an application context value (eg. etsi_inap_cs1.core-INAP-CS1-SSP-to-SCP-AC), or it can name the interceptor to use to determine the AC to use (eg. map.phase-1).

 
 _none_

Outbound ACN mappings
acn-outbound-mappings

Comma-separated list of values in <internal ASN.1>:<external OID> format. It allows the SIS to be configured to write the external application context name in place of the internal application context name. An internal ACN can be mapped to only one external ACN. Multiple internal ACNs can be mapped to the same external ACN.

 
 _none_

Relaxed BER decoding rules
relaxed-decoding

Specifies whether or not to relax the BER decoding rules to allow certain types of malformed data. If true, then some malformed BER encodings in protocol data will be accepted:

  1. Needlessly long encoding of INTEGER or ENUMERATED (more that 9 leading '0' or '1' bits).

  2. Primitive encoding of a BIT STRING with a length of zero.

  3. Encoding of an OID with a length of zero.

  4. Non-innermost TL pair in the encoding of NULL, BOOLEAN, INTEGER or ENUMERATED indicates indefinite length form of encoding but the tag lacks the"constructed" bit set.

  5. Needlessly long encoding of an exponent.

If false, then the BER rules are strictly enforced and malformed data will be rejected.

This property applies to the decoding of application protocol data contained within operations, errors, and user information. It does not apply to the decoding of the surrounding TCAP data; TCAP data is always strictly decoded.

 
 false

TCAP stack
stack

Name of the TCAP stack for the SIS to use. Three stacks are currently supported:

  • ocss7, a TCAP stack that connects to one or more TCAP Manager (SGC) processes;

  • signalware, a TCAP stack that connects to one or more backend processes running on Mavenir Signalware;

  • tcapsim, a simulated TCAP stack that does not require any specific hardware.

Example: ocss7

 
 _none_

Network interface definition parameters specific to the OCSS7 stack

Warning These parameters only need valid values if using the OCSS7 TCAP stack.
Parameter Description Default

SGCs
ocss7.sgcs

Comma-separated list of host:port pairs.
Example: ocss71:9703,ocss72:9703

The SIS will attempt to establish a connection to all of the configured host:port pairs.

 
 localhost:12201

URL List
ocss7.urlList

Comma-separated list of host:port locations where the SIS instance can expect to find OC SS7 SGC TCAP Manager processes running and listening for connections from the SLEE. Example: ocss71:8080,ocss72:8080

This parameter cannot be used with ocss7.sgcs. Use of ocss7.sgcs is recommended in preference to this parameter, see TCAP Stack and SGC Stack cooperation

 
 _none_

URL List Retry Interval
ocss7.urlList.retrySleep

The wait interval in milliseconds between subsequent connection attempts to the TCAP Managers. The value applies to all manager connections.

 
 1000

Local SSN
ocss7.local-ssn

The subsystem number used when the local-sccp-address property does not provide one, for example in the case when it is set to auto. Valid range: 2-255 (Only checked if actually needed)

 
 -1

Open Transactions Capacity
ocss7.trdpCapacity

The maximum number of open transactions (dialogs) at any moment in time. Valid range: 1000-2000000

 
 1000000

Max Scheduler Threads
ocss7.schThreads

The maximum number of threads used by the scheduler. Valid range: 1-100.

 
 10

Scheduler Node List Size
ocss7.schNodeListSize

The number of events that may be scheduled on a single scheduler thread. This value multiplied with the value for Max Scheduler Threads should be directly proportional to Open Transactions Capacity. Valid range: 0 (autosize) or 1000-2000000.

 
 0

Waiting Tasks Capacity
ocss7.taskdpCapacity

The maximum number of inbound messages and timeout events that may be waiting to be processed at any moment in time. This value should be directly proportional to Open Transactions Capacity. Valid range: 0 (autosize) or 1000-2000000.

 
 0

Worker Group Queues
ocss7.wgQueues

The number of threads used by the worker group to process timeout events and inbound messages. Valid range: 1-100.

 
 100

Worker Queue Size
ocss7.wgQueuesSize

The maximum number of tasks in one worker queue. This value multiplied with the value for Worker Group Queues should be directly proportional to (2 * Waiting Tasks Capacity). Valid range: 0 (autosize) or 1000-2000000.

 
 0

Sender Queue Size
ocss7.senderQueueSize

The maximum number of outbound messages in the sender queue. This value is directly proportional to Open Transactions Capacity. Valid range: 0 (autosize) or 1000-2000000.

 
 0

Heartbeat Enabled
ocss7.heartbeatEnabled

This property only affects operation when connecting to SGC versions 1.0.1 and older. Heartbeat is always enabled when connecting to SGCs 1.1.0 and newer. Enables or disables the heartbeat between the TCAP stack and the SGC. Also enables the heartbeat timeout detection mechanism. N.B. If the heartbeat is enabled on the SGC it must also be enabled here. Valid values: true or false

 
 true

Heartbeat Period
ocss7.heartbeatPeriod

The period between heartbeat sends in seconds. Heartbeat timeout is also a function of this value (twice this value). When connecting to SGC version 1.0.1 and older the value configured here must match that configured on the SGC. When connecting to SGC version 1.1.0 and newer, this value is communicated to the SGC during handshake negotation. It is not necessary to separately configure the SGC’s heartbeat. Valid range: 1+

 
 5

Network interface definition parameters specific to the Signalware stack

Warning These parameters only need valid values if using the signalware TCAP stack.
Parameter Description Default

Backends
signalware.backends

Comma-separated list of host:port locations where the SIS instance can expect to find Signalware backend processes running and listening for connections from the SLEE.

Example: signalware1:10001,signalware2:10001

none

Base weight
signalware.base-weight

Base incoming traffic weight advertised to backends.

This property is a comma-separated list that must include at least one numeric item — the weight value used by any node that does not explicitly specify a weight. Additional items may specify weights for particular nodes, using the form
{nodeid,nodeid,…​}weight.

For example, the value 100,{101}50,{102,103}75 specifies a weight of 50 for node 101, a weight of 75 for nodes 102 and 103, and a default weight of 100 for all other nodes.

Each weight is a positive integer used to balance load between nodes. The values have no particular unit other than relative to each other. A node will receive new dialogs in proportion to its weight; for example, two nodes with weights of 10 will receive about the same number of dialogs each, and a node with a weight of 20 will receive twice as many as a node with a weight of 10.

Tip One approach is to treat them as percentages and assign 100 to the busiest node, with smaller values for nodes that take less load.

The actual weight used for a particular node is the base weight specified here, modified by the function defined by weight function below, based on the amount of traffic that node has processed.

 
 100

Weight function
signalware.weight-function

Definition of the weight function applied to "full-rate" weights to find the actual rate to use. This is used to gradually increase load on a newly-joined cluster node, so as not to immediately swamp it with traffic.

The function is specified as a series of comma-separated values S(1),T(1),S(2),T(2),…​,S(N-1),T(N-1),S(N) where:

  • S(i) is the multiplier (in the range [0.0 .. 1.0]) of the "full-rate" weight to use in state (i)

  • T(i) is the total number of dialogs that must be received on a particular node before moving to state (i+1).

 
 0.01,10,0.10,1000,
0.50,5000,1.00

Fiber map size
signalware.fiber-map-size

The number of fibers in the fixed-size fiber map used to process incoming traffic. This value must be at least as large as the value of the TCAP Fibers Queue Size property.

 
 256

Dialog allocation timeout
signalware.dialog-allocation-timeout

The maximum time, in milliseconds, to block while waiting to allocate a new dialog before returning an error to the calling service code.

 
 5000

Dialog pool size
signalware.dialog-pool-size

The size of the pre-allocation pool for outgoing dialogs. This pool is used to satisfy requests for new outgoing dialogs, and is refilled asynchronously. If the pool becomes empty due to a high rate of dialog creation, outgoing dialogs must wait for the backend to allocate a new dialog, increasing latency.

One pool is maintained per backend connection.

 
 100

Network interface definition parameters specific to the simulated TCAP stack

Warning These parameters only need valid values if using the simulated TCAP stack.
Parameter Description Default

Listen addresses
tcapsim.listen-addresses

Comma-separated list of host:port[:nodeID] addresses to listen on for incoming connections from other tcapsim TCAP stacks. Example: localhost:10100

none

Maximum dialogs
tcapsim.max-dialogs

Maximum number of concurrent dialogs to support.

 
 10000

Routing table
tcapsim.routing-table

Path to the file containing the routing table description.

 
 ${rhino.dir.home}
${/}config${/}
tcapsim-routing-table.txt

Global title translation table
tcapsim.gt-table

Path to the file containing the global translation table description

 
 ${rhino.dir.home}${/}
config${/}
tcapsim-gt-table.txt

Creating Network Interface Definitions

To create a network interface definition, use the following sis-console command, Ant task, or related MBean operation.

Console command

createnetworkinterface

Command

 
createnetworkinterface <ra-entity> <interface-name> (<property-name> <property-value>)*
    Add a new network interface definition to the SIS.  Optionally followed by a
    list of property names and values for the interface
Note For a list of supported properties for each type of network interface, please see Network Interface Properties.
Warning You must specify a value for each network interface property that does not have a default value, when you create a network interface.

Example

To create a SIS-IN network interface definition called default-in with properties:

  • local-sccp-address : type=c7,ri=pcssn,pc=4012,ssn=123

  • stack : `signalware

  • signalware.backends : signalware-host:10123

in the SIS instance named sis:

$ ./sis-console createnetworkinterface sis default-in \
    local-sccp-address type=c7,ri=pcssn,pc=4012,ssn=123 \
    stack signalware \
    signalware.backends signalware-host:10123
Created network interface definition default-in

Ant task

createnetworkinterface

Task

 
<createnetworkinterface name="...">
    <property name="..." value="..."/>
    ...
</createnetworkinterface>

Example

To create a SIS-IN network interface definition called default-in with the example property values shown for the sis-console:

<sis-in-management>
    <createnetworkinterface name="default-in">
        <property name="local-sccp-address" value="type=c7,ri=pcssn,pc=4012,ssn=123"/>
        <property name="stack" value="signalware"/>
        <property name="signalware.backends" value="signalware-host:10123"/>
    </createnetworkinterface>
</sis-in-management>

or to create a SIS-SIP network interface definition called default-sip

<sis-sip-management>
    <createnetworkinterface name="default-sip">
        <property name="IPAddress" value="AUTO"/>
        <property name="ViaSentByAddress" value="192.168.0.1"/>
        <property name="VirtualAddresses" value="sip-host:5086"/>
        <property name="Port" value="5086"/>
        <property name="SecurePort" value="5087"/>
    </createnetworkinterface>
</sis-sip-management>

MBean operation

MBean

Network Interface Management

createNetworkInterfaceDefinition

Operation

To create a network interface definition:

public ObjectName createNetworkInterfaceDefinition(String name, Map<String,String> properties)
    throws NullPointerException, InvalidArgumentException,
           AlreadyDeployedException, InvalidConfigurationException,
           ManagementException;

Updating Network Interface Definitions

To update a network interface definition, use the following sis-console command, Ant task, or related MBean operation.

Console command

updatenetworkinterface

Command

 
updatenetworkinterface <ra-entity> <interface-name> (<property-name> <property-value>)*
    Update an existing network interface definition with the given properties. A
    property-value of "null" will remove that property from the interface.
Note For a list of supported properties for each type of network interface, please see Network Interface Properties.

Example

To update a network interface definition called default-in with new configuration properties:

  • stack: tcapsim

  • listen-addresses: localhost:10123

in the SIS instance named sis:

$ ./sis-console updatenetworkinterface sis default-in stack tcapsim listen-addresses localhost:10123
Updated network interface definition default-in

Ant task

updatenetworkinterface

Task

 
<updatenetworkinterface name="...">
    <property name="..." value="..."/>
    ...
</updatenetworkinterface>

Example

To update a network interface definition called default-in with the example property values shown for the sis-console :

<sis-in-management>
    <updatenetworkinterface name="default-in">
        <property name="stack" value="tcapsim"/>
        <property name="listen-addresses" value="localhost:10123"/>
    </updatenetworkinterface>
</sis-in-management>

or to update a network interface definition called default-sip with the property VirtualAddresses: apps.foo.com:

<sis-sip-management>
    <updateenetworkinterface name="default-sip">
        <property name="VirtualAddresses" value="apps.foo.com"/>
    <updateenetworkinterface/>
</sis-sip-management>

MBean operation

MBean

Network Interface Definition

updateProperties

Operation

To update the network interface definition managed by this MBean:

public void updateProperties(Map<String,String> properties)
    throws NullPointerException, InvalidArgumentException,
           InvalidConfigurationException, ManagementException;

Enabling Network Interfaces

To enable a network interface, use the following sis-console command, Ant task, or related MBean operation.

Console command

enablenetworkinterface

Command

 
enablenetworkinterface <ra-entity> <interface-name>
    Enable the network interface on the SIS instance

Example

To enable the network interface called default-in in the SIS instance named sis:

$ ./sis-console enablenetworkinterface sis default-in
Enabled network interface default-in on SIS instance sis

Ant task

enablenetworkinterface

Task

 
<enablenetworkinterface name="..."/>

Example

To enable a network interface called default-in:

<sis-in-management>
    <enablenetworkinterface name="default-in"/>
</sis-in-management>

or to enable a network interface called default-sip:

<sis-sip-management>
    <enablenetworkinterface name="default-sip"/>
</sis-sip-management>

MBean operation

MBean

Network Interface Management

enableNetworkInterface

Operation

To enable a network interface:

public void enableNetworkInterface(String name)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, ManagementException;

Disabling Network Interfaces

To disable a network interface, use the following sis-console command, Ant task, or related MBean operation.

Console command

disablenetworkinterface

Command

 
disablenetworkinterface <ra-entity> <interface-name>
    Disable the network interface on the SIS instance
Warning A network interface cannot be disabled if it is currently being used in one or more network routes.

Example

To disable the network interface called default-in in the SIS instance named sis:

$ ./sis-console disablenetworkinterface sis default-in
Disabled network interface default-in on SIS instance sis

Ant task

disablenetworkinterface

Task

 
<disablenetworkinterface name="..."/>

Example

To disable a network interface called default-in:

<sis-in-management>
    <disablenetworkinterface name="default-in"/>
</sis-in-management>

or to disable a network interface called default-sip:

<sis-sip-management>
    <disablenetworkinterface name="default-sip"/>
</sis-sip-management>

MBean operation

MBean

Network Interface Management

disableNetworkInterface

Operation

To disable a network interface:

public void disableNetworkInterface(String name)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, ManagementException;

Removing Network Interface Definitions

To remove a network interface definition, use the following sis-console command, Ant task, or related MBean operation.

Console command

removenetworkinterface

Command

 
removenetworkinterface <ra-entity> <interface-name>
    Remove a network interface definition from the SIS
Warning A network interface must be disabled before it can be removed.

Example

To remove the network interface definition called default-in in the SIS instance named sis:

$ ./sis-console removenetworkinterface sis default-in
Removed network interface definition default-in

Ant task

removenetworkinterface

Task

 
<removenetworkinterface name="..."/>

Example

To remove a network interface definition called default-in:

<sis-in-management>
    <removenetworkinterface name="default-in"/>
</sis-in-management>

or to remove a network interface definition called default-sip:

<sis-sip-management>
    <removenetworkinterface name="default-sip"/>
</sis-sip-management>

MBean operations

MBean

Network Interface Management

removeNetworkInterfaceDefinition

Operation

To remove a network interface definition:

public void removeNetworkInterfaceDefinition(String name)
    throws NullPointerException,  UnrecognizedComponentException,
           InvalidStateException, ManagementException;

MBean

Network Interface Definition

remove

Operation

To remove the network interface definition managed by this MBean:

public void remove()
    throws InvalidStateException, ManagementException;

Viewing Network Interface Definitions

To list or display network interface definitions, use the following sis-console commands or related MBean operations.

Console commands

listnetworkinterfaces

Command

 
listnetworkinterfaces <ra-entity>
    List all network interface definitions
Note This command lists the names of all network interface definitions created in the SIS.

Example

 
$ ./sis-console listnetworkinterfaces sis
default-in
service-network

listenablednetworkinterfaces

Command

 
listenablednetworkinterfaces <ra-entity>
    List all network interfaces that have been enabled on the SIS instance
Note This command lists the names of all network interfaces that have been enabled in the SIS.

Examples

 
$ ./sis-console listenablednetworkinterfaces sis
default-in
service-network

dumpnetworkinterface

Command

 
dumpnetworkinterface <ra-entity> <interface-name>
    Display a network interface definition
Note This command displays the properties of the network interface definition.

Examples

 
$ ./sis-console dumpnetworkinterface sis default-in
_name_              : default-in
_state_             : DISABLED
local-sccp-address  : type=c7,ri=pcssn,pc=4012,ssn=123
signalware.backends : signalware-host:10123
stack               : signalware

MBean operations

MBean

Network Interface Management

getNetworkInterfaceDefinitions

Operation

 
public String[] getNetworkInterfaceDefinitions()
    throws ManagementException;
Note This operation returns the names of all network interface definitions in the SIS.

getEnabledNetworkInterfaces

Operation

 
public String[] getEnabledNetworkInterfaces()
    throws ManagementException;
Note This operation returns the names of all network interfaces that have been enabled in the SIS.

MBean

Network Interface Definition

getDescriptor

Operation

 
public CompositeData getDescriptor()
    throws ManagementException;
Note This operation returns the network interface descriptor in the form of an MBean CompositeData object.

Managing Network Routes

This section includes procedures for managing network routes using the Network Interface Management and Network Route MBeans.

Note
What is a network route?

A network route identifies when a particular network interface will be used when an outbound network dialog is created. It includes:

  • a rule, used to determine when the network route is selected

  • the name of the network interface selected if the rule is satisfied

  • an ordered position within the routing table.

The SIS evaluates network route rules in position order, starting from position 0, until a rule matches.

A SIS instance should also define a default route. A default route has no rule associated with it and is used if no other rule in the routing table is satisfied. The default route always occupies the last position in the routing table. If a default route is not defined for a SIS instance and an attempt to route a dialog results in no matching rule, a routing failure will occur and the dialog will be deemed unroutable.

Network Interface Management MBeans

The Network Interface Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Add a network route

 
 addnetworkroute
adddefaultnetworkroute
 
  Network Interface Management &rarr; addRoute
Network Interface Management &rarr; addDefaultRoute

Procedure: Remove a network route

 
 removenetworkroute
removedefaultnetworkroute
 
  Network Interface Management &rarr; removeRoute
Network Interface Management &rarr; removeDefaultRoute

Procedure: View network routes

 
 dumpnetworkroutes
 
  Network Interface Management &rarr; getRoutes

Network Route MBean

The Network Route MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Update a network route

 
 dumpnetworkroutes
updatenetworkroute
 
 Network Route &rarr; getRule
Network Route &rarr; getInterfaceName
Network Route &rarr; setRule
Network Route &rarr; setInterfaceName

Procedure: Get and set the position of a network route

 
 dumpnetworkroutes
repositionnetworkroute
 
 Network Route &rarr; getPosition
Network Route &rarr; reposition

Procedure: Remove a network route

 
 removenetworkroute
removedefaultnetworkroute
 
  Network Route &rarr; remove

Adding Network Routes

To add a network route, use the following sis-console commands, Ant tasks, or related MBean operations.

Console commands

SIP

addnetworkroute

Command

 
addnetworkroute <ra-entity> <rule> <interface-name> [position]
    Add a new network route to the SIS.  Rules are of the format "<type> [<value>]".
     The rule type may be "ip", "domain", "regex", "all", or "none".  If the rule
    type is "ip", "domain", or "regex", a value must be specified for the rule.
Note The position parameter is optional. If not specified, the new route is added to the end of the current route list.

Example

To add a network route in the SIS instance named sis which specifies that all requests routed to a subdomain of internal.home1.net should be sent on the sis-internal interface:

$ ./sis-console addnetworkroute sis "domain internal.home1.net" sis-internal
Network route added
adddefaultnetworkroute

Command

 
adddefaultnetworkroute <ra-entity> <interface-name>
    Add a default route to the SIS
Note At most one default route of a given type may be configured in a single SIS instance.

Example

To add a default network route in the SIS instance named sis that uses the network interface named default:

$ ./sis-console adddefaultnetworkroute sis default
Default route added

IN

addnetworkroute

Command

 
addnetworkroute <ra-entity> <rule> <interface-name> [position]
    Add a new network route to the SIS.  Rules are of the format "<type> [<value>]".
     The rule type may be "protocol", "orig-address", or "dest-address", and a value
    must always be specified.  Multiple rules may be specified, delimited using the
    ampersand '&'.
Note The position parameter is optional. If not specified, the new route is added to the end of the current route list.

Example

To add a network route in the SIS instance named sis which specifies that the network interface named external-scp should be used if the destination SCCP address is a global title address with digit prefix 3460100:

$ ./sis-console addnetworkroute sis "dest-address type=c7,ri=gt,digits=3460100" external-scp
Network route added
adddefaultnetworkroute

Command

 
adddefaultnetworkroute <ra-entity> <interface-name>
    Add a default route to the SIS
Note At most one default route may be configured in a single SIS instance.

Example

To add a default network route in the SIS instance named sis that uses the network interface named default:

$ ./sis-console adddefaultnetworkroute default
Default route added

Ant tasks

addnetworkroute

Task

 
<addnetworkroute rule="..." interface="..." position="..."/>

Example

To add a network route with a rule specifying to select the network interface named external-scp if the destination SCCP address is a global title address with digit prefix 3460100:

<sis-in-management>
    <addnetworkroute rule="dest-address type=c7,ri=gt,digits=3460100" interface="external-scp"/>
</sis-in-management>

or to add a network route with a rule specifying to select the network interface named sis-internal:

<sis-sip-management>
    <addnetworkroute rule="domain internal.home1.net" interface="sis-internal"/>
</sis-sip-management>

adddefaultnetworkroute

Task

 
<adddefaultnetworkroute interface="..."/>

Example

To add a default network route that uses the network interface named default:

<sis-in-management>
    <adddefaultnetworkroute interface="default"/>
</sis-in-management>

or

<sis-sip-management>
    <adddefaultnetworkroute interface="default"/>
</sis-sip-management>

MBean operations

SIP

MBean

SIP Network Interface Management
addRoute

Operation

To add a network route:

public ObjectName addRoute(String rule, String interfaceName, int position)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedComponentException, AlreadyDeployedException,
           InvalidStateException, ManagementException;

IN

MBean

IN Network Interface Management
addRoute

Operation

To add a network route:

public ObjectName addRoute(String rule, String interfaceName, int position)
    throws NullPointerException, InvalidArgumentException,
           UnrecognizedComponentException, AlreadyDeployedException,
           InvalidStateException, ManagementException;

Common

MBean

Network Interface Management
addDefaultRoute

Operation

To add a default network route:

public ObjectName addDefaultRoute(String interfaceName)
    throws NullPointerException, UnrecognizedComponentException,
           AlreadyDeployedException, InvalidStateException,
           ManagementException;

Removing Network Routes

To remove a network route, use the following sis-console commands, Ant tasks, or related MBean operations.

Console commands

removenetworkroute

Command

 
removenetworkroute <ra-entity> <position>
    Remove a network route from the SIS.

Example

To remove a network route from position 0 in the SIS instance named sis:

$ ./sis-console removenetworkroute sis 0
Network route removed

removedefaultnetworkroute

Command

 
removedefaultnetworkroute <ra-entity>
    Remove a default route from the SIS

Example

To remove a default network route in the SIS instance named sis:

$ ./sis-console removedefaultnetworkroute sis
Default route removed

Ant tasks

removenetworkroute

Task

 
<removenetworkroute position="..."/>

Example

To remove a network route from position 0:

<sis-in-management>
    <removenetworkroute position="0"/>
</sis-in-management>

or

<sis-sip-management>
    <removenetworkroute position="0"/>
</sis-sip-management>

removedefaultnetworkroute

Task

 
<removedefaultnetworkroute/>

Example

To remove a default network route:

<sis-in-management>
    <removedefaultnetworkroute/>
</sis-in-management>

or

<sis-sip-management>
    <removedefaultnetworkroute/>
</sis-sip-management>

MBean operations

MBean

Network Interface Management

removeRoute

Operation

To remove a network route:

public void removeRoute(int position)
    throws InvalidArgumentException, ManagementException;

removeDefaultRoute

Operation

To remove a default network route:

public void removeDefaultRoute()
    throws InvalidStateException, ManagementException;

Viewing Network Routes

To display network routes, use the following sis-console command or related MBean operation.

Console commands

dumpnetworkroutes

Command

 
dumpnetworkroutes <ra-entity>
    Display all network routes
Note This command displays the network routing table for the specified SIS instance.

Example

 
$ ./sis-console dumpnetworkroutes sis
position     interface        rule
-----------  --------------  -----------------------------------------------------
          0   external-scp    dest-address type=C7,ri=gt,digits=3460100,gti=2,tt=0
          1   external-scp    dest-address type=C7,ri=gt,digits=3460200,gti=2,tt=0
 2147483647   default                                                      default
3 rows

MBean operation

MBean

Network Interface Management

getRoutes

Operation

 
public TabularData getRoutes()
    throws ManagementException;
Note This operation returns the network routes in the form of an MBean CompositeData object.

Updating Network Routes

To update a network route, use the following sis-console command, Ant task, or related MBean operations.

Console command

updatenetworkroute

Command

 
updatenetworkroute <ra-entity> <position> [-rule <rule>] [-interface <interface-name>]
    Update an existing network route in the SIS

Example

To update a network route in position 0, in the SIS instance named sis, with a new rule that specifies selecting the route’s network interface if the destination SCCP address is a PC/SSN address with an SSN of 146:

$ ./sis-console updatenetworkroute sis 0 -rule "dest-address type=c7,ri=pcssn,ssn=146"
Network route updated

Ant task

updatenetworkroute

Task

 
<updatenetworkroute position="..." rule="..." interface="..."/>

Example

To update a network route in position 0, with a new rule that specifies selecting the route’s network interface if the destination SCCP address is a PC/SSN address with an SSN of 146:

<sis-in-management>
    <updatenetworkroute position="0" rule="dest-address type=c7,ri=pcssn,ssn=146"/>
</sis-in-management>

or if the destination is the domain domain internal.home1.net

<sis-sip-management>
    <updatenetworkroute position="0" rule="domain internal.home1.net" interface="sis-internal"/>
</sis-sip-management>

MBean operations

MBean

Network Route

getRule

Operation

To get the network route rule:

public String getRule()
    throws ManagementException;

setRule

Operation

To set the network route rule:

public void setRule(String rule)
    throws NullPointerException, InvalidStateException,
           InvalidArgumentException, AlreadyDeployedException,
           ManagementException;

getInterfaceName

Operation

To get the name of the network interface used by the route:

public String getInterfaceName(()
    throws ManagementException;

setInterfaceName

Operation

To set the name of the network interface used by the route:

public void setInterfaceName(String interfaceName)
    throws NullPointerException, UnrecognizedComponentException,
           InvalidStateException, AlreadyDeployedException,
           ManagementException;

Reordering Network Routes

To reposition a network route, use the following sis-console command, Ant task, or related MBean operations.

Console command

repositionnetworkroute

Command

 
repositionnetworkroute <ra-entity> <old-position> <new-position>
    Move an existing network route in the SIS from one position to another

Example

To move the network route from position 3 to position 1 in the SIS instance named sis:

$ ./sis-console repositionnetworkroute sis 3 1
Network route repositioned

Ant task

updatenetworkroute

Task

 
<updatenetworkroute position="..." newPosition="..."/>

Example

To move a network route from position 3 to position 1:

<sis-in-management>
    <updatenetworkroute position="3" newPosition="1"/>
</sis-in-management>

or

<sis-sip-management>
    <updatenetworkroute position="3" newPosition="1"/>
</sis-sip-management>

MBean operations

MBean

Network Route

getPosition

Operation

To get the network route position:

public int getPosition()
    throws ManagementException;

reposition

Operation

To move the network route to a new position:

public void reposition(int newPosition)
    throws ManagementException;

Managing Trigger Address Tracing

The Trigger Address Tracing Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

Note
Managing debug logging levels for trigger addresses

You can enable debug tracing for selected calls using trigger address tracing. For example, to enable debug logging for a particular MSISDN:

  1. Make sure the address selectors include the initial request signaling parameter where you expect the MSISDN to appear (for example, Calling Party Number or Called Party Number).

  2. Set the debug level for the MSISDN trigger address as appropriate.
Tip The effect of trigger address tracing is the same as assigning a fine-grained tracing level to an address subscription, but trigger address tracing is more flexible in that many more different signaling parameters are available to trigger debug logging, and a subscription does not have to be selected in order to enable the debug logging.
sis-console command(s) MBean(s) → Operation

Procedure: Get and set the name of the profile table used to store trigger address tracing information

 
 getTriggerAddressTracingProfileTableName
setTriggerAddressTracingProfileTableName
 
 Trigger Address Tracing Management &rarr; getTriggerAddressTracingProfileTableName
Trigger Address Tracing Management &rarr; setTriggerAddressTracingProfileTableName

Procedure: Get and set address selectors

 
 getTriggerAddressTracingSelectors
setTriggerAddressTracingSelectors
 
 Trigger Address Tracing Management &rarr; getSelectors
Trigger Address Tracing Management &rarr; setSelectors

Procedure: Get and set the debug level for a trigger address

 
 getTriggerAddressDebugLevel
setTriggerAddressDebugLevel
 
 Trigger Address Tracing Management &rarr; getDebugLevel
Trigger Address Tracing Management &rarr; setDebugLevel

Procedure: Get and set the audit logging for a trigger address

 
 getTriggerAddressAuditLogging
setTriggerAddressAuditLogging
 
 Trigger Address Tracing Management &rarr; isAuditLoggingEnabled
Trigger Address Tracing Management &rarr; setAuditLoggingEnabled

Getting and Setting Trigger Address Tracing Profile Table Names

To get or set the trigger address tracing profile table name, use the following sis-console commands or related MBean operations.

Console commands

getTriggerAddressTracingProfileTableName

Command

 
gettriggeraddresstracingprofiletablename <ra-entity>
    Get the current configured trigger address tracing profile table name

Example

To get the trigger address tracing profile table name for the SIS instance named sis:

$ ./sis-console gettriggeraddresstracingprofiletablename sis
Trigger address tracing profile table name=sis-trigger-address-tracing

setTriggerAddressTracingProfileTableName

Command

 
settriggeraddresstracingprofiletablename <ra-entity> <table-name>
    Set the configured trigger address tracing profile table name. To remove the
    table name, specify 'null' as the argument

Example

To set the trigger address tracing profile table name for the SIS instance named sis to sis-trigger-address-tracing:

$ ./sis-console settriggeraddresstracingprofiletablename sis sis-trigger-address-tracing

MBean operations

MBean

Trigger Address Tracing Management

getTriggerAddressTracingProfileTableName

Operation

 
public String getTriggerAddressTracingProfileTableName()
    throws ManagementException;

setTriggerAddressTracingProfileTableName

Operation

 
public void setTriggerAddressTracingProfileTableName(String tableName)
    throws ManagementException;

Getting and Setting Address Selectors

To get or set the address selectors for trigger address tracing, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

SIP

getTriggerAddressTracingSelectors

Command

 
gettriggeraddresstracingselectors <ra-entity> <trigger-type>
    Get the current configured initial event parameters selected for trigger address
    tracing examination.  The trigger type is either 'originating' or 'terminating'

Example

To get the trigger address tracing selectors for originating triggers for the SIS instance named sis:

$ ./sis-console gettriggeraddresstracingselectors sis originating
The following selectors are currently configured: [CallingPartyNumber]
setTriggerAddressTracingSelectors

Command

 
settriggeraddresstracingselectors <ra-entity> <trigger-type> <selectors>
    Set the initial event parameters selected for trigger address tracing
    examination.  The trigger type is either 'originating', 'terminating', or
    'third_party'.  The selectors are a comma-separated list from the following
    possibilities: [Request-URI, From, To, P-Asserted-Identity, P-Called-Party-ID,
    P-Served-User]

Example

To set the trigger address tracing selectors for originating triggers for the SIS instance named sis to include both the From and P-Called-Party-ID:

$ ./sis-console settriggeraddresstracingselectors sis originating From,P-Called-Party-ID
The following selectors have now been configured: [From, P-Called-Party-ID]

To remove all existing selectors for terminating triggers for the SIS instance named sis:

$ ./sis-console settriggeraddresstracingselectors sis terminating ""
The following selectors have now been configured: []

IN

getTriggerAddressTracingSelectors

Command

 
gettriggeraddresstracingselectors <ra-entity> <trigger-type>
    Get the current configured initial event parameters selected for trigger address
    tracing examination.  The trigger type is either 'originating', 'terminating',
    or 'third_party'

Example

To get the trigger address tracing selectors for originating triggers for the SIS instance named sis:

$ ./sis-console gettriggeraddresstracingselectors sis originating
The following selectors are currently configured: [CallingPartyNumber]
setTriggerAddressTracingSelectors

Command

 
settriggeraddresstracingselectors <ra-entity> <trigger-type> <selectors>
    Set the initial event parameters selected for trigger address tracing
    examination.  The trigger type is either 'originating', 'terminating', or
    'third_party'.  The selectors are a comma-separated list from the following
    possibilities: [CallingPartyNumber, CalledPartyNumber, CalledPartyBCDNumber,
    RedirectingPartyID, LocationNumber, OriginalCalledPartyID,
    AdditionalCallingPartyNumber, DestinationSubscriberNumber, SmscAddress]

Example

To set the trigger address tracing selectors for originating triggers for the SIS instance named sis to include both the CalledPartyNumber and RedirectingPartyID:

$ ./sis-console settriggeraddresstracingselectors sis originating CallingPartyNumber,RedirectingPartyID
The following selectors have now been configured: [CallingPartyNumber, RedirectingPartyID]

To remove all existing selectors for terminating triggers for the SIS instance named sis:

$ ./sis-console settriggeraddresstracingselectors sis terminating ""
The following selectors have now been configured: []

Ant task

SIP

settriggeraddresstracingselectors

Task

 
<settriggeraddresstracingselectors triggertype="...">
    <selector name="..."/>
    ...
</settriggeraddresstracingselectors>

Example

 
<sis-sip-management>
    <settriggeraddresstracingselectors triggertype="originating">
        <selector name="From"/>
        <selector name="P-Called-Party-ID"/>
    </settriggeraddresstracingselectors>
</sis-sip-management>

IN

settriggeraddresstracingselectors

Task

 
<settriggeraddresstracingselectors triggertype="...">
    <selector name="..."/>
    ...
</settriggeraddresstracingselectors>

Example

 
<sis-in-management>
    <settriggeraddresstracingselectors triggertype="originating">
        <selector name="CalledPartyNumber"/>
        <selector name="RedirectingPartyID"/>
    </settriggeraddresstracingselectors>
</sis-in-management>

MBean operations

SIP

MBean

SIP Trigger Address Tracing Management
getSelectors

Operation

 
public SipTriggerAddressTracingSelector[] getSelectors(TriggerType triggerType)
    throws NullPointerException, ManagementException;
setSelectors

Operation

 
public void setSelectors(TriggerType triggerType, SipTriggerAddressTracingSelector[] selectors)
    throws NullPointerException, ManagementException;

IN

MBean

IN Trigger Address Tracing Management
getSelectors

Operation

 
public INTriggerAddressTracingSelector[] getSelectors(TriggerType triggerType)
    throws NullPointerException, ManagementException;
setSelectors

Operation

 
public void setSelectors(TriggerType triggerType, INTriggerAddressTracingSelector[] selectors)
    throws NullPointerException, ManagementException;

Getting and Setting Trigger Address Debug Level

To get or set the debug level associated with a trigger address, use the following sis-console commands, Ant task, or related MBean operations.

Console command

getTriggerAddressDebugLevel

Command

 
gettriggeraddressdebuglevel <ra-entity> <address>
    Get current fine-grained tracing debug level for a trigger address

Example

To get the debug level for address 34607000123 in the SIS instance named sis:

$ ./sis-console gettriggeraddressdebuglevel sis 34607000123
Debug level for address 34607000123=0

setTriggerAddressDebugLevel

Command

 
settriggeraddressdebuglevel <ra-entity> <address> <debugLevel>
    Set fine-grained tracing debug level for a trigger address

Example

To set the debug level to 2 for address 34607000123 in the SIS instance named sis:

$ ./sis-console settriggeraddressdebuglevel sis 34607000123 2
Debug level for address 34607000123 set to 2

Ant task

setTriggerAddressDebugLevel

Task

 
<settriggeraddressdebuglevel address="..." debuglevel="..."/>

Example

 
<sis-in-management>
    <settriggeraddressdebuglevel address="34607000123" debuglevel="2"/>
</sis-in-management>

or

<sis-sip-management>
    <settriggeraddressdebuglevel address="34607000123" debuglevel="2"/>
</sis-sip-management>

MBean operations

MBean

Trigger Address Tracing Management

getDebugLevel

Operation

 
public int getDebugLevel(String address)
    throws NullPointerException, ManagementException;

setDebugLevel

Operation

 
public void setDebugLevel(String address, int debugLevel)
    throws NullPointerException, IllegalArgumentException, ManagementException;

Getting and Setting Trigger Address Audit Logging

To get or set audit logging for a trigger address, use the following sis-console commands, Ant task, or related MBean operations.

Console commands

getTriggerAddressAuditLogging

Command

 
gettriggeraddressauditlogging <ra-entity> <address>
    Determine if audit logging is enabled for a trigger address

Example

To determine if audit logging is enabled for trigger address 34607000123 in the SIS instance named sis:

$ ./sis-console gettriggeraddressauditlogging sis 34607000123
Audit logging for address 34607000123 is disabled

setTriggerAddressAuditLogging

Command

 
settriggeraddressauditlogging <ra-entity> <address> <boolean>
    Enable/disable audit logging for a trigger address

Example

To enable audit logging for trigger address 34607000123 in the SIS instance named sis:

$ ./sis-console settriggeraddressauditlogging sis 34607000123 true
Audit logging for address 34607000123 enabled

Ant task

setTriggerAddressAuditLogging

Task

 
<settriggeraddressauditlogging address="..." audit="..."/>

Example

 
<sis-in-management>
    <settriggeraddressauditlogging address="34607000123" audit="true"/>
</sis-in-management>

or

<sis-sip-management>
    <settriggeraddressauditlogging address="34607000123" audit="true"/>
</sis-sip-management>

MBean operations

MBean

Trigger Address Tracing Management

isAuditLoggingEnabled

Operation

 
public boolean isAuditLoggingEnabled(String address)
    throws NullPointerException, ManagementException;

setAuditLoggingEnabled

Operation

 
public void setAuditLoggingEnabled(String address, boolean enabled)
    throws NullPointerException, ManagementException;

Assigning Fine-Grained Tracing

The SIS lets you assign fine-grained tracing debug levels to components and subscriptions.

This means you do not need to enable debug logging for all calls that pass through the SIS — which can can significantly degrade performance — when you’re only interested in calls to (or with reference to) particular addresses or calls that trigger certain compositions.

Below are an overview of SIS trace debug levels, instructions for enabling fine-grained tracing, and an example.

Trace debug levels

The SIS currently supports the following trace debug levels:

Level Description

0

No debugging information output.

1

Trace messages output, summarising the flow of messages between the network, SIS and the SLEE.

2

Same as level 1, plus expanded detail of the contents of each message.

3

Same as level 2, plus all internal debugging of the SIS and its decision-making progress. (This is the most verbose debug level and produces a great deal of output.)

Component settings

You can assign fine-grained tracing debug levels to individual compositions, address subscriptions, service key subscriptions, and trigger addresses.

Tip
Initial settings, changes, and default

  • You can specify initial fine-grained trace level settings, that apply when a composition is installed or when a subscription is created.

  • Changes to component fine-grained trace level settings can be made at any time, and take immediate effect (if fine-grained tracing has been enabled).

  • The default component fine-grained trace level, if unspecified, is 0.
Warning
Changes only apply to new calls

The SIS determines the debug level for the lifetime of a call during composition selection. Any changes to debug levels in profiles, or enabling fine-grained tracing, apply only to new calls (those subsequently triggered in the SIS).

Fine-grained tracing

To use the SIS fine-grained tracing features:

  1. Enable fine-grained tracing in the SIS — required for the SIS to check any other fine-grained tracing settings.

  2. Reload the SIS configuration, for the configuration change to take effect.

  3. Configure fine-grained tracing debug levels for compositions, subscriptions, or trigger addresses in the SIS as required.

Example

Below are sis-console commands and Rhino log output for an example of assigning fine-grained tracing.

sis-console commands

[Rhino@localhost (#1)] setfinegrainedtracingenabled sis-cap true
Fine-grained tracing enabled

[Rhino@localhost (#2)] reload sis-cap
Reloaded SIS RA Entity sis-cap

[Rhino@localhost (#3)] updateaddresssubscription sis-cap 3460001234 -debuglevel 3
Updated subscription 34600001234

Rhino log output

2009-10-14 15:27:51.843  Info   [trace.sis_cap.insis.trigger-handler]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  dialog debugging triggered for Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0] at debug level 3 due to a subscription profile
2009-10-14 15:27:51.844  Info   [trace.sis_cap.insis-trace.flow]    Cap 0  NW   ---------O_InitialDP clg=600001234 cld=610031274---------> INSIS
2009-10-14 15:27:51.902  Info   [trace.sis_cap.insis-trace.detail]    Cap 0   NW -> INSIS(event:InitialDP)
    InitialDP[
        dialog=Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]
        invokeID=0
        serviceKey=50
        ...
        ]
2009-10-14 15:27:51.903  Info   [trace.sis_cap.insis.trigger-handler]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  accepting open request
2009-10-14 15:27:51.948  Info   [trace.sis_cap.insis-trace.flow]    Cap 0  NW   <-----------------OpenResponse[accepted]------------------ INSIS
2009-10-14 15:27:51.948  Info   [trace.sis_cap.insis-trace.detail]    Cap 0   NW <- INSIS(event:OpenRequest)
    OpenResponse[
        accepted?=true
        appContext=CAPv2:gsmSSF->gsmSCF
        ]
2009-10-14 15:27:51.949  Info   [trace.sis_cap.insis.trigger-handler]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  setState(SERVICE_COMPOSITION_DISCOVERY -> MONITORING)
2009-10-14 15:27:53.076  Info   [trace.sis_cap.insis.virtual-ssf]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  setFlags(INITIAL: [] -> [BUSY_INPUT])
2009-10-14 15:27:53.154  Info   [trace.sis_cap.insis.virtual-ssf]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  beginning event processing of: [OpenRequest, InitialDP, Delimiter]
2009-10-14 15:27:53.154  Info   [trace.sis_cap.insis.virtual-ssf]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  setState(INITIAL -> SERVICE_COMPOSITION_EVALUATION: [BUSY_INPUT])
2009-10-14 15:27:53.173  Info   [trace.sis_cap.insis.model]   [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  current call leg state: [1:{COLLECTED_INFO:[]}]
2009-10-14 15:27:53.216  Info   [trace.sis_cap.insis.virtual-ssf]   [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  service composition says to invoke ServiceRefID[VPN]
2009-10-14 15:27:53.235  Info   [trace.sis_cap.insis.virtual-ssf]   [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=4212,incarnationID=0]]  entering event processing loop for event(s): [OpenRequest, InitialDP, Delimiter]
...

Enabling Call Traffic Audit Logging

The call audit logging feature provides a summary of SIS decisions during a call, such as the trigger and composition selected and services invoked. Below is an overview of SIS audit levels, information collected by the audit, instructions for using audit logging, and some examples.

Audit logging levels

The SIS currently supports the following audit levels:

Level Information logged 
 ALL

every call received from the network

 
 COMPONENT

selected components only

 
 NONE

(no information)

Component settings

You can enable auditing for individual compositions, address subscriptions, service key descriptions, and trigger addresses.

Tip
Initial settings, changes, and default

  • You can specify initial audit settings, that apply when a composition is installed or when a subscription is created.

  • Changes to component audit settings can be made at any time, and take immediate effect.

  • The default component audit setting, if unspecified, is disabled.
Warning
Changes only apply to new calls

The SIS determines the audit level for the lifetime of a call during initial request processing. Any changes to audit settings apply only to new calls (those subsequently triggered in the SIS).

Collected information

An individual call audit log contains the network dialog identifier, parameters of the initial request, and any of the following optional information, depending on call processing:

Information Log details

if initial processing aborted

for example, due to insufficient license capacity or the initial request missing a required parameter

Outcome of trigger processing

subscription profile located

search key and name of profile

trigger matched and successfully found a composition

trigger’s component identifier

composition selected

composition’s component identifier

trigger matched and its failure clause invoked

trigger’s component identifier

no triggers matched

Outcome of composition evaluation

entry and exit from the script input and output interceptors (if present)

the name of the service reference of a composition service that becomes eligible for invocation

entry and exit from composition service input and output interceptors (if present)

the name of the extension reference of an extension component that is invoked by an interceptor

if the composition service invocation failed

reason for failure (for example, service response timeout, local service not active)

if the extension component invocation failed

reason for failure (for example, service response timeout)

if IN FurnishChargingInformation data from a composition service is discarded after initial acceptance due to the interaction policy in force

the name of the service reference for the service that generated the discarded FCI data

composition completed normally

composition halted by a script or service instruction
Tip
Initial request processing only

The audit log only reports on initial request processing — the decisions made during trigger processing and composition evaluation. It does not include any information about processing of events later in the call.

Using audit logging

To use the SIS audit logging features:

  1. Enable audit logging in the SIS. WARNING: This is required for the SIS to check any other audit logging settings.

  2. Reload the SIS configuration, for the configuration change to take effect.

  3. If the COMPONENT audit level is selected, configure audit settings for compositions or other entities in the SIS (such as subscriptions).

The SIS outputs one audit record log message:

  • for each call for which audit logging is enabled (either explicitly or implicitly)

  • using the SLEE Tracer named "audit", for the SIS instance at the Info trace level

  • to the Rhino console log (by default) using the log key trace.<SIS instance name>.audit.

You can capture audit records several ways, including: by registering a trace notification listener with the SLEE to capture the audit trace messages from the SIS, or by creating a Rhino logging configuration that channels the audit log messages to a separate log file.

Examples

Trigger failure 
2009-10-14 16:52:29.397  Info    [trace.sis_cap.insis.audit]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=91,incarnationID=0]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...610001234...eventType=(o) collected info...calledPartyBCDNumber=...610031097...]
    TriggerID[name=O-Trigger Handling,vendor=OpenCloud,version=1.0] failed (Fail[UserError[reason=missing-customer-record],dialog-termination=user-abort])
Basic composition with multiple services 
2009-10-14 16:56:03.916  Info    [trace.sis_cap.insis.audit]  [Dialog[appContext=CAPv2:gsmSSF->gsmSCF,appID=6617,dialogID=103,incarnationID=0]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...610051593...eventType=(o) collected info...calledPartyBCDNumber=...610072502...]
    address 34610051593 matched subscription 34610051593
    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
Composition with interceptors 
2009-10-14 17:05:23.110  Info    [trace.sis_inap.insis.audit]  [Dialog[appContext=INAP-CS1:SSP->SCP,appID=2868,dialogID=1,incarnationID=0]]:
    trigger event: InitialDP[dialog=...serviceKey=50,callingPartyNumber=...6109000003...calledPartyNumber=8000048...eventType=(o) collected info...]
    service key 50 matched subscription 50
    matched TriggerID[name=O-Trigger Handling,vendor=OpenCloud,version=1.0]
    selected CompositionID[name=07020106,vendor=OpenCloud,version=1.0]
    invoking service Home Zone
    evaluating service-input-interceptor
    invoking extension component ext-service1
    service-input-interceptor complete; invoking service
    evaluating service-output-interceptor
    service-output-interceptor complete
    invoking service VPN
    invoking service Call Duration Logging
    composition completed

Managing Experimental Features

The SIS may offer a number of experimental features — features which are either incomplete or have not had sufficient testing to be considered production quality.

Warning Experimental features are disabled by default.

The Experimental Feature Management MBeans for SIP and IN include operations for performing the following procedures on a SIS instance:

sis-console command(s) MBean(s) → Operation

Procedure: Listing supported experimental features

 
 listexperimentalfeaturessupported
 
 Experimental Feature Management &rarr; getSupportedExperimentalFeatures

Procedure: Enable an experimental feature

 
 enableexperimentalfeature
 
 Experimental Feature Management &rarr; enableExperimentalFeature

Procedure: Disable an experimental feature

 
 disableexperimentalfeature
 
 Experimental Feature Management &rarr; disableExperimentalFeature

Procedure: View experimental feature status

 
 listexperimentalfeaturesenabled
getexperimentalfeaturestatus
 
 Experimental Feature Management &rarr; getEnabledExperimentalFeatures
Experimental Feature Management &rarr; isExperimentalFeatureEnabled

Supported Experimental Features

Warning SIS 3.2 provides no experimental features. (Stay tuned for future releases!)

Listing Supported Experimental Features

To list supported experimental features, use the following sis-console command or related MBean operation.

Console command

listexperimentalfeaturessupported

Command

 
listexperimentalfeaturessupported <ra-entity>
    Display all experimental features supported by the SIS
Note This command lists the names of all experimental features supported by the SIS.

Example

 
$ ./sis-console listexperimentalfeaturessupported sis
No experimental features are supported by this SIS instance

MBean operation

MBean

Experimental Feature Management

getSupportedExperimentalFeatures

Operation

 
public String[] getSupportedExperimentalFeatures()
    throws ManagementException;
Note This operation returns the names of all experimental features supported by the SIS.

Enabling Experimental Features

To enable an experimental feature, use the following sis-console command, Ant task, or related MBean operation.

Console command

enableexperimentalfeature

Command

 
enableexperimentalfeature <ra-entity> <feature>
    Enable an experimental feature in the SIS

Example

To enable the experimental feature named rebranching in the SIS instance named sis:

$ ./sis-console enableexperimentalfeature sis rebranching
Enabled experimental feature rebranching

Ant task

enableexperimentalfeature

Task

 
<enableexperimentalfeature name="..."/>

Example

To enable the experimental feature named rebranching:

<sis-in-management>
    <enableexperimentalfeature name="rebranching"/>
</sis-in-management>

or

<sis-sip-management>
    <enableexperimentalfeature name="rebranching"/>
</sis-sip-management>

MBean operation

MBean

Experimental Feature Management

enableExperimentalFeature

Operation

To enable an experimental feature:

public void enableExperimentalFeature(String feature)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Disabling Experimental Features

To disable an experimental feature, use the following sis-console command, Ant task, or related MBean operation.

Console command

disableexperimentalfeature

Command

 
disableexperimentalfeature <ra-entity> <feature>
    Disable an experimental feature in the SIS

Example

To disable the experimental feature named rebranching in the SIS instance named sis:

$ ./sis-console disableexperimentalfeature sis rebranching
Disabled experimental feature rebranching

Ant task

disableexperimentalfeature

Task

 
<disableexperimentalfeature name="..."/>

Example

To disable the experimental feature named rebranching:

<sis-in-management>
    <disableexperimentalfeature name="rebranching"/>
</sis-in-management>

or

<sis-sip-management>
    <disableexperimentalfeature name="rebranching"/>
</sis-sip-management>

MBean operation

MBean

Experimental Feature Management

disableExperimentalFeature

Operation

To disable an experimental feature:

public void disableExperimentalFeature(String feature)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;

Viewing Experimental Features

To list or display experimental feature status, use the following sis-console commands or related MBean operations.

Console commands

listexperimentalfeaturesenabled

Command

 
listexperimentalfeaturesenabled <ra-entity>
    Display all experimental features currently enabled in the SIS
Note This command lists the names of all experimental features currently enabled in the SIS.

Example

 
$ ./sis-console listexperimentalfeaturesenabled sis
Enabled experimental features: rebranching

getexperimentalfeaturestatus

Command

 
getexperimentalfeaturestatus <ra-entity> <feature>
    Display the current status of an experimental feature in the SIS
Note This command displays the status of the experimental feature in the SIS (whether or not it is enabled).

Examples

 
$ ./sis-console getexperimentalfeaturestatus sis rebranching
Experimental feature rebranching is currently enabled

MBean operations

MBean

Experimental Feature Management

getEnabledExperimentalFeatures

Operation

 
public String[] getEnabledExperimentalFeatures()
    throws ManagementException;
Note This operation returns the names of all experimental features enabled in the SIS.

isExperimentalFeatureEnabled

Operation

 
public boolean isExperimentalFeatureEnabled(String feature)
    throws NullPointerException, UnrecognizedComponentException,
           ManagementException;
Note This operation returns true if the specified experimental feature is currently enabled in the SIS.

Installing SIS Modules

A SIS module is an optional feature that you can add to your SIS installation. It comes as a zip archive that you extract over the top of the SIS installation directory.

Note
Modules available with this SIS release

  • IM-SSF Module (SIP to IN Protocol Translation)

  • R-IM-SSF Module (IN to SIP Protocol Translation)

What is in a SIS module?

A SIS module typically includes:

  • a command-line extension library, which adds management commands to sis-console

  • an install directory, which contains deployable units, configuration files and an installer application.

Module directory structure

SIS module zip archives must be extracted from the SIS home. Each zip archive has the following structure:

File or directory Description 
 admin/remove-<module-name>-<module-version>.script

a script to run from the command-line console that will remove the module

 
 admin/lib/extensions/

command-line console extension library

 
 modules/<module-name>/<module-version>/install/

the install directory

 
 modules/<module-name>/<module-version>/install/CHANGELOG

the change log

 
 modules/<module-name>/<module-version>/install/install-module.sh

a shell script that runs the installer application

 
 modules/<module-name>/<module-version>/install/units

all the deployable units

plus any other files and directories that the module install requires

Installing a module

To install a SIS module:

  1. Install the SIS if it hasn’t already been installed.

  2. Unzip the module archive from the SIS home (<rhino-home>/sis/<protocol>/<sis-version>/).

  3. Change into the module install directory (<rhino-home>/sis/<protocol>/<sis-version>/modules/<module-name>/<module-version>/install).

  4. Run module-install.sh (and answer the install questions).

Warning

The module install process also:

  • may include an option to install a license, unless that module’s functions are already covered by the overall SIS license.

  • tries to activate the module, after checking that the required functions are licensed.

Appendixes

This document includes the following appendixes:

Alarms

The SIS may raise any of the following alarms. Below are tables of their messages, types, instance IDs, levels, what raises and clears them, and examples.

Note Removing a SIS instance from the SLEE automatically clears any alarms on it.

misconfigured/disabled

Alarm Message

The SIS is misconfigured, operational functionality disabled

Type

 
 misconfiguration

Instance ID

 
 SIS

Level

 
 CRITICAL

Raised if…​

…​the SIS instance is created with invalid basic configuration information. For example, the specified configuration profile does not exist, or the profile tables named in the configuration profile do not exist.

Cleared if…​

…​the configuration errors are resolved, and the new configuration information is successfully loaded.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946943:0 [RAEntityNotification[entity=sis],misconfiguration,SIS] was raised at 2011-09-30 12:30:01.000 to level Critical
        SIS is misconfigured, operational functionality disabled

misconfigured/continuing

Alarm Message

The SIS is misconfigured, continuing operational functionality based on most recent valid configuration

Type

 
 misconfiguration

Instance ID

 
 SIS

Level

 
 MINOR

Raised if…​

…​the user has changed the SIS resource adaptor entity configuration properties, or has requested the SIS reload its configuration information, and that configuration information is invalid. For example, the specified configuration profile does not exist, or the profile tables named in the configuration profile do not exist.

Cleared if…​

…​the configuration errors are resolved, and the new configuration information is successfully loaded.

Example

 
2011-09-30 12:30:01.000  Minor   [rhino.facility.alarm.manager]  Alarm 101:153983946943:1 [RAEntityNotification[entity=sis],misconfiguration,SIS] was raised at 2011-09-30 12:30:01.000 to level Minor
        SIS is misconfigured, continuing operational functionality based on most recent valid configuration

misconfigured/protocol

Alarm Message

Unable to load network adaptor protocol

Type

 
 misconfiguration

Instance ID

 
 protocol._name_

Level

 
 CRITICAL

Raised if…​

…​the SIS cannot load and initialise an enabled protocol. This typically indicates a build-time packaging problem, which should be reported to Metaswitch.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946950:1 [RAEntityNotification[entity=sis],misconfiguration,protocol.cap_v2] was raised at 2011-09-30 12:30:01.000 to level Critical
        Unable to load network adaptor protocol

misconfigured/network interface

Alarm Message

Failed to create network interface name

Type

 
 misconfiguration

Instance ID

 
 network-interface._name_

Level

 
 MAJOR

Raised if…​

…​a CGIN network interface could not be created, probably due to a misconfiguration.

Cleared if…​

…​the configuration errors are resolved, and the network interface can be created successfully.

Example

 
2011-09-30 12:30:01.000  Major   [rhino.facility.alarm.manager]  Alarm 101:153983946951:1 [RAEntityNotification[entity=sis],misconfiguration,network-interface.default] was raised at 2011-09-30 12:30:01.000 to level Major
        Failed to create network interface default

misconfigured/network interfaces

Alarm Message

No network interfaces are enabled

Type

 
 misconfiguration

Instance ID

 
 network-interfaces

Level

 
 CRITICAL

Raised if…​

…​the SIS instance is activated when no network interfaces have been enabled.

Cleared if…​

…​the SIS instance is deactivated.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946945:1 [RAEntityNotification[entity=sis],misconfiguration,network-interfaces] was raised at 2011-09-30 12:30:01.000 to level Critical
        No network interfaces are enabled

misconfigured/routes

Alarm Message

No network routes are defined

Type

 
 misconfiguration

Instance ID

 
 network-routes

Level

 
 CRITICAL

Raised if…​

…​no network routes have been configured.

Cleared if…​

…​at least one network route is configured.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946944:1 [RAEntityNotification[entity=sis],misconfiguration,network-routes] was raised at 2011-09-30 12:30:01.000 to level Critical
        No network routes are defined

misconfigured/default route

Alarm Message

No default route configured

Type

 
 misconfiguration

Instance ID

 
 network-routes

Level

 
 WARNING

Raised if…​

…​more than one network interface is enabled, and no default network route has been configured.

Cleared if…​

…​a default route is configured, or all but one enabled network interface are disabled.

Example

 
2011-09-30 12:30:01.000  Warning [rhino.facility.alarm.manager]  Alarm 101:153983946944:1 [RAEntityNotification[entity=sis],misconfiguration,network-routes] was raised at 2011-09-30 12:30:01.000 to level Warning
        No default route configured

activation/network interface

Alarm Message

Failed to activate network interface name

Type

 
 activation-failed

Instance ID

 
 network-interface._name_

Level

 
 CRITICAL

Raised if…​

…​a CGIN network interface could not be activated, probably due to a misconfiguration.

Cleared if…​

…​the configuration errors are resolved, and the network interface can be activated successfully.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946943:3 [RAEntityNotification[entity=sis],activation-failed,network-interface.default] was raised at 2011-09-30 12:30:01.000 to level Critical
        Failed to activate network interface default

activation/SIP

Alarm Message

Failed to start SIP stack

Type

 
 activation-failed

Instance ID

 
 network-adaptor

Level

 
 CRITICAL

Raised if…​

…​the SIP stack could not be started, probably due to a misconfiguration.

Cleared if…​

…​the configuration errors are resolved, and the stack can be started successfully.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946943:3 [RAEntityNotification[entity=sis],activation-failed,network-adaptor] was raised at 2011-09-30 12:30:01.000 to level Critical
        Failed to start SIP stack

licensing/consumption mode

Alarm Message

No consumption mode license installed — all incoming dialogs will being rejected

Type

 
 licensing

Instance ID

 
 consumption-mode

Level

 
 CRITICAL

Raised if…​

…​a SIS-IN instance is activated, or a dialog is received from the network while already active, without a valid consumption mode license being available.

Cleared if…​

…​the SIS-IN instance is deactivated, or a dialog is received from the network and a valid consumption mode license is subsequently found.

Example

 
2011-09-30 12:30:01.000  Critical [rhino.facility.alarm.manager]  Alarm 101:153983946947:1 [RAEntityNotification[entity=sis],licensing,consumption-mode] was raised at 2011-09-30 12:30:01.000 to level Critical
        No consumption mode license installed - all incoming dialogs will being rejected

licensing/call class

Alarm Message

No valid license providing the function-name function is installed — call-class-name dialogs will be rejected

Type

 
 licensing

Instance ID

 
 call-class.voice or call-class.sms

Level

 
 MAJOR

Raised if…​

…​a dialog is received from the network by a SIS-IN instance without a valid corresponding enabler license being available.

Cleared if…​

…​the SIS-IN instance is deactivated, or a dialog of the same call class is received from the network and a valid corresponding enabler license is subsequently found.

Example

 
2011-09-30 12:30:01.000  Major [rhino.facility.alarm.manager]  Alarm 101:153983946947:2 [RAEntityNotification[entity=sis],licensing,call-class.voice] was raised at 2011-09-30 12:30:01.000 to level Major
        No valid license providing the Rhino-SIS-IN-Voice function is installed - voice dialogs will be rejected

licensing/service class

Alarm Message

No valid license providing the function-name function is installed — service-class-name services cannot be invoked

Type

 
 licensing

Instance ID

 
 service.local or service.external

Level

 
 MAJOR

Raised if…​

…​a composition attempts to invoke a local or external service, but a corresponding enabler license for that class of service is not available.

Cleared if…​

…​the SIS instance is deactivated, or a composition attempts to invoke the same class of service (local or external) and a valid corresponding enabler license is subsequently found.

Example

 
2011-09-30 12:30:01.000  Major [rhino.facility.alarm.manager]  Alarm 101:153983946947:3 [RAEntityNotification[entity=sis],licensing,service.external] was raised at 2011-09-30 12:30:01.000 to level Major
        No valid license providing the Rhino-SIS-SIP-External-Service function is installed - external services cannot be invoked

SIS reconfigured

Alarm Message

Configuration changes made to the property-name property will not take effect until the SIS is deactivated and reactivated

Type

 
 active-reconfiguration

Instance ID

 
 SIS

Level

 
 WARNING

Raised if…​

…​SIS resource adaptor entity configuration properties that do not support active reconfiguration have been changed (see Reconfiguring a SIS Instance). The SIS instance must be deactivated and reactivated for changes to configuration properties not supporting active reconfiguration to take effect.

Cleared if…​

…​the SIS instance is deactivated, and when it returns to the INACTIVE state.

Example

 
2011-09-30 12:30:01.000  Warning [rhino.facility.alarm.manager]  Alarm 101:153983946943:4 [RAEntityNotification[entity=sis],active-reconfiguration,SIS] was raised at 2011-09-30 12:30:01.000 to level Warning
        Configuration changes made to the SISWorkerQueueSize property will not take effect until the SIS is deactivated and reactivated

network properties reconfigured

Alarm Message

Configuration changes made to the protocol support, network interfaces, or routing table will not take effect until the SIS is deactivated and reactivated

or

Configuration changes made to network interfaces or routing table will not take effect until the SIS is deactivated and reactivated

Type

 
 active-reconfiguration

Instance ID

 
 network-interfaces

Level

 
 WARNING

Raised if…​

…​SIS resource adaptor entity configuration properties related to enabled protocols, network interface properties for which the SIS does not support active reconfiguration, or the network routing table have been changed while the SIS instance is active (see Reconfiguring a SIS Instance). The SIS instance must be deactivated and reactivated for changes to configuration properties not supporting active reconfiguration to take effect.

Cleared if…​

…​the SIS instance is deactivated, and when it returns to the INACTIVE state.

Example

 
2011-09-30 12:30:01.000  Warning [rhino.facility.alarm.manager]  Alarm 101:153983946945:5 [RAEntityNotification[entity=sis],active-reconfiguration,network-interfaces] was raised at 2011-09-30 12:30:01.000 to level Warning
        Configuration changes made to the protocol support, network interfaces, or routing table will not take effect until the SIS is deactivated and reactivated

can’t connect

Alarm Message

Lost connection to backend host:port

Type

 
 noconnection

Instance ID

 
 _host:port_ of backend

Level

 
 MAJOR

Raised if…​

…​the SIS instance cannot establish a connection to a suitable backend process at the specified host and port address, or if an existing connection is lost at any time.

Cleared if…​

…​a connection to a suitable backend process at the specified host and port address can be (re)established.

Example

 
2011-09-30 12:30:01.000  Major   [rhino.facility.alarm.manager]   Alarm 101:153983946945:6 [RAEntityNotification[entity=sis],noconnection,signalware:10222] was raised at 2011-09-30 12:30:01.000 to level Major
        Lost connection to backend signalware:10222

external address

Alarm Message

Address address in external platform external-platform-name has failed

Type

 
 externalplatform

Instance ID

 
 _external platform name_/_address_

Level

 
 MINOR

Raised if…​

…​an external address of an external platform has failed.

Cleared if…​

…​the external address is detected to have recovered.

Example

 
2011-09-30 12:30:01.000  Minor [rhino.facility.alarm.manager]   Alarm 101:153983946945:7 [RAEntityNotification[entity=sis],externalplatform,VPN/SccpAddress[type=c7,ri=pcssn,pc=2,ssn=166]] was raised at 2011-09-30 12:30:01.000 to level Minor
        Address SccpAddress[type=c7,ri=pcssn,pc=2,ssn=166] in external platform VPN has failed

external addresses

Alarm Message

ALL addresses in external platform external-platform-name have failed

Type

 
 externalplatform

Instance ID

 
 _external platform name_

Level

 
 MAJOR

Raised if…​

…​all external addresses of an external platform have failed.

Cleared if…​

…​at least one external address of the external platform is detected to have recovered.

Example

 
2011-09-30 12:30:01.000  Major [rhino.facility.alarm.manager]   Alarm 101:153983946945:8 [RAEntityNotification[entity=sis],externalplatform,VPN] was raised at 2011-09-30 12:30:01.000 to level Major
        ALL addresses in external platform VPN have failed

audit failed

Alarm Message

Audit failed. To clear this alarm, check SIS configuration and retry audit.

Type

 
 sis.audit

Instance ID

 
 _n/a_

Level

 
 WARNING

Raised if…​

…​an audit failed.

Cleared if…​

…​a subsequent audit passes successfully.

Example

 
2011-09-30 12:30:01.000  Warning [rhino.facility.alarm.manager]   Alarm 101:153983946945:9 [RAEntityNotification[entity=sis],sis.audit,] was raised at 2011-09-30 12:30:01.000 to level Warning
        Audit failed. To clear this alarm, check SIS configuration and retry audit.

Recorded Statistics

The SIS records many statistics, which you can examine to learn about its behaviour and performance (and that of the services it’s running).

These include:

Tip
Using rhino-stats and the Stats Management MBean

You can monitor SIS statistics using:

  • the rhino-stats tool supplied with Rhino (in the client/bin directory of the Rhino installation)

  • Rhino’s Stats Management MBean to monitor statistics programmatically .

General Statistics

All SIS implementations record the following statistics:

SIS Work Queue Statistics

The SIS records the following statistics for the work queue it uses to manage the execution of internal tasks.

Note

The SIS manages work using:

  • work items — single units of work that, when executed, achieve some progression in call processing

  • fibers — ordered lists of zero or more work items awaiting processing; the SIS uses a unique fiber to represent each call that it processes, and allocates fibers to available threads to process their work items as needed.

Total processing threads: threadsTotal

Records the total number of…​

…​processing threads configured for the SIS.

Increments…​

…​if the configured thread count increases.

Decrements…​

…​if the configured thread count decreases.

Default rhino-stats view

gauge

Available processing threads: threadsAvailable

Records the total number of…​

…​SIS processing threads currently not processing any work.

Increments…​

…​whenever a thread becomes available for work.

Decrements…​

…​whenever a thread is allocated work to perform.

Default rhino-stats view

guage

Fibers waiting to be processed: fibersPending

Records the total number of…​

…​fibers that are currently queued awaiting execution of related work by a SIS processing thread.

Increments…​

…​whenever an idle fiber is added to the work queue due to the addition a new work item.

Decrements…​

…​whenever all work items for a fiber are processed and the fiber becomes idle again.

Default rhino-stats view

guage

Total fibers processed: fibersProcessed

Records the total number of…​

…​fibers that have been processed by the SIS .

Note A single fiber may be processed multiple times during a single call as work items are added to it (at different stages during the call).

Increments…​

…​whenever an idle fiber is added to the work queue due to the addition of a new work item.

Decrements…​

…​never.

Default rhino-stats view

delta

Queue overload: busy

Records the total number of…​

…​fibers that have been processed in the originating thread due to the SIS work queue having already reached maximum capacity.

Increments…​

…​whenever a fiber cannot be queued and needs to be processed in the originating thread.

Decrements…​

…​never.

Default rhino-stats view

delta

Work items waiting to be processed: tasksPending

Records the total number of…​

…​work items that are currently awaiting execution by a SIS processing thread.

Increments…​

…​whenever a work item is added to a fiber.

Decrements…​

…​whenever a work item is processed by the SIS.

Default rhino-stats view

guage

Total work items successfully processed: tasksCompleted

Records the total number of…​

…​work items that have been successfully processed by the SIS.

Increments…​

…​whenever a work item is successfully processed.

Decrements…​

…​never.

Default rhino-stats view

delta

Total work items unsuccessfully processed: tasksFailed

Records the total number of…​

…​work items that unexpectedly failed to be processed by the SIS.

Increments…​

…​whenever a work item is fails to be successfully processed.

Decrements…​

…​never.

Default rhino-stats view

delta

Fiber processing latency: fiberLatency

Samples…​

…​time fibers spend queued waiting for processing.

When…​.

From the time the fiber is queued…​ to the time the fiber is dequeued for processing by a thread.

Calculates…​

Fiber processing latency for all fibers processed by the SIS.

Fiber processing time: fiberProcessingTime

Samples…​

…​fiber processing time.

When…​.

From the time a thread starts processing work items on a fiber…​ to the time all work items on the fiber have been processed.

Calculates…​

Fiber processing time for all fibers processed by the SIS.

Work item processing latency: taskLatency

Samples…​

…​time work items spend queued waiting for processing.

When…​.

From the time a work item is added to a fiber…​ to the time a SIS processing thread starts processing the work item.

Calculates…​

Work item processing latency for all work items created by the SIS.

Work item processing time: taskProcessingTime

Samples…​

…​work item processing time.

When…​.

From the time a thread starts processing a work item…​ to the time the thread has finished processing the work item.

Calculates…​

Work item processing time for all work items created by the SIS.

IN-Specific Statistics

SIS for IN also records the following statistics, in addition to the general statistics:

Statistics for Network-Initiated Dialogs

The SIS records the following statistics for conducted dialogs.

Note Conducted dialogs are network-initiated dialogs for which the SIS receives a trigger event, and imposes some orchestration behaviour onto.

Activities

Live activities — liveActivities

Records the total number of…​

…​live conducted dialogs for which the SIS instance has executed one or more services. (Trigger events that do not execute services do not affect this statistic, since the dialog closes immediately after sending a response to the trigger.)

Increments…​

…​whenever the SIS instance receives a trigger event from the network, and determines that it needs to deliver the event to one or more services.

Decrements…​

…​when a conducted dialog terminates.

Default rhino-stats view

gauge

Total activities — totalActivities

Records the total number of…​

…​network-initiated dialogs that the SIS instance has processed.

Increments…​

…​when the SIS receives a TC_BEGIN event from the network.

Decrements…​

…​never.

Default rhino-stats view

delta

Dialogs Accepted

Total dialogs accepted — acceptedDialogs

Records the total number of…​

…​network-initiated dialogs that the SIS has accepted for processing. The value of this statistic should always be equal to the sum of acceptedDialogsZeroLengthComposition + acceptedDialogsNonZeroLengthComposition + terminatedDialogsMissingParameter + terminatedDialogsInvalidParameter + terminatedDialogsUnprovisioned + terminatedDialogsOtherReason + terminatedDialogsContinued + terminatedDialogsReleased + terminatedDialogsConnected + terminatedDialogsRedirected.

Increments…​

…​when a composition is selected by the SIS for a trigger event received from the network.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted for zero-length compositions — acceptedDialogsZeroLengthComposition

Records the total number of…​

…​network-initiated dialogs that the SIS has accepted for processing, for which it selects a service composition without any services to execute. (For this statistic, the SIS does not count an IN redirect prefix in the composition as a service to be executed.)

Increments…​

…​when, for a trigger event from the network, the SIS selects a service composition that needs no services executed.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted for non-zero-length compositions — acceptedDialogsNonZeroLengthComposition

Records the total number of…​

…​network-initiated dialogs that the SIS has accepted for processing, for which it selects a service composition with one or more services to execute. (For this statistic, the SIS does not count a redirect prefix provisioned in the composition as a service to be executed.)

Increments…​

…​when, for a trigger event from the network, the SIS selects a service composition that needs one or more services executed.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated due to a missing parameter — terminatedDialogsMissingParameter

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a User Error response being received during composition selection, indicating that a required trigger event parameter is missing.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated for this reason, without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated due to an invalid parameter — terminatedDialogsInvalidParameter

Records the total number of…​

…​network-initiated dialogs that have been terminated before a composition is selected, due to a User Error response being received during composition selection, indicating that a required trigger event parameter is invalid.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated for this reason, without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated due to missing provisioning information — terminatedDialogsUnprovisioned

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a User Error response being received during composition selection, indicating that a service composition could not be selected using the parameters specified in the initial request.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated for this reason, without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated due to some other reason — terminatedDialogsOtherReason

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a User Error response for a reason other than the termination reasons specified above.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated for some other reason, without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated with a continue — terminatedDialogsContinued

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a continue response for the initial request being received during composition selection.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated with this response without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated with a released — terminatedDialogsReleased

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a release response for the initial request being received during composition selection.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated with this response without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated with a connect — terminatedDialogsConnected

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a connect response for the initial request being received during composition selection.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated with this response without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs accepted but terminated with a redirect — terminatedDialogsRedirected

Records the total number of…​

…​network-initiated dialogs that the SIS has terminated before a composition is selected, due to a redirect response for the initial request being received during composition selection.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated with this response without recording the response as a dialog rejection.

Decrements…​

…​never.

Default rhino-stats view

delta

Dialogs Rejected

Total dialogs rejected — rejectedDialogs

Records the total number of…​

…​network-initiated dialogs whose initial request the SIS has rejected for processing. For this statistic, the SIS counts execution of a failure clause in a trigger, and a Service Composition Selection extension component returning a reject response, as rejection of the dialog. The value of this statistic should always be equal to the sum of rejectedDialogsInvalidApplicationContext + rejectedDialogsMissingParameter + rejectedDialogsInvalidParameter + rejectedDialogsUnprovisioned + rejectedDialogsOtherReason + rejectedDialogsContinued + rejectedDialogsReleased + rejectedDialogsConnected + rejectedDialogsRedirected.

Increments…​

…​when processing of a trigger event received from the network cannot be completed for some reason.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to an invalid application context — rejectedDialogsInvalidApplicationContext

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected for processing, due to an unsupported dialog application context specified in the TC_BEGIN.

Increments…​

…​when the SIS receives a TC_BEGIN with an unsupported (or invalid) application context.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to input rate limiting — rejectedDialogsInputRateLimited

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected for processing, due to input rate limiting

Increments…​

…​when the SIS receives a new dialog request from the network and the current input rate exceeds the configured maximum rate.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to a missing parameter — rejectedDialogsMissingParameter

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a User Error response that a required trigger event parameter is missing.

Increments…​

…​when:

  • The SIS cannot complete processing of a trigger event it receives from the network, because of a missing parameter (for example, an InitialDP request is missing the eventTypeBCSM parameter)

  • a trigger’s failure clause is invoked where:

    • that failure clause indicates a User Error response with a missing parameter reason

    • or the equivalent reject response is returned by a service using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to an invalid parameter — rejectedDialogsInvalidParameter

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a User Error response being received during composition selection, indicating that a required trigger event parameter is invalid.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a User Error response with an invalid parameter reason

  • or the equivalent reject response is returned by a service using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to missing provisioning information — rejectedDialogsUnprovisioned

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a User Error response being received during composition selection, indicating that a service composition could not be selected using the parameters specified in the trigger event.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a User Error response with a missing customer record reason

  • or the equivalent reject response is returned by a service using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected due to some other reason — rejectedDialogsOtherReason

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a User Error response being received during composition selection for a reason other than the rejection reasons specified above.

Increments…​

…​when an extension component using the Service Composition Selection Extension Resource Adaptor Type indicates that composition selection should be terminated with this reject response.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected but continued — rejectedDialogsContinued

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a continue response for the initial request being received during composition selection.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a continue response

  • or the equivalent reject response is returned by an extension component using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected and released — rejectedDialogsReleased

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a release response for the initial request being received during composition selection.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a release response

  • or the equivalent reject response is returned by an extension component using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected but connected — rejectedDialogsConnected

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a connect response for the initial request being received during composition selection.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a connect response

  • or the equivalent reject response is returned by an extension component using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Total dialogs rejected but redirected — rejectedDialogsRedirected

Records the total number of…​

…​network-initiated dialogs that the SIS has rejected before a composition is selected, due to a redirect response for the initial request being received during composition selection.

Increments…​

…​when a trigger’s failure clause is invoked where:

  • that failure clause indicates a redirect response

  • or the equivalent reject response is returned by an extension component using the Service Composition Selection Extension Resource Adaptor Type.

Decrements…​

…​never.

Default rhino-stats view

delta

Triggers

Originating triggers received — originatingTriggersReceived

Records the total number of…​

…​initial requests that the the SIS instance has received, triggered for the originating call party.

Increments…​

…​when the SIS receives an initial request for the originating call party on a network dialog that it has accepted for processing.

Decrements…​

…​never.

Default rhino-stats view

delta

Terminating triggers received — terminatingTriggersReceived

Records the total number of…​

…​initial requests that the SIS instance has received, triggered for the terminating call party.

Increments…​

…​when the SIS receives an initial request for the terminating call party on a network dialog that it has accepted for processing.

Decrements…​

…​never.

Default rhino-stats view

delta

Originating triggers successfully processed — originatingTriggersSuccessful

Records the total number of…​

…​initial requests for originating triggers, for which the SIS has successfully located a service composition.

Increments…​

…​when a trigger successfully locates a composition for an initial request, triggered for the originating call party.

Decrements…​

…​never.

Default rhino-stats view

delta

Terminating triggers successfully processed — terminatingTriggersSuccessful

Records the total number of…​

…​initial requests for terminating triggers, for which the SIS has successfully located a service composition.

Increments…​

…​when a trigger successfully locates a composition for an initial request, triggered for the terminating call party.

Decrements…​

…​never.

Default rhino-stats view

delta

SIS internals

Upcalls — upcalls

Records the total number of…​

…​events on a conducted dialog that the SIS instance has received from the network.

Increments…​

…​when the SIS instance receives any such event from the network. (Includes IN dialog control events such as TC_CONTINUE and TC_END.)

Decrements…​

…​never.

Default rhino-stats view delta

Downcalls — downcalls

Records the total number of…​

…​messages on a conducted dialog that the SIS instance has sent to the network.

Increments…​

…​whenever the SIS instance sends such a message to the network. (Includes IN dialog control events such as TC_CONTINUE and TC_END.)

Decrements…​

…​never.

Default rhino-stats view

delta

Internal redirects — internalRedirects

Records the total number of…​

…​internal redirects the SIS instance has performed. An internal redirect occurs if:

  • all services in a composition have been executed

  • the composition has been provisioned with a redirect prefix

  • and the last service executed allowed processing of further services to continue.

Increments…​

…​whenever the SIS performs an internal redirect.

Decrements…​

…​never.

Default rhino-stats view

delta

Service failures — serviceFailures

Records the total number of…​

…​service failures (such as no-response timeouts) the SIS instance has experienced while invoking composition services.

Increments…​

…​each time a composition service does not provide a response to an event for which it is required to do so within the timeout period specified for the service (or the default timeout period if none has been specified).

Decrements…​

…​never.

Default rhino-stats view

delta

Initial response time — responseTime

Samples…​

…​SIS initial request response time.

When…​

From the time the SIS first considers the initial request for delivery to services…​ to the time all required services have executed and the SIS has sent its response to the network.

Calculates…​

Initial response time of trigger events for which the SIS has invoked at least one service.

If the SIS does not select any compositions for the initial request, it either:

  • selects a composition which determines no services to execute

  • performs an internal redirect only

In either case no initial response time is sampled, as processing time would be negligible.

Statistics for Service-Initiated Dialogs

The SIS records the following statistics for such unconducted dialogs.

Note The SIS only triggers multiple services (does service interaction) for network-initiated dialogs — not for SLEE-initiated dialogs. When sending and receiving messages and events on outgoing dialogs that services in the SLEE or the SIS create, the SIS does not process service interaction.

Live activities — liveActivities

Records the total number of…​

…​unconducted dialogs, that a service has created through the SIS, that are currently live.

Increments…​

…​whenever a service creates a dialog using the SIS instance as the dialog provider.

Decrements…​

…​when an unconducted dialog terminates.

Default rhino-stats view

gauge

Total activities — totalActivities

Records the total number of…​

…​unconducted dialogs, that a service has created through the SIS.

Increments…​

…​whenever a service creates a dialog using the SIS instance as the dialog provider.

Decrements…​

…​never.

Default rhino-stats view

delta

Upcalls — upcalls

Records the total number of…​

…​events that the SIS instance has received from the network on unconducted dialogs (includes IN dialog-control events such as TC_CONTINUE and TC_END).

Increments…​

…​when the SIS instance receives any such event from the network.

Decrements…​

…​never.

Default rhino-stats view

delta

Downcalls — downcalls

Records the total number of…​

…​messages that services have sent to the network on unconducted dialogs (includes IN dialog-control events such as TC_CONTINUE and TC_END).

Increments…​

…​whenever a service sends such a message.

Decrements…​

…​never.

Default rhino-stats view

delta

Service Statistics

The SIS records the following statistics for each composition service that it invokes.

Live activities — liveActivities

Records the total number of…​

…​current number of active activities created by the SIS that are directly related to the service.

Increments…​

…​each time composition evaluation causes a new service instance to be created in the SIS.

Decrements…​

…​when the service terminates its association with the call.

Default rhino-stats view

gauge

Total activities — totalActivities

Records the total number of…​

…​total number of activities directly related to the service that the SIS instance has created.

Increments…​

…​each time composition evaluation causes a new service instance to be created in the SIS.

Decrements…​

…​never.

Default rhino-stats view

delta

Upcalls — upcalls

Records the total number of…​

…​events specifically targeted at the service, that the SIS instance has attempted to deliver to the service. (Includes IN dialog-control events such as TC_CONTINUE and TC_END.)

Increments…​

…​whenever the SIS attempts to deliver an event to the service.

Decrements…​

…​never.

Default rhino-stats view

delta

Downcalls — downcalls

Records the total number of…​

…​messages received by the SIS from the service. (Includes dialog-control events such as TC_CONTINUE and TC_END.)

Increments…​

…​whenever the service sends a request, response, or other message to the SIS.

Decrements…​

…​never.

Default rhino-stats view

delta

Service failures — serviceFailures

Records the total number of…​

…​service failures (such as no-response timeouts) the SIS instance has experienced while waiting for a response from the service.

Increments…​

…​each time the service does not provide a response to an event for which it is required to do so within the timeout period specified for the service (or the default timeout period if none has been specified).

Decrements…​

…​never.

Default rhino-stats view

delta

Initial request response time — responseTime

Samples…​

…​service initial request response time.

When…​.

From the time the SIS instance attempts to deliver the initial request to the service…​ to the time the service sends the SIS its response to the request.

Calculates…​

Response time for initial request processing for every composition service invoked by the SIS, when the service does provide a response.

Extension Component Statistics

The SIS records the following statistics for each extension component that it invokes.

Upcalls — upcalls

Records the total number of…​

…​events that the SIS instance has attempted to deliver to the extension component.

Increments…​

…​whenever the SIS fires an event to the SLEE for the extension component.

Decrements…​

…​never.

Default rhino-stats view

delta

Downcalls — downcalls

Records the total number of…​

…​responses received by the SIS from the extension component.

Increments…​

…​whenever the extension component sends a response to the SIS for a previous request.

Decrements…​

…​never.

Default rhino-stats view

delta

Failures — failures

Records the total number of…​

…​extension component failures (such as no-response timeouts) the SIS instance has experienced while invoking extension components.

Increments…​

…​each time an extension component does not provide a response to an extension event for which it is required to do so within the timeout period specified for the extension component (or the default timeout period if none has been specified).

Decrements…​

…​never.

Default rhino-stats view

delta

Response time — responseTime

Samples…​

…​extension component response time.

When…​.

From the time the SIS instance fires an extension event to the extension component…​ to the time the extension component sends to the SIS its response to the event.

Calculates…​

Response time for extension components for every extension event the SIS fires.

SIP-Specific Statistics

SIS for SIP also records the following statistics, in addition to the general statistics:

SIP Worker Pool Statistics

The SIS records the following statistics for the SIP stack’s worker pool.

Note The SIP stack used by the SIS maintains its own pool of worker threads for processing incoming SIP messages.

Threads — threadsTotal

Records the total number of…​

…​threads in the worker pool.

Increments…​

…​when the worker pool starts a new thread to handle incoming work.

Decrements…​

…​when a worker thread terminates because it is no longer needed.

Default rhino-stats view

gauge

Available threads — threadsAvailable

Records the total number of…​

…​threads in the pool that are idle and available for work.

Increments…​

…​when a worker thread finishes its current task and begins waiting for more work.

Decrements…​

…​when a worker thread begins processing a new task.

Default rhino-stats view

gauge

Queue size — queueSize

Records the total number of…​

…​tasks waiting in the worker pool’s queue.

Increments…​

…​when a task is enqueued and there is no worker thread immediately available to process it.

Decrements…​

…​when a worker thread removes a task from the queue.

Default rhino-stats view

gauge

Rejected tasks — rejects

Records the total number of…​

…​tasks rejected because the queue was full.

Increments…​

…​when a task is unable to be enqueued because there is no space in the queue.

Decrements…​

…​never.

Default rhino-stats view

delta

Suspended network reads — flowControlSuspends

Records the total number of…​

…​times that network reads were suspended.

Increments…​

…​when the stack stops reading from a TCP socket because there is no space in the queue.

Decrements…​

…​never.

Default rhino-stats view

delta

Resumed network reads — flowControlResumes

Records the total number of…​

…​times that network reads were resumed.

Increments…​

…​when the stack resumes reading from a TCP socket because the queue is no longer full.

Decrements…​

…​never.

Default rhino-stats view

delta

Task processing time — processingTime

Samples…​

…​time spent by the SIP stack processing a message.

When…​

From the time the worker thread begins processing the message…​ to the time the message is handed off to a higher layer (the SIS).

Calculates…​

…​the total time for the SIP stack to parse a message, update transaction state and pass the message up to the SIS.

Task waiting time — queueTime

Samples…​

…​time spent by tasks waiting in the queue.

When…​

From the a task is placed on the queue…​ to the time the task is removed by a worker thread.

Calculates…​

…​the time spent waiting on the queue because no threads were available.

SIP Transport Statistics

The SIS records the following statistics for each type of SIP network transport (UDP, TCP and TLS).

Bytes transmitted — bytesTx

Records the total number of …​

…​bytes transmitted by the SIP stack.

Increments…​

…​whenever a SIP message is transmitted. Incremented by the number of bytes in the message.

Decrements…​

never.

Default rhino-stats view

delta

Bytes received — bytesRx

Records the total number of …​

…​bytes received by the SIP stack.

Increments…​

…​whenever a SIP message is received. Incremented by the number of bytes in the message.

Decrements…​

never.

Default rhino-stats view

delta

Messages transmitted — messagesTx

Records the total number of …​

…​messages transmitted by the SIP stack.

Increments…​

…​whenever a SIP message is transmitted.

Decrements…​

never.

Default rhino-stats view

delta

Messages received — messagesRx

Records the total number of …​

…​messages received by the SIP stack.

Increments…​

…​whenever a SIP message is received.

Decrements…​

never.

Default rhino-stats view

delta

Transmission errors — errorsTx

Records the total number of …​

…​transmission errors seen by the SIP stack.

…​when sending a SIP message fails because of a network error (such as out of buffer space).

Decrements…​

never.

Default rhino-stats view

Receive errors — errorsRx

Records the total number of …​

…​receive errors seen by the SIP stack.

…​when receiving a SIP message fails because of a network error (such as dropped connection).

Decrements…​

never.

Default rhino-stats view

Incoming connections — connectionsIn

Records the total number of …​

…​active incoming TCP or TLS connections.

Increments…​

…​when the SIP stack accepts a connection from a SIP client.

Decrements…​

…​when a connection is closed (by the SIP stack or the client).

Default rhino-stats view

gauge

Outgoing connections — connectionsOut

Records the total number of …​

…​active outgoing TCP or TLS connections.

Increments…​

…​when the SIP stack successfully opens a TCP or TLS connection with a SIP server.

Decrements…​

…​when a connection is closed (by the SIP stack or the server).

Default rhino-stats view

gauge

SIP Transaction Statistics

The SIS records the following statistics about SIP transactions in the SIP stack.

Tip

Transaction statistics can be viewed as a whole, or by SIP Method. E.g. clientTransactionsActive shows all active client transactions, but clientTransactionsActive.INVITE just shows active INVITE client transactions.

Active client transactions — clientTransactionsActive

Records the total number of…​

…​client transactions currently in progress.

Increments…​

…​when a client transaction is created to send a request.

Decrements…​

…​when a client transaction is terminated (as per RFC3261 §17.1).

Default rhino-stats view

gauge

Client transactions completed successfully — clientTransactionsCompleted2xx

Records the total number of…​

…​client transactions that completed successfully by receiving a 2xx response.

Increments…​

…​when a client transaction receives a 2xx final response.

Decrements…​

…​never.

Default rhino-stats view

delta

Client transactions completed with a redirect response — clientTransactionsCompleted3xx

Records the total number of…​

…​client transactions that completed by receiving a 3xx redirect response.

Increments…​

…​when a client transaction receives a 3xx final response.

Decrements…​

…​never.

Default rhino-stats view

delta

Client transactions completed with an error response — clientTransactionsCompletedError

Records the total number of…​

…​client transactions that completed by receiving a 4xx-6xx error response.

Increments…​

…​when a client transaction receives a 4xx-6xx final response.

Decrements…​

…​never.

Default rhino-stats view

delta

Failed client transactions — clientTransactionsFailed

Records the total number of…​

…​client transactions that failed due to an internal error.

Increments…​

…​when a client transaction fails due to an error, such as an IOException or host not found.

Decrements…​

…​never.

Default rhino-stats view

delta

Timed out client transactions — clientTransactionsFailedTimeout

Records the total number of…​

…​client transactions that timed out waiting for a final response.

Increments…​

…​when a client transaction’s final response timer expires (Timer B or Timer F in RFC3261 §17.1).

Decrements…​

…​never.

Default rhino-stats view

delta

Retransmits sent on client transactions — clientTransactionsRetransmits

Records the total number of…​

…​retransmitted requests sent on client transactions, while waiting for a response.

Increments…​

…​when a client transaction’s retransmit timer expires (Timer A or Timer E in RFC3261 §17.1).

Decrements…​

…​never.

Default rhino-stats view

delta

Active server transactions — serverTransactionsActive

Records the total number of…​

…​server transactions currently in progress.

Increments…​

…​when a server transaction is created to handle an incoming request.

Increments…​

…​when a server transaction is terminated (as per RFC3261 §17.2).

Default rhino-stats view

gauge

Server transactions completed successfully — serverTransactionsCompleted2xx

Records the total number of…​

…​server transactions that completed successfully by sending a 2xx response.

Increments…​

…​when a 2xx final response is sent on a server transaction.

Decrements…​

…​never.

Default rhino-stats view

delta

Server transactions completed with a redirect response — serverTransactionsCompleted3xx

Records the total number of…​

…​server transactions that completed by sending a 3xx redirect response.

Increments…​

…​when a 3xx final response is sent on a server transaction.

Decrements…​

…​never.

Default rhino-stats view

delta

Server transactions completed with an error response — serverTransactionsCompletedError

Records the total number of…​

…​server transactions that completed by sending a 4xx-6xx error response.

Increments…​

…​when a 4xx-6xx final response is sent on a server transaction.

Decrements…​

…​never.

Default rhino-stats view

delta

Failed server transactions — serverTransactionsFailed

Records the total number of…​

…​server transactions that failed due to an internal error.

Increments…​

…​when a server transaction fails due to an error, such as an IOException.

Decrements…​

…​never.

Default rhino-stats view

delta

Timed out server transactions — serverTransactionsFailedTimeout

Records the total number of…​

…​server transactions that timed out waiting for an ACK.

Increments…​

…​when a server transaction’s ACK timer expires (Timer H in RFC3261 §17.2).

Decrements…​

…​never.

Default rhino-stats view

delta

Retransmits sent on server transactions — serverTransactionsRetransmits

Records the total number of…​

…​retransmitted responses sent on server transactions.

Increments…​

…​when a server transaction retransmits its response, because it received a retransmitted request.

Decrements…​

…​never.

Default rhino-stats view

delta

SIP Service Statistics

The SIS records the following statistics for each local or remote SIP service

Initial requests sent — requestsUp

Records the total number of…​

…​initial requests sent to the service.

Increments…​

…​when the SIS sends an initial request to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Initial requests received — requestsDown

Records the total number of…​

…​forwarded initial requests received from the service.

Increments…​

…​when a service forwards an initial request back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Provisional responses sent — responses1xxUp

Records the total number of…​

…​provisional responses (100-199) sent to the service.

Increments…​

…​when the SIS sends an provisional response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Provisional responses received — responses1xxDown

Records the total number of…​

…​provisional responses (100-199) received from the service.

Increments…​

…​when a service sends a provisional response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Success responses sent — responses2xxUp

Records the total number of…​

…​success (200-299) responses sent to the service.

Increments…​

…​when the SIS sends a success response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Success responses received — responses2xxDown

Records the total number of…​

…​success (200-299) responses received from the service.

Increments…​

…​when a service sends a success response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Redirect responses sent — responses3xxUp

Records the total number of…​

…​redirect (300-399) responses sent to the service.

Increments…​

…​when the SIS sends a redirect response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Redirect responses received — responses3xxDown

Records the total number of…​

…​redirect (300-399) responses received from the service.

Increments…​

…​when a service sends a redirect response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Client error responses sent — responses4xxUp

Records the total number of…​

…​client error (400-499) responses sent to the service.

Increments…​

…​when the SIS sends a client error response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Client error responses received — responses4xxDown

Records the total number of…​

…​client error (400-499) responses received from the service.

Increments…​

…​when a service sends a client error response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Server error responses sent — responses5xxUp

Records the total number of…​

…​server error (500-599) responses sent to the service.

Increments…​

…​when the SIS sends a server error response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Server error responses received — responses5xxDown

Records the total number of…​

…​server error (500-599) responses received from the service.

Increments…​

…​when a service sends a server error response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Global failure error responses sent — responses6xxUp

Records the total number of…​

…​global failure (600-699) error responses sent to the service.

Increments…​

…​when the SIS sends a global failure error response to a service (up-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Global failure error responses received — responses6xxDown

Records the total number of…​

…​global failure error (600-699) responses received from the service.

Increments…​

…​when a service sends a global failure error response back to the SIS (down-call).

Decrements…​

…​never.

Default rhino-stats view

delta

Service failures — serviceFailures

Records the total number of…​

…​failures seen by the SIS when invoking the service.

Increments…​

…​when a service invocation times out, or the service fails to send a final response to the initial request.

Decrements…​

…​never.

Default rhino-stats view

delta

Service response time — responseTime

Samples…​

…​time spent by the service processing the initial request.

When…​

From the time the SIS sends the initial request to the service…​ to the time the SIS receives the forwarded request or a response from the service (whichever occurs first).

Calculates…​

…​the total time for the service to handle the initial request, and either respond or forward it back to the SIS.

SIP Composition Statistics

The SIS records the following statistics about SIP Service Compositions, found under the compositions parameter set for the SIS-SIP instance.

Tip

Composition statistics can be viewed as a whole, or by the SIP Method of the initial request. E.g. active shows all active compositions, but active.REGISTER just shows active compositions that were initiated by a REGISTER request.

Accepted compositions — accepted

Records the number of…​

…​compositions that have been accepted by the SIS.

Increments…​

…​when an incoming initial request starts a composition.

Decrements…​

…​never.

Default rhino-stats view

delta

Rejected compositions — rejected

Records the number of…​

…​compositions that have been rejected by the SIS.

Increments…​

…​when a composition cannot be created for an initial request due to licensing, exceeding the composition limit, or the SIS being deactivated.

Decrements…​

…​never.

Default rhino-stats view

delta

Completed compositions — completed

Records the number of…​

…​compositions that have been completed by the SIS.

Increments…​

…​when all invoked services in the composition have processed the initial request and its final response.

Decrements…​

…​never.

Default rhino-stats view

delta

Currently active compositions — active

Records the number of…​

…​compositions that are currently active in the SIS.

Increments…​

…​when a composition has been accepted.

Decrements…​

…​when a composition has been completed.

Default rhino-stats view

gauge

Parallel Triggering Service

The SIS can trigger services in parallel as explained in the parallel composition script section of SIS Overview and Concepts.

However in some cases the default parallel triggering behaviour might not be sufficient. The SIS allows you to override the default behaviour by using a parallel triggering service. Below is an overview of how a parallel triggering service works with the SIS, how the SIP parallel triggering service extends the default SIS parallel triggering behaviour, and how to install the SIP parallel triggering service.

Tip This is a SIS feature for SIP.

Using a parallel triggering service

Each parallel block in a composition may optionally use a parallel triggering service. You instruct the SIS to use such a service by adding the use-service extension option to the parallel block, as shown below:

<parallel extension-options="use-service=<service-ref>">
    <invoke service="Prepay"/>
    <invoke service="Location" primary="true"/>
</parallel>

The <service-ref> argument must be a valid local service reference. The rest of the parallel block is unchanged. If the service reference refers to an external service, the SIS will ignore it and fall back to its default parallel triggering behaviour.

When the SIS evaluates a parallel block with the use-service parameter, it fires an initial event to the parallel triggering service, containing information about the services to be invoked. It is then up to the parallel triggering service to invoke the other services in parallel. The SIS waits for the outcome from the service before continuing with the rest of the composition.

The SIP parallel triggering service

The default behaviour for SIP parallel triggering is to send the initial INVITE to all services in parallel, but only the primary service will see the successful responses to the INVITE, so only the primary service stays on the call. Non-primary services receive an error response to the initial INVITE, so they will not receive any further messages on the call.

The SIS includes a parallel triggering service for SIP. This service extends the default parallel triggering behaviour by allowing all services invoked in parallel to remain on the call. When this service is used, all services receive the initial INVITE and OK response in parallel, and any mid-dialog requests are delivered to all services sequentially. The SIP parallel triggering service acts as a B2BUA to each service, maintaining dialogs to and from each service.

Warning
Restrictions

Note that:

  • The SIP parallel triggering service only supports external services. If any services inside the parallel block are local, the SIS falls back to its default behaviour.

  • Currently the service input and output interceptors of invoke statements are ignored when using a parallel triggering service.

  • Care must be taken to ensure that services invoked in parallel do not use SIP extensions that are incompatible with the other services.

Installing the service

The SIP parallel triggering service is installed by default with the SIP examples in sis/sip/<sis-version>/examples/sip, using the service reference ParallelTrigger. Below are the necessary details for installing it manually (if required).

Service information

Deployable Unit

 
 sis/sip/<sis-version>/du/sis-sip-parallel-trigger-service-<sis-version>.du.jar

Service Name

 
 ParallelTrigger

Service Vendor

 
 OpenCloud

Service Version

 
 0.1

Example sis-console commands

[Rhino@localhost (#1)] installlocaldu sis/sip/3.0.0.0/du/sis-sip-parallel-trigger-service-3.0.0.0.du.jar
installed: DeployableUnitID[url=file:sis/sip/3.0.0.0/du/sis-sip-parallel-trigger-service-3.0.0.0.du.jar]
[Rhino@localhost (#2)] activateservice name=ParallelTrigger,vendor=OpenCloud,version=0.1
Activating service ServiceID[name=ParallelTrigger,vendor=OpenCloud,version=0.1] on node(s) [101]
Service transitioned to the Active state on node 101
[Rhino@localhost (#3)] createlocalserviceref sipsis ParallelTrigger name=ParallelTrigger,vendor=OpenCloud,version=0.1
Created service reference ParallelTrigger for local SLEE service ServiceID[name=ParallelTrigger,vendor=OpenCloud,version=0.1]

Example SIP Overload Control Plugin

This page illustrates a simple example of a SIP Overload Control Plugin that simply accepts every request it receives for consideration.

Plugin Implementation

Code for the simple plugin implementation is given below.

package com.opencloud.slee.services.example.sipoverload;

import javax.slee.facilities.Tracer;
import org.jainslee.resources.sip.SipRequest;
import org.jainslee.resources.sip.overloadcontrol.LimiterInstruction;
import org.jainslee.resources.sip.overloadcontrol.SipOverloadControlPlugin;

public class SimpleOverloadControlPlugin implements SipOverloadControlPlugin {
    public SimpleOverloadControlPluginImpl(Tracer tracer) {
        this.tracer = tracer;
    }

    @Override
    public LimiterInstruction invoke(SipRequest request) {
        tracer.info("Handling request for overload control: " + request);
        // just accept it
        return LimiterInstruction.accept();
    }

    private final Tracer tracer;
}

SBB Implementation

Code for the SBB that manages the plugin registration is given below.

A plugin may be given references to non-transactional SBB resources such as tracers (for logging) and usage parameter sets (for stats). Consequently, it is important that plugin objects are deregistered from the SIS no later than associated service deactivation to avoid potential memory leaks if the service is later uninstalled from the SLEE.

package com.opencloud.slee.services.example.sipoverload;

import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.slee.ActivityContextInterface;
import javax.slee.ActivityEndEvent;
import javax.slee.CreateException;
import javax.slee.RolledBackContext;
import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.facilities.Tracer;
import com.opencloud.rhino.slee.servicenodeactivity.ServiceNodeActivity;
import com.opencloud.rhino.slee.servicenodeactivity.ServiceNodeStartedEvent;
import org.jainslee.resources.sip.SipFactory;

public abstract class SimpleOverloadControlPluginSbb implements Sbb {
    @Override
    public void setSbbContext(SbbContext context) {
        tracer = context.getTracer("");
        try {
            sipFactory = (SipFactory)new InitialContext().lookup("java:comp/env/resources/sis");
        }
        catch (NamingException e) {
            throw new RuntimeException("JNDI lookup error", e);
        }
    }

    public void onServiceNodeStartedEvent(ServiceNodeStartedEvent e, ActivityContextInterface aci) {
        tracer.info("Registering overload control plugin");
        sipFactory.registerOverloadControlPlugin(new SimpleOverloadControlPluginImpl(tracer));
    }

    public void onActivityEndEvent(ActivityEndEvent e, ActivityContextInterface aci) {
        if (aci.getActivity() instanceof ServiceNodeActivity) {
            tracer.info("Deregistering overload control plugin");
            sipFactory.registerOverloadControlPlugin(null);
        }
    }


    @Override public void unsetSbbContext() {}
    @Override public void sbbCreate() throws CreateException {}
    @Override public void sbbPostCreate() {}
    @Override public void sbbActivate() {}
    @Override public void sbbPassivate() {}
    @Override public void sbbLoad() {}
    @Override public void sbbStore() {}
    @Override public void sbbRemove() {}
    @Override public void sbbExceptionThrown(Exception exception, Object event, ActivityContextInterface aci) {}
    @Override public void sbbRolledBack(RolledBackContext context) {}


    private Tracer tracer;
    private SipFactory sipFactory;
}

Deployment descriptors

The deployment descriptor for the SBB implementation illustrated above is given below:

<?xml version="1.0"?>

<!DOCTYPE sbb-jar PUBLIC
    "-//Sun Microsystems, Inc.//DTD JAIN SLEE SBB 1.1//EN"
    "http://java.sun.com/dtd/slee-sbb-jar_1_1.dtd">

<sbb-jar>
  <sbb>
    <description>Simple Overload Control Plugin SBB</description>
    <sbb-name>SimpleOverloadControlPluginSbb</sbb-name>
    <sbb-vendor>OpenCloud</sbb-vendor>
    <sbb-version>1.0</sbb-version>

    <sbb-classes>
      <sbb-abstract-class>
        <sbb-abstract-class-name>
          com.opencloud.slee.services.example.sipoverload.SimpleOverloadControlPluginSbb
        </sbb-abstract-class-name>
      </sbb-abstract-class>
    </sbb-classes>

    <event event-direction="Receive" initial-event="True">
      <event-name>ServiceNodeStartedEvent</event-name>
      <event-type-ref>
        <event-type-name>
            com.opencloud.rhino.slee.servicenodeactivity.ServiceNodeStartedEvent
        </event-type-name>
        <event-type-vendor>com.opencloud</event-type-vendor>
        <event-type-version>1.0</event-type-version>
      </event-type-ref>
      <initial-event-select variable="ActivityContext"/>
    </event>

    <event event-direction="Receive">
      <event-name>ActivityEndEvent</event-name>
      <event-type-ref>
        <event-type-name>javax.slee.ActivityEndEvent</event-type-name>
        <event-type-vendor>javax.slee</event-type-vendor>
        <event-type-version>1.0</event-type-version>
      </event-type-ref>
    </event>

    <resource-adaptor-type-binding>
      <resource-adaptor-type-ref>
        <resource-adaptor-type-name>EasySIP</resource-adaptor-type-name>
        <resource-adaptor-type-vendor>jainslee.org</resource-adaptor-type-vendor>
        <resource-adaptor-type-version>3.1.0</resource-adaptor-type-version>
      </resource-adaptor-type-ref>
      <resource-adaptor-entity-binding>
        <resource-adaptor-object-name>resources/sis</resource-adaptor-object-name>
        <resource-adaptor-entity-link>EASYSIP</resource-adaptor-entity-link>
      </resource-adaptor-entity-binding>
    </resource-adaptor-type-binding>
  </sbb>
</sbb-jar>

The deployment descriptor for a service using this SBB as a root SBB is also given below:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE service-xml PUBLIC
    "-//Sun Microsystems, Inc.//DTD JAIN SLEE Service 1.1//EN"
    "http://java.sun.com/dtd/slee-service_1_1.dtd">

<service-xml>
  <service>
    <service-name>SimpleOverloadControlPluginService</service-name>
    <service-vendor>OpenCloud</service-vendor>
    <service-version>1.0</service-version>
    <root-sbb>
      <sbb-name>SimpleOverloadControlPluginSbb</sbb-name>
      <sbb-vendor>OpenCloud</sbb-vendor>
      <sbb-version>1.0</sbb-version>
    </root-sbb>
    <default-priority>0</default-priority>
  </service>
</service-xml>

Custom Reject Responses

An overload control plugin that returns a REJECT instruction also has the option to return a custom response message to be sent to the network in place of the SIS' default overload control response. The example code below illustrates how an overload control plugin can do this.

@Override
public LimiterInstruction invoke(SipRequest request) {
    // status code should be a 3xx, 4xx, or 5xx response code
    int rejectStatusCode = XXX;

    // create response object
    SipResponse rejectResponse = ((IncomingSipRequest)request).createResponse(rejectStatusCode);

    // set any required headers as needed
    rejectResponse.setHeader(...);
    ...

    // return reject instruction with this response
    return LimiterInstruction.reject(rejectResponse);
}