Setup & Installation

Contents

Cyclos SMS banking module

The SMS module consists of the Controller and Driver see architecture. In the release the Driver and Controller are part of the same 'All In One (AIO)' package. In future releases it will be possible to host the Drive and Controller as separate services. This will only be useful for very specific cases.


The SMS module is published as a single file with three packages for different purposes:


Compatibility with Cyclos versions
Make sure that version of the SMS module is compatible with the Cyclos version. Here below a compatibility list:

Cyclos version SMS module version
Cyclos-3.6 ↔ SMS-1.0_RC1
Cyclos-3.6.1 ↔ SMS-1.0
Cyclos-3.7_RC1 ↔ SMS-1.1
Cyclos-3.7 ↔ SMS-1.2
Cyclos-3.7.1 ↔ SMS-1.2.1
Cyclos-3.7.2 ↔ SMS-1.2.1 or SMS-1.2.2
Cyclos-3.7.3 ↔ SMS-1.2.2

Note: With the ‘stand alone’ Cyclos package it is relatively easy to install and run Cyclos. Be aware that the SMS module has many configurations and will take more time. For the setup and configuration of SMS module some experience with server administration and mobile phone protocols are required.

Quick installation guide

This installation consists of 5 steps, we highly recommend for everybody to begin with installing the SMS Simulator first, because this is the easiest way to check if Cyclos is configured correctly. After the SMS simulator is working correctly the SMS Gateway or SMS modem can be configured relatively easy in step 4A and 4B.

Step 1: Install Cyclos

Step 2: Configure Cyclos

Note: This step can be skipped when you used the SMS embedded option for the database creation (see step 1)

Step 3: Install SMS Simulator

This step is not required, but we highly recommend you to first install the SMS simulator, because it is an easy way to test your configuration. When you skip this step you can still use the SMS monitor for testing your configuration.

3.1 Mysql configuration

mysql -uroot -p1234
Welcome to the MySQL monitor

mysql> create database cyclos3_sms_aio;
Query OK, 1 row affected (0.01 sec)

Ctrl-D (linux) or msyql>exit (windows)
msyql> bye

mysql -uroot -p1234 cyclos3_sms_aio < driver\sms_driver.ddl
mysql -uroot -p1234 cyclos3_sms_aio < controller\sms_controller.ddl
mysql -uroot -p1234 cyclos3_sms_aio < controller\session_keys_en.dml

Note: Make sure you import the schemas in the above listed order.

3.2 Edit baseDriverConfig.properties & config.xml

Note: This step can be ignored when you used the SMS embedded option for the database creation (see step 1)

3.3 Run simulator

Note: please take some time to test all the functionalities with the SMS simulator. If everything is working, then you have configured the SMS module successfully. Now you are ready to connect Cyclos to a gateway or modem.

Step 4: Setup communication with Telco

Now it is time to make the choice of how to send and receive the SMS messages, this can be done in several ways using: a gateway on mobile phone, an external SMS gateway provider or a local modem. For bigger projects we recommend to use an SMS gateway provider or SMS modem(s). But before starting negotiations with an SMS gateway provider it might be useful to use a mobile phone as an SMS gateway for evaluating the functionality. Once you have Cyclos working with a gateway on a mobile phone changing to an SMS gateway is very easy. For more information please see the Architecture page.

Option 1: Install gateway on a mobile phone

Common gateway steps
Installing the gateway app

There are various good (and free) gateway apps available for the Android and Iphone platforms. We had good results with SMS gateway for Android. As this gateway works over http(s) the communication setup between the phone and computer is usually easier than a setup where the phone and computer will communicate via a serial port (described in the option 3). This guide will describe the steps to use SMS gateway for Android for sending and receiving SMS messages. Other software packages can be configured more or less in the same way.

Configuring the gateway
Run the SMS module


Option 2: Connect to an SMS gateway provider



Option 3: Install SMS modem

The modem package allows connecting the SMS module working via mobile phone or modem. Usually (3G) modems that are used to connect devices (such as notebooks) to the Internet work fine. The modem needs to be configured to communicate with the SMS controller. Modems brands and types have their own configurations and it can be somewhat difficult to get it working. Connecting via a modem has the same advantages as using a mobile phone as gateway, described above in "Option 1: Install gateway on a mobile phone".


All modems which are full AT standard command compliant should work. The example below is based based on the Huawei E176. Currently the modem package has been tested with operating system Ubuntu 10.04, 32 bits and the modems:




Step 5: Problem solving & SMS monitor

Because the Cyclos SMS module can be used in a lot of different ways, it has to be very flexible. But because of this flexibility a lot of things need to be configured and set. This makes it easy to make a little mistake somewhere causing the SMS module not to work. Therefor in this paragraph will help you find the problem. It will also describe the SMS monitor, which is a very handy tool for detecting problems and checking the functionality.

Common mistakes

From our experience we know that a lot of times the following configuration mistakes are made, please check your configuration quickly if you made one of the following mistakes.

Regular expressions:

Language setup:

Controller setup:

Log files

Often problems can be easily detected by looking at the log files. The controller as well as the driver generate their own log files. The default configuration of the log4j.xml file generates two distinct files for each application, the first is a simple log file (e.g. SmsController.log), the second shows more details about all operations (e.g. SmsControllerDetails.log). The log files are per default generated in CATALINA_BASE/log and have the following names:


When operating with "All In One package (AIO)", the following files are generated:


For security reasons the default configuration does not write the message text to log files. But in some cases when detecting problems or configuring the SMS module it is necessary to have a detailed log and to trace the complete route of execution and processing of a message. Please read the Security setup how change these settings.

Quick basic testing

In general we would recommend to use the SMS monitor, but in some cases it might be useful to do some easy manual tests.


When Cyclos seems not to be receiving any messages (this only works when the messages are send using GET):


When Cyclos seems not to be sending any messages (this only works when the messages are send using GET):

SMS monitor

The monitor is a page (servlet) that allows to simulate the incoming messages from a provider and outgoing message to the provider. This can be a good help to quickly test some functions, or detect some problems. Message that are simulated to come from the provider will flow from the driver to the controller and from the controller to Cyclos, often this will generate an SMS send by Cyclos to the controller, to the driver and to the gateway/modem, so make sure that the phone number you use can receive an sms in case of live systems.


If you use the (default) AIO installation you can access the monitor by the URL: http://<TomcatIp>:<TomcatPort>/<folder name gateway,modem> (e.g. http://localhost:8080/sms). Make sure the ip of the computer you want to enter the monitor with is on the whitelist of the driver. The parameter white.list.hosts can be found in WEB-INF/classes/httpDriverConfig.properties (e.g. white.list.hosts=192.168.1.108, 127.0.0.1).


