1 Creating Applications for Oracle Communications Services Gatekeeper

As the worlds of Internet applications and of telephony-based functionality continue to converge, many application developers have become frustrated by the unfamiliar and often complex telecom interfaces that they need to master to add even simple telephony-based features to their programs. By using Oracle Communications Services Gatekeeper, telecom operators can instead offer developers a secure, easy-to-develop-for single point of contact with their networks, made up of simple Web Service interfaces that can easily be accessed from the Internet using a wide range of tools and languages.

The following chapter presents an overview of Services Gatekeeper's functionality, and the ways that application developers can use this functionality to simplify their development projects.

Basic Concepts

There are a few basic concepts you need to understand to create applications that can interact with Services Gatekeeper:

• Communication Services

• Traffic Types

  • Application-initiated Traffic

  • Network-triggered Traffic

• Management Structures

Communication Services

The basic functional unit in Services Gatekeeper is the communication service. A communication service consists of a service type (Short Messaging, User Location, etc.), an application-facing interface (also called a “north” interface), and a network-facing interface (also called a “south” interface). A request for service enters through one interface, is subjected to internal processing, including evaluation for policy and protocol translation, and is then sent on using the other interface.

Note:

Because a single application-facing interface may be connected to multiple protocols and hardware types in the underlying telecom network, it's important to understand that an application is communicating, finally, with a specific communication service, and not just the north interface. So in some cases it is possible that an application request sent to two different carriers, with different underlying network structures, might behave in slightly different ways, even though the initial request uses exactly the same north interface.

Traffic Types

In some Services Gatekeeper communication services, request traffic can travel in two directions - from the application to the underlying network and from the underlying network to the application - and in others 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 of some kind is returned synchronously. So, for example, an application could use the Third Party Call interface to set up a call. The initial operation, MakeCall, is sent to Services Gatekeeper (which sends it on to the network) and a string, the CallIdentifier, is returned to the application synchronously. To find out the status of the call, the application makes a new request, GetCallInformation, using the CallIdentifier 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 return to the application. For example, the application might send an SMS to a mobile phone that the user has turned off. The network won't deliver the message until the user turns the phone back on, which might be hours or even days later. The application can poll to find out whether or not the message has been delivered, using GetSmsDeliveryStatus, which functions much like GetCallInformation described above. But given the possibly extended period of time involved, 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 subscribing or registering for notifications via an application-initiated request. (In certain cases, this can also be accomplished by the operator, using OAM procedures.) Often this subscription includes filtering criteria that describes exactly what kinds of traffic it wishes to receive. 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 implementing a Web Service endpoint on its own site to which Services Gatekeeper dispatches the notifications, or by polling Services Gatekeeper to retrieve them. Notifications are kept in Services Gatekeeper for retrieval for only limited amounts of time.

Management Structures

In order to help telecom operators organize their relationships with application providers, Services Gatekeeper uses a hierarchical system of accounts. Each application is assigned a unique application instance ID which is tied to an Application Account. All the Application Accounts that belong to a single entity are assigned to a Service Provider Account. Application Accounts with similar requirements are put into Application Groups and Service Providers with similar requirements are put into Service Provider Groups. Each Application Group is associated with an Application Group Service Level Agreement (SLA) and each Service Provider Group are associated with Service Provider Group SLAs. These SLAs define and regulate the contractual agreements between the telecom operator and the application service provider, and cover such things as which services the application may access and the maximum bandwidth available for use.

Functional Overview

Services Gatekeeper allows operators to provide client application developers with a choice of interface types, based on the needs of their applications. Services Gatekeeper provides SOAP-based Web Services interfaces, RESTful interfaces (see RESTful Application Development Guide), and even two native telephony interfaces (MM7 and SMPP).

Note:

The exact mix of interfaces depends on the specific Services Gatekeeper installation.

The SOAP-based Web Services APIs are based on the Parlay X 2.1 and 3.0 standards and also include three additional Extended Web Services ones to cover Binary SMS, Subscriber Profile, and WAP Push functionality, which are not supported by Parlay X. The functionality supported by these communication services includes:

• Third Party Call (Parlay X 2.1 and 3.0)

  Using this communication service, an application can set up a call between two parties (the caller and the callee), poll for the status of the call, and end the call. In addition, using the 3.0 communication only, an application can set up a call among multiple participants and add, delete, or transfer those participants. The application can also use the Audio Call communication service to play audio messages to one or multiple of the call participants set up using Third Party Call and, using notifications set up with Call Notification PX 3.0, can also collect digits in response to playing the audio message.

• Audio Call (Parlay X 2.1 and 3.0)

  Using this communication service, an application can play audio to one or more call participants in an existing call session set up by PX 3.0 Third Party call, find out if the audio is currently being played, and explicitly end playing the audio. It can also collect digits from a participant in response to an audio message, and in conjunction with a notification set up using Call Notification PX 3. 0, can return that information to the application. It can also interrupt an ongoing interaction such as on-hold music.

