This document provides an overview of the CGIN connectivity pack.

Topics

Introducing the CGIN Connectivity Pack

What the CGIN connectivity pack is, and the case for 'CGIN' technology.

Inside the CGIN Connectivity Pack

An overview of the elements of the CGIN connectivity pack:

and how they releate to each other.

CGIN Unified RA vs INCC RAs

A description of the CGIN Unified Resource Adaptor, and how its approach differs from that of the INCC RAs it supercedes, with details of how it advances RA architecture and APIs.

CGIN Tool Chain

A brief introduction to the technology used to build the CGIN connectivity pack (the CGIN tool chain), how protocol engineers can use it to build support for protocols, and software engineers use the generated results.

Other documentation for CGIN can be found on the CGIN product page.

Introducing the CGIN Connectivity Pack

The CGIN (Computer Generated Intelligent Network) Connectivity Pack integrates the Rhino platform with SS7 networks and supports functional and load testing of SS7-based applications.

CGIN supports both industry standard and vendor-variant SS7 protocols. CGIN also includes tools to support functional and load testing of SS7-based applications.

Tip

For more information about the CGIN connectivity pack read:

Why CGIN?

OpenCloud already has excellent support for SS7 protocols but:

  • We need to support vendor variants of standard protocols.

  • We need to rapidly address integration issues with new equipment, because not all implementations of the standards are truly equal.

  • We need to support partners who wished to choose the SS7 stack or indeed had their own SS7 stack.

  • We need to make our SS7 APIs even better by adopting design patterns derived from our own extensive experience in writing applications.

Resolution

We use compiler-design and code-generation techniques to take protocol descriptions in ASN.1, and auto-generate not only the TCAP library, but the entire set of resource adaptor and associated metadata that a suite of tools needs for functional and load testing.

Inside the CGIN Connectivity Pack

The CGIN Connectivity Pack is OpenCloud’s product for integrating the Rhino platform with SS7 networks and supporting functional and load testing of SS7-based applications.

cgin conn pack wide

It includes:

1 the new CGIN Unified RA

2 interface to a TCAP stack

Available as a separate download, the Scenario Simulator can be used with CGIN for scenario testing. It includes:

3 Scenario Editor

4 Scenario Simulator

download If you are interested in evaluating CGIN download the latest CGIN Software Developers Evaluation Kit.

Unified Resource Adaptor

The Unified Resource Adaptor supports multiple SS7 protocols with a pluggable architecture.

It includes a number of TCAP based protocol libraries (INAP, CAP and MAP in the diagram below) that run on top of a TCAP stack.

cgin unified ra

The Unified RA:

  • can load multiple ASN.1 based protocols inside it

  • can be configured to load a subset of the defined protocols (for example, only MAP)

  • supports ETSI INAP CS1, CAP v1, v2, v3, v4, and MAP:

    • ETSI INAP CS1 (ETS 300 374-1: September 1994)

    • CAP v.1 (ETSI TS 101 046 / GSM 09.78 V5.7.0 Release 1996)

    • CAP v.2 (ETSI TS 101 046 / GSM 09.78 V7.1.0 Release 1998)

    • CAP v.3 (3GPP TS 29.078 V4.8.0 Release 4)

    • CAP v.4 (3GPP TS 29.078 v9.1.1 Release 9)

    • Mobile Application Part (MAP) (3GPP TS 29.002 v10.0.0 Release 10)

  • integrates with an SS7 stack at the TCAP layer (ITU TCAP is supported)

  • connects at the TCAP layer to either a real TCAP stack or a simulated TCAP stack.

TCAP Stack Interfaces

The Unified RA and the Scenario Simulator support TCAP in two ways, integrating with:

Simulated TCAP stack

The sim TCAP stack simulates most of the behaviour of a real SS7 network. It is embedded in both the Unified Resource Adaptor and the Scenario Simulator, and can be used for testing without the need for a real TCAP stack.

SimulatedTCAPstack
Warning The sim TCAP stack is ideal to augment your testing capabilities. However it is not a substitute for testing on a real network.

Each TCAP simulator (in the Unified Resource Adaptor entity and CGIN Scenario Simulator) connects to other TCAP simulator instances directly using SUA over a proprietary TCP-based protocol. Each TCAP simulator uses SUA dynamic routing configuration to discover its routing configuration, plus each has its own global title translation table.

Note

OCSS7 TCAP Stack

The Unified Resource Adaptor and the Scenario Simulator both integrate with the OCSS7 TCAP stack with:

  • a Java component that is embedded in the CGIN Unified RA and Scenario Editor

  • a signalling gateway client.

These two components communicate through a proprietary TCP/IP-based protocol.

OCSS7TCAPstack
Tip For more information about the OCSS7 TCAP stack, please contact OpenCloud.

Signalware TCAP Stack

