1 Overview of How Applications Interact with Services Gatekeeper

This chapter presents an overview of Oracle Communications Services Gatekeeper functionality, and the ways that application developers can use this functionality to interact with Services Gatekeeper.

Basic Concepts

This section provides an overview of the basic concepts you need to know in order to create applications that successfully interact with Services Gatekeeper.

Communication Services

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

Services Gatekeeper supplies facades for traditional SOAP Web Services interfaces, RESTful interfaces, and, in some cases, native telephony interfaces. This document focuses on the RESTful interfaces in Services Gatekeeper.

For more information on communication services, see Oracle Communications Services Gatekeeper Communication Service Guide.

Traffic Types

In some Services Gatekeeper communication services, request traffic can travel in two direction: from the application to the underlying network and from the underlying network to the application. In other communication services, traffic flows in one direction only.

Application-initiated Traffic

In application-initiated traffic, the application sends a request to Services Gatekeeper, the request is processed, and a response is returned synchronously.

For example, an application uses the Third Party Call interface to set up a call. The initial operation, Make Call, is sent to Services Gatekeeper (which sends it on to the network) and a string that identifies the call is returned to the application synchronously. To query the status of the call, the application makes a new request, Get Call Information, using the call identifier string to identify the specific call, and then receives the requested information back from Services Gatekeeper synchronously.

Network-triggered Traffic

In many cases, application-initiated traffic provides all the functionality necessary to accomplish the desired tasks. But there are certain situations in which useful information may not be immediately available for returning to the application.

For example, an application might send an SMS to a mobile phone that the user has turned off. The network will not deliver the message until the user turns the phone back on. The application can poll to find out whether or not the message has been delivered, using Get SMS Delivery Status, which functions much like Get Call Information described above.

The period of time involved in delivering the message could be hours or extend to days. As a result, it would be convenient simply to have the network notify the application once delivery to the mobile phone has been accomplished. To do this, two things must happen:

• The application must inform Services Gatekeeper that it wishes to receive information that originates from the network. It does this by beginning a notification via an application-initiated request. Depending on the underlying network configuration, Services Gatekeeper itself, or the operator using manual steps, informs the underlying network about the kind of data that is requested. These notifications may be status updates, as described above, or, in some instances, may even include short or multimedia messages from a terminal on the telecom network

• The application must arrange to receive the network-triggered information, either by setting up a subscription with Services Gatekeeper or by polling Services Gatekeeper directly to retrieve them. (Bayeux is the protocol that Services Gatekeeper requires applications to use to communicate with the server in association with RESTful interfaces. See "Bayeux Protocol".) Such notifications are kept in Services Gatekeeper for retrieval for only limited amounts of time.

Management Structures

Services Gatekeeper uses a hierarchical system of accounts and service level agreements to regulate the contractual agreements between the telecom operator and the application service provider. For more information on management structures, see Oracle Communications Services Gatekeeper Accounts and SLAs Guide.

Included Interfaces

RESTful Web Services consist of interfaces that provide applications with the operations they use to interact with Services Gatekeeper. The following interfaces are included in Services Gatekeeper:

• Third Party Call

  Applications use the Third Party Call interface to set up a call, get information on that call, cancel the call request before it is successfully completed, or end a call that has been successfully set up.

• Call Notification

  Applications use the Call Notification interface to set up and remove call notifications. Such notifications inform the application about the state of a call (busy, unreachable and so on) or to set up and remove call direction notifications (in which the application is queried for information on handling a call that is in a particular state).

• Short Messaging

  Applications use the SMS interface to send an SMS, a ringtone, or a logo, and to fetch SMSes and delivery status reports that have been received for the application and stored on Services Gatekeeper. It also allows an application to start and stop a notification.

• Multimedia Messaging

  Applications use the MMS interface to send an MMS and to fetch information on MMSs for the application that have been received and stored on Services Gatekeeper. It also allows the application to fetch those messages. The application can also get delivery status on sent messages, and start and stop a notification.

• Terminal Location

  Applications use the Terminal Location interface to get a location for an individual terminal or a group of terminals; to get the distance of the terminal from a specific location; and to start and stop notifications, based on geographic location or on a periodic interval.

• Audio Call

  Applications use the Audio Call interface to get an audio file from an independent location and send it to a terminal.

• Presence

  Applications use the Presence interface to act as either of two different parties to a presence interaction: as a presentity or as a watcher.

  A presentity agrees to have certain data (called attributes) such as current activity, available communication means, and contact addresses made available to others. As a presentity, an application can publish presence data about itself, check to see if any new watchers wish to subscribe to its presence data, authorize those watchers it chooses to authorize, block those it wishes not to have access, and get a list of currently subscribed watchers.

  A watcher is a consumer of such information. As a watcher, an application can request to subscribe to all or a subset of a presentity's data, poll for that data, and start and end presence notifications.

• Payment

  Applications use the Payment interface to charge an amount to an end-user's account using Diameter, refund amounts to that account, and split charge amounts among multiple end-users. An application can also reserve amounts, reserve additional amounts, charge against the reservation or release the reservation.

• WAP Push

  Applications use the WAP Push interface to send a WAP Push message and to receive status notifications about that message.

• Subscriber Profile

  Applications use the Subscriber Profile interface to query an operator's database for the attributes of an individual subscriber profile (for example, the terminal type), or for entire subscriber profiles.

• Session Manager

  Applications use the Session Manager interface to establish a session with the Services Gatekeeper operator. Operators can choose whether to use Services Gatekeeper in session-based mode.

Application Testing Workflow

You can develop applications and test them using the Application Test Environment (ATE).

This tool hosts a set of virtual communication services that correspond to many of the communication services provided by Services Gatekeeper. For example, you can test tasks such as opening sessions, sending and receiving messages, and examining delivery reports through a set of virtual communication services without having to connect to the network operator´s Services Gatekeeper installation.

For more information on using the Application Test Environment, see Oracle Communications Services Gatekeeper SDK User's Guide.