MOBITEK SMS Engine — Enterprise Edition version 7 Manual


RELEASE NOTES

VERSION DATE DESCRIPTION
7.1 2019-June-21 Released.

 

COPYRIGHT

© 2019 MOBITEK System Sdn. Bhd.  All rights reserved.

No part of this document may be reproduced, distributed, stored in a retrieval system or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical, photocopying, manual or otherwise, without the prior written permission of MOBITEK System Sdn. Bhd.

 

TRADEMARKS

MOBITEK® is a registered trademark owns by MOBITEK System Sdn. Bhd.
Product names, logos, brands and other trademarks referred in this document are the property of their respective trademark holders and are used only to directly describe the products being provided.

 

DISCLAIMER

MOBITEK makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose.

Furthermore, MOBITEK reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to notify any person of such revision or changes.

 

INTRODUCTION

MOBITEK® SMS Engine – Enterprise Edition is a Windows Service that sends and receives SMS. It is the engine that powers MOBITEK® MobiGATE SMS Gateway.

The MOBITEK® SMS Engine – Enterprise Edition uses SQL Server database to store incoming SMS, and to check if there is any pending SMS to be send out.

System integrator and software developer do not need to write any code to build a SMS Gateway.

To send out SMS, insert record into “outbox” table.

To read incoming SMS, retrieve record from “inbox” table. to read SMS.

 

FEATURES

  1. Running as Windows Service.
  2. Concatenate multiple SMS, i.e. support sending SMS longer than 160 characters and joining them into 1 SMS.
  3. Support Oracle 11g (not in standard package, separate license is required).
  4. MOBITEK® SMS Engine – Enterprise Edition will always try to initialise connection with MOBITEK® MobiGATE SMS Gateway e.g. If PC/server is rebooted, the engine service will automatically establish connection with SMS gateway .
  5. Auto-reconnection with modem – if modem is disconnected from PC/server (for whatever reasons), and then re-connected at later stage, service will automatically establish connection with modem.
  6. Uses Microsoft SQL Server, MySQL Server or Oracle Database to store incoming SMS, and to process outgoing SMS in database. Support both Windows and SQL authentication mode.
  7. Prevention of any lost of SMS:–
    1. During initialisation, if there are any database error, it will not send nor read SMS, therefore no message will be lost.
    2. Auto-reconnection with database server.
  8. Sending of SMS in alphanumeric character (text) and in Chinese character (Unicode).
  9. Intelligent SMS Sending Logic:-
    1. Scheduling of outgoing SMS – based on the date and time set in “datetime_schedule”
    2. Prioritisation of outgoing SMS – earliest “datetime_schedule” will be send out, and all “datetime_schedule = null” will be last to send out
    3. FIFO – if there is neither scheduling nor prioritization, then “FIFO” rule will be applied – SMS Engine will process the 1st record in the “outbox” table until the last record.
  10. Configure the direction of individual modem:-
    1. 2 way send and read SMS;
    2. 1 way read SMS; or
    3. 1 way send SMS.
  11. Scaleable – support 1 or more MOBITEK® MobiGATE SMS Gateway without any need to reinstall Engine.
  12. Load balancing – all modems in MOBITEK® MobiGATE SMS Gateway work together to broadcast message. It is NOT on “round-robin” basis.
  13. Fail-over – if modem no.1 cannot send out the SMS, modem no. 2 will take over, and so on until modem no. 4.
  14. Dynamic queue size – the Engine will dynamically allocate queue size, if more modems are successfully initialised then queue size will be increased.
  15. Configurable maximum queue size – the maximum queue size can be changed, default minimum size is 64 SMS/records per modem.
  16. Routing – sophisticated and intelligent routing logic that defines:-
    1. automatic routing;
    2. prefix routing – which modem to use for sending out SMS to designated prefix mobile number. Good for cost saving as SMS sent within the intra-network is cheaper than inter-network;
    3. manual routing – specify which modem to send out SMS manually.
  17. Number of retries – can be configured. If SMS fails to be send, it will retry until the specified time.

 

LIMITATION

  1. Sending of SMS in Chinese character with maximum of 70 characters length.
  2. Does not support receiving concatenate or long SMS. Receiving of SMS is limited to 160 characters (ASCII) or 70 characters (Unicode) per record in the “inbox” table; if the total is exceeded then the incoming SMS will be stored in multiple records in the “inbox” table.

 

