1 About Creating Applications that Interact with Services Gatekeeper

This chapter presents an overview of how you can develop applications that interact with Oracle Communications Services Gatekeeper.

See Services Gatekeeper Concepts for a complete description of the Services Gatekeeper structure and functionality.

Basic Concepts

These are the basic concepts you should understand before creating applications that can interact with Services Gatekeeper:

Understanding the Interfaces

In order to interact with Services Gatekeeper, applications use SOAP-based, RESTful, OneAPI, or native interfaces. For details about using these interfaces, see:

Also, see "Understanding the Supported Application Interfaces" for a list of the supported interfaces and a brief description of each.

Understanding 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, and so on), an application-facing interface (also called a north interface), and a network-facing interface (also called a south interface). See "Understanding Traffic Types" for details about these traffic types.

A request for service enters the communication service through one interface, is processed internally, including evaluation for policy actions and protocol translation, and then sent on using the other interface.

For an overview of communication services, see Services Gatekeeper Concepts.

For details about the communication services that Services Gatekeeper includes, see Services Gatekeeper Communication Service Reference Guide.

For details about administering and deploying communication services, see Services Gatekeeper System Administrator's Guide.

For information about creating your own custom communication services, see Services Services Gatekeeper Extension Developer's Guide.

Note:

A single application-facing interface may be using multiple protocols and hardware types in the underlying telecom network. However, an application is communicating, finally, with a specific communication service, and not only with the application-facing interface. So in some cases it is possible to send an application request to two different carriers that use different underlying network structures where the request behaves in slightly different ways, even though the initial request uses the same application-facing interface.

Understanding Traffic Types

In some communication services, request traffic can travel in two directions: from the application to the underlying network and from the underlying network to the application.

Understanding 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 could use the Third Party Call interface to set up a call. The initial request, MakeCall, is sent to Services Gatekeeper (which sends it on to the network). 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 callIdentifier to identify the specific call. The application then receives the requested information back from Services Gatekeeper synchronously.

Understanding 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 the message has been delivered by using the GetSmsDeliveryStatus request which functions such as GetCallInformation for application-initiated traffic. But it would be more convenient to have the network notify the application when the message has been delivered to the mobile phone. To do this, two things must happen:

  • The application must inform Services Gatekeeper that it wants to receive information that originates from the network. It does this by subscribing or registering for notifications using an application-initiated request. (In certain cases, registering can also be accomplished by the operator, using Oracle Access Manager (OAM) procedures.) Often this subscription includes filtering criteria that describes exactly what kinds of traffic the application wants 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 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.

Securing Applications from Malicious Traffic

See ”Securing Applications Against Malicious Traffic” in Services Gatekeeper Security Guide for details on how to protect Services Gatekeeper from malicious REST and SOAP traffic.

Adding Proxy Servers for Callbacks and Notifications

You can specify proxy servers to receive notifications or callback messages by adding them to the service provider or application SLA. Use the <proxyhost> and <proxyport> elements to specify the IP address and port number to listen on.

For details and an example, see the <proxyhost> and <proxyport> elements in Services Gatekeeper Accounts and SLAs Guide.

Understanding Mobile Applications

Application developers can create mobile applications running on devices such as smartphones and tablets that communicate with the Services Gatekeeper interfaces. Generally, the software development kit (SDK) for a mobile operating system, provided by the operating system vendor, includes the required tools for an application to communicate with Services Gatekeeper.

The following general guidelines list the basic steps used when developing a mobile application that communicates with Services Gatekeeper. The example provided uses the Google Android SDK. Though methods for interacting with web interfaces vary by operating system, the general procedure for other operating systems, such as Apple iOS or Microsoft Windows Phone, are similar.

To develop mobile applications that interface with Services Gatekeeper, consult the following sections:

Preparing a Development Environment

You must set up a development environment before developing a mobile application for use with Services Gatekeeper. You must include downloading and configuring the appropriate mobile operating system SDK, JDK and integrated development environment (IDE) such as Eclipse. For example, download the Android application development tools needed from the following web sites:

Configure your application development environment according to the requirements listed by your mobile operating system vendor. After setting up your development environment, create a project in your IDE where you will develop your application.

Creating a Mobile Application

This section explains the general steps required for interfacing with Services Gatekeeper from an Android mobile application. Application requirements vary depending on the mobile operating system you are using and the functionality you are providing. See the documentation for your mobile operating system SDK for procedures and examples for developing mobile application elements such as the user interface and security.

The following steps show how to call a Services Gatekeeper API RESTful interface from an Android application. This example creates a RESTful POST method in the IDE mobile application project and sends the request to Services Gatekeeper. You interact with other Services Gatekeeper interfaces in a similar way.

To create a POST operation to Services Gatekeeper using the Android SDK and Eclipse IDE:

  1. In the application project, create a JSON object using the org.json.JSONObject provided in the Android SDK.

  2. Populate the fields of this JSON object using the Services Gatekeeper communication service (or plugin) resource WADL file. See Communication Service Resource Guide for details on the communication services.

  3. Create an instance of the org.apache.http.client.methods.HttpPost object from the android.jar using the Services Gatekeeper RESTful service resource URL endpoint and the JSON object created in step 1 as the message parameters in the object.

  4. Create an org.apache.http.impl.client.DefaultHttpClient object to send the object created in step 3.

  5. Send the HttpPost object using the DefaultHttpClient object to the Services Gatekeeper RESTful interface. Services Gatekeeper provides a returned value as an object of org.apache.http.HttpResponse.

  6. Extract the JSON string included in the HttpResponse object returned by Service Gatekeeper.

  7. Create a JSON object from the extracted JSON string.

  8. Extract the desired fields required by your application from this JSON object.

Testing a Mobile Application

You must test your mobile application ensuring that it functions correctly. Mobile OS SDKs include emulators that can be used for testing the application against Services Gatekeeper. Alternatively, you can install the mobile application on a mobile device connected to your network for testing. See the mobile OS SDK documentation for more information about running your application for testing.

See "Understanding How to Test Applications" for information about testing your mobile application with Services Gatekeeper.

Distributing a Mobile Application

After completing sufficient testing of your application you distribute it to subscribers for use. Mobile OS vendors typically provide a store for application distribution. Alternative methods for distributing your application may also be available depending on mobile OS.

Understanding Management Structures

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 that is associated with an application account. Applications are assigned to service provider accounts. Each application account is associated with a service provider account. Application accounts with similar requirements are put into application groups, and service provider accounts with similar requirements are put into service provider groups. Each application group is associated with one application group service level agreement (SLA) and zero or more custom application group SLAs. Each service provider group is associated with one service provider group SLA and zero or more custom service provider group SLAs. These SLAs define and regulate the contractual agreements between the telecom operator and the application service provider. SLAs cover such things as which services the application may access and the maximum bandwidth available for use.

For more information about management structures, see Services Gatekeeper Portal Developer's Guide.

Understanding How to Test Applications

You test Applications in a telecom environment in stages. After basic functional issues are resolved, you can connect the application to an instance of Services Gatekeeper that is connected to the Platform Test Environment (PTE) network simulator for further 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 application test flow, from the functional tests to deployment in a live network. Services Gatekeeper simulator-based tests can be performed in-house by an application service provider. However, the other tests require the cooperation of the target network operator.

Figure 1-1 Application Testing Cycle

Description of Figure 1-1 follows
Description of ''Figure 1-1 Application Testing Cycle''

See Services Gatekeeper Platform Test Environment User's Guide for details about testing how your application works with a network simulator.