# Concepts and Architectural Overview

# Introducing Communication Services

The following chapter presents a high level introduction to Oracle Communications Services Gatekeeper’s communication services, including:

- Overview
- Platform Features

A separate document, Communication Services Reference, offers a more detailed look at specific services.

## Overview

All application service request data flows through Oracle Communications Services Gatekeeper using communication services. A communication service consists of a service type (Multimedia Messaging, Terminal Location, etc.), an application-facing interface (also called a “north” interface), and a network-facing interface (also called “south” interface).

### How They Work

Communication services are separated into two functional layers: the service facade and the service enabler. The service facade contains the application-facing interfaces, and manages interactions with applications. The service enabler contains the mechanisms necessary for dealing with the underlying network nodes.

Application-initiated requests (also called mobile terminated, or MT) enter through the service facade. A facade comprises a set of application-facing interfaces of a particular type. Oracle Communications Services Gatekeeper supplies facades for traditional SOAP Web Services interfaces, RESTful interfaces, and, in two cases, MM7 and SMPP, native telephony interfaces. There is also a facade specifically designed to work with the Oracle Service Bus, for SOA-style installations.

After the requests have been processed by the service facade, they are sent on to the service enabler using RMI. The service enabler layer manages service authorization and policy enforcement, charging, and traffic throttling and shaping. Then the enabler translates the request into a form appropriate for the underlying network node.

Note: | Although the operator may choose instead to run in a sessionless mode, by default Oracle Communications Services Gatekeeper requires that applications (except those using native telephony interfaces) acquire an Oracle Communications Services Gatekeeper session before beginning to send request traffic. Applications do this using the Session Manager interface appropriate for their facade type, which returns a session ID. The application then adds this session ID to the header of all its requests. Oracle Communications Services Gatekeeper can use this value to keep track of all the traffic that an application sends for the duration of the session.

Network-triggered (also called mobile originated, or MO) traffic is also supported by Oracle Communications Services Gatekeeper, enabling applications to receive data from the telecom network. To do so, the application must first send a request to Gatekeeper (or have the operator perform the equivalent task using OAM methods) to register a description of the types of data it is interested in - delivery notifications, incoming messages, etc. - and any criteria that the data must be meet to be acceptable. For example, an application might specify that it is only interested in receiving incoming SMSes that are addressed to the short code “12345” and that begin with the string “blue”.

Note: | For more on short codes, see “Parlay X 2.1 Short Messaging Communication Service” in Communication Services Reference, another document in this set.

### Typical Application-Initiated Traffic Flow

Figure 4-1 illustrates typical application-initiated traffic flow.

Note: | The two native interfaces, MM7 and SMPP, behave in slightly different ways.

Figure 4-1 Typical Application-Initiated Traffic Flow

1. Steps 1-3 are optional and may be turned off. An application establishes a session by using the Session Management Web Service in the Facade layer.
2. A session is established, and the SessionID is returned to the application. Once the application has been established, it may access multiple communication services across the cluster transparently.
3. The session is valid until the application terminates it or an operator-established time period has elapsed.

Note: | Sessions allow correlation among sequences of operations. They are not used for purposes of authentication.

4. A request for a particular operation, usually transported over SSL, enters at the application-facing interface in the facade layer, either directly from the application, or, if the particular installation uses an Oracle Service Bus (OSB), from the OSB. This interface is implemented as a SOAP- based Web Service or a RESTful Web Service. Requests using the RESTful requests are authenticated with HTTP basic authentication using username/password. SOAP-based Web Services requests are authenticated using WebLogic Server’s WS-Security, which supports plaintext or digest passwords, X.509 certificates, or SAML tokens.

Note: | All requests are authenticated in this manner, whether the application uses the session mode or not.

In addition, SOAP-based requests may be further secured through encryption using the W3C’s standard XML encryption and through digital signatures using the W3C XML digital signature standard. The particular security requirements of the installation are specified in the WS-Policy section of the operator published WSDL file.