REQUIREMENT

  1. MOBITEK® MobiGATE SMS Gateway
  2. System integrators and software developers must posses knowledge of:-
    1. SQL Database Administration for:-
      • Microsoft SQL Server, Microsoft SQL Server Enterprise Manager, Microsoft SQL Server Query Analyzer;
      • MySQL Database Server; or
      • Oracle Database Server
    2. Database programming:-
      • ODBC, ADO, ADO.net; and
      • SQL statement
    3. Windows Service Administration
  3. SIM card(s)
  4. Supported operating system:-
    1. Windows Server 2003 / 2008 / 2012 / 2016 Server 32-bit and 64-bit;
    2. Windows XP / Vista / 7 / 8 / 10 32-bit and 64-bit.
  5. Microsoft .NET Framework Version 2.0
  6. Microsoft .NET Framework Version 4.0 if using Oracle 11g
  7. Supported SQL Database Server:-
    1. Microsoft SQL Server 2000 / 2003 / 2008 Enterprise Edition;
    2. Microsoft SQL Server 2005 Express Edition;
    3. MySQL version 4.1 and above with MySQL ODBC driver version 5.1 in Windows OS;
    4. MySQL version 4.1 and above with MySQL ODBC driver version 5.1 in Linux OS; or
    5. Oracle 11g (separate license required)

 

 SYSTEM ARCHITECTURE

MOBITEK SMS Engine Enterprise Edition v.6-01

MOBITEK SMS Engine Enterprise Edition v.6-02

