Setup & Installation (old)

From Complete Cyclos documentation wiki
Revision as of 18:05, 15 November 2011 by Fabio (talk | contribs) (Configure the SMS service)
Jump to: navigation, search

Contents

Setup

Introduction

As explained in the architecture sections. The SMS module consists of the Controller and Driver. Besides these components there are various configurations in Cyclos. TODO describe deploy with brief overview of the projects
/simulator
/gateway (http)
/modem

List with short steps

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 security.properties file. It is recommended to avoid access to curious eyes to this file, as in this file you will find the de-encryption key for the texts stored in the database.

To avoid message encryption, and to show the texts in the log files, add the system property -Dlog.details.on.messages="true" to your tomcat. 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.

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:

  • message.encrypt.algoritm - Specifies the message encryption algorithm, currently set to "AES"
  • message.encrypt.charset - Character encoding format (7 bits) applied before encrypting a message.
  • message.encrypt.password - Encryption password for the texts in the table driver_message_log

Driver setup

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. cheaper rates)

Java comm configuration

If you want to work with a SMS modem you need to download and install the Java communication API extension (http://java.sun.com/products/javacomm/. The following steps are required:

  • The ../resources/javacomm/javax.comm.properties file should be placed in $JAVA_HOME/jre/lib (when working with Eclipse and Tomcat, the javax.comm.properties should not be located in your home directory).
  • javax.comm.properties should contain the available ports to be used by the modem, i.e:
 -\# Paths to server-side serial port devices
 serpath0 = /dev/ttyS0
 serpath1 = /dev/ttyS1
 serpath2 = /dev/ttyACM0
 serpath3 = /dev/ttyACM1
 serpath4 = /dev/ttyUSB0
 serpath5 = /dev/ttyUSB1 
  • copy ../resources/javacomm/comm.jar file in $JAVA_HOME/jre/lib/ext
  • To add the libLinuxSerialParallel.so to the runtime do ONE of the following:
    • Copy ../resources/javacomm/libLinuxSerialParallel.so to /usr/lib
    • Copy ../resources/javacomm/libLinuxSerialParallel.so to $JAVA_HOME/jre/lib/i386
    • If you are using Eclipse, add the following to the Tomcat run configuration: -Djava.library.path=${project_loc:/cyclos3_sms_driver}/resources/javacomm
Serial ports on Linux (udev command)

Some problems could arise if you are using a GSM modem (USB device) under linux. The main problem may be that the current user does not have permissions to access the device file. 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.

  • (A) type man udev to get help about the udev command
  • (B) Connect the device to the computer
  • (C) Execute dmesg command to know in what /dev the file got mounted
$ 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
......
$
  • (D) execute udevadm info -q all -n {path to the device mounting point} (or udevadm info -q all -n {path to the device mounting point} -a for details) to get more info about the device connected
$ 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
$
  • (E) create a file name for the udev rules in /etc/udev/rules.d/ name it wathever you want ending with .rules
  • (F) write down in a single line comma separated, ENV{Id param you see in step D}=value or ATTRS ({the subsystem you see in step C and D}=value), with values that identify the device you want,
  • (G) add SYMLINK+="newdevicename" were newdevicename is the name of the file you want the device to be plugged-in, MODE="0777" so you give permissions to everybody or whatever permission is right for your installation (the running user should have read and write permissions over the file)
$ 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"
$
  • (J) unplug the device
  • (K) sudo restart udev and wait a few seconds after it finishes
  • (L) plug-in the device and wait a few seconds
  • (M) udevadm info -q all -n /dev/{symlink name you added} (this should show you the device information)
$ 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
$
  • (N) setup your application configuration files to point to the symbolic link instead of the real device

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.

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:

  • (A) All letters (ascii 65-90 or 97-122 ) or digits (ascii 48-57) are allowed in a message text, except if the character is specified in point (B).
  • (B) All characters specified in the message.characterForbidden property (see Message filtering properties) will be replaced by the character specified in message.characterForbiddenReplacement (it can be empty).
  • (C) All characters specified in the message.characterToReplace property will be replaced by the character in the same list position of message.characterReplacement
  • (D) All characters specified in the message.characterAllowed property are allowed in a message text (same as for point (A) ).
  • (E) If a character is not specified in points (A), (C), or (D) it will be replaced by the character in the property message.characterForbiddenReplacement
  • (F) When a property specified a list of characters it should be separated by a comma character (,). I/E: U, u, \u00ED,;
  • (G) A character can't be duplicated in a character list of the properties message.characterForbidenReplacement, message.characterToReplace, or message.characterAllowed.
  • (H) All characters specified in the properties can be written as Unicode ("$" is the same as "\u0024")

Base driver configuration file

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.
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:

  • engine.to.controller.thread.pool.core.size - Available (permanent) for message dispatching. Every message that is pending for dispatching will use these threads
  • 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.
  • 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
  • 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.
  • 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.

  • controller.url - The base url to contact the web services served by controller (and the server to allow connection from controller).
  • controller.disableCNCheck - Allow to connect with Controller WS by SSL, without check the server name. Default value false.
  • controller.trustAllCert - Allow to connect with Controller WS by a SSL, without check if the cert is endorsed by a trusted entity.
  • controller.connection.timeout - The maximum time to establish a TCP connection with the controller.
  • 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

  1. db.connection.driverClass - Database driver. For example, for MySql the driver com.mysql.jdbc.Driver would be used
  2. db.connection.querydslTemplatesClass - set the class used to drive specified in driverClassName (for MySql use com.mysema.query.sql.MySQLTemplates).
  3. db.connection.url - The URL for the database connection. E.g. jdbc:mysql://localhost/cyclos3_sms_driver
  4. db.connection.username - Database user
  5. db.connection.password- Database password
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:

  • message.maxLength - Maximum length allowed
  • message.characterForbidden - List of characters that are not allowed
  • message.characterForbidenReplacement The character that will replace disallowed characters
  • message.characterAllowed List of characters that are allowed (in addition to letters and digits). (A character cannot be in both allowed and disallowed lists)
  • message.characterToReplace - List of character which should be replaced
  • message.characterReplacement - List of character used for replacement
Phone number format standardizing properties

All messages that are received from the Gateway the controller will be parsed and formatted before they are dispatched further. This is done in order a comply to a standard format of the origin phone number. The following settings can be defined:

  1. phone.with.area.code.len - The minimum number of digits that the phone number can have. If the digits are below this setting the message will not be processed.
  2. phone.area.code.prefix - Utilice esta propiedad para especificar el prefijo que explicita que un número telefónico contienen numero de área pero no código de país.?? *-
  3. phone.country.code - The driver can recieve and dispatch message from and to one country.?? This property is used for two cases:
    1. Verifyicar que los números telefónicos de origen de los mensajes que arriban desde un gateway (y que pueden encontrarse en su formato internacional) sea correspondiente al país que se maneja. ?? *-
    2. Para completar (de ser necesario) los números telefónicos de destino de aquellos mensajes que han de ser enviados al Gateway. ?? *-

baseDriverConfig.properties sample file

#########################################################################
# 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=
engine.class=

# 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=
controller.disableCNCheck=true
controller.trustAllCert=true
controller.connection.timeout=120000
controller.read.timeout=120000 

#Database settings
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=

# message from controller text filter
message.maxLength=240
message.characterForbidden=\u0025,#
message.characterAllowed=\u0024,-,<,>,[,],:,?,\u0021
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=8
phone.area.code.prefix=0
phone.country.code=598

Specialized drivers

HTTP Driver

The HTTP driver allows to receive and send messages through HTTP GET or HTTP POST parameters. To configure this driver, apply the following edit to the file /WEB-INF/classes/drivercontext.xml:

  1. In the accessControlManager.allowedIPMap bean, with merge="true", put the following key:
    <entry key="HTTP_GATEWAY_SERVLET" value="specific{white.list.hosts}"/>
  2. Make sure the file contains only one element of type <util:properties id="smsProperties" location=....> and that it contains the following value for location: classpath:/httpDriverConfig.properties

After theses adjustments, the file /WEB-INF/classes/drivercontext.xml must contain a section similar to the following:

<bean id="accessControlManager" parent="accessControlManagerBase">
   <property name="allowedIPMap">
      <map merge="true">
         <entry key="HTTP_GATEWAY_SERVLET" value="specific{white.list.hosts}"/>
         <entry key="MONITOR_SERVLET" value="monitor{white.list.hosts}"/>
      </map>			
   </property>
</bean>

<util:properties id="smsProperties" location="classpath:/httpDriverConfig.properties"/>

To test for proper working of message dispatch to the gateway (parameters and values sent over HTTP) you can set the tx.url parameter to http://localhost:puertoTomcat>/cyclos3_sms_driver/restricted/monitor/testServlet?command=receive&. In this case when the driver attempts to send a message to the gateway all the details will be added to the log file entry, without really sending the message to the gateway.

HTTP driver configuration

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, indeed the first property of the property file is engineClass=nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine

The comma-separated list of IP addresses from which the servlet will accept connections (IP addresses belonging to gateways from which messages will be accepted for processing) are configured in the property white.list.hosts.

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.

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.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.
  7. 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.
  8. 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.
  9. tx.apiId - Specifies the value which will be set to the parameter tx.apiIdParam.
  10. tx.messageParam - Specifies the name of the parameter which will be filled with the text of the message.
  11. 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.
  12. 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.
  13. 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.
  14. 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 - The value sent as tx.areaCodeParam will always be 0 and will not be extracted from the receiving complete phone number
    3. less than zero - The parameter tx.areaCodeParam will not be sent.
  15. 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.
  16. 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.
  17. 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.
  18. tx.password - Value for the parameter tx.passwordParam.
  19. tx.userParam - Specifies the name of a parameter in which a username for authentication with the gateway will be sent.
  20. tx.user - Value for the parameter tx.userParam.
  21. 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).
  22. 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).
  23. 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


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
httpDriverConfig.properties sample file
#####################################################
# Specific HTTP driver configuration                #
#####################################################

