MobiConnect™ Connectivity Framework - Chilliwire · can be a host‐to‐host connection to a...

MobiConnect™ Connectivity Framework

COPYRIGHT NOTICE: All rights reserved. This document contains information of proprietary nature. All information contained herein shall be kept in strict confidence. No part of this document may be reproduced, in any form or any means, without permission in writing from Chilliwire Technologies Sdn Bhd. None of this information shall be divulged to persons other than Chilliwire Technologies Sdn Bhd employees authorized by the nature of their duties to receive such information, or to individuals of organizations authorized by Chilliwire Technologies Sdn Bhdn in accordance with existing policy regarding the release of such information.

MobiConnect™

Copyright ©2007 Chilliwire Technologies Sdn Bhd | 1

obiConnect™ is a development framework which enables connections to Telco Operator Recharge Systems to provide electronic voucher reload systems. These systems can be a Direct Telco Operator Recharge System or an Intermediation Recharge System.

A Direct Telco Operator Recharge System is a recharge system which is provided by A Telco Operator for any electronic dealers (can be Master Dealers, Retailers) to reload its electronic vouchers. The Telco Operator provides gateways for electronic dealers to connect to their recharge system. The gateways can be a host‐to‐host connection to a server which implements a specific protocol likes ISO8583, RPC‐XML, etc. or any others devices which assist to reload an electronics voucher. The device can be a GSM modem which implements USSD protocol to reload an electronics voucher.

An Intermediation Recharge System is a recharge system which is provided by an institution which provides an electronic voucher reload system for a Telco Operator. This institution has a host‐to‐host connection to a Direct Telco Operator Recharge System and provides a gateway for any other electronic dealers which don’t have a direct host‐to‐host connection to the Telco Operator. The electronic dealers benefit the gateway as an intermediation to connect to the Telco Operator Recharge system. In common the connection between an electronic dealer and an Intermediation Recharge System follows the protocol which is defined by the institution providing the system.

As a part of MobiChargeTM, MobiConnectTM provides connections to a recharge system not only for MobiChargeTM, but also provides it for other electronic dealers. This is enabled by deploying a host‐to‐host connection base on a specific protocol.

M

MobiConnect™


MobiConnectTM Connection Model

MobiConnect™


MobiConnectTM consists of the following components:

MobiConnectTM Components

MobiConnect™


1. Incoming Gateway

Base on who initiate a request, there are two request types which will be handled by the MobiConnectTM. The first is electronic recharge requests from the MobiChargeTM and the second is electronic recharge requests from other electronic dealers.

Referring to the requests, MobiConnectTM provides two internal connectors. The first is the MobiChargeTM Incoming Connector which handles all incoming requests from MobiChargeTM. The second is the External Connector which is a port of the Incoming Gateway that has responsible to receive all incoming requests from other electronic dealers and return back a response related to the request.

A request come in to an incoming gateway will be proceeded to the selector component. The component will extract the request data and will identify the type of the request mode. There are two type of the request. There are:

• Recharging request is a request which is intended to recharge an electronic voucher.

• Maintenance request is a request which is intended to maintain a recharge gateway or to get parameter status of a recharge gateway.

If the request is a recharging mode then the request will be passed to a balancer, but if the request is a maintenance mode then the request will be passed directly to a recharge gateway connector.

The balancer will distribute the request to a recharge gateway by considering the loading of the gateway. It will make the gateways inside a group to be in balance. The group can be made based on:

• Telco company

• Product type

• Region

• Etc.

After balancing the request, the data will be encapsulated before passing to a recharge gateway which is determined by the request balancer.

MobiConnect™


2. Recharge Gateway

This component will provide a connection to an electronic recharge system. This system can be provided by a Telco company it self or can be provided by another electronic dealer (Intermediation Recharge System).

The connection between this gateway and a Recharge System can be a host‐to‐host connection which follows a specific protocol or can be implemented using another device like a GSM modem. Sometimes in order to make a connection to a Recharge System, the MobiConnectTM will elaborate with another third party application to deploy a gateway.

MobiConnect™


MobiConnectTM Features

1. Platform independence

MobiConnectTM is developed under pure java application. It is deployed under a web server in a wide variety of platforms including Windows 98/NT/2000/ME/XP, Linux, and Solaris. It is also supported by using My SQL as MobiConnectTM database which could be deployed under any platforms.

2. System Scalability

The MobiConnectTM is developed base on a HTTP protocol and internet technology. It makes the system could be extended easily. Any components of the system could be deployed in a different server as long as supported by an internet connection.