INSTALLATION of SMS ENGINE ENTERPRISE EDITION

  1. Optional, install Microsoft .NET Framework Version 2.0 (install it from the USB thumb drive)
  2. Add a new database or use existing database.
  3. Execute SQL script (in USB thumb drive) to add new tables to a new database or existing database.
  4. The SQL script will generate 4 tables:
    1. inbox
    2. outbox
    3. modem_state
    4. retry_send

      Note:  please make sure you have back-up your database before executing SQL script. 

  5. Install MOBITEK® SMS Engine — Enterprise Edition version 7 (install it from the USB thumb drive)
  6. Copy the configuration file “config.xml” from USB thumb drive to the location (path) where the engine is installed
    • C:\Program Files (x86)\SMS Engine Enterprise Edition
  7. Install Control Panel for SMS Engine from USB thumb drive and edit the “config.xml” with Control Panel (refer to the user guide).
  8. The contents of config.xml is as follows:
    <SMSConfig>
    <RETRY_SEND>3</RETRY_SEND>
    <QUEUE_SIZE>16</QUEUE_SIZE>
    <ROUTING>P</ROUTING><MODEM_LIST>
    <MODEM>
    <ID>1</ID>
    <PORT>41</PORT>
    <ENABLED>true</ENABLED>
    <MODE>B</MODE>
    <TARGET_PREFIX>*</TARGET_PREFIX>
    </MODEM><MODEM>
    <ID>2</ID>
    <PORT>42</PORT>
    <ENABLED>true</ENABLED>
    <MODE>B</MODE>
    <TARGET_PREFIX>*</TARGET_PREFIX>
    </MODEM><MODEM>
    <ID>3</ID>
    <PORT>43</PORT>
    <ENABLED>true</ENABLED>
    <MODE>B</MODE>
    <TARGET_PREFIX>*</TARGET_PREFIX>
    </MODEM><MODEM>
    <ID>4</ID>
    <PORT>44</PORT>
    <ENABLED>true</ENABLED>
    <MODE>B</MODE>
    <TARGET_PREFIX>*</TARGET_PREFIX>
    </MODEM>
    </MODEM_LIST><DATASOURCE>
    <DBTYPE>MySQL</DBTYPE>
    <SERVER>localhost</SERVER>
    <USERNAME>root</USERNAME>
    <PASSWORD>root</PASSWORD>
    <DATABASENAME>smseee6</DATABASENAME>
    <AUTHMODE>SQL</AUTHMODE>
    </DATASOURCE></SMSConfig>

    This table explains the node in the “config.xml” file:

    NODE VALUE DESCRIPTION
    <RETRY_SEND> A number, starting from 0

    <RETRY_SEND>0</RETRY_SEND> = no retry

    <RETRY_SEND>3</RETRY_SEND> = retry 3 times

    Enter the number of retry in the event if SMS cannot be sent. The total number of sending is 1 + number of retry. This is a global setting that will affect all modems.

    <QUEUE_SIZE>

    Note: this function has been deprecated will be removed in future version.

    A number, default is 16.

    <QUEUE_SIZE>16</QUEUE_SIZE> = Engine will select 16 records from “outbox” table

    Minimum is 16.

    Maximum is unlimited

    Maximum number of records that the Engine will select from the “outbox” table.

    The larger the queue size, the lesser connection/query is made to the SQL Database.

    <ROUTING> Value can be “A”, “P” or “M”.

    <ROUTING>A</ROUTING> = automatic routing and load balancing

    <ROUTING>P</ROUTING> = routing by pre-fix based on value in <TARGET_PREFIX>

    <ROUTING>M</ROUTING> = manual routing based on value in the outbox.target_modem

    To set the routing mode.

    This is a global setting that will affect all modems.

    <MODEM> N/A Setting for each modem. If there are 8 modems in MobiGATE, then there must be 8 <MODEM> nodes. If there are 4 modems, then there must be 4 <MODEM> nodes.
    <ID> A number starting from 1.

    <ID>1</ID> = this modem’s ID or number is 1

    <ID>2</ID> = this modem’s ID or number is 2

    ID of modem or modem number. Depending on the model of MobiGATE, the range of ID can be from 1 to 4 or 1 to 8.
    <PORT> A number, starting from 1

    <PORT>9</PORT> = this modem is connected to COM port number 9

    COM port of which the modem is connected.

    Please refer to “Device Manager > Ports” to find out the COM port numbers.

    <ENABLED> Value is either “True” or “False”.

    <ENABLED>True</ENABLED> = modem is enabled

    <ENABLED>False</ENABLED> = modem is disabled, neither SMS will be send nor read on this modem

    To enable or disable a modem.

    Engine will need to be restarted to take effect.

    <MODE> Value can be “B”, “R” or “S”.

    <MODE>B</MODE> = bi-directional, modem will read and send SMS

    <MODE>R</MODE> = one way read SMS only

    <MODE>S</MODE> = one way send SMS only

    To set the direction mode of modem.
    <TARGET_PREFIX>
    • A number
    • List of numbers, separated by comma
    • blank
    • “*” wild card

    <TARGET_PREFIX>016</TARGET_PREFIX> = this modem will only send out SMS to mobile numbers with 016 prefix

    <TARGET_PREFIX>017,012</TARGET_PREFIX> = this modem will only send out SMS to numbers with 017 and 012 prefix

    <TARGET_PREFIX></TARGET_PREFIX> = this modem will NOT send out any SMS

    <TARGET_PREFIX>*</TARGET_PREFIX> = this modem will send SMS to any mobile numbers

    To configure the prefix rule, modem will only send out SMS if prefix rule is matched.

    The routing must be set to <ROUTING>P</ROUTING> in order for the target prefix to work, else it will be ignored

    <MODEM>

    <ID>1</ID>

    <PORT>41</PORT>

    <ENABLED>true</ENABLED>

    <MODE>B</MODE>

    <TARGET_PREFIX>17,012</TARGET_PREFIX>

    </MODEM>

    N/A Modem ID 1 is connected to COM port number 41.

    It is enabled, and the mode is send and read SMS.

    It will only send SMS to numbers with 017 and 012 prefix.

    <DATASOURCE> N/A Settings for SQL Database Server
    <DBTYPE> “MYSQL” or “MSSQL”

    <DBTYPE>MYSQL</DBTYPE> = Database server is MySQL

    <DBTYPE>MSSQL</DBTYPE> = Database server is MS SQL

    To set which type of database server is used.
    <SERVER> “IP address” or “name of server”

    <SERVER>192.168.1.66</SERVER> = IP address of the database server

    <SERVER>localhost</SERVER> = database server is on local server

    <SERVER>127.0.0.1SQLEXPRESS
    </SERVER> = IP address of MS SQL Express database server
    Note: for MS SQL Express Edition, add a suffix – “SQLEXPRESS” , e.g. 127.0.0.1SQLEXPRESS

    To set the IP address or name of database server.
    <USERNAME> <USERNAME>root</USERNAME> = user name is “root”; default for MySQL

    <USERNAME>sa</USERNAME> = user name is “sa”; default for MS SQL

    To set the user name of the login account of the database server
    <PASSWORD> <PASSWORD>root</PASSWORD> = password is “root”; default for MySQL

    <PASSWORD>sa</PASSWORD> = password is “sa”; default for MS SQL

    To set the password of the login account of the database server
    <DATABASENAME> Alpanumeric.

    <DATABASENAME>smseee6</DATABASENAME> = name of the database used is “smseee6”

    To set the database name used.
    <AUTHMODE> Value can be “SQL”, “WIN” or blank

    <AUTHMODE>SQL</AUTHMODE> = MS SQL Server will use SQL authentication mode

    <AUTHMODE>WIN</AUTHMODE> = MS SQL Server will use Windows authentication mode

    <AUTHMODE></AUTHMODE> = leave blank if using MySQL Database Server

    To set the authentication mode, only applies for MS SQL Database Server.

    For MySQL, leave it blank.

  9. Make sure MOBITEK® MobiGATETM is powered on and each modem’s blue LED is blinking:-
  10. Make sure VCOM is running:-
  11. Start the Engine (Windows service) via Control Panel:-
  12. In Control Panel for SMS Engine, open log file to see if service is successfully started:-

 