engine.id=httpDriver
engine.class=nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine

# 190.135.3.186 64.76.64.187 190.56.161.122
white.list.hosts=127.0.0.1, 64.76.64.187

#sending
tx.url=http://localhost:8080/cyclos3_sms_aio/testUtils/testServlet?command=receive&
tx.disableCNCheck=true
tx.trustAllCerts=true
tx.apiIdParam=
#tx.apiId=cyclos.sms.driver
tx.messageParam=message
tx.fromParam=from
tx.toParam=numeroDest
tx.countryCodeLen=3
tx.areaCodeLen=1
tx.countryCodeParam=codPaisDest
tx.areaCodeParam=areaCodeUsedOnlyForSimulation
tx.passwordParam=password
tx.userParam=pasaporte
tx.password=18818941
tx.user=demotca02
# HTTP method to send (POST, GET)
tx.method=GET
# Regular expression to idenitfy a succesfull send command
tx.okResponse=ok

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

#reception
rx.messageParam=message
rx.toParam=to
rx.providerParam=provider
rx.areaCodeParam=areacode
rx.countryCodeParam=countrycode
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

# Provider Configuration
tx.providerParam=codAreaDest
tx.provider.value.DEFAULT=0
Modem Driver

The MODEM driver allows sending and receiving messages with a SMS modem. To configure this driver apply the following changes to the file /WEB-INF/classes/drivercontext.xml :

  1. In the bean accessControlManager.allowedIPMap, with merge="true" put the following entry:
    <entry key="HTTP_GATEWAY_SERVLET" value="specific{white.list.hosts}"/>
  2. Make sure the file contains only one element of type <util:properties id="smsProperties" location=....> and that it contains the following value for location: classpath:/modemDriverConfig.properties

After the adjustments, the file /WEB-INF/classes/drivercontext.xml must contain a section like the following:

<bean id="accessControlManager" parent="accessControlManagerBase">
   <property name="allowedIPMap">
      <map merge="true">
         <entry key="MONITOR_SERVLET" value="monitor{white.list.hosts}"/>
      </map>			
   </property>
