Developer's Guide for Parlay X

Get
Adobe Reader

Parlay X Web Services API

The following sections describe the Parlay X Web Services API:

About Parlay X Web Services APIs

The Parlay X Web Services API offers a set of methods that adds telecom functionality to any application that uses Web Services.

The API is designed for rapid application development. From an architectural point of view, the implementation of the API resides on top of the service capability modules in WebLogic Network Gatekeeper.

All applications, accessing the WebLogic Network Gatekeeper through the Web Services interfaces uses a Kerberos type of service token-based authentication. The application is provided with a user name (the application instance group ID) and a password. When an application wants access to the WebLogic Network Gatekeeper the application instance logs in using the user name and password together with the application account ID and service provider ID to retrieve a service token. This mechanism may be extended, as an option using, for example Passport or other extended Kerberos Key Distribution Centre (KDC) authentication solutions.

To run a Parlay X Web Services application, access to either a WebLogic Network Gatekeeper or an ATE is needed, together with a set of WSDL files defining the API, login credentials and IDs of resources to use. These are provided by the service provider.

The Parlay X Web Services APIs are separated in different APIs. Each main component is contained in a specific module. The modules are:

Module	Defines
Third party call	Methods for handling application initiated calls.
Network-initiated third party call	Methods for handling network initiated calls.
SMS	Methods for handling sending and reception of SMS:es.
Multimedia Message	Methods for handling sending and reception of MMS:es.
Payment	Methods for handling charging based on content.
Terminal location	Methods for retrieving the geographical position of a mobile terminal.
User status	Methods for retrieving information on the status of mobile terminals.

In addition there is a an API, Access, that handles login-sessions towards WebLogic Network Gatekeeper. This API is specific for WebLogic Network Gatekeeper, and is not defined in the Parlay X standard. All Parlay X based applications that use the WebLogic Network Gatekeeper as a Parlay X Gateway use this API as an entry point.

All APIs, except Account Management, are supported by the WebLogic Network Gatekeeper. For detailed information on individual methods and WebLogic Network Gatekeeper specifics not covered by the standard, see API Description Parlay X for WebLogic Network Gatekeeper. For information on the standard itself, see Parlay X Specification, http://www.parlay.org.

WSDL files

There are two sets of WSDL files describing the Parlay X API

SOAP-encoded files. These are known as rpc/encoded files. These files do not use "import" statements. The files can be used in platforms such as .Net.
WS-I Basic Profile compliant files. These are known as rpc/literal files. This is the expected future-proof set of files. The drawback is that, currently, there are few tools supporting this approach.

The WebLogic Network Gatekeeper supports the Parlay X API using the SOAP encoding (RPC encoding) approach.

By default, the WSDL files can be fetched from:

http://<URL to WebLogic Network Gatekeeper>/parlayx/servlet/AxisServlet (The Web Services, also the endpoints)
The WSDL files for the northbound (Listener) interfaces can be fetched from
http://<URL to WebLogic Network Gatekeeper>/parlayx/wsdl (definitions of the listener interfaces)

Module	WSDL-file to download	API
Access	Access	Access This API is specific for WebLogic Network Gatekeeper, hence not part of the Parlay X specification.
Third Party Call	ThirdPartyCallPort	Call
Network Initiated Third Party Call	parlayx_network_initiated_call_service	Call
SMS	SendSmsPort	Send SMS
	parlayx_sms_notification_service	SMS Notification
Multimedia Message	SendMessagePort	Send Message
		Receive Message
	parlayx_mm_notification_service	Message Notification
Payment	AmountChargingPort	Amount Charging
	VolumeChargingPort	Volume Charging
	ReserveAmountChargingPort	Reserved Amount Charging
	ReserveVolumeChargingPort	Reserved Volume Charging
Terminal Location	MobileTerminalLocationPort	Terminal Location
User Status	UserStatusPort	User Status

For a description of the methods in each API, see API Description Parlay X for WebLogic Network Gatekeeper.

About the examples

The examples in this chapter are using Java and Axis. The invocation techniques used is JAX-RPC using Dynamic Invocation Interface. The WSDL files describing the services are used to generate stubs and skeletons in Java.

Workflow

The main program control flow when executing applications based on Parlay X Web Services is described in pseudo code in Figure 3-1, Application execution workflow, on page 3-5.