3. Secured data

The data that is sent among the systems is encapsulated in a bean. The bean must be implemented in any involved systems. Without the bean, the data cannot be extracted.

For handling an external request, the data is interchanged following the ISO8583 protocol. This is the standard protocol for a finance transaction. It is secure as the data can only be extracted by the system which has the same template as the sender.

4. Multi protocols supported

The MobiConnectTM can connect to any recharging systems by developing a recharge gateway. The gateway could be developed under an ISO8583 protocol, a XML RPC protocol, a USSD Command, or any other protocols.

5. Ease to maintain

By implementing a HTTP Request/Response, the maintenance request could be handled remotely. Starting and stopping a service and also getting a status of the service could be done remotely. It makes the maintenance process could be run by an engineer in distance away from the server.

MobiConnect™


6. Ability to send / receive asynchronously

By extending an HTTPServlet from the J2EE package, The MobiConnectTM could receive and respond to requests via a HTTP channels. By utilizing the java.lang.Thread package from Sun since version 1.1, and implementing an asynchronous HTTP Request / Response, the data can be interchanged asynchronously and provide real‐time transaction.

7. Ability to change a system property on the fly

The system properties are stored in a configuration file. They are loaded when the system started. By providing maintenance functions embedded in a HTTPservlet, the altering a property value can be done without disturb the system.

MobiConnect™


MobiConnectTM Functional Specifications

All MobiConnectTM components are developed using J2SE development tools. They are running under an application server likes the Tomcat Server or the Jetty Server. The components need a database server as a media to keep the data.

MobiConnectTM Incoming Gateway

MobiChargeTM Connector

The function of this component is to receive a request from another component of MobiChargeTM. The request is sent to the gateway using a HTTP protocol. The data is sent by the MobiChargeTM using the Post method and is encapsulated in a Request Bean. It means the data could only be extracted by the system which has the same request bean.

The MobiChargeTM and the MobiConnectTM could be located in a different area even in different countries. In this case, the data is sent via the internet. Therefore it needs a security aspect to make sure that the request comes from the right person.

The Request Bean consists of the following parameters:

• Username

It is a string parameter which identifies the user that sends the request.

• Password

It is a string parameter which is matched with the username. The username and the password become parameters which determine that the request come from the right person.

MobiConnect™


• Method

It is a string value which identifies a request mode. It can be a recharging request or a maintenance request.

• Data

It can be any object value. In this case, a vector value is used to populate all information related to a request. The variable information which the vector contains depends on the request mode.

A recharging request contains variables as following:

1. Transaction ID

This ID is a reference ID of every recharging request. The requestor could check the status of a recharging request by referring to the ID.

2. MSISDN Number

This is a mobile phone number.

3. Product Code

The product code is a code which represents an electronic voucher. This code commonly contains information about product type and product value.

Variables which a maintenance request contains would be different among recharge gateways. However they commonly contain the following information:

1. Gateway ID

This ID represents a recharge gateway. Every recharge gateway has a specific ID and it must be different between each other.

MobiConnect™


2. Action Type

This variable tells a recharge gateway what have to be done by the gateway. It can be a starting or stopping instruction, a status requesting, a configuration requesting, etc.

3. Subsystem ID

This variable is related to the action type. If the variable has a value, commonly the action type is addressed to the subsystem.

Other variables might be added to the data depend on the action type and the gateway which the action is addressed to.

External Connector

External connection is provided by a connector by implementing a host‐to‐host connection following the ISO 8583 version 1987 protocol. The External Connector acts as an ISO Server on the other hand a connection gateway which is provided by an electronic dealer acts as an ISO Clients. The server and the client are built by extending a socket server and a socket client.

The ISO 8583 is a standard financial protocol for data interchanging. There are two message types which are supported by the connector. They are:

1. Recharging message

This is a message which is intended to reload an electronic voucher.

2. Network management message

This is a message which is intended to handle network maintenance. The maintenance which is supported by the connector is only an Echo message. An electronic dealer sends this message to check the connection status between his gateway and the external connector.

The message which is sent by a dealer gateway is started with a message header. The header is a two bytes network byte which represents the length of the message without the header. After the header, the message is followed by the following fields:

MobiConnect™


1. Recharging Message

Field 0: Message Type Indicator – The value is ‘0200’ for a request and ‘0210’ for a response. This is the specific code for recharging message. This field is mandatory.

Field1: Bitmap – This is a 16 byte hexadecimal. This field represents the availability of the other fields. This field is mandatary.