OUTBOX TABLE – SEND SMS & USSD COMMAND

By default, SMS Engine send out SMS based on the ascending order of the “msg_id”. That is “msg_id = 1” will be send out first then “msg_id = 2”.

  1. To send USSD command, the SQL statement is:-
    Insert into Outbox (message, destination, msg_type, target_modem) values ('*122#', '', 'D', '2');
    Note: for USSD to work, the routing must be set to “M” <ROUTING>M</ROUTING>
  2. To send out SMS in text mode, the SQL statement is:-
    Insert into Outbox (message, destination) values ('Hello!', '+60172233111');
  3. To send out SMS having Chinese character, the SQL statement is:-
    Insert into Outbox (message, destination, msg_type) values ('你好', '+60172233111', 'U');
  4. To send out SMS by manual routing via modem ID 4 (provided that <ROUTING>M</ROUTING> is set), the SQL statement is:-
    Insert into Outbox (message, destination, target_modem) values ('Hello!', '+60172233111', '4');
  5. To schedule a SMS to be send out at a predetermined date, the SQL statement is:-
    Insert into Outbox (message, destination, datetime_schedule) VALUES ('Happy New Year!', '+60176096718', '2020-01-01 00:01:00');

 

FILED NAME DATA TYPE DESCRIPTION REMARK
msg_id bigint

(primary key)

Outgoing SMS unique identifier key. Automatically increased. Reserved. Do not modified.
message text Outgoing message (SMS) or USSD command. Maximum length is 160 characters or more.

If exceed 160, then it will be concatenated. Only valid for text format, not valid for unicode.

For unicode (Chinese), the maximum number of character is 70. Value ‘U’ must be entered into “msg_type” field.

msg_ref integer Message reference given by the SMSC. Automatically generated by SMS Engine. Reserved. Do not modified.
datetime_queued datetime Date and time of outgoing SMS queued to be send. Format according to system’s setting. Automatically generated by SMS Engine. Reserved. Do not modified.
destination varchar Recipient’s mobile number Value required to send out SMS.

The format must be

‘+country code then prefix then number’

e.g.

+60123477527

+6598770270

If you do not insert +country code, e.g. 0123477527, the message can still be send out but there will not be any delivery report.

sent_status varchar Status of outgoing SMS

‘P’ – Pending

‘L’ – Processing

‘S’ – Sent

‘R’ – Retry

‘F’ – Fail to send

Default value is ‘P’. Automatically generated by SMS Engine. Reserved. Do not modified.

The process flow is as follows
P -> L -> S or F
or
P -> L -> R -> S or F
The final value is either ‘S’ or ‘F’.

datetime_sent datetime Date and time of outgoing SMS being sent. Automatically generated by SMS Engine. Reserved. Do not modified.
delivery_status varchar ‘D’ – delivered