The Unified Resource Adaptor and the Scenario Simulator both integrate with the Ulticom Signalware TCAP stack with:

  • a Java component that is embedded in the CGIN Unified RA and Scenario Editor

  • a C++ component that executes in the Signalware environment.

These two components communicate through a proprietary TCP/IP-based protocol.

SignalwareTCAPstack
Tip See Using the Ulticom Signalware TCAP Stack for more details about configuring the Signalware TCAP stack.

MACH7 TCAP Stack

The Unified Resource Adaptor and the Scenario Simulator both integrate with the teleSys MACH7 TCAP stack with:

  • a Java component that is embedded in the CGIN Unified RA and Scenario Simulator

  • an application server dispatcher client, provided as part of the standard teleSys MACH7 installation.

These two components communicate through a proprietary TCP/IP- or SCTP-based protocol.

teleSysMACH7TCAPstack
Tip See Using the teleSys MACH7 TCAP Stack for more details about configuring the teleSys MACH7 TCAP stack.

Scenario Editor

ScenarioEditor
Scenario Editor in action

The Scenario Editor is a visual tool for building call flow scenarios for use with the Scenario Simulator.

The screenshot to the right shows the Scenario Editor in action scripting an originating call scenario for a VPN-style application that is querying the HLR for location information of the called party.

The Scenario Editor is parameterised by protocol schema libraries that encode the rules of the protocol, such as the Application Context Names (ACNs) available, the operations and responses supported by each ACN, and so on.

You use the Scenario Editor to:

  • Define network roles and dialogs for use in a signaling scenario.

  • Create operation call flows including request, response, and error operations.

  • Define the parameters of each operation. You simply choose the parameters to include, fill in fields and select values from pull-down lists.

  • Explore protocols with the built-in schema browser. For example you can browse the ACNs to see what operations and responses are supported, or you can choose an operation/response and see which ACNs use it.

  • Edit multiple scenarios at the same time, and easily copy data between them.

  • Visually display and correct problems with a scenario before running it in the Scenario Simulator. The Scenario Editor monitors your progress and provides constant feedback about the conformance of your scenario to the requirements of the protocols used.

  • Export scenarios to an image file for use in presentations or documentation.

Tip Read the Scenario Editor User Guide for more details about creating signalling use cases with the Scenario Editor.

Scenario Simulator

The Scenario Simulator is a very powerful and flexible testing tool for simulating traffic in SS7 networks.

Each supported SS7 protocol is specified by a protocol schema. A protocol schema defines the types of messages and fields which are valid for a particular protocol.

You can use the scenario simulator to generate traffic (for example, to emulate an SSF) or to receive traffic (for example, to emulate an SCP or HLR) for functional and load testing. Imagine, for instance, you are working on a VPN-style application. You can write scenario definitions covering all the ways your application can interact with the switch, and also all the ways your application can interact with an HLR. The Scenario Simulator incorporates powerful scenario-matching technology and applies the most appropriate scenario based on the messages sent and received.

scen sim

You use the scenario simulator for testing network elements and services by building a test environment with:

  • test cases defined as scenario definitions — Each scenario definition (defined with the Scenario Editor) describes the end-to-end message flow for a particular call-flow use case. The Scenario Simulator can simulate many scenarios at the same time.

  • test data as data-sets — Tables of data used in scenario definitions during runtime. Data-sets can either be specified inline (inside the scenario), or in an external CSV file.

  • endpoints — You can configure physical network endpoints with an associated address. Endpoints are bound to roles that are defined in the scenario definitions. The endpoints are part of the configuration data.

  • a TCAP stack — You configure the simulator to connect with an external TCAP stack or to use the built-in sim TCAP stack

Tip Read the Scenario Simulator User Guide for more details about generating traffic with the Scenario Simulator for functional and load testing.

CGIN Unified RA vs INCC RAs

In this section we explore the CGIN-based support for SS7 by considering CGIN APIs and resource adaptors in contrast to our previous offerings for SS7 — INCC-based APIs and resource adaptors in the IN Connectivity pack.

CGIN approach to SS7 APIs and resource adaptors

cgin unified ra

  • One resource adaptor for all protocols

  • Resource APIs, resource adaptor types, and resource adaptor implementation are auto-generated by the CGIN toolchain

  • All "TCAP libraries" are auto-generated by the CGIN toolchain

  • Only integration with Signalware TCAP is needed

  • Any protocol with an ASN.1 definition is supported by the CGIN toolchain. For example, vendor variants and customisations of standard protocols can be supported.

  • Available in the CGIN Connectivity Pack

INCC approach to SS7 APIs and resource adaptors