Field2: Account ID – This is a LLVar (19), a character type up to 19 characters length which is following the 2 byte integers of the character’s length. This field is mandatory. This field represents an ID of an electronic dealer.

Field7: Transaction Date – This is a numeric (10), a numeric type with 10 numeric characters length. The format is ‘MMDDHHmiss’. This field is mandatary. This field represents a date and time when an external request sent.

Field11: Transaction ID – This is a numeric (6), a numeric type with 6 numeric characters length and ‘0’ right padded. The field is mandatory. This field represents an id which is unique for every request which is received within a day.

Field32: Password – This is a LLVar (11), a character type up to 11 characters length which is following the 2 byte integers of the character’s length. This field is mandatory of a request. The field represents a password which is owned by the Account ID of an electronic dealer.

Field34: Private Data – This is a LLVar (28), a character type up to 28 characters length which is following the 2 byte integers of the character’s length. The field is optional of a request and represents a private data for an electronic dealer internal purpose.

Field39: Response Code – This is a numeric (2), a numeric type with 2 numeric characters length. The field is mandatory of a response which indicates a response status of a request.

Field41: Product Code – This is a Var (8), a character type with 8 characters length and space left padded. This field is mandatory and represents a product code which is requested by an electronic dealer.

Field53: MSISDN – This is a numeric (16), a numeric type with 16 numeric characters length and space left padded. This field is mandatory and represents a mobile phone number which need to be recharged.

MobiConnect™


Field55: Response Detailed – This is a LLLVar (999), a character type up to 999 characters length which is following the 3 byte integers of the character’s length. This field is mandatory of a response and describes the response code in detailed.

2. Network Management Message

Field 0: Message Type Indicator – The value is ‘0800’ for a request and ‘0810’ for a response. This is the specific code for recharging message. This field is mandatory.

Field1: Bitmap – This is a 16 byte hexadecimal. This field represents the availability of the other fields. This field is mandatary.

Field7: Transaction Date – This is a numeric (10), a numeric type with 10 numeric characters length. The format is ‘MMDDHHmiss’. This field is mandatary. This field represents a date and time when an external request sent.

Field11: Transaction ID – This is a numeric (6), a numeric type with 6 numeric characters length and ‘0’ right padded. The field is mandatory. This field represents an id which is unique for every request which is received within a day.

Field39: Response Code – This is a numeric (2), a numeric type with 2 numeric characters length. The field is mandatory of a response which indicates a response status of a request.

Field70: Network Management Code – The value is ‘301’ indicating an echo request.

MobiConnect™


Gateway Group Selector

Gateway Group Selector Flow Diagram

MobiConnect™


The request which is received by the connector is sent to the gateway group selector. If the request comes from an external connector then the request is a recharging request.

If the request comes from the MobiChargeTM then the request needs to be identified whether it is a recharging request or a maintenance request. Identifying a request from the MobiChargeTM is base on the method parameter in a request bean. This parameter could be ‘Recharging’ or ‘Maintenance’.

If the request is a recharging request then the request must be matched to a gateway group. The matching process is made base on the Telco Operator, product code and region. The information about the Telco Operator and the product code can be identified at product code. If a gateway group is made by considering a region, the information about the region can be extracted from the prefix of a MSISDN. By defining a gateway group, the request is sent to a appropriate gateway group balancer.

The maintenance request which is identified base on the method parameter is directly sent to a recharge gateway connector to be encapsulated before sending to a recharge gateway.

Gateway Group Balancer

A balancer has responsibility to balance request handling by servers within a group. This component works base on a round‐robin concept. The first request is handling by the first gateway. The next request will be handled by the next gateway until the maximum number of gateway reached. If all gateways have ever received a request, the next request will be processed by the first gateway. This is the way to make gateways within a group run on balance.

Recharge Gateway Connector

After determined the pointed server which is going to handle the request, the request needs to be encapsulated in a request bean. The request bean structure is similar with the request bean which is involved in connection between the MobiChargeTM and the MobiChargeTM Connector.

MobiConnect™


The request bean contains a username, a password, a method and data as bean parameters. The data is a vector data type which is same as the data which is received by the MobiChargeTM Connector.

By implementing the java.net as a component to connect to a recharge gateway through an internet connection, the request bean is sent to the recharge gateway. A recharge gateway is represented by a URL address. A URL Object is instantiated base on the URL Address. A URL connection to the gateway is instantiated by opening a connection of the URL Object. After the connection established, the request is sent to the recharge gateway and the connector is waiting for a response related to the request.

MobiConnectTM Recharge Gateway