‘F’ – fail to deliver

‘U’ – unknown status

Whenever there is a delivery status report from the network, it will be automatically inserted by SMS Engine. Reserved. Do not modified.
datetime_delivered datetime Date and time of outgoing SMS being delivered to recipient. Whenever there is a delivery status report from the network, it will be automatically inserted by SMS Engine. Reserved. Do not modified.
modem_id varchar Modem that sends out SMS.

Correspond to the modem ID as described in “config.xml”.

Automatically generated by SMS Engine. Reserved. Do not modified.
msg_type varchar To indicate the message type, values are:-

‘T’ – SMS in text mode
‘U’ – SMS in unicode
‘D’ – USSD command

Default value is ‘T’.

Insert ‘U’ to send out SMS in unicode format.

datetime_schedule datetime To indicate when this message/record is to be send. Default value “null”.

Scheduling: insert date and time if you want to schedule this message to be send out later.

Prioritization: earliest “datetime_schedule” will be send out, and all “datetime_schedule = null” will be last to send out.

The Engine will query the “outbox” 2 times, 1st time for scheduled records and 2nd time for unscheduled records. All unscheduled records will be send only after current scheduled records are send.

target_modem varchar To indicate which modem to be used for sending out SMS Default value “null”.

 

INBOX TABLE – READ SMS & USSD REPLY

SQL Statement:

  • To read all new SMS

Select * from Inbox where read_status = 'N'

  • To change the status of new SMS to “read”

Update Inbox Set read_status = 'Read' Where Status = 'N'

or

Update Inbox Set read_status = 'Read' Where msg_id = 'ID of the message that SI/SD is processing'

 

FILED NAME DATA TYPE DESCRIPTION REMARK
msg_id varchar Incoming SMS unique identifier key. Automatically increased. Reserved. Do not modified.
message varchar Incoming SMS. Maximum of 160 characters; or

USSD reply.

Whenever there is an incoming SMS, it will be automatically inserted by SMS Engine; or

A USSD reply to the USSD command issued in the “outbox” table

Reserved. Do not modified.

datetime_recv datetime Date and time of incoming SMS received by server. Whenever there is an incoming SMS, it will be automatically inserted by SMS Engine. Reserved. Do not modified.
receive_from varchar Sender Mobile number of incoming SMS . Whenever there is an incoming SMS, it will be automatically inserted by SMS Engine. Reserved. Do not modified.
read_status varchar Status of incoming SMS.
‘N’ – New (default value)
Whenever there is an incoming SMS, ‘N’ will be automatically inserted by SMS Engine.SI/SD can change the value after reading the SMS.
Value can be modified.
modem_id varchar Modem that receives incoming SMS.
Correspond to the modem ID as described in “config.xml”.
Automatically generated by SMS Engine. Reserved. Do not modified.
scts datetime Date and time of incoming SMS received by SMS centre. It is NOT the date, and time of the server. Automatically generated by SMS Engine. Reserved. Do not modified.
ussd varchar the USSD command issued Automatically generated by SMS Engine. Reserved. Do not modified.

 

RETRY SEND TABLE

This table is used for logging number of retries for a message.

 

FILED NAME DATA TYPE DESCRIPTION REMARK
id automatic increment Automatically increased. Reserved. Do not modified.
msg_id varchar The message ID of the “outbox” table.

[outbox].[msg_id]

Automatically generated by SMS Engine. Reserved. Do not modified.
modem_id varchar The modem used for retrying

Correspond to the modem ID as described in “config.xml”.

Automatically generated by SMS Engine. Reserved. Do not modified.
total_retry integer Number of retries done by the particular modem.

The number should be less than or equal to <RETRY_SEND>3</RETRY_SEND>

as described in “config.xml”.

Automatically generated by SMS Engine. Reserved. Do not modified.

 

For example, if a record with ID “118” has this value:-

FILED NAME VALUE
id 118
msg_id A3210
modem_id 1
total_retry 3

It means – modem with ID number 1 had retried 3 times to send out the message having ID “A3210”.

 

CHECK LIST

These are import factors to ensure SMS Engine operates smoothly:

  1. VCOM has started and running
  2. SMS Engine Windows Service has started and running

 