incc ras

  • OpenCloud’s earlier architecture

  • Resource adaptor per protocol

  • Resource APIs, resource adaptor types, and resource adaptor implementations were all developed by hand

  • Utilised Ulticom’s "TCAP libraries" for protocols such as CAP, INAP, and MAP

  • Hand-crafted integration with the Signalware stack is required for each protocol

  • Limited to the protocols supported by the SS7 stack vendor. For example, vendor variants and customisations are unlikely to be supported.

  • Available in the IN Connectivity Pack

The following sections compare and contrast the CGIN unified resource adaptor to the deprecated INCC based resource adaptors in terms of Resource Adaptor Architecture and Resource Adaptor APIs.

Resource Adaptor Architecture

Interfaces for SS7 protocols (such as INAP, CAP, and MAP) are provided by one resource adaptor. There is no need to install separate resource adaptors for INAP, CAP, and MAP as SS7 support has been unified.

The architecture behind this unification is illustrated by the following diagrams.

new Unified RA old IN RA
cgin ra

CGIN technology now allows us to rapidly build our own support for INAP, CAP, and MAP — we do not need to rely on third parties for these layers any more. These application protocol layers now reside in the Java part of the resource adaptor (TCAP libraries in the diagram) and are used by the Unified Resource Adaptor implementation. These libraries not only provide support for their respective protocol, they also provide a corresponding resource adaptor type and metadata about the protocol. This Java "upper layer" has a single point of integration to a TCAP back end that encapsulates a TCAP stack from a third-party vendor.
in ra

In contrast, our old SS7 resource adaptors required hand-crafted adaptation per protocol to integrate with third-party vendor APIs for INAP, CAP, and MAP. The architecture of our old RAs is similar (Java front end, native back end); however this approach meant we needed a Java front end per protocol and a native back end per protocol. Whilst our old SS7 resource adaptors work extremely well, their approach means there is more code to maintain, and our ability to address incompatibilities in the support for application protocols and proprietary variants is limited. CGIN technology removes these barriers completely!

Resource Adaptor APIs

CGIN adopts some features and design patterns from INCC. One important feature of the INCC APIs that has been preserved is the idea of abstracting the common features of call control APIs into a common API — this was the INCC (IN Call Control) API.

Concrete call control protocols (such as INAP and CAP) were supported with APIs that extended INCC (for example CAPv2InitialDPReq is a sub-type of InitialDPReq). The INCC API (and extensions for each concrete protocol) were all hand-crafted. CGIN APIs, on the other hand, are almost entirely code-generated.

This page presents the CGIN family of APIs and also discusses some important differences in the design patterns adopted for the CGIN APIs.

CGIN family of APIs

CGIN provides a suite of APIs for INAP, CAP, and MAP. The diagram below shows the set of APIs provided in the CGIN Connectivity Pack.

Call control protocol APIs are defined as a hierarchy where each protocol API is defined as an extension of another protocol API. For example CAP v4 extends CAP v3, which extends CAP v2, which extends CAP v1.

At the root of the hierarchy is the CGIN Call Control (CGIN CC) API. CGIN CC is a synthetic call control protocol that is the intersection of ETSI INAP CS1 and CAP v4. Call control applications can be written in terms of the CGIN CC API and may be largely independent of the actual signaling protocols used.

Note The CGIN Call Control API is also generated by the CGIN toolchain. CGIN CC has its own ASN.1 description, which is why we refer to it as a synthetic protocol.
cgin apis

  • Call Control API — API for the synthetic protocol that is the intersection of INAP and CAP.
    The CGIN Call Control API plays the same role as the core/common classes of the deprecated INCC (IN Call Control) API.

  • INAP APIs — A family of INAP APIs that are based on a common definition of ETSI INAP CS1

    • ETSI INAP CS1 (ETS 300 374-1: September 1994)

    • Please contact OpenCloud for information pertaining to INAP variants supported

  • CAP APIs — A family of CAP APIs that are based on the definition of CAP v1

    • CAP v.1 (ETSI TS 101 046 / GSM 09.78 V5.7.0 Release 1996)

    • CAP v.2 (ETSI TS 101 046 / GSM 09.78 V7.1.0 Release 1998)

    • CAP v.3 (3GPP TS 29.078 V4.8.0 Release 4)

    • CAP v.4 (3GPP TS 29.078 v9.1.1 Release 9)

  • MAP API — An API for GSM MAP.

    • Mobile Application Part (MAP) (3GPP TS 29.002 v10.0.0 Release 10)

  • IN Datatypes API — A library of classes to represent types for which their ASN.1 specification is OCTET STRING, and for which standards define the layout of bit-fields within the octet string (for example CalledPartyNumber and ISDNSubaddress).

Note
Learn more…​

See: CGIN APIs for javadoc of all APIs in the CGIN family.

An API design pattern for SS7 APIs