This gateway is connected to a Telco Recharge System or an Intermediation Recharge System owned by other electronic dealer. The connection can be directly host‐to‐host connection or assisted by other devices or other third party software.

Commonly the host‐to‐host connection is established by implementing a protocol likes an ISO 8583 or a XML‐RPC. The other protocol is a USSD protocol which is implemented with assistant of a GSM Modem.

A Request bean which is received by this gateway must be validated by matching the username and the password kept in the properties files to the parameters in the bean. By extracting the method parameter, the request bean can be identified whether it is a recharging request or a maintenance request. The request which is handled by the gateway is related to the protocol which is used by the gateway.

ISO 8583 Recharge Gateway

Many Telco companies implement an ISO 8385 as a standard protocol to pull stock of an electronic voucher from them. This reason is because the protocol is used widely as industrial protocol to interchange a financial transaction. Commonly the recharge gateway is running as an ISO 8385 client, meanwhile a recharge system is running as an ISO 8583 server.

MobiConnect™


A request bean which is received would be transformed to be an ISO 8583 message. An ISO 8583 message has following format:

Message Header Message Type Indicator Message Bitmap Message Fields

• Message Header indicates the length of a message in bytes without the message header. Depend on the protocol specification from the recharge system, the message header can be 2 network bytes, 4 network bytes or can be 4 ASCII characters.

• Message Type Indicator indicates the type of a message. It is represented with 4 bytes. The message type can be ‘0200’ for a recharge request, ‘0210’ for a recharge response, ‘0800’ for a network management request, ‘0810’ for a network management response, etc.

• Message Bitmap indicates which fields are available in the message fields. This bitmap is divided by 2 types. The first is primary bitmap and the second is secondary bitmap. The primary bitmap represents field availability up to 64 fields. Meanwhile the secondary one represents field availability up to 128 fields.

• The message fields represent all information which is needed for a transaction request. The maximum number of fields is 128. A field function is defined by a Recharge System provider.

An ISO 8583 client is developed by using JPOS1.5 API as component library. The JPOS API is a expanding of a socket. A connection between an ISO Server and an ISO Client is represented by an ISO Channel. The ISO client implements this channel to send an ISO message.

Before message interchanging, both the client and server must have a message template. This template becomes a reference to extract an ISO Message. The template is represented by an ISO Package.

The ISO message which would be sent by a client must wrap in an ISO Request. In order to handle more than one ISO Message in one time, it is implemented a multiplexer, called an ISO Mux. ISO Mux allows multiple terminals in a LAN or WAN to asynchronously send and receive ISO messages over a single ISO Channel link.

MobiConnect™


ISO 8583 Functional Diagram

XML‐RPC Recharge Gateway

Some Telco operator implements a XML‐RPC as a standard protocol to communicate to their recharging system. XML‐RPC is a Remote Procedure Calling protocol

that works over the Internet.

An XML‐RPC message is an HTTP‐POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML. Procedure parameters can be scalars, numbers, strings, dates, etc.; and can also be complex record and list structures.

MobiConnect™


XML‐RPC Block Diagram

A XML‐RPC contains two components. The first is a header and the second is a payload xml format.

• RPC‐XML Header

The format of the URI in the first line of the header is not specified. For example, it could be empty, a single slash, if the server is only handling XML‐RPC calls. However, if the server is handling a mix of incoming HTTP requests, we allow the URI to help route the request to the code that handles XML‐RPC requests. (In the example, the URI is /RPC2, telling the server to route the request to the "RPC2" responder.)

A User‐Agent and Host must be specified.

The Content‐Type is text/xml.

The Content‐Length must be specified and must be correct.

MobiConnect™


• Payload format

The payload is in XML, a single <methodCall> structure.

The <methodCall> must contain a <methodName> sub‐item, a string, containing the name of the method to be called. The string may only contain identifier characters, upper and lower‐case A‐Z, the numeric characters, 0‐9, underscore, dot, colon and slash.

If the procedure call has parameters, the <methodCall> must contain a <params> sub‐item. The <params> sub‐item can contain any number of <param>s, each of which has a <value>.

A <value> can be nested by the following data type:

Tag Type Example

<i4> or <int> four‐byte signed integer ‐12

<boolean> 0 (false) or 1 (true) 1

<string> string hello world

<double> double‐precision signed floating point number ‐12.214

<dateTime.iso8601> date/time 19980717T14:08:55

<base64> base64‐encoded binary eW91IGNhbid0IHJlYWQgdGhpcyE=

A value can also be of type <struct>.