</bean>

<util:properties id="smsProperties" location="classpath:/modemDriverConfig.properties"/>


Modem driver configuration

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, indeed the first property of the file is

  • engineClass=nl.strohalm.cyclos.driver.http.engine.HttpGatewayEngine

Description of 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.ModemManufacturer - self-explanatory, see smsDriver.gateway.ModemModel.
  4. smsDriver.gateway.ModemModel - self-explanatory, actually we only support Huawei modems, with models E176 y E220 (or full AT standard command compliant)
  5. smsDriver.gateway.simPhoneNumber - the phone number through which messages will be received (corresponding to the modem's SIM)
  6. smsDriver.PIN - pin for SIM card
  7. driver.modem.adminPhoneNumber - Administrator phone number (e.g.: used to get the sms balance, see driver.modem.adminMessageMark, and driver.modem.telcoPhoneNumber)
  8. 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.
  9. driver.modem.telcoPhoneNumber - TELCO support phone number (e.g.: for movistar is 222)
modemDriverConfig.properties sample file
engineClass=nl.strohalm.cyclos.driver.modem.engine.ModemDriverEngine
smsDriver.gateway.port=/dev/gsmmodem
smsDriver.gateway.serialSpeed=19200
smsDriver.gateway.ModemManufacturer=Huawei
smsDriver.gateway.ModemModel=E176
smsDriver.gateway.simPhoneNumber=59895272093

driver.modem.adminPhoneNumber=59894590042
driver.modem.adminMessageMark=audit
driver.modem.telcoPhoneNumber=222

smsDriver.PIN=1234


Controller setup

The controller configuration is defined in two files: config.xml and cyclosInstance.properties. The config.xml file (placed in WEB-INF/classes/) allows to set various rules and behaviors. It also contains the logic for message routing between Cyclos and the Driver

Config.xml file

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.

  • cyclosInstances - A list of Cyclos instances that operate with the controller. It include the rules to route message from the cyclosInstance to driverInstances???
  • driverInstances - A list of drivers that operate with this controller. Its include the rules to route message from the driverInstance and the cyclosInstances
  • globalSettingConfig - general options
  • databaseSettings - database connection values.
  • sessionSettings - adjust session behavior.
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:

  • name - used to identify a cyclos instance, this item must have the same value as the field Identification for external channels, located at adminMenu->Settings->LocalSettings in Cyclos (see Cyclos setup). It's used just like an ID
  • language - Specifies the ISO language code to evaluate the language translation file
  • country - Specifies the ISO country code to evaluate the language translation file
  • variant - ISO variant suffix to evaluate the language translation file
  • accountAliasess - an alias list with:
    • name - Will be the name accepted in a message to identify an account.
    • value - The unit symbol in the referenced cyclos instance
  • commands - A command list containing:
    • name - Internal identifier of the command, currently valid identifiers are: confirm, requestPayment, accountDetails, performPayment, help, registration, infoText. See Operations
    • requestConfirmation - Indicates if the request requires a confirmation before executing the command (see Security confirmation)
    • A parameter list which allows to configure the behavior of the operation. Each of the elements contains the following attributes:
      • name - The parameter name, which must match the parameter expected for the command being configured (ver Operation settings).
      • value - The parameter value.
  • driverRouting - A list of route elements which specify:
    • fromProvider - A possible value for providerCustomField. All messages for members which contain this value in the providerCustomField field will be routed to 'toDriver and the corresponding usedFromNumber, specified below.
    • toDriver - A name value valid for driverInstance for which a configuration exists
    • usedFromNumber - Indicates the source number used for sending messages.
    • default - Defines that this routing is to be used as default if no specific route could be found for a providerCustomField value. Only one route where the attribute default is set to true can exist for each cyclosInstance, the default value is false.
  • connectionSettings - Defines the properties of communication with the Cyclos web services for this cyclosInstance with the following attributes:
    • rootUrl - This attribute contains the cyclos web services path (and the server to allow connection from Cyclos)
    • disableCNCheck - Allow to connect with Cyclos web service with SSL, without checking the server name. Default value is false
    • trustAllCert - Allow to connect with Cyclos web service with SSL, without checking if the certificate is endorsed by a trusted entity (root authority). Default value is false
    • connectionTimeout - Timeout waiting for establishing a TCP connection.
    • readTimeout - Timeout waiting for a response after having sent data.
  • memberSettings - Settings for member and message management in this cyclosInstance:
    • phoneCustomField - The cyclos custom field containing the member's phone number. The member's phone number must be stored without international code prefix inside cyclos (as a cyclosInstance can only operate for a single country)
    • msgParamPrincipalType - How to identify a member when referenced inside a message. The value USER implies that the member will be referenced by login name. This value can also be a member custom field defined as unique in Cyclos (including the same phoneCustomField value to use the user's phone number as identification)
    • providerCustomField - The member custom field in Cylos which contains the provider of SMS dispatching. When using a single provider, like a gateway, this attribute can be omitted. The value contained in the member custom field is used to determine the driverRouting at the moment of message sending to a user. The value contained in the member custom field is also transmitted to the Driver (where it could be used for properties mapping, see Http driver configuration ).
    • notifyNotRegisteredUser - If set to true, the system will respond with an internationalized message with key command.memberNotRegistered to messages coming from not registered members (except for member registration messages if enabled, in which case the response will be the result of the member registration)
    • principalSettings:
      • regexp - Any reference to a member contained in the text of a message must first of all match this regular expression to be considered valid (this improves security).
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.

  • Account details - See command Account details
    • nameLen - Allows to define if to show or not the name (and how much of it) of members associated to the transactions. A value greater than zero implies that for each transaction shown in the response message the first characters (as many as specified in this parameter) of the counterparty member name (the receiver if it relates to a payment, or the payer if relates to a receiving payment). Per default this parameter is 0 (zero, thus no member name characters of the participating members in the transaction). A very large value can result in the surpassing of the maximum message length as defined by the intermediary providers (the gateway or the phone operators), in which case the text may be truncated at message reception or split into more than one message (with all the costs generated). As an example, if this parameter has a value of 10, then the resulting response message would look like the following: Available balance U$S 785,50. Movs: 17/05 Daniel Mol. 25,00. 20/05 Jane Carso. -50,00. 25/05 Andriu Car. 100,00.
    • pageSize - Allows to define the amount of transactions included in the response of an account details command. Per default the value of this parameter is 3.
  • Register new user - See command Register
    • useLoginName - Determines if a login name needs to be specified as a first mandatory parameter of a registration message. If this option is enabled, the the user name registration message parameter turns optional (if not receiving a user name, the same value or login name is used). Default is true.
    • defaultInitialGroup - Allows to define the ID of the default group for which members will be registered. If not defined, it is mandatory to set the parameter aliasGroup. If a defaultInitialGroup has been defined the first parameter of the registration message will be considered a group if (and only if) it is preceded by the character(s) defined in groupPrefixChar.
    • groupPrefixChar - Specifies a character or prefix which identifies a group the first parameter of a registration message. This parameter only applies if a defaultInitialGroup has been defined..
    • aliasGroup - A parameter group (name, value) allowing to define aliases for the distinct group IDs for which member registrations are allowed.
    • notifyErrorByDriver - Determines that all error responses in the execution of this command will be sent directly by the driver (this means that Cyclos will not be able neither to apply nor register any fee of any type for this kind of messages sent). The default value is true.
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:

  • name - the name is used as an identifier of the driverInstance (see tag cyclosInstance.driverRouting.toDriver)

Every element of driverInstance, also contains the following entries:

  • cyclosRouting - determines the possible routes to cyclos instances for message processing. Consists of a list of route elements with the following attributes:
    • fromTargetNumber - The recipient phone number for messages coming from this driverInstance
    • toCyclos - A name of a defined cyclosInstance . This will be the cyclos with which messages sent to fromTargetNumber and received from this driverInstance will be processed
    • usingPrefix - Allows to define that messages received by a single driver and short number can be routed to different cyclosInstances by reference of the beginning of the text received. This attribute is optional, if present determines that all messages beginning with the specified text will be processed using this route (and its toCyclos specified).
  • connectionSettings - Specifies required values for connections with the driverInstance (used at the moment of sending messages to a member). Consists of the following attributes:
    • rootUrl - URL for the driverInstance webservices.
    • connectionTimeout - Maximum timeout awaited to establish a TCP connection to rootUrl.
    • readTimeout - Maximum timeout awaited to receive a response after having sent a request to driverInstance.
    • disableCNCheck - Allows to connect with driverInstance webservice by SSL, without checking the server name.
    • trustAllCert - Allows to connect with driverInstance webservice by a SSL, without checking if the certificate is endorsed by a trusted entity.
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).

  • responseInvalidMessages - determines that the controller sends a response to received messages that cannot be processed by any of the configured cyclos instances (and thus it can not be defined in which of those the sending member resides; this only applies when the driver instance receiving the message contains routing to more than one cyclos instance). The response message will be sent directly through the driver (and thus at the exclusive expense of the organization). This attribute is optional, and its value per default is FALSE.
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:

  • url - The connection URL to the database
  • driverClassName - The name of the class handling the database connection (for mysql use com.mysql.jdbc.Driver)
  • querydslTemplatesClassName - The name of the class managing the query language for the database used in driverClassName (for mysql use com.mysema.query.sql.MySQLTemplates).
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:

  • control - Specifies parameters for the management of control sessions. For every message the system is processing a control session is defined (except the message being a confirmation for a previous session). Contains the following attributes:
    • timeoutInSeconds - The timeout in seconds
    • maxWrongTries - Defines the maximum amount of consecutive invalid (or failed) commands (from the same mobile device) which will be processed in the timeout specified by timeoutInSeconds. If maxWrongTries in timeoutInSeconds have been surpassed from the same origin phone number, the message received (regardless if, from the same origin number, it is incoming correctly or incorrectly) will be ignored and discarded, until the timeout has been reached.
  • confirmation - Specifies parameters for the management of command or payment confirmations. Contains the following attributes:
    • timeoutInSeconds - Timeout in seconds
    • maxWrongTries - Defines the maximum amount of confirmation attempts for an invalid session key from the same phone number, until the timeout defined. If maxWrongTries in timeoutInSeconds have been surpassed, the incoming message (regardless if, from the same origin number, it is incoming correctly or incorrectly) will be ignored and discarded, until the timeout defined.
    • maxWrongPinTries - Defines the maximum amount of confirmation attempts for a valid session with an invalid credential (PIN). If maxWrongPinTries in timeoutInSeconds have been surpassed, the incoming message (regardless if, from the same origin number, it is incoming correctly or incorrectly) will be ignored and discarded, until the timeout defined. This blocking is independent of the one cyclos can generate from the concepts of invalid PIN or password.
    • keyLength - The length of the unique session password (One Time Password). Each confirmation session is identified by a randomly generated unique password of keyLength characters.
    • pendigsByCommand - Defines the maximum amount of commands that can be awaiting confirmation at the same time. If pendigsByCommand has been reached for the same origin number and a new incoming message is received (again from the same origin number), this new message (regardless if incoming correctly or incorrectly) will be ignored and discarded (except the message being a confirmation attempt).
    • useKeyFromDictionaryFirst - boolean. Determines that the unique session passwords (OTP) will be extracted from a dictionary of words in the database (instead of randomly generated). Take note that the system will use a keyword from the dictionary for the time specified in controller->sessionSettings->removeExpiredDelayInSeconds for every action it manages. If all the passwords in the dictionary table would be used up in the time span specified, the system will automatically switch to random password generation again (until passwords in use by other sessions are freed again).
Controller configuration (config.xml) sample file
<?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">
      <accountAliases>
      	<alias name="Units" value="units"/>        
      </accountAliases>
      <commands> 
		<command name="confirm" requestConfirmation="false"/> 
		<command name="requestPayment" requestConfirmation="false"/>
		<command name="accountDetails" requestConfirmation="true">
			<parameter name="nameLen" value="10"/>
			<parameter name="pageSize" value="3"/>
		</command> 
		<command name="performPayment" requestConfirmation="false"/>
		<command name="help" requestConfirmation="false"/>
		<command name="registration" requestConfirmation="false">		
		    <parameter name="useLoginName" value="true"/>
         	<parameter name="groupPrefixChar" value="."/>
        	<paramGroup name="aliasGroup">
            	<parameter name="full" value="5"/>
            	<parameter name="new" value="6"/>
        	</paramGroup>  
		</command>
		<command name="infoText" requestConfirmation="false"/>
      </commands>
      <driverRouting>
        <route fromProvider="*" toDriver="httpDriver" usedFromNumber="8648" 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="httpDriver">
      <cyclosRouting>
        <route fromTargetNumber="8648" toCyclos="cyclos" default="true"/>        
      </cyclosRouting>
      <connectionSettings connectionTimeout="120000" readTimeout="120000" disableCNCheck="true" trustAllCert="true"/>
    </driverInstance>
  </driverInstances>
  <databaseSettings username="root" password="">
  	<url>jdbc:mysql://localhost/cyclos3_sms_controller</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" keyLength="4" pendingsByCommand="3"/>
  </sessionSettings>
</controller>

Internationalization

The controller can be configured to work with multiple instances of cyclos, and each of them with a different language, text and message customization. To support these customizations a set of internationalization files exist.

Currently the versions of the SMS module include the texts necessary to operate in English and Spanish (the possibility to generate new internationalized languages is given).

The controller can generate response messages at the moment of interpreting a received SMS or when an error in the execution of a command occurs.

Internationalization files

The internationalization files can be found in the /WEB-INF/classes/i18n folder, following a naming convention:

<type>_<language>_<country>_<variant>.properties

The type is determined by the semantics of their content, which could be errors or cyclosInstance. The elements language, properties and variant are obtained from each cyclos instance configuration (see Cyclos instance). This way a cyclos instance with the following configuration:

<cyclosInstance name="c3u" language="es" country="UY" variant="C3">

entails that all messages which will be processed in that instance can generate messages with corresponding texts in the files /WEB-INF/classes/errors_es_UY_C3.properties or /WEB-INF/classes/cyclosInstance_es_UY_C3.properties. Response messages without customization in any of the files mentioned will take their text in the immediately preceding layer of the hierarchy. For example, in the case of a message key error.INVALID_AMOUNT_PARAMETER.401, generated for a received SMS message in the cyclos instance of the example above, the text resolving sequence is as follows (the order is relevant)

  • 1. /WEB-INF/classes/errors_es_UY_C3.properties
  • 2. /WEB-INF/classes/errors_es_UY.properties
  • 3. /WEB-INF/classes/errors_es.properties
  • 4. /WEB-INF/classes/errors.properties

The keys of the texts that each command / operation can generate can be found in the description of each one of them in the section Operations.

Operation messages

Operation The file /WEB-INF/classes/cyclosInstance_<language>_<country>.preference contains regular expressions which map to the matching of each command, they structure for them is command.<command>.regularExpression

For example, the file /WEB-INF/classes/cyclosInstance.preference has:

command.accountDetails.regularExpression=(\\s*)(dt|detail)(\\s+.*)*$

In this example, the given regular expression results in that the command 'Account detail' will be identified when the first characters of a message be dt or detail (the system will accept these words in uppercase, lowercase or a combination). The matching group (\\s*) is mandatory at the beginning of all keys of type regularExpression, and allows that the sequences identifying the command (in this case, dt or detail) could be preceded by blank spaces.


Confirmation The file /WEB-INF/classes/cyclosInstance_<language>_<country>.preference contains the format for messages which will be sent to users when operations requiring confirmations are used (see Security confirmation). Each command has an own template for confirmation messages with a key which follows the format command.<command>.confirmation.

The text in the key command.<command>.confirmation receives a variable component identified by {0}; this component will be substituted by the message received (indicating the operation which should be executed).

On the other hand, in /WEB-INF/classes/cyclosInstance_<language>_<country>.preference there also is a general template for a confirmation message with the key confirmation.template. This template has two parameters:

  • {0} - will be substituted by the text resulting from the key command.<commandName>.confirmation
  • {1} - will be substituted by a key valid once only, generated by the system, and which will need to be included in the confirmation message (One Time password).

An example of the text for the confirmation message for the command Direct payment, contained in the file /WEB-INF/classes/cyclosInstance.preference is:

command.performPayment.confirmation=Please verify the payment: {0}
confirmation.template={0}. Confirm sending: cf {1} <your pin>

For this example, when sending a message to the system with the text "py 094590041 10" the confirmation request message will be: "Please verify the payment: py 094590041 10. Confirm sending: cf WALL <your pin>".

All In One package setup

The package All In One (AIO) allows a Controller and a Driver to work in the same virtual machine. 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.

Configuration files

The AIO package has the configuration files config.xml, for the controller, baseDriverConfig.property for the driver, and the specific configuration of the driver (for example httpDriverConfig.properties) 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.

Cyclos setup

The following steps need to be done.

Configure the SMS service

  1. in AdminMenu->CustomFields–>MemberFields create (or verify the existence of) the member fields specified next. Enable all custom member fields mentioned below to work with the member groups operating with SMS (property Enable fields for groups). For all custom member fields mentioned below set the property Member can hide:No.
    1. Provider - This field must be a List of options containing the labels identifying all providers configured in the property fromProvider of the controller (ver Cyclos instances)
    2. MovilPhone - Use the following characteristics:
      1. Data type: String
      2. Input pattern: According to a cell phone number including the area code (if using an areaCodePrefix, add this too)
      3. Unique: Yes
  2. In AdminMenu->Settings–>Channels it is necessary to define a channel representing the operations for SMS. In following settings we will refer to this channel as 'SMS'. Configure a channel with the following settings:
    1. Display name: SMS
    2. Internal name: sms
    3. User identification: Login name, MovilPhone
    4. Default user identification: MovilPhone
    5. Credentials: Usage of PIN is recommended, but any available is valid.
    6. Supports payment request: Yes
    7. Web service url - Write here the access route to the web service for the payment request in the controller. Typically this value is composed like: 'http//<ServerNameController>:<PortController>/cyclos3_sms_controller/services/paymentRequest'
  3. In AdminMenu->Settings->Localsettings we have to indicate a cyclos which can use SMS for notifications. To this end check these properties and verify (load) the cyclos identification:
    1. Section Cyclos instance identification:
      1. Identification for external channels - Use the value Cyclos, this value is the one which needs to be loaded in the property name of the cyclosInstance of the controller (see Cyclos instances)
    2. Section SMS:
      1. Enabled: Yes
      2. Operations channel: SMS
      3. Send SMS web service url: Write here the access route to the smsSender request web service in the controller. Typically this value is composed like: 'http://<ServerNameController>:<PortController>/cyclos3_sms_controller/services/smsSender'
  4. In AdminMenu->Settings->WebServicesClients - we have to create an access to the SMS controller with the following properties:
    1. Name: SMS Controller
    2. Internet address - Set here the IP address (or DNS name) from which cyclos will be accessed (the IP address or DNS name of the server running the controller)
    3. Channel: SMS
    4. Credentials required: Yes
    5. Permissions.Perform payments: Select here all TransferTypes created for usage in SMS payments (see Enable SMS by groups)
    6. Permissions.IgnoreEMailAndCustomFieldValidations: Yes
    7. Permissions.Access account details: Yes
    8. Permissions.Send SMS messages: Yes

Enable SMS by groups

Aplique en su Cyclos los siguientes puntos para que un grupo pueda operar y/o recibir notificaciones por SMS

  1. Tomar nota de las cuentas (asociadas a los grupos) para los cuales se habilitará el servicio. En particular diagrame desde que cuenta y hacia que cuenta se permitirá a los miembros hacer pagos (o requerirlos).
  2. AdminMenu->Accounts->ManageAccounts - para cada una de las cuentas desde las cuales desea que se puedan hacer pago (por SMS) debe crear un TransferType que lo permita, con la característica de:
    1. Chanels: SMS
    2. AllowSMSNotification: Yes
  3. Para las cuentas de los grupos desde las cuales sería posible debitar liquidez por el envío de mensajes SMS, crear un TransferType que permita dicho débito (o tomar nota del existente):
    1. En AdminMenu->Accounts->ManageAccounts - desde la cuenta del miembro cree un TransferType a la cuenta que considere debe recaudar los gastos por envío de SMS. Configure las siguientes propiedades:
      1. Name: SMS operation, Notification
      2. Chanels: SMS
  4. En AdminMenu->Users&Groups->PermissionGroups - para cada uno de los Grupos que trabajen con SMS cargar las siguientes características:
    1. Modify:
      1. en la sección Access settings:
        1. Accessible channels - marque aqui el canal SMS
        2. Default channels - si desea que las operaciones de SMS esten habilitadas por defecto para los miembros del grupo marque el canal SMS
      2. en la seccion de Notification settings, cargar las siguientes propiedades:
        1. SMS allowed messages: - marque aquí todos los tipos de notificaciones que se deseen disponibles por SMS para los miembros del grupo. En particular marque el tipo de notificacion Payment events y no habilitar Payments made via external channels.
        2. Default messages sent by SMS - marque aqui todas las notificaciones que desee se encuentren marcadas por defecto para los miembros.
        3. SMS charge transfer type - seleccione aqui la trasnferType creada a fin de poder debitar liquidez al usuario por concepto de envíos de SMS.
        4. Free SMS - ingrese aquí el número de mensajes mensuales que se podrá enviar a cada miembro sin generar un cargo por dicho envío.
        5. Additional charged SMS package - ingrese aquí la cantidad de mensajes que será vendida en cada paquete. Un paquete es automáticamente vendido a un miembro si se han acabado los Free SMS para el corriente mes y no posee mensajes (sin vencer, ver Additional SMS package expires after) de paketes comprados anteriormente, al momento de enviar un mensaje de notificación (el miembro debe autorizar estas ventas seleccionando la opcion correspondiente en MemberMenu->Preferences->Notifications)
        6. Additional SMS amount - ingrese aquí el monto que se debitará al miembro cada vez que este adquiera un paquete de mensajes.
        7. Additional SMS package expires after - Los mensajes vendidos en paquetes tienen un tiempo de expiracion, seleccione aquí dicho tiempo. Ejemplo si un miembro ha comprado (en forma automática, al intentar enviar un SMS y no restarle Freee SMS para el mes en curso) un paquete de 10 mensajes, y al comenzar un nuevo mes aún le restan 3 mensajes del paquete comprados estos mensajes se comenzarán a utilizar (en tanto no expiren) luego que se terminen los Free SMS (asignados en el mes que ha comenzado).
        8. Es recomendable verificar los valores en las propiedades Max pin wrong tries y Pin block time after max tries ya que estos pueden afectar el comportamiento del sistema si se ha elegido el PIN como credential para el canal SMS.
    2. Edit permissions:
      1. En la propiedad Payments.Member payments marcar el o los TransferType creados para que el grupo pueda realizar pagos
      2. En caso de que este grupo sea capaz de solicitar pagos,en la propiedad Payments.Request payments from other channels marcar el canal SMS
      3. Si se desea que los miembros del grupo puedan ver su log de SMS enviados, marcar la opcion SMS logs.view
  5. AdminMenu->Settings->WebServicesClients - En el cliente SMS Controller marcar en la propiedad Permissions.Perform payments los TransferType creados para que el grupo pueda realizar pagos .
  6. AdminMenu->CustomFields->MemberFields - Para los custom fields Provider y MovilPhone, seleccionar este frupo en el campo Enabled fields for groups.

Configurar las preferencias de miembro

El miembro puede redefinir los valores por defecto de sus preferencias de notificacion. Desde MemberMenu->Preferences->Notifications, el miembro puede cambiar los valores para los siguientes elementos:

  1. Notificaciones de Cyclos - Cyclos genera mensajes de notificaciones, y las notificaciones pueden, o no, ser enviadas por SMS. Para configurar que un evento determine el envío de un mensaje SMS, marque la casilla correspondiente a la columna SMS para la fila del evento del cual desea recibir los mensajes. Se sugiere habilitar la notificacion Payment events, del mismo modo no se recomienda activar la notificacion de eventos Payments made via external channels
  2. Operaciones por SMS: las operaciones básicas (pago, cobro, obtener detalle de cuenta) pueden ser realizadas por SMS. Para que Cyclos admita el procesamiento de operaciones provenientes de sms marque la opcion Enable SMS operations. Si esta opción no es marcada el sistema no procesará solicitudes de operaciones SMS para el miembro.
  3. SMS Mailing - el administrador puede enviar un mensaje por SMS a un miembro o a un grupo.
    1. Accept free SMS mailings - Si el miembro marca esta opción, admite recibir mensajes del administrador que le sean enviados sin cargo. Si esta opción no se encuentra marcada y el administrador envia un mensaje si cargo al miembro, el mismo será desechado (excepto que sea un mensaje individual).
    2. Accept paid SMS mailings - Si el miembro marca esta opcion admite recibir mensajes del administrador que le sean enviados con cargo. Si esta opción no se encuentra marcada y el administrador envia un mensaje con cargo al miembro, el mismo será desechado.

Common mistakes

Once you have setup the environment it is important to run some test to check the setup was successfull.

Regular expressions

  • Take care of spaces at the begining and the end of the expression.
  • Check you accept decimal values with the right separators.

Language setup

  • Check you defined all needed keys in the properties file.
  • Check Cyclos and Controller language are the same.

Controller setup

  • Check driver names you link to different URLs.
  • Check Cyclos names you link to different URLs.
  • Check session timeout and session digits values.


Testing the system

Usted puede probar su sistema con un simulador de recepción de mensajes y un logger del driver (que le permita ver los mensajes que deberían ser enviados a un provider).

Dummy driver

El dummy driver permite probar el sistema mostrando la información de mensajes enviados en el logger del driver (visible también en el archivo catalina.out de tomcat) sin un medio real de despacho de SMS. De esta forma Ud. puede ver que se generan mensajes que serían enviados de existir un proveedor conectado al driver.

Dummy driver setting

En el archivo /WEB-INF/classes/driverContext.xml, realice la siguiente configuración:

  • (1) En el elemento <map merge="true"> (dentro de la propiedad allowedIPMap del bean accessControlManager). Coloque la siguiente configuración:
<entry key="HTTP_GATEWAY_SERVLET" value="specific{white.list.hosts}"/>
<entry key="MONITOR_SERVLET" value="monitor{white.list.hosts}"/>
  • (2) Asegurese de que existe el elemento <util:properties id="monitorProperties" con el valor classpath:/monitor.properties en su atributo location
  • (3) Asegurese de que existe un único elemento en el archivo del tipo <util:properties id="smsProperties" location=....> y que tenga el siguiente valor en location: classpath:/httpDriverConfig.properties.

El archivo /WEB-INF/classes/driverContext.xml debe quedar similar a este ejemplo:

...........
<bean id="accessControlManager" parent="accessControlManagerBase">
   <property name="allowedIPMap">
     <map merge="true">
       <entry key="HTTP_GATEWAY_SERVLET" value="specific{white.list.hosts}"/>
       <entry key="MONITOR_SERVLET" value="monitor{white.list.hosts}"/>
     </map>			
   </property>
</bean>
<util:properties id="monitorProperties" location="classpath:/monitor.properties"/>
<util:properties id="smsProperties" location="classpath:/httpDriverConfig.properties"/>

Monitor servlet

TODO: update with new screen shot

El monitor servlet le permite simular el arribo de mensajes al driver (provenientes de un provider). Las IP (lista de Ip's separadas por espacios) que pueden acceder a este servlet son las epecificadas en la propiedad white.list.hosts del archivo /WEB-INF/classes/monitor.properties.


Para acceder a este servlet apunte su navegador a http://<TomcatIp>:<TomcatPort>/cyclos3_sms_driver/restricted/monitor/

Driver simulation servlet

Text fields
    • Simulate: allow to select a simulation action
      • Sms to Controller: Simulate a received message from a cellular phone (the message will be send to controller)
      • Sms to TELCO: Simulate a received message from controller (the message will be send to cellular phone)
    • to: In case of 'SMS to Controller' corresponds to the short number, in case of 'SMS to TELCO' it's the target cellular phone
    • from: In case of 'SMS to Controller' corresponds to the origin cellular phone, in case of 'SMS to TELCO' it's the short number
    • Message: message text to send or to receive (depending of Simulate value)

Text Log files

Tanto el Controlador como el Driver generan sus propios archivos de Log. La configuración por defecto del archivo log4j.xml genera dos archivos por cada aplicación, el primero es un log simple en tanto que el segundo es mas fino y muestra detalles del funcionamiento.

Los archivos de log se generan por defecto en CATALINA_BASE/log y poseen los siguientes nombres:

  • SmsController.log
  • SmsControllerDetails.log
  • SmsDriver.log
  • SmsDriverDetails.log

En el caso de operar con el paquete integrado AIO, se generan los archivos SmsControllerDriver.log y SmsControllerDriverDetails.log

Texto de los mensajes

Por razones de seguridad en la configuracion por defecto los archivos de Log no registran el texto de los mensajes. Muchas veces es necesario tener un log detallado y trazar toda la ruta de ejecución y el procesamiento de un mensaje, para este fin existe la propiedad del sistema log.details.on.messages. Puede habilitar el registro completo de los textos de mensajes colocando el argumento -Dlog.details.on.messages="true" al tomcat (esta configuración también afecta el encriptado del texto de los mensajes en las bases de datos, por mayores detalles acceda ala seccion de Security setup).

PRECAUCIÓN: El registro completo del texto de los mensajes expone información confidencial de las transacciones y los miembros que operan mediante SMS a cualquier operador con acceso a los archivos.

Use case

Simulate: Sms to controller
Country: <empty>
area:<empty>
from: 59894590041
to: 8648
Message: pay 7410 94590042 3 units

The sample will simulate a received message (by driver) which would make a payment: from memeber with cellular 59894590041, to member with celphone number 94590042, an by 3 unit in the default currency (8648 is the short number for Cyclos, and 5678 is the payer PIN).

En la pantalla del formulario del monitor se puede observar una tabla que transcribe lo que se muestra en el Log. Para nuestro ejemplo el archivo SmsControllerDriver.log mostraría:

2011-08-24 12:35:23  WARN DriverMonitorServlet - Message received by test interface: 59894590041, 8648
2011-08-24 12:35:23  INFO ToControllerMessageProcessor - Sending message to controller: Driver Message: 
   to           = 	 8648 
   text         = 	 pay 7410 094590042 3 units 
   words        = 	 5 
   driverId     = 	 httpDriver 
   provider     = 	 null 
   from         = 	 094590041 

2011-08-24 12:35:23  INFO ControllerFacade - Message has arrived from driver. Driver Message: 
   to           = 	 8648 
   text         = 	 pay 7410 094590042 3 units 
   words        = 	 5 
   driverId     = 	 httpDriver 
   provider     = 	 null 
   from         = 	 094590041  

2011-08-24 12:35:23  INFO Command - Executing command [performPayment] with cyclos instance [cyclos] for Driver Message: 
   to           = 	 8648 
   text         = 	 pay 7410 094590042 3 units 
   words        = 	 5 
   driverId     = 	 httpDriver 
   provider     = 	 null 
   from         = 	 094590041 

2011-08-24 12:35:25  INFO SmsSenderWebServiceImpl - Message from cyclos: cyclos. Target member: Cellular 094590042. Text: Cyclos: A payment of 3,00 units was received from   094590041. Your balance is 4.984,88 units
2011-08-24 12:35:25  INFO ControllerFacade - Sending message to cyclos instance with id 'cyclos. Target: 094590041, toCharge: 094590041, text: You have made a payment of 3,00 units to member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14 units
2011-08-24 12:35:25  INFO ControllerFacade - Sending to driver: httpDriver. Controller message: 
   to           = 	 094590042 
   text         = 	 Cyclos: A payment of 3,00 units was received from 094590041. Your balance is 4.984,88 units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO DriverServiceImpl - A message from Controller has arrived: Controller message: 
   to           = 	 094590042 
   text         = 	 Cyclos: A payment of 3,00 units was received from 094590041. Your balance is 4.984,88 units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO HttpGatewayEngine - Sending message to provider: Controller message: 
   to           = 	 59894590042 
   text         = 	 Cyclos: A payment of 3,00 units was received from 094590041. Your balance is 4.984,88 units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO SmsSenderWebServiceImpl - Message from cyclos: cyclos. Target member: Cellular 094590041. Text: Cyclos: You have made a payment of 3,00 units to  member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14 units
2011-08-24 12:35:25  INFO ControllerFacade - Sending to driver: httpDriver. Controller message: 
   to           = 	 094590041 
   text         = 	 Cyclos: You have made a payment of 3,00 units to member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14  units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO DriverServiceImpl - A message from Controller has arrived: Controller message: 
   to           = 	 094590041 
   text         = 	 Cyclos: You have made a payment of 3,00 units to member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14  units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO HttpGatewayEngine - Sending message to provider: Controller message: 
   to           = 	 59894590041 
   text         = 	 Cyclos: You have made a payment of 3,00 units to member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14  units 
   provider     = 	 null 
   from         = 	 8648 

2011-08-24 12:35:25  INFO HttpTestServlet - ======================================== BEGIN OF EXTERNAL SERVICES ========================================
2011-08-24 12:35:25  INFO HttpTestServlet - ======================================== BEGIN OF EXTERNAL SERVICES ========================================
2011-08-24 12:35:25  INFO HttpTestServlet - testServlet has been invoked from 127.0.0.1 (127.0.0.1)
2011-08-24 12:35:25  INFO HttpTestServlet - testServlet has been invoked from 127.0.0.1 (127.0.0.1)
2011-08-24 12:35:25  WARN SMSMessageGenerator - Incoming message: [message={Cyclos: A payment of 3,00 units was received from 094590041. Your balance is 4.984,88 units},  areaCodeUsedOnlyForSimulation={9}, codPaisDest={598}, numeroDest={4590042}, command={receive}, pasaporte={demotca02}, from={8648}, codAreaDest={0}, password={18818941}]
2011-08-24 12:35:25  WARN SMSMessageGenerator - Incoming message: [message={Cyclos: You have made a payment of 3,00 units to member Cellular 094590042 (094590042). Transaction ID: 00267. Your new account balance is 4.849,14 units}, areaCodeUsedOnlyForSimulation={9}, codPaisDest={598}, numeroDest={4590041}, command={receive}, pasaporte={demotca02}, from={8648}, codAreaDest={0}, password={18818941}]
2011-08-24 12:35:25  WARN SMSMessageGenerator - Ignoring message for generator: invalid message response for unknown test case id (null)
2011-08-24 12:35:25  WARN SMSMessageGenerator - Ignoring message for generator: invalid message response for unknown test case id (null)

Connectivity to gateway and Telco's

Connectivity to gateway

Cyclos shuttle service for transactions via SMS can work through an SMS Gateway povider. Provider Gateway is designed to a more stable base and facilitate negotiations with each locale telcos. A continuación se consideran una serie de puntos a tener en cuenta al momento de contratar un servicio gateway para operar con Cyclos.

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:

  • The cost of messages between two TELCOS is usually more expensive than one message within the same TELCO
  • We require a short number to be unique among all TELCOS to ensure that all cellphones (regardless of the TELCO to which they belong) send messages to the same number.

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

  • You pay a fixed monthly amount to the Gateway. In some cases this include a maximum number of SMS.
  • You pay for SMS traffic.

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.