<-- -->
Navigate Up
Sign In

Development Toolkit - Notification Services (old)

Notification Services ToolKit

1. Introduction to mGov
2. Registering a Government Service with mGov
3. mGov Messages
4. mGov Message Routing
5. The mGov Gateway
6. The mGov Simulator
7. Known mGov Limitations
8. Sample Code & References

Introduction to mGov

The mGov eGovernment Shared Service (eGSS) offers a medium between Government Applications and Mobile operators, providing the following mobile government functionality:
  1. Registration / Deregistration of new Government Application Services;
  2. Registration / Deregistration of new Mobile Numbers (Recipients) to a Service;
  3. Manual and Integrated posting of SMS via XML with acknowledgements;
  4. Receipt and Validation of incoming SMS from Recipients;

 

As specified within the Download PDF Document mGov Design Abstract v3.0, this Shared Service may be used either manually through a web interface (Manual mode), or integrated within any type of software application through the Application Programmatic Interface (API) which is based on the two-way exchange of predefined XML files (Automated mode).
For information regarding the available web interfaces for manual use of the mGov service please refer to the Adobe PDF Document mGovernment Services System User Manual.
In order to integrate with the mGov API a developer is required to modify the respective application functionality to package SMS Messages into a batch within an XML file (in accordance to a defined XSD), which is later posted to the mGov Gateway as a stream of bytes. The developer may create an mGov Listener, implemented as a web page embedded within the application’s backend, which is used to receive messages and acknowledgements from the mGov Gateway.
 
1_Diagram.jpg 
 
 
In order to make use of mGov, a Government entity representative needs to raise an eRFS (electronic request for service), applying for a new mGov Service Account. The application should contain details of:
  1. the Government Entity;
  2. the assigned primary contact;
  3. the Government Service Application;
  4. the assigned developer;
  5. the type of interface mechanism (Manual/Automated);
  6. (if Automated) the URL of the mGov Listener page within the application’s backend.
    e.g. of an mGov Listener URL:


http://cms.myservice.gov.mt/mGov/mGovListener.ashx

Once the new account is created, it will be assigned a unique MCA Number with which the Government Service will be identified by the mGov Gateway, the mobile operators and other Government Services. An email will be sent to the client with instructions and the credentials to be used each time new messages are sent to mGov.
Should an entity want to deregister a Government Service, an entity representative needs to raise another eRFS through the MITA Portal, in which case the respective Service account will be deactivated and not deleted, but any registered mobile numbers will be deregistered and deleted.

mGov Messages

Software Applications may send three (3) types of messages to the mGov Gateway:
  1. Registration of a mobile number to the mGov Service Account;
  2. Deregistration of a mobile number from the mGov Service Account;
  3. An SMS message or batch of SMS messages to be sent to registered mobile numbers.
It is important to note that Software Applications must comply with Data Protection Act thus the sending of unsolicited messages is prohibited even though the mGov Gateway (similar to an email gateway) does not prevent such use.
The XML Schema used to send messages to the mGov Gateway, as defined within the Download PDF Document Communication between Services and mGov gateway document (v6.2), produces an XML document similar to the example portrayed below:
Example of an XML message sent from an Application to the mGov Gateway:
 
<PostData>
  <Params>
          <UserID>User ID</UserID>
          <Password>Password</Password>
          <Src>A</Src>
  </Params>
<Root>
  <Transaction>
    <TransID>Transaction ID</TransID>
    <Orig>Origin Number</Orig>
    <Dest>Destination Number</Dest>
    <TimeStamp>Timestamp</TimeStamp>
    <Type>51</Type>
    <Msg>Message Content</Msg>
    <Mobile>Recipient Mobile Number</Mobile>
    <Subject>Subject</Subject>
  </Transaction>
</Root>
</PostData>
 
Element Description
UserID Username assigned by MITA support to access mGov.
Password Password assigned by MITA support to access mGov.
Src Character indicating the type of service using mGov: M - Manual, A - Automated
TransID 256 character string containing a unique hash value (SHA 256) created by the application by hashing the concatenated string of the Origin, Destination, Mobile, Timestamp and message.
Orig Unique 6 digit value denoting the predefined MCA Number for the Origin Service of a message.
Dest Unique 6 digit value denoting the predefined MCA Number for the Destination Service of a message. In case of outgoing messages, this value should be determined according to the Recipient mobile number’s prefix as defined within the mGov Message Routing part of this article. In case of incoming messages, this value would be the respective Government Service MCA Number.
Timestamp 19 character string in the format “dd/mm/yyyy hh:mm:ss”, showing the time when message was sent.
Type 3 digit value denoting the type of message being sent:
51 indicates a new message
52 indicates an acknowledgment (ack52)
53 indicates an acknowledgment (ack53)
54 indicates a bulk registration
55 indicates a bulk de-registration
Msg 160 character string containing the actual message being passed or null in case of an acknowledgement. Only characters with ASCII 32 to 125 are accepted and ASCII 38 (&) and 60 (<) are replaced with ASCII 32 ( ).
Mobile 13 character string containing the recipient mobile number in international format starting with the prefix for Malta: 00356
Priority Integer indicating the priority or order of the message being passed to the operators: 0 - Normal priority, 1 - High priority. This element is not required since it is up to the mGov Gateway to assign message priority depending on the Service and Load.
State Integer indicating the status of a message: 0 - Successful, 1 - Unsuccessful, Other numbers specify particular errors.
Subject String containing a Service Topic with which mobile numbers may be registered / deregistered.
 