Note: | It is possible to use the appropriate standard Parlay X 2.1 or 3.0 WSDL to create SOAP-based requests, but the developer would then be required to ascertain the appropriate security type from the operator and insert the information manually.

5. The request is serialized and is passed on to the service enabler over RMI.

Note: | From this point on in the flow, requests that enter the communication service using the SOAP Service Facade and those using the RESTful Service Facade use the same service enablers. SLA construction, CDRs/EDRs/Alarms, and so forth are same for the SOAP-based requests as they are for the RESTful requests of the same type.

6. The entrance point for the service enabler marks the beginning of the application-initiated transaction.
7. The request is sent to the Plug-in Manager.
8. The Plug-in Manager invokes the Interceptor Stack to evaluate the request. The Interceptor Stack is a flexible set of chained evaluation steps that:

- Validates the request
- Enforces a range of policy decisions based on SLAs (and, possibly, additional rules)
- Performs any necessary data manipulation
- Routes the request to an appropriate protocol translation module (a network plug-in). Routing can be done on a wide variety of parameters.

Note: | Should a request fail because of an unavailable module, an interceptor retries the request using one of the remaining eligible modules.

9. The request is sent to the network plug-in to be translated into the protocol suitable for the underlying network node. All state information required by the underlying network node is stored within the network plug-in.
10. The request is passed to the network.
11. When the node acknowledges the request, charging data about the completed request are recorded.
12. The transaction commits.

### Typical Network-Triggered Traffic Flow

The key difference between application-initiated traffic flow and network-triggered traffic flow (other than the direction) is that the application must first indicate to Oracle Communications Services Gatekeeper that it is interested in receiving traffic from the network. It does this by registering for (or subscribing to) notifications, either by sending a request to Oracle Communications Services Gatekeeper or by having the operator set up the notification using OAM methods. For example, the application could send Oracle Communications Services Gatekeeper a request to begin receiving SMSs from the network, indicating that it is only interested in SMSs that are sent to the address “12345” and that begin with the string “blue”. In SOAP-based requests it indicates the URL of the Web Service that the application has implemented to receive these notifications back. In RESTful requests it indicates the channel to which the notifications should be published.

The registration for notifications is stored in the appropriate network plug-in, which in most cases passes it on to the underlying network node itself (in certain cases the Oracle Communications Services Gatekeeper operator must do this manually.) When a matching SMS reaches the plug-in from the network, the plug-in sends it to the Plug-in Manager, which invokes the Interceptor Stack for evaluation. Then, using RMI, the final interceptor passes the notification, along with the appropriate location from the registration, to the facade layer, which sends it on, either to the application, the channel, or, in the OSB case, to the OSB.

Note: | Installations that include multiple facade layers (for example, both RESTful and SOA) can be set up to use the same service enabler layer. Special configuration is required in such installations to route network-triggered traffic to the appropriate facade layer. See “Managing and Configuring the Tier Routing Manager” in System Administrator’s Guide, another document in this set, for more information.

See Figure 3-2 and Figure 3-3 for more information on the general traffic flow, although those figures document delivery notifications.

## Platform Features

Some functionality is common to all communication services. This functionality includes:

- Service Level Agreements and Policy Enforcement
- Service Level Agreements and Network Protection
- Traffic Security
- Events, Alarms, and Charging
- Statistics and Transaction Units

### Service Level Agreements and Policy Enforcement

All application access to Oracle Communications Services Gatekeeper’s communication services is governed by a set of service level agreements (SLAs) between the application service provider and the Oracle Communications Services Gatekeeper operator. Oracle Communications Services Gatekeeper uses a two-tiered account grouping system to categorize application services and their providers and to simplify the creation and maintenance of SLAs:

- Service Provider Group
- Application Group

For more information on the account system, see The Administration Model, a section in this document. Out of the box, Oracle Communications Services Gatekeeper provides standard SLAs for both of these types. Custom SLAs for both types can also be created.

These SLAs define whether a member of a service provider group or application group:

- Has access to a particular communication service, which can be regulated down to supported methods and parameters
- Participates in any quality of service (QoS) agreements such as:

- Specifying the guaranteed number of requests a service provider may send through a particular communication service in a given period of time. These guarantees may be modulated by:

- Time of Day/Day of Week
- Rate (Invocations per time period)
- Quota (Aggregated number of invocations)

For a more detailed look at Service Provider and Application SLA structure, see “Defining Service Provider Level and Application Level Service Agreements” in Managing Accounts and SLAs. For a communication service-focused description, see the respective communication service chapters in Communication Service Reference. These books are separate documents in this set.

SLA enforcement for communication services is provided by the Interceptor Stack. As in previous versions of Oracle Communications Services Gatekeeper, it is also possible to create extended rules that are evaluated using the external policy engine, which is called from an interceptor.

Note: | These rules represent operator specific policies defined by the operator and implemented by Oracle or a selected partner.

A simplified version of the flow is illustrated in Figure 4-2 below.

Figure 4-2 Simplified Communication Service Policy Execution Flow

Network-triggered requests are also evaluated using the Interceptor Stack.

### Service Level Agreements and Network Protection

There are also SLAs that help protect the underlying network node by setting priorities for sending requests, on the level of a particular service provider group or of Oracle Communications Services Gatekeeper as a whole. Depending on the status of the underlying network, traffic can be throttled and shaped. If a particular node is overloaded, lower-priority traffic can be rejected altogether. For general information on these traffic-based (called Node) SLAs, see The Administration Model in this document. For more detailed information, see the “Defining Global Node and Service Provider Group Node SLAs” chapter in Managing Accounts and SLAs. Out of the box, Oracle Communications Services Gatekeeper provides standard SLAs for both these types. Custom SLAs for the Global Node type can also be created.

### Traffic Security

For SOAP-based Web Services interfaces, Oracle Communications Services Gatekeeper uses special SOAP headers to authenticate service provider applications. These headers are documented in the WS-Policy section of each interface’s WSDL file. Processing is managed by WebLogic Server’s WS-Security, which supports plaintext or digest passwords, X.509 certificates, or SAML tokens for authentication. To guarantee the confidentiality of communication between Oracle Communications Services Gatekeeper and the application, traffic can be encrypted - fully or partially - using W3C’s standard XML encryption. Message integrity can be assured using the W3C XML digital signature standard. The WS-Policy section of the published WSDL for each interface describes if and how either of these standards is being used. For more information on WebLogic Server’s capabilities, see Securing WebLogic Web Services, a document in the WLS set. Access to a particular communication service is based on the two types of SLAs discussed in Service Level Agreements and Policy Enforcement.

For RESTful Web Services interfaces, Oracle Communications Services Gatekeeper supports HTTP basic authentication, using username/password. SSL is required.

In addition, if the underlying network node provides an authentication interface, Oracle Communications Services Gatekeeper protocol plug-ins can register with it and be authenticated, making the request’s transfer to the network secure.

Note: | This capability is highly dependent on the protocol and the specific implementation in the node and the plug-in.

### Events, Alarms, and Charging

All Oracle Communications Services Gatekeeper modules can produce general events, alarms and charging events. General events are expected system occurrences that are of importance to the operator but do not need corrective action. Alarms are system occurrences that are unexpected and may require corrective action. Charging events are the basis for CDRs, the records that provide the information needed to charge for services. CDRs are written only when the transaction that brackets the request’s flow through the Network Tier commits. For more information on events and charging, see “Events, Alarms, and Charging” in Communication Service Reference. For more information on alarms, see Handling Alarms. These books are separate documents in this set.

### Statistics and Transaction Units

Usage costs for Oracle Communications Services Gatekeeper are based on a maximum allowed rate (measured in transaction units per second or TUPS) during a specific time period per 24-hour interval. Two TUPS rates are measured: Base Platform - the more general rate - and Oracle Module - which covers only Oracle Communications Services Gatekeeper-supplied communication services. For more information on how these statistics are gathered, see Licensing, another document in this set.