• Call Notification (Parlay X 2.1 and 3.0)

  Using this communication service, an application can set up and end notifications on call events, such as a callee in a third party call attempt is busy. In addition, in some cases the application can then reroute the call to another party. In addition, using the PX 3.0 communication service, an application can interact with PX 3.0 Audio Call to return digits collected from a call participant back to the application and to end calls.

• Device Capabilities (Parlay X 3.0)

  Using this communication service, an application can request a device's unique device ID, device/model name, and a link to the User Agent Profile XML file, or device's equipment identifier.

• Short Messaging (Parlay X 2.1)

  Using this communication service, an application can send SMS text messages, ringtones, or logos to one or multiple addresses, set up and receive notifications for final delivery receipts of those sent items, and arrange to receive SMSes meeting particular criteria from the network.

• Multimedia Messaging (Parlay X 2.1)

  Using this communication service, an application can send Multimedia Messages to one or multiple addresses, set up and receive notifications for final delivery receipts of those sent items, and arrange to receive MMSes meeting particular criteria from the network or to poll for such messages.

• Terminal Location (Parlay X 2.1)

  Using this communication service, an application can request the position of one or more terminals or the distance between a given position and a terminal. It can also set up and receive notifications based on geographic location or time intervals.

• Terminal Status (Parlay X 2.1)

  Using the Terminal Status communication service, an application can:

  • Obtain the status (reachable, unreachable, or busy) of a single terminal or group of terminals as often as you specify, within a time period you specify.

  • Return the status of a terminal or group of terminals if the status changes. The terminal statuses are checked as frequently as you specify, for a time period you specify, and the status is returned if it changes.

• Presence (Parlay X 2.1)

  Using this communication service, an application can be a watcher for presence information or a presentity (an end user who has agreed to have certain data, such as current activity, available communication means, and contact addresses made available to others). So a presentity might say that at this moment he is in the office and prefers to be contacted by SMS at this number. Before the watcher can receive this information, it must subscribe and be approved by the presentity. Once this is done, the watcher can either poll for specific presentity information, or set up status notifications based on a wide range of criteria published by the presentity. The presentity can control the kinds of information, or attributes, that he makes available to watchers.

• Payment (Parlay X 3.0)

  Using the communication service based on this interface, an application can charge an end user's account a specific amount, refund an amount, and split costs among multiple end user accounts. An application can also reserve an amount in an account, extend the amount associated with that reservation, make a charge against that reservation, and release the reservation.

• Binary SMS (EWS)

  Using the communication service based on this interface, an application can send and receive generic binary objects (for example, a vCard) using SMS mechanisms, and set up and receive notifications. This interface is not based on the Parlay X standards, but instead belongs to the Oracle Extended Web Services (EWS) set.

• WAP Push (EWS)

  The application-facing interface of this communication service is not based on the Parlay X 2.1 specification. Many elements within it, however, are based on widely distributed standards. Using the communication service based on this interface, an application can send a WAP Push message, send a replacement WAP Push message, or set up status notifications about previously sent messages.

• Subscriber Profile (EWS)

  The application-facing interface of this communication service is based on a subset of that in a proposed Parlay X version. Using this communication service, an application can retrieve particular information or an entire profile (subject to internal filtering) for a subscriber from an LDAP server attached to the network.

• Session Manager (EWS)

  Using this communication service, an application can establish a Services Gatekeeper session. Whether sessions are used is up to the operator.

There are three native telephony APIs supported by Services Gatekeeper.

• Native MM7

  The application-facing interface of this communication service is based on the 3GPP MM7 standard. Using the communication service based on this interface, an application can send and receive MMSs and receive status notifications about previously sent messages.

• Native SMPP

  The application-facing interface of this communication service is based on the SMS Forum standard. Using the communication service based on this interface, an application can send and receive SMSs and receive status notifications about previously sent messages.

• Native UCP

  The application-facing interface of this communication service is based on the Short Message Service Centre EMI-UCP Interface 5.0 specification. Using the communication service based on this interface, an application can send and receive SMSs and receive status notifications about previously sent messages.

Application Testing Workflow

Application testing in a telecom environment is usually conducted in a stepwise manner. For the first step, applications are run against simulators like the optional Services Gatekeeper Simulator. The Services Gatekeeper Simulator emulates both the Services Gatekeeper and the underlying network, and allows developers to sort out basic functional issues without having to be connected to a network or network simulator. Once basic functional issues are sorted through, the application is connected to an instance of the Services Gatekeeper attached to a network simulator for non-functional testing. Next the application is tested against a test network, to eliminate any network related issues. Finally, the application can be placed into production on a live network. Figure 1-1, "Application Testing Cycle" shows the complete application test flow, from the developer's functional tests to deployment in a live network. While Services Gatekeeper Simulator-based tests may be performed in-house by an Application Service Provider, the other tests require the cooperation of the target network operator.

Figure 1-1 Application Testing Cycle