You can login the monitor with a tomcat username and password. Make sure this tomcat user has the role "admin". This can be set in the file \<tomcat home>\conf\tomcat-users.xml e.g. in this case you can login with the username cyclos and the password 1234: 

<tomcat-users>
  <role rolename="ADMIN"/>
  <user username="cyclos" password="1234" roles="ADMIN"/>
</tomcat-users>

Note: The monitor is available in the modem and gateway package, NOT in the simulator package.


Description of fields in monitor

Driver simulation servlet

The following fields can be set in the SMS monitor, please see also the picture on the right:


Example
Simulate: Sms to controller
from: 094590041
to: 9999
Message: pay 7410 094590042 3 units

The sample will simulate a received message (by driver) which would make a payment: from member with cellular 094590041, with the pin number 7410, to another member with the cellphone number 094590042 and it will transfer 3 units. The message is send to 9999, which is the short number for Cyclos. In from you can insert the complete international phone number, then the number will be reformatted using the settings in the configuration files, but it is also possible to insert the number that is used in Cyclos.


On the screen of the monitor a table will be shown showing all which is going to be written to the log. For our example, the screen would show: Monitor use case

Security setup

It is per default not possible in an installation to see the messages entering the system. In the log files, the text of the messages is represented with *, while in the database of the system these texts are encoded with symmetric encryption. The cryptography configuration of the database can be found in the WEB-INF\classes\security.properties file. It is recommended to avoid access to curious eyes to this file, as in this file you will find the decryption key for the texts stored in the database. To avoid message encryption (for example for trouble shouting), and to show the texts in the log files, add the system variable -Dlog.details.on.messages="true" to your tomcat (JAVA-OPTS). This configuration will allow to show the complete non-encrypted texts of incoming messages in your log files and the database.


WARNING: Enable full non-encrypted text view of messages for resolving error situations only. A complete message entry will expose confidential information about transactions and members interacting over SMS to any operator with access to log files and database.

Configure file: security.properties

This file resides in the WEB-INF/classes folder of each of the applications (Driver, controller or AllInOne package). The configurable properties are as follows:


Sample file: security.properties

message.encrypt.algoritm=AES
message.encrypt.charset=UTF-8
message.encrypt.password=CHANGEME


Information flows & AIO

Information flows and configuration

When connecting to an SMS gateway the information will flow from the mobile phone ↔ gateway ↔ http driver ↔ base driver ↔ controller ↔ Cyclos and vice versa. When connecting to an SMS modem the information will flow from the mobile phone ↔ SMS modem ↔ modem driver ↔ base driver ↔ controller ↔ Cyclos and vice versa. The picture on the right show this for connecting to an SMS gateway. It also show which variables and which configuration files are used at what moment. For more information about this please read the Architecture and the the Driver setup and the Controller setup.

The driver and the controller are published on sourceforge as a single installation, the so called 'All In One (AIO)' package. The advantage of the AIO package is that controller and driver can communicate directly, without slow data exchange. Consequently, the webservice connection configurations do not apply. Only in specific cases it is interesting of separating the driver and controller e.g. in case of having physical modems (connected to local Drivers) on different locations. Below you can find more information about the AIO setup:

Configuration files

The AIO package has the configuration files config.xml, for the controller, baseDriverConfig.property for the driver, and the specific configuration httpDriverConfig.properties for the HTTP driver or modemDriverConfig.properties when the driver connects to a modem. All configuration files can be found in the folder /WEB-INF/classes.

rootURL

When using the AIO package the config.xml of the controller (integrated in AIO) must be configured without a URL to connect to the integrated driver, that is, the configuration of the driverInstance element pertaining to the integrated driver will have an element connectionSettings like the following (without rootURL): 

<connectionSettings connectionTimeout="120000" readTimeout="120000" disableCNCheck="true" trustAllCert="true"/>

As mentioned before, using an AIO package does not limit the controller to using only one driver (the integrated one). Thus, if operation with an additional external driver is required (NOT the integrated one), a new driverInstance must be created, and its connectionSettings set to something like the following (specifying the rootURL for the web service connection): 

<connectionSettings rootUrl="[URL_driver_WS]" connectionTimeout="120000" readTimeout="120000" disableCNCheck="true" trustAllCert="true"/>

Like the controller, the integrated driver of an AIO package does not require a URL to connect to the controller (as the communication with the integrated controller will be done in the same virtual machine). Thus, in the file baseDriverConfig.properties of the AIO we have to put the element "controller.url" to an empty value and will look like: 

controller.url=

Database

When using the AIO package, the database configuration used by the SMS module is the one found in baseDriverConfig.properties, ignoring what is contained in config.xml.

Note: Even while the database configuration will be loaded from baseDriverConfig.properties, the configuration in config.xml (which will NOT be considered when operating in AIO mode) MUST be kept present in order to preserve the formats of the files.

Driver setup

The single task of the driver is to handle the communication with a (physically attached) modem or an SMS Gateway provider (GSP). The reason for developing the driver software was to decouple the controller from the complexities of different communication channels. The driver configuration is defined in three files: baseDriverConfig.properties (this configuration file is always used), the file httpDriverConfig.properties is used for connecting via http to an SMS gateway and the file modemDriverConfig.properties is used for connecting to a physical modem.

Base driver configuration

Configure file: baseDriverConfig.properties

The baseDriverConfig.properties file is placed on folder WEB-INF/classes, this allows to configure some characteristic and behaviors.

  1. engine.id - All driver applications need a label Id. This label Id will be used by controller to identify the driver instances and route the messages between it and Cyclos instances.
  2. messageInterceptor.class - Optional property. By default the class nl.strohalm.cyclos.driver.message.interceptor.DefaultMessageInterceptorImpl is used. If specific logic is required you can write your own implementation class. For more details please see the Message intercepting section. Note: this property is available from version 1.2.3 and later.


Duplicated message filter:

It is possible to configure the Driver in such a way that duplicated messages will be discarded. Duplicated messages are considered to have the same message text, origin and destination number, and credential (PIN or login password) within a specified time frame. This can be prevent double operations (e.g. payments) when there is a delay with the SMS delivery and the customer sends the same message.

  1. engine.duplicated.messages.timeWindow - Time window in which messages with the same format will be considered duplicated and will be ignored. (default, 10 minutes)
  2. engine.messages.digest.cleaner.delay - Time window in which messages after which the CLEANER process will discard the duplicated messages. This property will need to be at least 10 times smaller than the engine.duplicated.messages.timeWindow value. (default, 1 minutes).


