NOKIA M2M GATEWAY 2.2 SERVICE PROVIDER EDITION ......Gateway Service Provider Edition1 to external billing systems. 1 Note that the billing support feature is included only in the

Cop

yrig

ht ©

200

2-20

03 N

okia

. All

right

s re

serv

ed.

Iss

ue 2

.0

935

5674

NOKIA M2M GATEWAY 2.2 SERVICE PROVIDER EDITION

BILLING SUPPORT PROGRAMMING GUIDE

Contents

ACRONYMS AND TERMS ......................................................................................................1 1. ABOUT THIS DOCUMENT ..............................................................................................2 2. INTRODUCTION..............................................................................................................3 3. BILLING EVENTS FROM THE GATEWAY......................................................................4

3.1 SESSION START ......................................................................................................4 3.2 SESSION END ..........................................................................................................4 3.3 MESSAGE TRANSMIT..............................................................................................5 3.4 WAKE-UP ..................................................................................................................5 3.5 SHORT MESSAGE....................................................................................................5

4. FIELDS OF BILLING EVENTS.........................................................................................6 4.1 COMMON FIELDS.....................................................................................................6

4.1.1 Transmit bearer info ...............................................................................................6 4.1.2 Billing session info..................................................................................................7 4.1.3 Billing info ...............................................................................................................7 4.1.4 Data unit .................................................................................................................8 4.1.5 Direction .................................................................................................................8 4.1.6 Session end reason................................................................................................8 4.1.7 Fail reason............................................................................................................10

4.2 SESSION START EVENT .......................................................................................10 4.3 SESSION END EVENT ...........................................................................................11 4.4 MESSAGE TRANSMIT EVENT...............................................................................11 4.5 WAKE-UP EVENT ...................................................................................................11 4.6 SHORT MESSAGE EVENT.....................................................................................12

5. BILLING ADAPTER........................................................................................................13 5.1 MEDIATOR INTERFACE.........................................................................................14

5.1.1 setTransportDriver() method ................................................................................14 5.1.2 close() method......................................................................................................14 5.1.3 Event processing methods ...................................................................................15

5.2 TRANSPORT DRIVER INTERFACE.......................................................................15 5.2.1 startTransport() method........................................................................................16

5.2.2 closeTransport() method ......................................................................................16 5.2.3 sendMessage(byte[] message) method ...............................................................16 5.2.4 Example Transport Driver ....................................................................................16

6. USING THE BILLING ADAPTER APPLICATION ..........................................................18 APPENDIX .............................................................................................................................19

Legal Notice

Copyright © 2002-2003 Nokia. All rights reserved.

Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice.

Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused.

The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

ACRONYMS AND TERMS

Acronym/term Description

CORBA Common Object Request Broker Architecture

CP Connection Provider

CSD Circuit Switched Data

DCD Data Carrier Detect

Downlink Connection away from the Nokia M2M Gateway

GGSN Gateway GPRS Support Node

GIOP General Inter-ORB Protocol

GPRS General Packet Radio Service

HTTP Hypertext Transfer Protocol

IDL Interface Definition Language

IP Internet Protocol

JAXP Java™ API for XML Processing

LCP Link Control Protocol

M2M Machine-to-Machine

MSISDN Mobile Subscriber ISDN Number

NAS Network Access Server

ORB Object Request Broker

RADIUS Remote Authentication Dial-in User Server

SMS Short Message Service

SMSC Short Message Service Centre

USSD Unstructured Supplementary Service Data

USSDC Unstructured Supplementary Service Data Centre

Uplink Connection towards the Nokia M2M Gateway

XML eXtensible Markup Language

1/20

1. ABOUT THIS DOCUMENT

This document specifies the Mediator and TransportDriver interfaces for implementing the generation and transfer of billing records from the Nokia M2M Gateway Service Provider Edition1 to external billing systems.

1 Note that the billing support feature is included only in the Nokia M2M Gateway Service Provider Edition and not in other editions.