parlayXfor3GSM_api_general.html

See Login and retrieve login ticket.

See Define the security header.

See Get hold of a Port.

See Add security header.

See Invoke a method.

See Logout

Login and retrieve login ticket

To use any Web Service provided by WebLogic Network Gatekeeper, a login ticket is needed. A login is needed to retrieve the ticket. The login ticket identifies the login session. This ticket is valid until a logout is performed. The ticket is sent in each consecutive method invocation to identify the originator of the invoker.

Details about locators, endpoints, so on are explained later in this section

Listing 3-1 Login

        AccessService accessService = new AccessServiceLocator();

        java.net.URL endpoint = new java.net.URL(wsdlUrl);

        Access access = accessService.getAccess(endpoint);

        String sessionId = access.applicationLogin(spID,

                                                   appID,

                                                   appInstGroupID,

                                                   appInstGroupPassword);

The login ticket ID retrieved when invoking applicationLogin is used in each consecutive invocation towards WebLogic Network Gatekeeper. See Define the security header.

The login credentials; spID, appID, appInstGroupId, and appinstGoupPassword are provided by the service provider.

Define the security header

The login ticket ID, as retrieved when logging in, is sent in the SOAP header together with a username/password combination for each invocation of a Parlay X web service method.

Listing 3-2 Define the security header

org.apache.axis.message.SOAPHeaderElement header =

 new org.apache.axis.message.SOAPHeaderElement(wsdlUrl, "Security", "");

 header.setActor("wsse:PasswordToken");

 header.addAttribute(wsdlUrl, "Username", ""+userName);

 header.addAttribute(wsdlUrl, "Password", ""+sessionId);

 header.setMustUnderstand(true);

The login ticket is supplied in the Password attribute. The userName attribute is defined by the service provider, normally in the format
<myUserName>@<myapplication>.

The header is defined upon the object representing the Web Service port to use. Also see Add security header.

Get hold of a Port

Below is the code for getting hold of a port. The example is using the Send SMS API.

Listing 3-3 Get hold of a port

SendSmsService sendSmsService = new SendSmsServiceLocator();

java.net.URL endpoint = new java.net.URL(sendSmsWsdlUrl);

SendSmsPort sendSms = sendSmsService.getSendSmsPort(endpoint);

The details on the parameters of the send SMS API are described in API Description Parlay X for WebLogic Network Gatekeeper.

Add security header

Adding the security header to a request is straightforward, as illustrated below. For information on how create the header, see Define the security header.

Listing 3-4 Add security header

 ((org.apache.axis.client.Stub)sendSms).setHeader(header);

Invoke a method

Below it is illustrated how to get hold of a port. The example is using the Send SMS API.

Listing 3-5 Invoke a method

String sendID = sendSms.sendSms(eui, myMailbox, "CP_FREE", myMessage );

The details on the parameters of the send SMS API are described in API Description Parlay X for WebLogic Network Gatekeeper.

Logout

The logout destroys the login ticket.

Listing 3-6 Logout

access.applicationLogout(sessionId);

The login Ticket is destroyed and cannot be used in consecutive method invocations.

Access

Access API

This API is specific for WebLogic Network Gatekeeper, and is hence not part of the Parlay X specification.

The following functionality is provided:

Login an application to WebLogic Network Gatekeeper.
Logout an application from WebLogic Network Gatekeeper.
Change password.

For a description on how to use this API, see Login and retrieve login ticket and Logout. There is also support for changing the password.

Third Party Call

Call API

This API contains Web Services methods for handling application initiated, two-party telephony calls.

The following functionality is provided:

Connect two parties in a call.
End the call.
Get information about an ongoing call.
Cancel call setup.

Network Initiated Call

Call API

This API contains Web Services methods for handling network initiated calls.

It is a listener interface, which is implemented on the server-side of the application.

The following functionality is provided:

Get information on if the terminal of a called party is busy (off-hook before the call attempt).
Get information on if the called party is not reachable. For example, if a mobile terminal is switched off.
Get information on if a called party does not goes off-hook (No answer). If the called party has not answered after a certain time-interval. The time-interval is defined in the telecom network.
Get information on if a called party goes off hook.

Several possible actions can be taken when any of the above listed information reaches the application:

Continue the call handling with as it normally would be performed in the network.
Re-route to a called party specified by the application.
End the call.