Message queue towards the controller:

The message that arrive from the gateway are put in a queue to be dispatched to the controller, before possible errors are generated the driver will retry to send the message within a time window. The properties to control this queue behavior are:

  1. engine.to.controller.thread.pool.core.size - Available (permanent) for message dispatching. Every message that is pending for dispatching will use these threads
  2. engine.to.controller.thread.pool.queue.size - Maximum items in dispatching queue. If all threads defined in the engine.to.controller.thread.pool.core.size are busy and a new message arrives, that will be stored in a waiting queue in order to send.
  3. engine.to.controller.thread.pool.max.size - If the dispatching queue is full engine.to.controller.thread.pool.core.size and a new message arrives, then a new thread will be opened. This process will be repeated until the max size defined in this property is not reached anymore
  4. engine.retry.failed.messages.delay - This is the time (in seconds) after which the driver will retry to dispatch a message. If there is an error when a message is trying to be dispatched to the controller because the engine.to.controller.thread.pool.max.size has been reached or because of a connectivity (TCP) error. After time defined in the engine.retry.failed.messages.delay has been reached the driver will retry to dispatch the message.
  5. engine.failed.messages.validity - This is the time (in seconds) after which the driver will stop retrying to retry to dispatch a message. After this time it is considered that it would be not useful anymore to dispatch the message, or dispatching message after the delay could even be a risk.


Controller connection settings properties:

These settings define the connection between the Driver and the Controller.

  1. controller.url - The base url to contact the web services served by controller (and the server to allow connection from controller).
  2. controller.disableCNCheck - Allow to connect with Controller WS by SSL, without check the server name. Default value false.
  3. controller.trustAllCert - Allow to connect with Controller WS by a SSL, without check if the cert is endorsed by a trusted entity.
  4. controller.connection.timeout - The maximum time to establish a TCP connection with the controller.
  5. controller.read.timeout - The maximum time the Driver will wait for a response after sending an request to the controller.


Database settings properties:

The Driver uses a database to store the message queues. These properties define the connection to the database. Besides the specific parameters described in this section you can pass any of the parameters accepted by the connection pool of the database (detailed information about these parameters can be found at: DBCP configuration page). To pass a parameter to the connection pool the keys of the "db.connection. *" are used. For example, you want to pass the property testWhileIdle' you should pass the property as follows: db.connection.testWhileIdle = true.

Here below the most common DBCP parameters are listed (and used in the default configuration):

  1. driverClass - Database driver. For example, for MySql the driver com.mysql.jdbc.Driver would be used
  2. querydslTemplatesClass - set the class used to drive specified in driverClassName (for MySql use com.mysema.query.sql.MySQLTemplates).
  3. jdbcProperties - The connection properties that will be sent to the JDBC driver when establishing new connections. The associated value must be of the form [connection_property=value;]*
  4. url - The URL for the database connection. E.g. jdbc:mysql://localhost/cyclos3_sms_driver
  5. username - Database user
  6. password - Database password
  7. validationQuery - SQL instruction used to validate pool connections.
  8. testOnBorrow - Indicates that the objects need to be validated before dispatch.
  9. initialSize - Number of connections created at system initialization.
  10. maxActive - Maximum number of connections allowed by the pool (-1 is no limitation).
  11. maxIdle - The maximum number of connections that can remain idle in the pool, without extra ones being released, or negative for no limit.
  12. maxWait - The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned, or -1 to wait indefinitely.
  13. timeBetweenEvictionRunsMillis - The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
  14. minEvictableIdleTimeMillis - The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). Default 30 mins.
  15. connectionInitSqls - SQL statements that will be used to initialize physical connections when they are first created. These statements are executed only once.

Note: In order to define the active time zone the MySql it is necessary to apply db.connection.connectionInitSqls=set time_zone <ACTIVE_ZONE> time_zone = set. Make sure that the active zone set for MySql is the same as the one that used by Tomcat (for more details see: Make sure the Tomcat and MySQL server use the same time zone )


Message filtering process:

A message will arrive at the driver from the controller and the driver will send the message to a modem, gateway or other medium. The message text has to follow some rules and processes:


Message filtering properties:

The texts in the messages coming from the controller are verified on length and characters before the message is send to the modem, gateway or other medium (see #Message filtering process). To control the texts the following properties are available:

  1. message.maxLength - Maximum length allowed
  2. message.characterAllowed List of characters (or characters range) that are allowed.
  3. message.characterToReplace - List of character which should be replaced
  4. message.characterReplacement - List of character used for replacement


Phone number format standardizing properties:

All the messages that are received by the BaseDriver can be parsed before being dispatched. The following settings can be defined:

  1. phone.with.area.code.len - The exact number of digits the phone number has, this should have the same amount of digits as the member field in Cyclos has. When this number is not correct the messages will not be forwarded by the driver. There are two cases in which the phone.with.area.code.len won't have the same length of the phone number field of a Cyclos: a) When the phone.area.code.prefix is not empty, in this case the phone.with.area.code.len should be equal to the length of the phone number in Cyclos minus the amount of digits of the phone.area.code.prefix, b) If phone.with.area.code.len has zero or less as value, the parser and formating will not be applied by driver.
  1. phone.area.code.prefix - This parameter is only applied when phone.with.area.code.len is one or more. This field can be left blank for most countries, it is only used in some specific countries like the Netherlands or Uruguay. Mobile phone numbers in the Netherlands for example are in the format 0612345678 but from outside the Netherlands they are 0031612345678. The number 0612345678 is used in Cyclos and as user identification, but the number 0031612345678 is used by the gateway. In this case the following settings should be used phone.area.code.prefix=0, phone.with.area.code.len=9 (make sure not to include the prefix in the amount of digits) and phone.country.code=0031. For messages coming from the gateway first the country code is subtracted and subsequently the phone area code prefix is added. For messages from Cyclos first the area code prefix is subtracted and subsequently the country code is added (see example 1 below).
  2. phone.country.code - This parameter is only applied when phone.with.area.code.len is one or more. If the gateway uses the complete international number for sending and receiving sms messages and you do not want to use these in Cyclos, this parameter can be used. If you enter the country code here only messages coming from the gateway with this country code will be processed. In messages from the gateway the country code will then be subtracted from the number and the number without country code will be used in Cyclos. When Cyclos sends an SMS this country code will be added to the number registered in Cyclos. For strictly regional projects even the country code and regional code can be subtracted, then only messages from a certain region will be processed by the driver (see example 3 below).

The gateway Driver (o Gateway AIO) supports the E.123 format for the FROM of the received MO's. If a message is sent from a phone with number +31612345678 and recieved by the gateway it will be converted to 0031612345678. This measn that the symbol for the international number "+" is replaced by "00". See example 4

Note: Some countries have different phone lengths. This can be solved by disabling the phone length check. The phone.with.area.code.len and phone.country.code and phone.area.code.prefix need to be empty. The number in the user profiles will need to have the complete number (country, area, number). It will only work with the gateway. The simulator does not support different phone lengths.


Below three examples are given how the phone number is processed by the BaseDriver when it flows from the gateway to Cyclos and vise versa.

Example 1: Dutch mobile phone
↓ Gateway ↓
0031612345678 phone.country.code=0031 Country code is added/removed, only messages from gateway with 0031 are processed.
612345678 phone.with.area.code.len=9 Phone number is counted, only numbers with 9 digits are forwarded.
0612345678 phone.area.code.prefix=0 Prefix 0 is added/removed.
↑ Cyclos ↑


Example 2: Brazilian mobile phone gateway doesn't use international prefix (0055)
↓ Gateway ↓
5112345678 phone.country.code= Nothing is removed or added.
5112345678 phone.with.area.code.len=10 Phone number is counted, only numbers with 10 digits are forwarded.
5112345678 phone.area.code.prefix= No prefix is added or removed.
↑ Cyclos ↑


Example 3: United states mobile phone for local project
↓ Gateway ↓
00121212345678 phone.country.code=001212 Country and regional code is added/removed, only messages from gateway with 001212 are processed (from New York).
12345678 phone.with.area.code.len=8 Phone number is counted, only numbers with 8 digits are forwarded.
12345678 phone.area.code.prefix= No prefix is added or removed.
↑ Cyclos ↑


Example 4: Dutch mobile phone with format E.123 in the Gateway application
↓ Gateway ↓
+31612345678 phone.country.code=0031 The symbol "+" is replace by "00" in the Gateway application. The region and country code is removed (and added 0031 to the message coming from Cyclos). Only messages from the Gateway with "0031" o "+31" are processed
12345678 phone.with.area.code.len=8 Phone number is counted, only numbers with 8 digits are forwarded.
12345678 phone.area.code.prefix= No prefix is added or removed.
↑ Cyclos ↑


Example 5: Conversion y parseo deshabilitado (phone.with.area.code.len=0)
↓ Gateway ↓
+31612345678 The symbol "+" is replace by "00" in the Gateway application. All messages from/to the Gateway are processed. No country code is added/removed to message.
0031612345678 Phone number is not counted, all numbers, with any digits lenght, are forwarded.
0031612345678 No prefix is added or removed.
↑ Cyclos ↑


Default TO Phone number property: In some driver implementations you do not have a TO phone number (when you are receiving a MO message), in this case Driver will use the phone.to.default property.

Sample file: baseDriverConfig.properties
#########################################################################
# Properties file used by the Driver framework							#
# These properties are not specific for any driver implementation		# 
#########################################################################

#The driver's id and class used the send messages to controller (both mandatory)
engine.id=aioDriver
engine.class=

# Time window used to check for duplicated MO messages (in seconds)
# 0 means no duplicated check is done   
engine.duplicated.messages.timeWindow=1200
# Delay between duplicated messages cleaner executions (in seconds)  
engine.messages.digest.cleaner.delay=60

# Thread pool settings used to dispatch the messages to Controller
engine.to.controller.thread.pool.core.size=10
engine.to.controller.thread.pool.max.size=25
engine.to.controller.thread.pool.queue.size=250

# Delay between retries when a message send has failed (in seconds)
engine.retry.failed.messages.delay= 30

# This is the lifetime of the failed messages (in seconds) 
engine.failed.messages.validity=600 

#Controller connection settings using Web Services
#controller.url=http://localhost:9090/cyclos3_sms_controller
controller.url=
controller.disableCNCheck=true
controller.trustAllCert=true
controller.connection.timeout=120000
controller.read.timeout=120000

#DBCP connection pool settings
#Each property MUST be prefixed with db.connection. to be taken into account for the pool. 
#Comments from: http://commons.apache.org/dbcp/configuration.html
db.connection.driverClass=com.mysql.jdbc.Driver
db.connection.querydslTemplatesClass=com.mysema.query.sql.MySQLTemplates
db.connection.url=jdbc:mysql://localhost/cyclos3_sms_aio
db.connection.username=root
db.connection.password=

#The SQL query that will be used to validate connections from this pool before returning to the caller
#It must be a SELECT statement 
db.connection.validationQuery=SELECT 1

#If it is true then the connections will be validated before being borrowed from the pool. 
db.connection.testOnBorrow=true 

#The initial number of connections that are created when the pool is started. 
db.connection.initialSize=0 

#The maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit. 
db.connection.maxActive=35

#The maximum number of connections that can remain idle in the pool, without extra ones being released, or negative for no limit. 
db.connection.maxIdle=20

#The maximum number of milliseconds that the pool will wait (when there are no available connections) 
#for a connection to be returned, or -1 to wait indefinitely. 
db.connection.maxWait=20000

#The number of milliseconds to sleep between runs of the idle object evictor thread. 
#When non-positive, no idle object evictor thread will be run. 
db.connection.timeBetweenEvictionRunsMillis=60000 

#The minimum amount of time an object may sit idle in the pool before it is eligible for eviction 
#by the idle object evictor (if any). Default 30 mins.
db.connection.minEvictableIdleTimeMillis=1800000

#SQL statements that will be used to initialize physical 
#connections when they are first created. These statements are executed only once.
#IMPORTANT: To make sure Tomcat and MySQL use the same time zone you should set it using this property (see the example below)
#If there are more than one SQL statement each one must be terminated with a double semicolon (;;)
#db.connection.connectionInitSqls=set time_zone='America/Montevideo'

#The connection properties that will be sent to the JDBC driver when establishing new connections. 
#The associated value must be of the form [connection_property=value;]*
db.connection.jdbcProperties=useUnicode=true;characterEncoding=utf8;


# message from controller text filter
message.maxLength=160
message.characterAllowed= \u0024, ALPHANUMERIC, PUNCTUATION, <, >
message.characterToReplace=\u00E1,\u00E9,\u00ED,\u00F3,\u00FA,\u00F1,\u00D1
message.characterReplacement=a,e,i,o,u,n,N
message.characterForbidenReplacement=_

# Phone composition
# The driver doesn't accept phone numbers without area code.
phone.with.area.code.len=9
phone.area.code.prefix=
phone.country.code=

# when receive a MO message, this can use a default "to" value (only used if to is null or empty)
phone.to.default=9999


HTTP driver configuration

The HTTP driver allows to receive and send messages through HTTP GET or HTTP POST parameters. Communication with Gateway providers is commonly handled via this Driver. The HTTP driver is configured by the WEB-INF/classes/httpDriverConfig.properties file. The engine of this driver is the class nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine, therefor the first property of the configuration file is engineClass=nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine.

The parameters sent or received along with the messages are completely configurable in this property file. A parameter configured empty means it will be ignored when receiving messages or omitted when sending. For example: "tx.passwordParam=" means no password parameter will be sent.

Configure file: httpDriverConfig.properties
  1. white.list.hosts - The comma-separated list of IP (or domain URL) addresses from which the servlet will accept connections (IP addresses belonging to gateways from which messages will be accepted for processing).


Parameters and values for sending messages:

  1. tx.httpClient.maxConnection - The maximum count of concurrent connections which will be setup with the remote server (the gateway).
  2. tx.httpClient.connectionTimeout - Maximum timeout (in milliseconds) awaiting connection with the remote server (the gateway).
  3. tx.httpClient.readTimeout - Maximum timeout (in milliseconds) awaiting a response from the remote server (the gateway) after a POST or GET request.
  4. tx.url - URL to which messages for cell phones will be sent (the URL on which the gateway will accept messages we want to send to cell phones).
  5. tx.method - HTTP method used for sending parameters, possible values are POST or GET.
  6. tx.charset - Charset used to encoding text message when send a MT message (to gateway). The use UTF-8 by default, but some gateway only recognize ISO-8859-1.
  7. tx.disableCNCheck - If set to true, the server name is not checked for HTTPS connections when sending messages (MT) with the gateway. The default value is false.
  8. tx.trustAllCerts - If set to true, the certificate authority of the server certificate in HTTPS connections is not verified when sending messages (MT) with the gateway. The default value is false.
  9. tx.apiIdParam - Specifies the name of a parameter which will be passed to the gateway (if empty it will be ignored when sending). Usually this parameter identifies the application sending messages (in this case the driver) to the gateway.
  10. tx.apiId - Specifies the value which will be set to the parameter tx.apiIdParam.
  11. tx.messageParam - Specifies the name of the parameter which will be filled with the text of the message.
  12. tx.fromParam - Specifies the name of the parameter which will be filled with the origin number of the message. If empty it will be ignored on sending.
  13. tx.toParam - Specifies the name of the parameter which will be filled with the basic phone number to which the message will be sent. The value of this number depends on the settings of the parameters tx.countryCodeLen and tx.areaCodeLen.
  14. tx.countryCodeLen - Specifies the number of digits (counting from the beginning of the receiving phone number) corresponding to the country code. The initial digits of the (complete) phone number sent with the parameter tx.countryCodeParam will be subtracted from the beginning of the complete phone number and will be excluded from the rest of digits sent in the parameter tx.toParam.
  15. tx.areaCodeLen - Specifies the number of digits corresponding to the area code. The initial digits of the (complete) phone number sent with the parameter tx.areaCodeParam will be subtracted from the beginning of the complete phone number (after having subtracted the number of digits corresponding to the parameter tx.countryCodeLen) and will be excluded from the rest of digits sent in the parameter tx.toParam. This parameter has three value ranges:
    1. greater than zero - Equivalent to the number of digits identifying the area code
    2. 0 or less than zero - The parameter tx.areaCodeParam will not be sent.
  16. tx.countryCodeParam - Specifies the name of the parameter in which the country code digits of the receiving phone number will be sent. The value of this parameter depends of the setting in tx.countryCodeLen.
  17. tx.areaCodeParam - Specifies the name of the parameter in which the area code of the receiving phone number will be sent. The value of this parameter depends of the setting in tx.areaCodeLen.
  18. tx.passwordParam - Specifies the name of a parameter in which a password for authentication with the gateway will be sent. If empty the parameter will be omitted when sending.
  19. tx.password - Value for the parameter tx.passwordParam.
  20. tx.userParam - Specifies the name of a parameter in which a username for authentication with the gateway will be sent.
  21. tx.user - Value for the parameter tx.userParam.
  22. tx.okResponse - Specifies a regular expression to which the text response from the gateway will be matched for the response to be considered valid (when sending a message MT).
  23. tx.providerParam - Specifies the name of a parameter the value of which will be mapped to a value of a possible custom field (configured in the controller).
  24. tx.provider.value.DEFAULT - The value which will be used by default (when no mapping can be found for a key tx.provider.value.<value>) for the parameter tx.providerParam
  25. tx.traceParam - Reference (for trace operation) to input message or transaction.


Parameters and values for receiving messages:

  1. rx.messageParam=message - Specifies the name of the parameter in which the text of the message will be received.
  2. rx.toParam - Specifies the name of the parameter containing the phone number to which the message has been sent.
  3. rx.providerParam - Specifies a label which will be put to all messages received by this driver.
  4. rx.areaCodeParam - Specifies the parameter containing the area code of the phone number to which the message has been sent.
  5. rx.countryCodeParam - Specifies the name of the parameter containing the country code of the phone number to which the message has been sent.
  6. rx.fromParam - Specifies the name of the parameter containing the phone number from which the message has been sent. NOTE: to comply with international phone numbers the driver will concatenate the values of the parameters rx.countryCodeParam, rx.areaCodeParam, and rx.fromParam.
  7. rx.response - Specifies the response text (when there are no errors) sent to the gateway each time a message from the latter will be received.
  8. rx.userParam - Specifies the name of the parameter in which a username for gateway authentication can be received. If it is empty (or its value cannot be validated), it will be ignored when receiving messages.
  9. rx.user - Specifies the value expected in the parameter specified by rx.userParam
  10. rx.passwordParam - Specifies the name of the parameter in which a password for gateway authentication can be received. If it is empty (or its value cannot be validated), it will be ignored when receiving messages.
  11. rx.password - Specifies the value expected in the parameter specified by rx.passwordParam
  12. rx.traceParam - Unique Id for message (it will be included on response messages generated by this)


Sample file: httpDriverConfig.properties
engine.id=aioDriver
engine.class=nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine

white.list.hosts=127.0.0.1

#****************** Parameters used to SEND a request to the Gateway ******************
tx.url=http://localhost:8888/sms?
tx.disableCNCheck=true
tx.trustAllCerts=true
tx.apiIdParam=
tx.apiId=
tx.messageParam=message
tx.fromParam=
tx.toParam=to
tx.countryCodeLen=0
tx.areaCodeLen=0
tx.countryCodeParam=
tx.areaCodeParam=
tx.passwordParam=
tx.userParam=
tx.password=
tx.user=

# HTTP method to send (POST, GET)
tx.method=GET

# MT message, charset encoding
tx.charset=ISO-8859-1 

# Regular expression to identify a successful send command
tx.okResponse=.*

tx.httpClient.maxConnection=3
tx.httpClient.connectionTimeout=120000
tx.httpClient.readTimeout=120000

# Provider Configuration
tx.providerParam=
tx.provider.value.DEFAULT=0

#Define the parameter used to send back the trace data  
tx.traceParam=trace

#****************** Parameters used when RECEIVE a request from the Gateway ******************
rx.messageParam=message
rx.toParam=
rx.providerParam=
rx.areaCodeParam=
rx.countryCodeParam=
rx.fromParam=from 

# User and Password access
rx.passwordParam=
rx.userParam=
rx.password=
rx.user=

rx.method=POST 

#the response to send back to the invoker
rx.response=OK

#Define the parameter used to read trace data set by the GW  
rx.traceParam=

Modem driver configuration

The MODEM driver allows sending and receiving messages with a SMS modem. The modem driver is configured by the WEB-INF/classes/modemDriverConfig.properties file. The engine of this driver is the class nl.strohalm.cyclos.driver.modem.engine.ModemDriverEngine, therefor the first property of the configuration file is: engineClass=nl.strohalm.cyclos.driver.modem.engine.ModemDriverEngine.

Configure file: modemDriverConfig.properties
  1. smsDriver.gateway.port - tty port for serial in linux (usb adapter where the modem is connected), or com port in windows.
  2. smsDriver.gateway.serialSpeed - serial speed, with modem.
  3. smsDriver.gateway.serialPolling - serial port will be polled (instead of to wait an event, default value false).
  4. smsDriver.gateway.ModemManufacturer - self-explanatory, see smsDriver.gateway.ModemModel.
  5. smsDriver.gateway.ModemModel - self-explanatory, actually we only support Huawei modems, with models E176 y E220 (or full AT standard command compliant).
  6. smsDriver.gateway.simPhoneNumber - the phone number through which messages will be received (corresponding to the modem's SIM).
  7. smsDriver.PIN - pin for SIM card.
  8. driver.modem.adminPhoneNumber - Administrator phone number (e.g.: used to get the sms balance, see driver.modem.adminMessageMark, and driver.modem.telcoPhoneNumber).
  9. driver.modem.adminMessageMark - If an incoming message starts with this value it indicates a message from the driver.modem.adminPhoneNumber, then the message should be redirected to the TELCO directly.
  10. driver.modem.telcoPhoneNumber - TELCO support phone number (e.g.: for movistar is 222).


Sample file: modemDriverConfig.properties
engine.id=aioDriver
engine.class=nl.strohalm.cyclos.driver.modem.engine.ModemDriverEngine

smsDriver.gateway.port=/dev/gsmmodem
smsDriver.gateway.serialSpeed=19200 
smsDriver.gateway.serialPolling=true
smsDriver.gateway.ModemManufacturer=Huawei
smsDriver.gateway.ModemModel=E176
 
smsDriver.gateway.simPhoneNumber=9999
smsDriver.PIN=1234


Controller setup

The controller serves as a bridge between Cyclos and the driver software. It handles the processing of messages, it parses messages, identifies the type of the operation (payment, account info etc), manages a session per operation, processes operations and sends return messages (confirmation, error etc). The controller configuration is defined in two files: WEB-INF/classes/config.xml and cyclosInstance.properties. The config.xml file allows to set various rules and behaviors. It also contains the logic for message routing between Cyclos and the Driver.

Configure file: config.xml

The first XMl element level (controller) contain: A controller can handle communication with more than one Drivers and more than one Cyclos instances. This is defined in the following settings.


Cyclos instances:

The Cyclos instance configuration has information about a specific cyclos instance operating with this controller. It contains a list of cyclosInstance with the following elements:


Operation settings:

Some of the commands allow parameters to be passed which affect their behavior. Following is a list of commands which accept parameters and how these affect the command's behavior.


Driver instances:

Consists of a list of driverInstance, each representing a driver from which messages will be received and through which messages can be sent to members (see element cyclosInstance.DriverRouting). The element driverInstance has an attribute:

Every element of driverInstance, also contains the following entries:


Gobal setting config:

Here we define settings affecting the general function of the controller (specifically related to the routing between cyclos instances and driver instances).


Database settings:

This setting contains required data to connect to the database in which records about confirmation sessions, commands and executions as well as message data will be stored. It contains attributes username and password which represent values used for the connection. It also contains the following elements:


Session settings:

Set here data required for the function of session control for payment confirmations and commands, as well as access blocking due to incorrect access. This element contains the attribute removeExpiredDelayInSeconds specifying the time (in seconds) a session will be tracked (thus the time a session can determine an action). Has the following elements:


Sample file: config.xml

<?xml version="1.0" encoding="UTF-8"?>
<controller language="es" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="config.xsd">
  <cyclosInstances>
    <cyclosInstance name="cyclos" language="en" country="US">
       <instanceSettings whenOffline="RETRY"/>
       <currencies>
         <currency symbol="units" default="true">
           <alias name="U"/>
           <alias name="Un"/>
           <alias name="Unit"/>
           <alias name="Units"/>
         </currency>
       </currencies>
       <commands> 
	  <command name="confirm" requestConfirmation="false"/> 
	  <command name="requestPayment" requestConfirmation="false"/>
	  <command name="accountDetails" requestConfirmation="false">
	    <parameter name="nameLen" value="0"/>
	    <parameter name="pageSize" value="3"/>
	  </command> 
	  <command name="performPayment" requestConfirmation="false"/>
	  <command name="help" requestConfirmation="false"/>
	  <command name="registration" requestConfirmation="false">
           <parameter name="notifyErrorByDriver" value="false"/>
	    <parameter name="useLoginName" value="true"/>
           <parameter name="defaultInitialGroup" value="6"/>
           <parameter name="groupPrefix" value="."/>
           <paramGroup name="groupAliases">
             <parameter name="full" value="5"/>
             <parameter name="new" value="6"/>
           </paramGroup> 
	  </command>
	  <command name="infoText" requestConfirmation="false"/>
       </commands>
       <driverRouting>
         <route fromProvider="*" toDriver="aioDriver" usedFromNumber="9999" default="true"/>
         </driverRouting>
       <connectionSettings rootUrl="http://localhost:8080/cyclos" disableCNCheck="true" connectionTimeout="120000" readTimeout="120000" trustAllCert="true"/> 
       <memberSettings phoneCustomField="mobilePhone" msgParamPrincipalType="mobilePhone" providerCustomField="provider" notifyNotRegisteredUser="false">
     	  <principalSettings regexp="^(\d){7,9}$"/>
       </memberSettings>
    </cyclosInstance>
  </cyclosInstances>
  <driverInstances>
    <driverInstance name="aioDriver">
      <cyclosRouting>
        <route fromTargetNumber="9999" toCyclos="cyclos"/>        
      </cyclosRouting>
      <connectionSettings connectionTimeout="120000" readTimeout="120000" disableCNCheck="true" trustAllCert="true"/>
    </driverInstance>
  </driverInstances>
  <globalSettings responseInvalidMessages="false"/>
  <databaseSettings username="root" password="">
    <url>jdbc:mysql://localhost/cyclos3_sms_aio</url>
    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
    <querydslTemplatesClassName>com.mysema.query.sql.MySQLTemplates</querydslTemplatesClassName>
  </databaseSettings>
  <sessionSettings removeExpiredDelayInSeconds="120">
    <control timeoutInSeconds="300" maxWrongTries="10"/>  		
    <confirmation timeoutInSeconds="300" maxWrongTries="3" maxWrongPinTries="4" useKeyFromDictionaryFirst="true" keyLength="4" pendingsByCommand="3"/>
  </sessionSettings>
</controller>


Cyclos SMS configuration


Note: after a member is created, the default settings for the sms operations/notifications/mailings are used. It is possible for individual members to specify its personal preferences.


Logging with Log 4J

The SMS module uses Log4J for logging. If you prefer to change the log4j characteristics you would need to change the log4j.xml or log4j.properties files (they are placed in the root directory of sources for both applications, driver and controller). To know how to configure log4j with an XML file please refer to log4j web site.

Working with MODEMS

Most project will have the driver connected to a gateway provider. In some case it can be preferable to connect to a physical modem (e.g. for cheaper local rates, or no good gateway service provider in the region). This documentation explains how to do this.


Java communication implementation

  1. In order for the Driver of the modem to be able to connect to the hardware you need to install an implementation of the Java communication API. We suggest to use RXTX.
  2. Download the RXTX binaries rxtx-2.2pre2. For our tests we used versions with Windows XP 32 and Ubuntu 10.10 32/64 with good results. NOTE: This version shows a version warning in the log but this can be ignored.
  3. Go to the root of the ZIP file and copy the file RXTXcomm.jar to JAVA_HOME/jre/lib/ext
  4. In the zip file select the directory depending on your platform.
    1. i686 linux-gnu
    2. win 32
    3. X86_64 linux-gnu
  5. In the platform directory, copy the file rxtxSerial.dll (or librxtxSerial.so for linux) to $JAVA_HOME/jre/bin ($JAVA_HOME/jre/lib/i386 or $JAVA_HOME/jre/lib/amd64 for Linux)


Serial ports on Linux (udev command)

Another problem is that the device could appear connected as a different file under the /dev folder every time you plug the device. udev can help solve this by mapping the device to a unique file. 

$ dmesg
........
[88208.964028] usb 1-4: new high speed USB device using ehci_hcd and address 14
[88209.102329] usb 1-4: configuration #1 chosen from 1 choice
[88209.108233] option 1-4:1.0: GSM modem (1-port) converter detected
[88209.108385] usb 1-4: GSM modem (1-port) converter now attached to ttyUSB0
[88209.118211] option 1-4:1.1: GSM modem (1-port) converter detected
[88209.118348] usb 1-4: GSM modem (1-port) converter now attached to ttyUSB1
......
$

$ udevadm info -q all -n /dev/ttyUSB1
P: /devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4:1.1/ttyUSB1/tty/ttyUSB1
N: ttyUSB1
S: char/188:1
S: serial/by-path/pci-0000:00:1d.7-usb-0:4:1.1-port0
S: serial/by-id/usb-HUAWEI_Technology_HUAWEI_Mobile-if01-port0
S: gsmmodem
E: UDEV_LOG=3
E: DEVPATH=/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4:1.1/ttyUSB1/tty/ttyUSB1
E: MAJOR=188
E: MINOR=1
E: DEVNAME=/dev/ttyUSB1
E: SUBSYSTEM=tty
E: ID_PORT=0
E: ID_PATH=pci-0000:00:1d.7-usb-0:4:1.1
E: ID_VENDOR=HUAWEI_Technology
E: ID_VENDOR_ENC=HUAWEI\x20Technology
E: ID_VENDOR_ID=12d1
E: ID_MODEL=HUAWEI_Mobile
E: ID_MODEL_ENC=HUAWEI\x20Mobile
E: ID_MODEL_ID=141e
E: ID_REVISION=0000
E: ID_SERIAL=HUAWEI_Technology_HUAWEI_Mobile
E: ID_TYPE=generic
E: ID_BUS=usb
E: ID_USB_INTERFACES=:ffffff:080650:
E: ID_USB_INTERFACE_NUM=01
E: ID_USB_DRIVER=option
E: ID_IFACE=01
E: ID_VENDOR_FROM_DATABASE=Huawei Technologies Co., Ltd.
E: DEVLINKS=/dev/char/188:1 /dev/serial/by-path/pci-0000:00:1d.7-usb-0:4:1.1-port0 /dev/serial/by-id/usb-HUAWEI_Technology_HUAWEI_Mobile-if01-port0 /dev/gsmmodem
$

$ cat /etc/udev/rules.d/gsmmodem.rules
# UDEV sample for two modems:
#     interface 1, modem Huawei (vendorId=12d1)
#     modem motorola G24 (vendorId=22b8)
SUBSYSTEM=="tty", ENV{ID_VENDOR_ID}=="12d1", ATTRS{bInterfaceNumber}=="01",SYMLINK+="gsmmodem",MODE="0777"
SUBSYSTEM=="tty", ENV{ID_MODEL}=="Motorola_Phone__G24_", ENV{ID_VENDOR_ID}=="22b8",SYMLINK+="gsmmodem",MODE="0777"
$

$ udevadm info -q all -n /dev/gsmmodem 
P: /devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4:1.1/ttyUSB1/tty/ttyUSB1
N: ttyUSB1
S: char/188:1
S: serial/by-path/pci-0000:00:1d.7-usb-0:4:1.1-port0
S: serial/by-id/usb-HUAWEI_Technology_HUAWEI_Mobile-if01-port0
S: gsmmodem
E: UDEV_LOG=3
E: DEVPATH=/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4:1.1/ttyUSB1/tty/ttyUSB1
E: MAJOR=188
E: MINOR=1
E: DEVNAME=/dev/ttyUSB1
E: SUBSYSTEM=tty
E: ID_PORT=0
E: ID_PATH=pci-0000:00:1d.7-usb-0:4:1.1
E: ID_VENDOR=HUAWEI_Technology
E: ID_VENDOR_ENC=HUAWEI\x20Technology
E: ID_VENDOR_ID=12d1
E: ID_MODEL=HUAWEI_Mobile
E: ID_MODEL_ENC=HUAWEI\x20Mobile
E: ID_MODEL_ID=141e
E: ID_REVISION=0000
E: ID_SERIAL=HUAWEI_Technology_HUAWEI_Mobile
E: ID_TYPE=generic
E: ID_BUS=usb
E: ID_USB_INTERFACES=:ffffff:080650:
E: ID_USB_INTERFACE_NUM=01
E: ID_USB_DRIVER=option
E: ID_IFACE=01
E: ID_VENDOR_FROM_DATABASE=Huawei Technologies Co., Ltd.
E: DEVLINKS=/dev/char/188:1 /dev/serial/by-path/pci-0000:00:1d.7-usb-0:4:1.1-port0 /dev/serial/by-id/usb-HUAWEI_Technology_HUAWEI_Mobile-if01-port0 /dev/gsmmodem
$



Connectivity to gateway and Telco's

In most cases it is best to use a gateway service provider (GSP) for sending and receiving SMS messages. In this way it is not necessary to have negotiations with all the telco's. This chapter lists some considerations when using a GSP.


Abbreviations and Concepts

TELCO Company cellphone and SMS service.
MO Mobile Originated: a message sent by a mobile phone. The message can be sent to a phone or to a software application.
MT Message Terminated: a message to a mobile phone. The message can be sent by phone or by a software application.
GSM MODEM An electronic device that allows the sending and receiving messages (and / or data) in a cellular network. In current cellular networks, this device requires an ID chip, known as SIMM to operate.
SMS GATEWAY A provider which allow to send messages to TELCOS hidding the complexities of the TELCOS interfaces.


Connection for sending and receiving SMSs
The Driver is the module that is connected to the Gateway to allow sending and receiving messages. Another option is connect the Driver to a GSM Modem, however working with a Gateway is probably the best option.


Network Protocols
The supported connection between the Driver and the service provider is HTTP or HTTPS. You can also negotiate a VPN. However connecting through a VPN or not, we always recommend to use the HTTPS connection to improve security.


Communication protocol
It is the way the Gateway and the Driver module will interact. It is accustom to use REST as communication technologies, although we are not limited to those technologies. An agreement should be made between the Gateway and Driver technical staff about the communication protocol so one or both of them could start developing and testing the integration.


TELCO works with
It is important that the chosen provider operates with all the TELCOS you want integrate with. This is important for two reasons:


Short Number
There is typically only one short number to receive SMS messages. This short number must be requested in each TELCO you want to operate. It is usually easier for Gateways to negotiate short numbers among different TELCOS, in that case the only thing you need to do is give all information the Gateway ask for.


Cost of service
In general there are two types of contracts


Message Costs
Except the case of MT recovery message (see MT message recovery), all other messages sent by Cyclos would generate a cost to the organization that operates it. That cost is fixed by the TELCO through which the message is sent. Telcos generally tend to work by selling packets of messages, which are valid at the time (similar to a prepaid card for sending SMS messages). For this reason, the cost of sending an SMS message can depend on TELCO whereby the trafficked. In some cases gateway providers charge the organization with a cost per message traffic (received as sent, in whatever form). This cost is added to the monthly fixed cost for the service and will depend on the volume of message sent and / or received from each of the TELCO with which they work. NOTE: when the personal interview with a Gateway provider, check what are the fixed costs for the service and whether there are variable costs depending on the traffic of messages (or otherwise).


MT message recovery
Often organizations want to avoid variable costs. For these cases you can use the MT message. This type of message is charged to the recipient thereof. Depending on the laws of each region (country), may require additional clauses in contracts with users who access this service or a kind of instantaneous activation and deactivation of the same (eg via SMS). In general the cost charged for the message to the recipient exceeds the cost of a normal SMS and must be specified and informed service user. The price for the message must be negotiated with the TELCO when requesting the services of short number (for details, see the section on short number). In some cases the Gateway operator can add a fee to his favor at the cost of MT (payable by the recipient of the message). NOTE: At the time of the interview with the gateway is important to record the plans that they suggest (and whether they can work on your order against the TELCO) service for the show, and make an outline of costs for each message.


Transfer service ID (Caller ID)
Every SMS you receive comes with the service ID of the sender (The caller ID is the cellphone number). This information is essential to identify what member sent the message and that way validate the transactions. NOTE: Sometimes (especially when the message is transferred from a TELCO to another, or when the message travels across international borders), that information may not get properly. At the time of the interview with the Gateway's staff is important to note that ID is required for us to work properly.


Safety Requirements
As Cyclos operates on economic transactions special attention must be paid to data security. SMS messages should include personal data as transaction PIN, username, etc. In many countries, personal data are regulated by law. You must take into account the legislation of the region to assess the requirements of confidentiality of the information contained in the messages. For this reason the data and the means of transfer must be consistent in its protection. See also the connection point for sending and receiving data


TELCO connectivity
Gateway operator must connect each of the TELCO in which it does (to send and receive messages). Special attention should be paid to the security of data transfer. NOTE: at the time of the interview with the operator of Gateway is important to emphasize this fact and point out that security in data transfer becomes a key point. Try to get as much information as possible about the background of the Gateway operator in terms of security in their methods of operation.


Logs, and confidentiality clauses
It is important to include confidentiality clauses regarding the data that is included in messages that are trafficked, and the logs that are kept from them. NOTE: To avoid surprises, at the time of the interview with the staff of Gateway providers do note that the request will include confidentiality clauses referring to the data traffic in the messages.