A <struct> contains <member>s and each <member> contains a <name> and a <value>. A <struct> can be recursive, any <value> may contain a <struct> or any other type, including an <array>.

A value can also be of type <array>. An <array> contains a single <data> element, which can contain any number of <value>. A <array> elements do not have names.

MobiConnect™


Request example

POST /RPC2 HTTP/1.0 User‐Agent: Frontier/5.1.2 (WinNT) Host: betty.userland.com Content‐Type: text/xml Content‐length: 181 <?xml version="1.0"?> <methodCall> <methodName>SATprepaid.recharge</methodName> <params> <param> <value> <string>TestTopUp</string> <struct> <member> <name>msisdn</name> <value><string>081314405899</string></value> </member> </struct> <array> <data> <value><boolean>0</boolean></value> <value><i4>‐31</i4></value> </data> </array> </value> </param> </params> </methodCall>

MobiConnect™


Response format

Unless there's a lower‐level error, always return 200 OK.

The Content‐Type is text/xml. Content‐Length must be present and correct.

The body of the response is a single XML structure, a <methodResponse>, which can contain a single <params> which contains a single <param> which contains a single <value>.

The <methodResponse> could also contain a <fault> which contains a <value> which is a <struct> containing two elements, one named <faultCode>, an <int> and one named <faultString>, a <string>.

A <methodResponse> cannot contain both a <fault> and a <params>.

Fault example

HTTP/1.1 200 OK Connection: close Content‐Length: 426 Content‐Type: text/xml Date: Fri, 17 Jul 1998 19:55:02 GMT Server: UserLand Frontier/5.1.2‐WinNT <?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value><int>4</int></value>

MobiConnect™


</member> <member> <name>faultString</name> <value><string>Too many parameters.</string></value> </member> </struct> </value> </fault> </methodResponse>

A XML‐RPC recharge gateway is commonly a XML‐RPC client. On the other hand, the recharging system is a XML‐RPC server. The connection between client and server follows HTTP Protocol through a internet connection.

The XML‐RPC recharge gateway is developed by implementing the Apache HttpClient API. The method that is used for sending a XML request is a POST method. The post method has a request header which must be set to ‘text/xml’. After sending the XML request, the response would be passed through the post method class. By calling a getResponseBodyAsString function within the post method class, the response can be grabbed as a string.

USSD Recharge Gateway

USSD (Unstructured Supplementary Service Data) is a Global System for Mobile(GSM) communication technology that is used to send text between a mobile phone and an application program in the network. Applications may include prepaid roaming or mobile chatting.

USSD is similar to Short Messaging Service (SMS), but, unlike SMS, USSD transactions occur during the session only. With SMS, messages can be sent to a mobile phone and stored for several days if the phone is not activated or within range. Users do not need to access any particular phone menu to access services with USSD‐ they can enter the Unstructured Supplementary Services Data (USSD) command direct from the initial mobile phone screen and is routed back to the home mobile network.

MobiConnect™


USSD strings are involving the use of the "*" and "#" characters to denote the start and finish of the USSD string. USSD strings for regularly used services can be stored in the phonebook, reducing the need to remember and re‐enter them. The strings which are sent through a GSM modem are initiated by send a AT command to the modem. The command format is “AT+CUSD=1,[USSD strings]”.

USSD Recharge Gateway Component Diagram

MobiConnect™


A USSD Recharge Gateway benefits the SMSLIB2.0 API as main component to connect to a GSM modem. Within this API, a GSM modem is represented by a CService class. A USSDBOX is an extending class of a CService. The common functions of a GSM Modem related to USSD functions are populated in the USSDBOX. For example: a function to check balance, a function to check stocks, a function to send USSD command, a function to get a CCID of a SIM Card, etc.

A Modem Alive Manager is a component which has responsibility to check the life status of a modem. It is a separated thread that periodically sends an “AT” command to the modem. The life modem status is represented by an “OK” respond. If the manager received any responds except “OK” then the modem is considered modem died. This information is sent to the Auto Restart Modem Manager.

An Auto Restart Modem Manager is checking the content of a RestartedModemVector periodically. This vector informs which modems need to be restarted. All the modems stated in the vector are going to be restarted at the next period.

The main function of the USSDBOX Manager is to maintain all requests coming from a recharge gateway connector through the sendussd servlet. The manager also controls the balance of the USSDBOX requests so all the GSM modems running on balance.

MobiConnect™ Connectivity Framework - Chilliwire · can be a host‐to‐host connection to a...

Documents

Transcript of MobiConnect™ Connectivity Framework - Chilliwire · can be a host‐to‐host connection to a...