The mGov Gateway will reply asynchronously to the Software Application mGov Listener with two (2) types of messages:
  1. Acknowledgement 52 (ack52) is sent to acknowledge that a message was received by the mGov Gateway from the Government Application;
  2. Acknowledgement 53 (ack53) is sent to acknowledge that a message was received on the recipients mobile;
The reply acknowledgment message sent by the mGov Gateway to the Software Application mGov Listener will use the XML schema as defined in the Download PDF Document Communication between Services and mGov gateway document (v6.2), similar to the example portrayed below:
Example of an XML message sent from the mGov Gateway to an Application's Listener:

<PostData>
<Root>
<Transaction>
<TransID>Transaction ID</TransID>
<Orig>Origin Number</Orig>
<Dest>Destination Number</Dest>
<TimeStamp>Timestamp</TimeStamp>
<Type>52 or 53</Type>
<Msg>null</Msg>
<Mobile>Recipient Mobile Number</Mobile>
<State>Message Status</State>
<Subject>Subject</Subject>
</Transaction>
</Root>
</PostData>

In case of registration and deregistration of mobile numbers, the mGov Gateway will reply with an acknowledgement to the Software Application mGov Listener only in case of an unsuccessful process.
When mGov receives an incoming message from an operator, it will forward the message to the respective Software Application mGov Listener according to the specified MCA Number within the destination node.

mGov Message Routing

 

Operators Number Expression mGov routing Number / MCA Number
Vodafone 9900-9999 xxxx
9897 xxxx
501501
GO 7900-7911 xxxx
7913-7914 xxxx
7917-7999 xxxx
501502
RED 9811-9813 xxxx Can be routed to either Vodafone or GO MCA Numbers
Ping 9889 xxxx Can be routed to either Vodafone or GO MCA Numbers
Melita 7700-7799 xxxx Can be routed to either Vodafone or GO MCA Numbers
YOM 9696 xxxx Can be routed to either Vodafone or GO MCA Numbers
 
The above table portrays the MCA Numbers which have been assigned to the various mobile operators operating in Malta. Government applications need to extract the prefix from every Recipient mobile number and determine which operator MCA number to use according to the specified prefix ranges.
BEST PRACTICE: Developers are urged not to hardcode these ranges and values within their applications since this data is liable to change as new operators emerge within the mobile industry. Ideally these should be kept within a configuration file (e.g. operators.xml) within the respective application, allowing easy administration of the data in case of changes.
Example of an Operators XML configuration file:
<?xml version="1.0" encoding="UTF-8"?>
     <Configuration>
        <Service>
            <Name>Vodafone</Name>
            <MCA>501501</MCA>
           <Ranges>
           <Range>
              <StartPrefix>9900</StartPrefix>
              <EndPrefix>9999</EndPrefix>
           </Range>
          <Range>
              <StartPrefix>9897</StartPrefix>
              <EndPrefix>9897</EndPrefix>
          </Range>
          <Ranges>
        </Service>
        <Service>
          <Name>Go Mobile</Name>
          <MCA>501502</MCA>
          <Ranges>
           <Range>
            <StartPrefix>7900</StartPrefix>
            <EndPrefix>7911</EndPrefix>
           </Range>
           <Range>
             <StartPrefix>7913</StartPrefix>
             <EndPrefix>7914</EndPrefix>
           </Range>
          <Range>
             <StartPrefix>7917</StartPrefix>
             <EndPrefix>7999</EndPrefix>
          </Range>
          <Ranges>
        </Service>
...
</Configuration>
This configuration file may be referenced as an appropriate key within the Software Application’s main configuration file (e.g. web.config as shown below):
<!—- mGov Gateway Operator MCA Numbers -->
<add key="OperatorsXML"
value="https://myservice.gov.mt/mGov/operators.xml"/>

The mGov Gateway

The mGov Gateway is a web application which accepts and processes registration, deregistration and new SMS messages. Software Applications may post a batch containing up to 1000 messages as a stream of bytes in XML format to the mGov Gateway URL. In the past, it was also possible to send a single high priority message to an OnDemand mGov Gateway URL, a functionality which is now deprecated.
C# Snippet:
HttpWebRequest request = null;
HttpWebResponse response = null;
Stream requestStream = null;