All the above events originates from WebLogic Network Gatekeeper. The events comes in form of Web Service method invocations from WebLogic Network Gatekeeper to the end-point of the server-side of the application. The endpoint of the server-side application is defined off-line. The end-point details must be communicated to the service provider.

For more information on implementing Web Services, see Server-side Web Services using XML based RPC and Example: Server-side Web Service.

SMS

Send SMS API

This API contains Web Services methods for sending SMS:es.

The following functionality is provided:

Send SMS.
Send SMS logo.
Send SMS ringtone.
Get the delivery status of an SMS.

SMS Notification API

This API contains Web Services methods for getting notifications on new incoming SMSes.

It is a listener interface, which is implemented on the server-side of the application.

The following functionality is provided:

Get information on when a new SMS has arrived to WebLogic Network Gatekeeper.

For more information on implementing Web Services, see Server-side Web Services using XML based RPC and Example: Server-side Web Service.

Receive SMS API

This API contains Web Services methods for fetching SMSes.

The following functionality is provided:

Get SMSes that has arrived to WebLogic Network Gatekeeper.

Multimedia Message

Send Message API

This API contains Web Services methods for handling sending of multimedia messages. MMS and e-mail is supported.

The following functionality is provided:

Send message.
Get delivery status of a sent message.

Receive Message API

This API contains Web Services methods for fetching multimedia messages.

The following functionality is provided:

Poll for new messages.
Fetch individual messages.

Message Notification API

This API contains Web Services methods for getting notifications on new incoming multimedia messages.

It is a listener interface, which is implemented on the server-side of the application.

The following functionality is provided:

Get information on when a new multimedia message has arrived.

For more information on implementing Web Services, see Server-side Web Services using XML based RPC and Example: Server-side Web Service.

Payment

Amount Charging API

This API contains Web Services methods for handling charging in amount units based on content.

The following functionality is provided:

Charge an amount from a user's account.
Refund an amount to a user's account.

Volume Charging API

This API contains Web Services methods for handling charging in volume units based on content.

The following functionality is provided:

Charge a volume from a user's account.
Refund a volume to a user's account.
Convert a volume to an amount.

Reserved Amount Charging API

This API contains Web Services methods for reservation of amount units based on content.

The following functionality is provided:

Reserve an amount from a user's account.
Reserve and unreserved an additional amount.
Charge a reservation.
Refund funds left in a reservation and release the reservation.

Reserved Volume Charging API

This API contains Web Services methods for reservation of volume units based on content.

The following functionality is provided:

Get the amount that corresponds to a given volume.
Reserve a volume from a user's account.
Reserve an additional volume.
Charge a reservation.
Refund funds left in a reservation and release the reservation.

Terminal Location

Terminal Location API

This API contains Web Services methods to get the geographical position of a mobile terminal.

The following functionality is provided:

Get the location of a mobile terminal.

User Status

User Status API

This API contains Web Services methods to get the status of a terminal, for example busy and off hook.

The following functionality is provided:

Get the status of a user. Status can be one of the following: online, offline, busy, and other.

Addresses

Addresses are specified as EndUserIdentifiers. This is a datatype defined by Parlay X.

The EndUserIdentifier is defined as an Uniform Resource Identifier according to Specified as a URI: [scheme]:[schemeSpecificPart] (RFC 2396, amended by RFC 2732).

Where scheme is one of the following: [tel | sip | mailto] and schemeSpecificPart is the actual address.

Examples

If the address is a telephone number, the EnduserIdentifier is as follows: "tel:+461234567"

If the address is a e-mail address, the EnduserIdentifier is as follows: "mailto:someone@somecompany.com"

If the address is a sip telephone number, the EnduserIdentifier is as follows: "sip:someone@somecompany.com"

Data types and enumerations

Some datatypes, for example EndUserIdentifier, are defined by the Parlay X standard. These datatypes are defined using WSDL. Also some datatypes are enumerations of values.

Different programming languages uses different approaches for handling variables or classes of these types.

Using Java, it would look like this to define an EnduserIdentifier which holds a telephone number:

EndUserIdentifier eu = new EndUserIdentifier();
eu.setValue(new URI("tel", "4654176700"));

For a information on all datatypes, see API Description Parlay X for WebLogic Network Gatekeeper.