An updated pattern for our SS7 APIs has been introduced as a part of CGIN. We decided to make this change based on our own experiences using our INCC APIs and on our customers' feedback. There are several reasons why we did this:

  • There are some common use cases for programming with our SS7 APIs that were harder to implement than we liked. For example it was difficult to copy a message from one dialog to another.

  • We noticed some common errors programmers were making using our APIs. These were related to rules imposed on the programmer by the SLEE programming model that programmers were not following.

  • We can guarantee all CGIN APIs are mutually consistent, with consistent naming schemes, by using code-generation techniques. We could not provide this guarantee previously, as INCC APIs were hand-crafted.

CGIN APIs

The CGIN APIs represent an SS7 message as a POJO (Plain Old Java Object). This SS7 message POJO is only responsible for encapsulating the fields of the SS7 message it represents. Applications can therefore safely store messages in CMP fields.

The CGIN CC InitialDP, for example, is represented by the CCInitialDPArg class.

// A POJO that represents an InitialDP
public class CCInitialDPArg extends AbstractFieldsObject {

    public CalledPartyNumber getCalledPartyNumber()   { ... }
    public CallingPartyNumber getCallingPartyNumber() { ... }

    // + other methods for accessing fields of the InitialDP
}

SLEE events are represented as a separate class with an associated message POJO.

The CGIN CC InitialDP request, for example, is shown below. The CCInitialDPRequestEvent extends from the OperationInvokeEvent generic class, with a type parameter value of CCInitialDPArg. CCInitialDPArg is the POJO class that represents the InitialDP message itself.

/** * Base class for all operation-specific invoke event classes. * Individual protocols subclass this event for each operation they support. * Each operation defines its own event type. */
public class OperationInvokeEvent<ArgType> extends OperationEvent {

    public ArgType getArgument() { return argument; }

    // ...
}

// ...

public class CCInitialDPRequestEvent extends OperationInvokeEvent<CCInitialDPArg> {

    // ...

}

INCC APIs

In the INCC APIs, each SS7 message was represented with a Java interface. This interface fulfilled two roles: 1) it represented the event object that the resource adaptor submitted to the SLEE and 2) it encapsulated all the fields of the SS7 message it represented.

The INCC InitialDP request, for example, is shown below. It is a Java interface that represents both the InitialDP request event and the fields of the InitialDP message.

/** * This interface defines the IN Call Control InitialDP request message that * may be sent to the network. */
public interface InitialDPReq extends Request {

    public CalledPartyNumber getCalledPartyNumber();
    public CallingPartyNumber getCallingPartyNumber();

    // + other operations for accessing fields of the InitialDP
}
Note
Restrictions imposed by the SLEE programming model

The SLEE programming model imposes some restrictions on what a SLEE application can do with an event. An important one that programmers often misunderstand (or simply forget!) is that event objects should not be stored by the service in CMPs (or by using any other method) for use in future transactions. This is simply because the event is owned by the resource adaptor and the SLEE has no knowledge of how the event object has been implemented (and therefore cannot make any assumptions in terms of persistence and so on).

CGIN Tool Chain

CGIN (Code-Generated IN) is a suite of tools, libraries, and frameworks from OpenCloud that we use to build SS7 resource adaptors and tools for the Rhino platform.

The CGIN tool chain supports a build process for generating:

  • protocol APIs that developers use to build applications on the Rhino platform

  • protocol libraries that plug into the CGIN Unified Resource Adaptor

  • protocol schema definitions that plug into the Scenario Editor and the Scenario Simulator.

The outputs of the CGIN tool chain are collected into the CGIN Connectivity Pack.

Building support for protocols and using the generated results

The following diagram shows an overview of the CGIN tool chain in relation to protocol engineers who are building support for protocols, and software engineers who use the generated results.

cgin toolchain roles

1 Prepare input …​

Input to the CGIN process includes:

  • ASN.1 protocol definitions — The ASN.1 defines the Application Contexts (ACs) defined by the protocol; all the requests, responses, and errors possible for those ACs; as well as the parameters of these messages.

  • Protocol and API adaptations — Protocol engineers can script custom adaptations of the protocol using the OpenCloud adaptation Domain Specific Language (DSL). For example a protocol engineer can: exploit existing handwritten types by mapping them to ASN.1 types, interpret data contained within plain OCTET STRINGs, define how the protocol fits into the OpenCloud call-control API hierarchy, and so on.

2 Execute the CGIN tool chain …​

The CGIN tool chain is then used by protocol engineers to transform the ASN.1 and adaptation definition into:

  • an API and corresponding SLEE resource adaptor type — so software engineers can write SLEE-based applications that use the protocol

  • documentation of the API in the form of Javadoc — to make the software engineers' job easier as they write their applications

  • Java components that plug into the OpenCloud Unified Resource Adaptor — so software engineers can run their applications on the Rhino platform

  • a protocol schema definition — so software engineers can write scenario definitions (signaling use cases) for the protocol, using the Scenario Editor, to use with the Scenario Simulator for functional and load testing.