FREQUENTLY ASKED QUESTIONS

Please refer to https://mobitek-system.com/blog/category/sms/sms-gateway/

 

REQUEST FOR SUPPORT

Please write to support@mobitek.my with:

  1. company name
  2. invoice number (located at back of modem)
  3. description of problem
  4. attach screen capture of VCOM showing all COM ports and its IP address
  5. attach log file (located at C:\Program Files (x86)\SMS Engine Enterprise Edition\log)
  6. attach “config.xml” file

 

APPENDIX 1: HOW TO SET-UP MSSQL SERVER EXPRESS

  1. Install Microsoft SQL Server 2008 R2, you can get it from Microsoft official site.
  2. Run Microsoft SQL Server Management Studio.
  3. On the first run, “Connect to Server” will pop-up
    MOBITEK SMS Engine Enterprise Edition v.6-06

    1. Choose:-

      • Server type : Database Engine
        MOBITEK SMS Engine Enterprise Edition v.6-07
      • Server name: <browse for more → local server → database engine →your pc name >
        MOBITEK SMS Engine Enterprise Edition v.6-08
      • Authentication : Windows Authentication
        MOBITEK SMS Engine Enterprise Edition v.6-09
      • Press connect.

  1. On “object explorer” → right click on databases → create new database.
    MOBITEK SMS Engine Enterprise Edition v.6-10
    MOBITEK SMS Engine Enterprise Edition v.6-11
  2. Give it a name “smseee” and press OK
  3. On “object explorer” → right click on your new created database → New Query
    MOBITEK SMS Engine Enterprise Edition v.6-12
  4. <plang=”en-US”>Copy and paste the sql command from “mssql.sql”
  • Execute the commandMOBITEK SMS Engine Enterprise Edition v.6-13
  1. The database is set up, in case you want to know about the detail of you database for further use in MOBITEK® SMS Engine (Enterprise Edition), right click on your database → properties
    MOBITEK SMS Engine Enterprise Edition v.6-14
  2. In “config.xml” file, edit as follows:-

    <DATASOURCE><DBTYPE>MSSQL</DBTYPE><SERVER>DELL-D630SQLEXPRESS</SERVER><USERNAME>abc</USERNAME><PASSWORD>abc</PASSWORD><DATABASENAME>smseee5</DATABASENAME><AUTHMODE>WIN</AUTHMODE> </DATASOURCE>

 

APPENDIX 2: HOW TO SET-UP MySQL DATABASE

  1. Run the “WampServer64” to install Apache, MySQL Database and PHP.

  2. After successful installation, at the taskbar, click “Start All Services”.MOBITEK SMS Engine Enterprise Edition v.6-15

  1. Click “Localhost”.MOBITEK SMS Engine Enterprise Edition v.6-16

  1. Your localhost should be opened at the browser like below. Click at the “phpmyadmin”.
    MOBITEK SMS Engine Enterprise Edition v.6-17

  1. You will be directed to “localhost/phpmyadmin”. Click “New” on the left side.
    MOBITEK SMS Engine Enterprise Edition v.6-18

  1. Enter the nameas “smseee6” then click “Create”.
    MOBITEK SMS Engine Enterprise Edition v.6-19

  1. Click the “smsee6”.
    MOBITEK SMS Engine Enterprise Edition v.6-20

  2. Click at the ‘SQL’ one you are directed like below.
    MOBITEK SMS Engine Enterprise Edition v.6-21

  1. Go to your folder and open up your mysql-smsee6. Right click and click edit with “Notepad++” or “Notepad”.
    MOBITEK SMS Engine Enterprise Edition v.6-22

  1. Select all and copy the SQL script.
    MOBITEK SMS Engine Enterprise Edition v.6-23

  1. Go back to your “phpmyadmin” page. Right click and paste it at “Run SQL query/queries on database smseee6”. Then click “Go” button.
    MOBITEK SMS Engine Enterprise Edition v.6-24

  1. If successful, it will display the following result.:
    MOBITEK SMS Engine Enterprise Edition v.6-25

  1. There you can see 4 tables inside your database which are “inbox”, “modem_state”, “outbox” and “retry_send”.
    MOBITEK SMS Engine Enterprise Edition v.6-26