2/20

2. INTRODUCTION

The Mediator and TransportDriver interfaces are part of the so-called Billing Adapter framework delivered by Nokia. It can be used as a basis for connecting the Gateway to external billing systems. Customers build their implementations on top of this framework.

The Billing Adapter gathers atomic billing events from the Gateway and composes these events into billing records suitable for the used billing system. The Gateway uses Common Object Request Broker Architecture (CORBA) Event Service for sending events to the Billing Adapter. The CORBA Event Service is not delivered by Nokia, but must be acquired separately.

M2Mapplication

Nokia M2MGateway Service Provider Edition Gateway

billing events

push pull

Event channel

Customerbilling

records

CORBAEvent

Service

M2MBilling

Adapter

Customerbilling

system

GSMnetwork

Nokia GSMConnectivity Terminals

SMSC/USSDCGGSNNAS

Figure 1. Billing architecture

3/20

3. BILLING EVENTS FROM THE GATEWAY

Billing from the Gateway is based on transmitted messages and communication sessions. Five different billing events are specified in Table 1.

Table 1. Billing events

Event type Description

SessionStartEvent Session establishment.

SessionEndEvent Session close.

MessageTransmitEvent GIOP message (M2M communication) routed via the Gateway.

WakeUpEvent Wake-up message sent by the Gateway to a terminal that is asking it to initiate a data call or open a GPRS context.

ShortMessageEvent Non-GIOP message, such as plain text SMS message or Smart Message, routed via the Gateway.

The CORBA Interface Definition Language (IDL) specifications for these events are described in the Appendix. The billing events are explained in the following chapters.

3.1 SESSION START A SessionStartEvent is generated when the connection is initiated either by the Gateway (downlink) or a terminal (uplink). With Short Message Service (SMS) and Unstructured Supplementary Service Data (USSD) bearers, the session starts when the Gateway handles the first message coming from or going to a terminal that belongs to a known domain. With General Packet Radio Service (GPRS) and Circuit Switched Data (CSD) bearers, the session starts when the Remote Authentication Dial-in User Server (RADIUS) notifies the Billing Manager of an opened connection.

3.2 SESSION END With SMS and USSD bearers, a SessionEndEvent is generated when no messages are transmitted within a given idle period. With GPRS and CSD bearers, a SessionEndEvent is generated when the RADIUS server notifies the Billing Manager of a dropped connection.

4/20

3.3 MESSAGE TRANSMIT A MessageTransmitEvent is generated when the Gateway has transferred a General Inter-ORB Protocol (GIOP) message to its destination. The message includes the count of used data units, and information on the session and on possible errors.

3.4 WAKE-UP A WakeUpEvent is generated when the Gateway sends an SMS to a terminal asking it to initiate a data call or to open a GPRS context.

3.5 SHORT MESSAGE A ShortMessageEvent is generated the Gateway transmits a message that is not GIOP-related, such as a text message or a smart message.

5/20

4. FIELDS OF BILLING EVENTS

This chapter describes all the events of the CORBA IDL specification (see the ).

All the used time values are presented as integers. These values show the time in milliseconds from the standard base time known as ‘the epoch’ (January 1st, 1970, 00:00:00 GMT).

4.1 COMMON FIELDS Some structures and constants are common to all events as described in Table 2.

Table 2. Common structures and constants

Structure/constant Description

TransmitBearerInfo Information on the session used in MessageTransmitEvents.

BillingSessionInfo Information on the session used in SessionStartEvents and SessionEnd Events.

BillingInfo Information on the used communication resources.

DataUnit Specifies the different communication resources.

Direction Direction of connection.

SessionEndReason Reason for closing the current session.

FailReason Reason for transmit failure.

4.1.1 Transmit bearer info The fields of TransmitBearerInfo structure are presented in Table 3.

Table 3. TransmitBearerInfo

Name IDL type Description