byte[] requestBytes = Encoding.UTF8.GetBytes(xmlDocument.OuterXml);

// Prepare the HTTP web request
request = (HttpWebRequest)WebRequest.Create(strmGovGatewayURL);
request.Method = "POST"; request.ContentType = "text/xml";
request.ContentLength = requestBytes.Length;

// Transmit the XML document
requestStream = request.GetRequestStream();
requestStream.Write(requestBytes, 0, requestBytes.Length);
requestStream.Close(); requestStream.Dispose();

// Get the HTTP web response
response = (HttpWebResponse) request.GetResponse();
requestStream = response.GetResponseStream();

// Read the HTTP web response
StreamReader reader = new StreamReader(requestStream);
string strState = reader.ReadToEnd();

reader.Close();
reader.Dispose();

requestStream.Close();
requestStream.Dispose();

// Check whether the mGov Gateway returned an unsuccessful status
if (strState.StartsWith("_ERR"))
{
// An error has occurred, handle with an appropriate exception
// ..
}

// Check whether the mGov Gateway returned a successful status
if (strState.StartsWith("_OK"))
{
// mGov Gateway received the XML document successfully
// log and proceed accordingly
// ..
}
On successfully receiving an XML file the mGov Gateway will reply back with an HTTP Status Code 200 and a string starting with _OK and the file size in bytes (e.g. _OK 512). If the XML file failed any initial validation the mGov Gateway will still reply with an HTTP Status Code 200 but will return a string starting with _ERR and some details about the exception. Developers need to verify the string returned within the HTTP response (strState in the above code) to ascertain that the XML has been validated and accepted by mGov. It must be noted that the XML is still pending further processing by the mGov Gateway which occurs asynchronously.
After successfully processing the XML, the Gateway will send an asynchronous Acknowledgement 52 (ack52) XML message to the respective Software Application mGov Listener URL (specified during Service registration). At this point the SMS messages will routed to the Mobile Operator according to the destination specified in the XML document. The mGov Gateway will relay the Mobile Operator acknowledgements to the Software Application as Acknowledgement 53 (ack53) XML message.
The mGov Gateway is capable of relaying SMS messages originating from a mobile device based on the MCA number used. The Software Application will need to process these messages accordingly to the agreed business logic.
It is important to note that the Software Application mGov Listener needs to be hosted in a publicly available location on the Internet and does not require authentication. It is recommended that an audit is kept for all messages sent by the eGovernment Service application and all acknowledgements and incoming messages the application receives from the mGov Gateway.
A new web service is also available for the registration of mobile numbers via SOAP instead of sending registration messages within the mGov XML streams. This web service will authenticate the service credentials and if successful, register the new mobile number with the specified service and return the value true.
BEST PRACTICE: Developers are urged to set the live URL pointing at the Gateway and all other mGov related parameters as keys within their application configuration files (such as web.config) in order to maximise the configurability and maintainability of their applications:
Example of typical XML configuration keys:
<!-- mGov Configuration Parameter Set -->

<!—- mGov Gateway -->
<add key="OperatorsXML"
value="https://myservice.gov.mt/mGov/Operators.xml"/>
<add key="mGovGateway"
value="https://secure.intra.gov.mt/mGov/xml_gp.asp"/>
<add key="mGovSMSBatchSize" value="1000"/>
<add key="IsLive" value="true"/>

<!—- mGov Listener Location -->
<add key="mGovListener"
value="https://cms.myservice.gov.mt/mGov/mGovListener.ashx"/>

<!—- mGov Registration WebService Location -->
<add key="mGovRegister" value="http://mGov.gov.mt/services.wsdl"/>

<!—- mGov Credentials -->
<add key="mGovUserID" value="grect024"/>
<add key="mGovPassword" value="P4$$W0RD"/>
<add key="mGovSRC" value="A"/>

<!—- mGov Elements -->
<add key="mGovOrigin" value="501024"/>
<add key="mGovTimeFormat" value="dd/MM/yyyy HH:MM:SS"/>
<add key="mGovMessageLength" value="160"/>
<add key="mGovMobileLength" value="13"/>
<add key="mGovMobileDefaultPrefix" value="00356"/>

<!—- mGov Message Types -->
<add key="mGovTypeNew" value="51"/>
<add key="mGovTypeACK1" value="52"/>
<add key="mGovTypeACK2" value="53"/>
<add key="mGovTypeReg" value="54"/>
<add key="mGovTypeDeReg" value="55"/>
<add key="mGovTypeTest" value="101"/>
<add key="mGovTypeTestACK" value="102"/>

<!—- mGov Priority Types -->
<add key="mGovPriorityNormal" value="0"/>
<add key="mGovPriorityHigh" value="1"/>

<!—- mGov Status Types -->
<add key="mGovStateOK" value="0"/>
<add key="mGovStateNO" value="1"/>
<add key="mGovStateError" value="9999"/>

<!-- End of mGov Configuration Parameter Set -->


The mGov Simulator

http://qa.mitts.gov.mt/simulator.mgov/Gateway.ashx

An mGov Simulator was created as a test harness disconnected from operators, which can process and validate incoming test XML from Government Applications during development and testing and send the appropriate acknowledgements as the live mGov would. In order to start using the simulator, developers need to modify their code in order to send the XML messages to the simulator URL together with a special URL query string (urlEndpoint) containing the Listener URL of the Service being tested. Any fake credentials may be passed within the Param section but not null values.
Example of mGov Simulator XML Configuration keys within an Application's config file:
<!—- mGov Gateway -->
<add key="OperatorsXML"
value="https://quality-mitts.gov.mt/
securea/myservice/mGov/Operators.xml"/>
<add key="mGovGateway"
value="http://qa2.mitts.gov.mt/simulator.mgov/Gateway.ashx"/>
<add key="mGovSMSBatchSize" value="1000"/>
<add key="IsLive" value="false"/>

<!—- mGov Listener Location -->
<add key="mGovListener"
value="https://quality-mitts.gov.mt/
securea/myservice-cms/mGov/mGovListener.ashx"/>

<!—- mGov Registration WebService Location -->
<add key="mGovRegister"
value="http://qa.mitts.gov.mt/mgovservices/services.asmx"/>
Given the above test configuration, the mGov Simulator URL to which test data should be sent would be:

http://qa.mitts.gov.mt/simulator.mgov/Gateway.ashx?urlEndpoint=https://quality-mitts.gov.mt/securea/myservice-cms/mGov/mGovListener.ashx

Please note that data within URL query strings should always be URL Encoded, thus the URL should be:

http://qa.mitts.gov.mt/simulator.mgov/Gateway.ashx?urlEndpoint=https%3a%2f%2fquality-mitts.gov.mt%2fsecurea%2fmyservice-cms%2fmGov%2fmGovListener.ashx

This query string is required ONLY by the mGov Simulator and SHOULD NOT be used with live mGov. For this purpose it is suggested that an IsLive key be included within the software application’s configuration file which will disable the urlEndpoint if true.
As with live mGov, developers need to verify the HTTP response for an '_OK' in order to ascertain that a valid XML was sent to the mGov Simulator. When the Simulator receives an XML stream, it will validate the messages contained against the XML schema and send a Gateway acknowledgement message (ack52 according to mGov specifications) after 10 seconds to the Listener URL provided within the urlEndpoint query string. After 2 seconds, the Simulator will send another acknowledgement message (ack53) to the Listener.
Due to new network security restrictions on the Government Network, the mGov Simulator will not be able to send acknowledgements to Listeners hosted outside the network. In this case, developers need to ensure that a web response containing ‘_OK’ is being received and they should send fake acknowledgements to their application’s mGov Listener in order to test it.
http://qa.mitts.gov.mt/mgovservices/services.asmx

A test version of the new mobile number registration web service is also available. This web service will authenticate the service credentials and if successful return the value true. In order to make use of this web service, developers need to contact the MITA Quality Assurance Unit for test mGov Service credentials.
Should a client like to perform a live mGov test prior to live deployment, a new eRFS will need to be raised requesting that the mGov listener be set to point at the test listener. If the application being tested is not hosted on the Government web framework or the MITA test environment, test environment details need to be included within the eRFS so that both application and its listener are white listed through bluecoat. Once this is done, mGov will be able to interact with the test application without any limitations. Upon completion of testing, a new eRFS will be required reverting to the previous live configuration.


Known mGov Limitations

The following is a list of limitations which where identified within the current mGov implementation and which will be tackled in future enhancements:
  1. Gateway only caters for SMS technology (no EMS, MMS …);
  2. A primitive communication channel is currently used. Ideally all communication should be switched to SOAP Web Services;
  3. There is a limit of 1000 messages that may be sent in a bulk/batch;
  4. Messages are limited to 160 characters. There is no functionality allowing messages greater that this value to be automatically split into more than one message;
  5. Messages are limited to ASCII characters, no Unicode and multilingual support;
  6. SMS messages may be sent only to local mobile numbers with 00356 prefix;
  7. Better reporting required providing detailed statuses and registration information to be used by Government Services;


Sample Code & References

The follwoing source code is provided "as is" without warranties or guarantees. The Government of Malta, MITA, the author and/or distributors of this source code will not accept any responsibilities for the use of this source code. The user is advised to test any derived source code thoroughly before relying on it. The user must assume the entire risk of using the source code.
 
Download: Sending an SMS message using the mGov Gateway