SessionID long long ID for the billing session.

Domain String Name of the domain.

ConnectionProviderName String Name of the Connection Provider (CP).

BearerType String SMS, USSD, GPRS, CSD, or TUNNELING.

Msisdn String Mobile Subscriber International ISDN N b (MSISDN) ( t d

6/20

Name IDL type Description ISDN Number (MSISDN) (not used with incoming CSD).

4.1.2 Billing session info The fields of the BillingSessionInfo are presented in Table 4.

Table 4. BillingSessionInfo

Name IDL type Description

SessionID long long ID for the billing session.

Domain String Name of the domain.

BearerType String SMS, USSD, GPRS, or CSD.

TerminalID String ID for a terminal.

NASAddress String Network address for the Gateway GPRS Support Node (GGSN), Network Access Server (NAS), Short Message service Centre (SMSC), or Unstructured Supplementary Service Data Centre (USSDC).

Port Short Port for SMSC or USSDC.

chargingID2 String Charging identifier (GGSN).

IPAddress String Internet Protocol (IP) address for M2M devices (used with CSD and GPRS bearers).

Msisdn String MSISDN (used with incoming SMS, USSD, and GPRS).

Imsi3 String Used with GPRS.

4.1.3 Billing info BillingInfo is a sequence of BillingData structures. The fields of the BillingData structure are presented in Table 5.

2 Attribute number 221 (reserved from the implementation specific range) contains the charging ID of a mobile station. The charging ID format is in binary coded decimal and contains four bytes. 3 Attribute number 224 (reserved from the implementation specific range) contains the International Mobile Subscriber Identity (IMSI) of a mobile station. The IMSI format is in binary coded decimal with extra four bits set to 1 for an odd number of digits, for example, 123 equals to hexadecimal bytes 21 F3.

7/20

Table 5. BillingInfo

Name Value Explanation

unit DataUnit Type of the used communication resource.

count long Number of used resources.

4.1.4 Data unit DataUnit specifies different kinds of communication resources. The fields of the DataUnit are presented in Table 6.

Table 6. DataUnit

Constant Value Description

GIOP_DATA_UP 0 GIOP data unit sent towards the Gateway.

GIOP_DATA_DOWN 1 GIOP data unit sent by the Gateway.

SMS_MESSAGE_UP 2 SMS sent towards the Gateway.

SMS_MESSAGE_DOWN 3 SMS sent by the Gateway.

USSD_MESSAGE_UP 4 USSD sent towards the Gateway.

USSD_MESSAGE_DOWN 5 USSD sent by the Gateway.

WAKE_UP_MESSAGE 6 Wake-up message sent by the Gateway.

4.1.5 Direction The fields of the Direction constant are presented in Table 7.

Table 7. Direction

Constant Value Description

DOWNLINK true Connection from the Gateway.

UPLINK false Connection towards the Gateway.

4.1.6 Session end reason The SessionEndReason constant describes the trigger for the SessionCloseEvent. The fields of the SessionEndReason are described in Table 8.

8/20

Table 8. Session end reason

Constant Value Explanation

UNKNOWN 0 The Gateway could not resolve the reason for session end.

USER_REQUEST 1 User requested the termination of service, for example with Link Control Protocol (LCP) Terminate or by logging out.

LOST_CARRIER 2 Data Carrier Detect (DCD) was dropped at the port.

LOST_SERVICE 3 Service can no longer be provided; for example, connection between the user and the host was interrupted.

IDLE_TIMEOUT 4 Idle timer expired.

SESSION_TIMEOUT 5 Maximum session length timer expired.

ADMIN_RESET 6 Administrator reset the port or session.

ADMIN_REBOOT 7 Administrator is ending the service at NAS, for example prior to rebooting it.

PORT_ERROR 8 NAS detected an error at the port that required ending the session.

NAS_ERROR 9 NAS detected an error (other than at the port) that required ending the session.

NAS_REQUEST 10 NAS ended the session for a non-error reason not listed here.

NAS_REBOOT 11 NAS ended the session in order to perform a non-administrative reboot.

PORT_UNNEEDED 12 NAS ended the session because resource usage fell below the low-water mark (for example, if a bandwidth-on-demand algorithm decided that the port was no longer needed).

PORT_PREEMPTED 13 NAS ended the session to allocate the port to a higher priority use.

PORT_SUSPENDED 14 NAS ended the session to suspend a virtual session.

SERVICE_UNAVAILABLE 15 NAS was unable to provide the requested service.

9/20

Constant Value Explanation

CALLBACK 16 NAS is terminating the current session in order to perform call-back for a new session.

USER_ERROR 17 Termination of the session due to an error in user input.

HOST_REQUEST 18 Login host terminated the session normally.

M2M_GATEWAY_MAX_TIME 99 Session reached its maximum alive time.

M2M_GATEWAY_IDLE_TIME 100 Session reached its idle time, for example, no SMS messages were sent within this session during the last 10 minutes.

M2M_GATEWAY_SHUTDOWN 101 The Gateway is shutting down

4.1.7 Fail reason The fail reason describes the reason for a failed transmit event. A successful transmission is presented with the value 0. For more information, please contact Nokia’s technical support.

4.2 SESSION START EVENT The fields of the SessionStartEvent are described in Table 9.

Table 9. SessionStartEvent

Name IDL type Explanation

gatewayID string ID of the Gateway.

sessionInfo BillingSessionInfo Session identification.

startTime long long Start time of the session.

direction Direction Direction of connection (uplink/downlink).

10/20

4.3 SESSION END EVENT The fields of SessionEndEvent are described in Table 10.

Table 10. Session end event




startTime long long Start time of the session.

endTime long long End time of the session.

direction Direction Direction of connection (uplink/downlink).

billingInfo BillingInfo Information on the used communication resources.

reason SessionEndReason Reason for closing the session.

4.4 MESSAGE TRANSMIT EVENT The fields of the MessageTransmitEvent are described in Table 11.

Table 11. Message transmit event



upSessionInfo TransmitBearerInfo TransmitBearerInfo for uplink direction.

downSessionInfo TransmitBearerInfo TransmitBearerInfo for downlink direction.

upTime long long Time a message was received by the Gateway.

downTime long long Time a message was sent by the Gateway.

billingInfo BillingInfo Information on the used communication resources.

reason FailReason Reason for transmit failure.

4.5 WAKE-UP EVENT The fields of the WakeUpEvent are described in Table 12.

11/20

Table 12. WakeUpEvent




connectionProviderName string Name of the CP.

bearerType string SMS, USSD, GPRS, or CSD.

address string Destination address of the WakeUpEvent.

4.6 SHORT MESSAGE EVENT The fields of the ShortMessageEvent are described in Table 13.

Table 13. ShortMessageEvent


messageType string ‘SmartMessage’ or ‘TextMessage’.


domain string Name of the domain.

connectionProviderInstanceName

string Name of the CP instance

bearerType string SMS or USSD.

msisdn string Destination address (MSISDN) of the WakeUpEvent.

time long long Time of the event.

direction Direction Direction of the message.

databytes long Number of transferred bytes.

12/20

5. BILLING ADAPTER

All Billing Adapter classes and interfaces belong to a Java™ language package named com.nokia.m2m.billingadapter, delivered by Nokia. The event classes generated from the IDL specifications are in a package named com.nokia.m2m.billingadapter.billingevents. The IDL file is also included in the Billing Adapter so that customers can generate their own classes from the IDL specifications for the Object Request Broker (ORB) they are using.

The Billing Adapter framework consists of three components: control classes, Mediator interface, and TransportDriver interface.

Billing Adapter

Event Service

Custommediator

implementation

Controlclasses

Mediator TransportEventchannel

Customtransport

implementation

pull

Figure 2. Components of the Billing Adapter

Control classes are already implemented and they:

• Start up the Billing Adapter

• Dynamically load Mediator and TransportDriver implementations

• Start listening to the event channel where the Gateway pushes the billing events

• Pass events to the Mediator implementation

For complete reference, see the Javadoc documentation of the classes in the com.nokia.m2m.billingadapter package.

13/20

5.1 MEDIATOR INTERFACE The purpose of the Mediator component is to construct messages for the used billing system.

The Mediator interface has five methods that must be implemented.

Mediator interface methods include com.nokia.m2m.billingadapter.billingEvents.*; public interface Mediator { void processMessageTransmit(messageTransmitEvent); void processSessionEnd(SessionEndEvent event); void processSessionStart(SessionStartEvent event); void processWakeUp(WakeUpEvent event); void processShortMessage(ShortMessageEvent event) void setTransportDriver(TransportDriver driver); void close(); }

5.1.1 setTransportDriver() method This method is called by the startAdapter() method of the BillingAdapter class. StartAdapter() dynamically loads both the Mediator and the Transport driver implementations, and uses the setTransportDriver() method to set the driver for the Mediator.

5.1.2 close() method The Billing Adapter calls this method when it is shutting down. This method should include the necessary actions for a controlled shutdown of the Mediator implementation.

14/20

5.1.3 Event processing methods All five billing events have an event processing method of their own, which is called by the Billing Adapter framework. The event is given as a parameter. These methods should process the billing events and the generated billing records to a suitable format for the used billing system using the TransportDriver implementation transport.

In the following example, an eXtensible Mark-up Language (XML) message is constructed from a billing event. After the XML message is generated, it is converted to a byte array so that the TransportDriver method writeMessage(byte[] record) can be used.

An example of Mediator implementation import javax.xml.transform.dom.*; import javax.xml.transform.*; import javax.xml.transform.stream.*; import org.w3c.dom.*; import java.io.*; public void processSessionStart(com.nokia.m2m.billingadapter.billingEvents.SessionStartEvent event) { try { // create new XML Document // containing information from the billing event // create String presentation from the XML Document // String to bytes // init transport driver.startTransport(); // write message driver.writeMessage(bytes); } catch (Exception exception) { // handle exception } }

5.2 TRANSPORT DRIVER INTERFACE The TransportDriver implementation transports the generated billing records to the billing system of the customer.

15/20

The TransportDriver has three different methods that must be implemented.

TransportDriver interface methods package com.nokia.m2m.billingadapter; public interface TransportDriver { void startTransport(); void closeTransport(); void sendMessage(byte[] message); }

5.2.1 startTransport() method This method initialises the connection to the used billing system.

5.2.2 closeTransport() method This method closes the connection.

5.2.3 sendMessage(byte[] message) method This method writes the generated billing record to the connection initialised by the startTransport() method.

5.2.4 Example Transport Driver In this example, billing records are transported to a billing system over Hypertext Transfer Protocol (HTTP). An example servlet reads the transported record from ServletInputStream.

An example of TransportDriver implementation package com.nokia.m2m.billingadapter; import java.io.*; import java.net.*; public class ExampleTransportDriver implements TransportDriver { private HttpURLConnection connection = null; public ExampleTransportDriver() { super(); } public void startTransport() { try { // Create new URL and connect to it } catch (Exception e) {

16/20

// handle exception } public void stopTransport() {} // close URL connection public void writeMessage(byte[] message) { try { // create OutPutStream // write message to OutPutStream // close stream // get responsecode } catch (Exception e) { // handle exception } }

17/20

6. USING THE BILLING ADAPTER APPLICATION

The Billing Adapter can be started with a start-up script that depends on the operating system. In Windows environment, this may be, for example, billing_adapter_visibroker.bat, and in Unix environments, for example, billing_adapter_visibroker.sh. These files are located in the bin directory of the Gateway. The start-up scripts call the main() method of the BillingAdapter class.

The shutdown script, for example shutdown_billing_adapter_visibroker.bat or shutdown_billing_adapter_visibroker.sh depending on the used operating system, stops the Billing Adapter. These files are located in the bin directory of the Gateway.

Set the properties by placing the billingadapter.properties file, located in the lib directory of the Gateway, to the classpath of the system. The needed properties are:

• Reference of the used event channel

• The used Mediator and TransportDriver implementation classes

• Parser class settings that used to initialise the parser factory (parsing of the atomic billing events follows the factory design pattern)

An example of a billingadapter.properties file #event channel initial reference ORBInitRef.M2MBillingEventChannel=corbaname:rir:#BillingEventChannel #Transportdriver implentation wipunen.billingadapter.transportdriver= com.nokia.m2m.billingadapter.ExampleTransportDriver #mediator implentation wipunen.billingadapter.mediator= com.nokia.m2m.billingadapter.ExampleMediator # available parser class for billing events wipunen.billingadapter.eventfactory.SessionStart=com.nokia.m2m.billingadapter.SessionStartParser wipunen.billingadapter.eventfactory.SessionEnd=com.nokia.m2m.billingadapter.SessionEndParser wipunen.billingadapter.eventfactory.MessageTransmit=com.nokia.m2m.billingadapter.MessageTransmitParser wipunen.billingadapter.eventfactory.WakeUp=com.nokia.m2m.billingadapter.WakeUpParser wipunen.billingadapter.eventfactory.ShortMessage.class=com.nokia.m2m.billingadapter.ShortMessageParser

Note: The example application writes data in XML format, and this is why Java API for XML Processing (JAXP) is required.

18/20

APPENDIX

CORBA IDL specifications for billing events #pragma prefix "com.nokia.m2m" module billingEvents { typedef boolean Direction; const Direction UPLINK = TRUE; const Direction DOWNLINK = FALSE; struct TransmitBearerInfo { long long sessionID; string domain; string connectionProviderName; string bearerType; string msisdn; }; struct BillingSessionInfo { long long sessionID; string domain; string bearerType; string terminalID; string networkAddress; short port; string chargingID; string address; string msisdn; string imsi; }; typedef octet DataUnit; const DataUnit GIOP_DATA_UP = 0; const DataUnit GIOP_DATA_DOWN = 1; const DataUnit SMS_MESSAGE_UP = 2; const DataUnit SMS_MESSAGE_DOWN = 3; const DataUnit USSD_MESSAGE_UP = 4; const DataUnit USSD_MESSAGE_DOWN = 5; const DataUnit WAKE_UP_MESSAGE = 6; struct BillingData { DataUnit unit; long count; }; typedef sequence <BillingData> BillingInfo; typedef octet SessionEndReason; typedef long FailReason; struct SessionStartEvent { string gatewayID; BillingSessionInfo sessionInfo; long long startTime; Direction direction; }; struct SessionEndEvent {

19/20

20/20

string gatewayID; BillingSessionInfo sessionInfo; long long startTime; long long endTime; Direction direction; BillingInfo billingInfo; SessionEndReason reason; }; struct MessageTransmitEvent { string gatewayID; TransmitBearerInfo upSessionInfo; TransmitBearerInfo downSessionInfo; long long upTime; long long downTime; BillingInfo billingInfo; FailReason reason; }; struct WakeUpEvent { string gatewayID; BillingSessionInfo session; string connectionProviderName; string bearerType; string address; }; struct ShortMessageEvent { string messageType; string gatewayID; string domain; string connectionProviderInstanceName; string bearerType; string msisdn; long long time; Direction direction; long databytes; }; };

Documents

NOKIA M2M GATEWAY 2.2 SERVICE PROVIDER EDITION ......Gateway Service Provider Edition1 to external billing systems. 1 Note that the billing support feature is included only in the