Difference between revisions of "Setup & Installation (old)"

From Complete Cyclos documentation wiki
Jump to: navigation, search
m (Phone number format standardizing properties)
m (Cyclos instances)
Line 559: Line 559:
 
* '''country''' - Specifies the ISO country code to evaluate the language translation file (see [[Translation]])
 
* '''country''' - Specifies the ISO country code to evaluate the language translation file (see [[Translation]])
 
* '''variant''' - ISO variant suffix to evaluate the language translation file (see [[Translation]])
 
* '''variant''' - ISO variant suffix to evaluate the language translation file (see [[Translation]])
* <span style="background:#FFFF00"> '''currencies''' - listas de monedas soportadas en esta instancia
+
* '''currencies''' - list of units supported in this instance
** <span style="background:#FFFF00"> '''currency''' - Representa una moneda con la cual se puede operar, el atributo ''symbol'' es el simbolo que identifica a esta moneda en cyclos
+
** '''currency''' - Represents a unit with which operating is supported, the attribute ''symbol'' is the symbol identifying this unit inside cyclos
*** <span style="background:#FFFF00"> '''alias''' - el atributo ''name'' de este elemento especifica un texto con el cual puede identificarse esta moneda dentro de un mensaje. Por elemplo <alias name="units"> permite que la moneda sea identificada en un mensaje de texto como ''pay PIN RECEIVER AMOUNT units''.
+
*** '''alias''' - The attribute ''name'' of this element specifies a text with which this unit can be identified inside a me. For example, <alias name="units"> allows that the unit will be identified in a text message as ''pay PIN RECEIVER AMOUNT units''.
 
* '''commands''' - A ''command'' list containing:
 
* '''commands''' - A ''command'' list containing:
 
** '''name''' - Internal identifier of the command, currently valid identifiers are: ''confirm'', ''requestPayment'', ''accountDetails'', ''performPayment'', ''help'', ''registration'', ''infoText''. See [[#Operations|Operations]]
 
** '''name''' - Internal identifier of the command, currently valid identifiers are: ''confirm'', ''requestPayment'', ''accountDetails'', ''performPayment'', ''help'', ''registration'', ''infoText''. See [[#Operations|Operations]]

Revision as of 16:52, 12 December 2011

Contents

Setup

Installation steps

As explained in the architecture section. The SMS module consists of the Controller and Driver. Besides these components there are various configurations in Cyclos.

The SMS module is published as a single file with three packages

  • Simulator: This package can be used to test the Cyclos and SMS controller configuration without the need of connectivity to a phone operator.
  • Gateway: Used to connect to mobile phone providers or SMS Gateway providers.
  • Modem: It is possible to connect the SMS module directly to a local SMS modem or mobile phone.


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 as there is no ‘quick install’ SMS package. For the setup and configuration of SMS module experience with server administration and mobile phone protocols are required.


Common steps

  1. Download and install Cyclos (see Cyclos standard installation, or, if you prefer, Stand alone quick installation)
  2. Configure cyclos as described in Cyclos setup.
    1. Additionally in AdminMenu->Settings->WebServiceClient->SMSController
      1. In the field Manage members select the group Inactive members
      2. Select the option Access informations
    2. In order to simplify the test, give all groups that are enabled for SMS the permissions Free SMS by going to AdminMenu->User&Groups->PermissionGroups and putting 100000 in the filed NotificationSettings->FreeSMS
  3. Create two new members in cyclos:
    1. AdminMenu->User&Groups->ManageMembers->CreateMember : select the group to which SMS operation has been enabled during the cyclos SMS configuration
      1. Input and note the data of the required fields
      2. In the field "Mobile phone" input a valid phone number
    2. Register a PIN for the created members.
      1. Access the profile of each member and in the action Access->ExternalAccess set the PIN in external channels.
      2. Now the members have have credit for outgoing SMS and the possibility to accept charged messages (for more details see Configuring member preferences)
  4. Download the distribution SMS package and deploy the module you want to install to tomcat (from zip file select a folder gateway, modem or simulator, rename it as sms and put it in the tomcat webapps directory)
  5. In a local mysql create the database cyclos3_sms_aio with the schemas
    1. sms_<version>.zip/sms_<version>/db/controller/sms_controller.ddl
    2. sms_<version>.zip/sms_<version>/db/controller/session_keys_en.ddl
    3. sms_<version>.zip/sms_<version>/db/driver/sms_driver.ddl
  6. Configure the installed SMS module (for more information about this configuration, please check Driver setup and Controller setup)
    1. In the file WEB-INF/classes/baseDriverConfig.properties, edit for the configuration to access the database previously created. Modify the properties db.connection.xxxx according to your installation
    2. In the file WEB-INF/classes/config.xml:
      1. in the section controller->cyclosInstances->cyclosInstance->connectionSettings change the value of the attribute rootUrl to point to the installed cyclos instance
  7. Continue with the configuration steps for the AIO you are going to use (Simulator, Gateway(http), o Modem).


Simulator

We suggest first to install the SMS simulator. The simulator is a web page that allows testing the Cyclos configuration (see example on On-line SMS simulator) It will simulate a mobile phone and operator. This means you can simulate the entire SMS flow.

  1. Go through the common installation / configuration steps
  2. Add the following configuration in Cyclos:
    1. in AdminMenu->Settings->WebServiceClient->SMSController:
      1. Select the la option Search members (in Permissions)
      2. In the field Manage members select the group of the members that will access the simulation.
  3. Configure the installed SMS module (for more information about this configuration, please check Driver setup and Controller setup)
    1. In the file WEB-INF/classes/simulatorDriverConfig.properties check the values of the following properties:
      1. simulator.phoneLength=9
      2. cyclos.ws.baseUrl=http://<ipCyclos>:<portCyclos>/cyclos
  4. Use 9 digit mobile phone numbers for the members created in cyclos (field Mobile phone in each members' profile)
  5. From a browser access the application through the URL: http://<ipTomcat>:<portTomcat>/sms
    1. For Phone number enter one of the mobile phone numbers assigned to one of the members created in the previous step.


Note: A next step to test 'real live' operations could be done by configuring Cyclos/SMS and an SMS gateway application on a mobile phone as described in "Using a mobile phone as gateway"
Such a setup can be useful to run a pilot, and for some projects it could be used as a 'live' system.

Gateway (http)

Required information

The SMS gateway pacakge uses HTTP POST or GET to communicate with the gateway (for receiving/sending messages). The technical details about the gateway communication can be found in this section Connectivity to gateway and Telco's.

For the system configuration (and to be able to follow the steps of this guide) it will be necessary to gather some data concerning the connection with the gateway. Thus, before starting with the configuration steps, collect the following information:

  • 1 - Find out the amount of digits for phone numbers (with this amount you will have to register the member's mobile phone numbers in cyclos, and this same amount is to be used for sending and receiving messages to and from the gateway)
  • 2 - To receive MO messages (messages originated from a mobile phone):
    • 2.1 - IP address from which requests will be issued (the IP address of the gateway server from which requests to our server will be issued in order to deliver messages)
    • 2.1 - POST or GET parameter carrying the originating mobile phone number
    • 2.1 - Parameter POST or GET carrying the SMS message
  • 3 - To send MT messages (messages generated in the system which will be sent to mobile phones):
    • 3.1 - URL for sending messages MT to the gateway (from the system to a mobile phone).
    • 3.1 - Sending format (POST or GET, POST being the recommended option, if possible)
    • 3.2 - Parameter carrying the destination mobile phone number
    • 3.3 - Parameter carrying the message text
    • 3.4 - Parameters which depend on gateway requirements
      • 3.4.2 - Parameter name and value carrying the username to access the service
      • 3.4.3 - Parameter name and value carrying the password to access the service
Gateway (http) steps
  1. Step through the common installation / configuration steps
  2. Configure the installed SMS module (for more information about this configuration, please check Driver setup and Controller setup)
    1. Configure the amount of digits of mobile phone numbers. Configure this amount (in digits) in the following items:
      1. In the file WEB-INF/classes/baseDriver.properties edit the value of the phone.with.area.code.len=<longitudNumerosMoviles> property
      2. In the file WEB-INF/classes/config.xml, controller->cyclosInstances->cyclosInstance->memberSettings edit the line <principalSettings regexp="^(\d){<amountOfPhoneNumberDigits>}$"/>
    2. Configure the parameters for receiving MO messages and sending MT messages (from and to the gateway):
      1. In the file WEB-INF/classes/httpDriverConfig.properties edit the following parameters:
        1. Source IP address for requests of the gateway for delivering MO messages (triggered by a mobile phone). Edit the white.list.hosts=127.0.0.1, <SourceIPAddress1>, <SourceIPAddress2>, ... property
        2. Parameters for sending MT messages (from the system to a mobile phone):
          1. Select POST or GET for the protocol editing the property: tx.method=<POST or GET>
          2. Parameter carrying the destination mobile phone number: tx.toParam=<paramName>
          3. Parameter carrying the message text: tx.messageParam=<paramName>
        3. Parameters for receiving MO messages (originated in a mobile phone). Edit the properties:
          1. Parameter carrying the source mobile phone number of the message rx.fromParam=<paramName>
          2. Parameter carrying the message text rx.messageParam=<paramName>
        4. The URL in which MT messages will be delivered (generated in the system going to a mobile phone). Edit the property tx.url=<DeliveryURL>? (Watch out, do not forget the ? at the end of the property)
  3. From a mobile phone number registered to a member inside cyclos, send a message with a "help" text. The system should respond with a list of available commands. You can monitor the file <tomcatDir>/logs/SmsControllerDriverDetails.log to evaluate the correct operation of the system.
Using a mobile phone as Gateway

In stead of connecting to a gateway provider it is also possible to configure a locally connected mobile phone as an SMS gateway. This can be useful if you want to run a pilot with 'real live' messages before contracting gateway services. But it can also be an interesting solution for communities in remote areas where gateway services are not available, or too expensive. The only thing that is needed to deploy a payment system would be a computer running Cyclos/SMS and a mobile phone running a gateway program. The Cyclos administration could be done locally at the computer via the web interface and the users would do the operations via SMS.

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 those gateways work 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 next section).

Modem

The modem package allows connecting the SMS module working via mobile phone or modem. Usually (3G) modems that are used to connect devices 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 "Using a mobile phone as gateway"

Currently the Modem package has been tested with operating system Ubuntu 10.04, 32 bits and the modems:

  • Huawei E176
  • Huawei E226
  • Motorola Phone G24
  • Motorola V3I

This example is based based on the Huawei E176.

Preparatory steps

This guide assumes that the modem is installed en active at a serial port. Many modems have drivers for the Windows what makes the install in Windows somewhat easier. In Linux the most straightforward way is to to install a USB modem via a serial port. See Working with MODEMS.

Step by Step Modem
  1. Go first through the common installation / configuration steps
  2. Configure the SMS Modem module (for more information about this configuration, please check Driver setup and Controller setup)
    1. Configure la amount of digits in the phone number:
      1. In the file WEB-INF/classes/baseDriver.properties edit the value of the phone.with.area.code.len=<longitudNumerosMoviles> property
      2. In the file WEB-INF/classes/config.xml, controller->cyclosInstances->cyclosInstance->memberSettings edit the line <principalSettings regexp="^(\d){<amountOfPhoneNumberDigits>}$"/>
      3. Configure el the serial port that is used to connect the modem. In the file: modemDriverconfig.properties modify the parameter smsDriver.gateway.port (this parameter usually has value like /dev/gsmmodem or COM4).
      4. Configure the modem properties in the file: modemDriverconfig.properties. Modify the properties: (example used with the modem Huawei E176)
        1. smsDriver.gateway.ModemManufacturer=Huawei
        2. smsDriver.gateway.ModemModel=E176
        3. smsDriver.PIN=1234
  3. To test send from a registered user with a phone number and send a message with the text "help" to the modem nr. If correct the message should be appear in the log <catalina.base>/logs/SmsControllerDriverDetails.log (which can be viewed in the Monitor)


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
Security properties sample file
message.encrypt.algoritm=AES
message.encrypt.charset=UTF-8
message.encrypt.password=CHANGEME

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 implementation

In order for the Driver of the modem to be able to connect to the hardwoare you need to install an implementation of the Java communication API. We suggest to use RXTX.

  1. 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.
  2. Go to the root of the ZIP file and copy the file RXTXcomm.jar to JAVA_HOME/jre/lib/ext
  3. In the zip file select the directory depending on your platform.
    1. i686 linux-gnu
    2. win 32
    3. X86_64 linux-gnu
  4. 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)

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 - Use this property to declare the prefix which defines a number to have area code but no country code. For example, if configured as phone.area.code.prefix=0, the mobile phone number 12345678, which has an integrated area code, can be written as <countrycode>12345678 or 012345678.
  3. phone.country.code - The driver can receive and dispatch message from and to one country. This property is used for two cases:
    1. Verify that the source mobile phone numbers coming from a gateway (which could be in an international format) correspond to the country the driver is configured for. If this verification fails the message is ignored (and discarted without passing it to the controller). *
    2. To complete (if necessary) destination mobile phone numbers of messages which have to be sent to the gateway. *

baseDriverConfig.properties sample file

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

# 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. Communication with Gateway providers is commonly handled via this Driver.

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 or 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
  24. 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)
httpDriverConfig.properties sample file
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.to.default=9999
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

The MODEM driver allows sending and receiving messages with a SMS modem.

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.modem.engine.ModemDriverEngine

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.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)
modemDriverConfig.properties sample file
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 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 (see Translation)
  • country - Specifies the ISO country code to evaluate the language translation file (see Translation)
  • variant - ISO variant suffix to evaluate the language translation file (see Translation)
  • currencies - list of units supported in this instance
    • currency - Represents a unit with which operating is supported, the attribute symbol is the symbol identifying this unit inside cyclos
      • alias - The attribute name of this element specifies a text with which this unit can be identified inside a me. For example, <alias name="units"> allows that the unit will be identified in a text message as pay PIN RECEIVER AMOUNT units.
  • 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.
    • groupPrefix - 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..
    • groupAliases - 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">
       <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>

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).
    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)
      1. Internal name: provider
    2. Movil Phone - Use the following characteristics:
      1. Internal name: mobilePhone
      2. Data type: String
      3. Input pattern: According to a cell phone number including the area code (if using an areaCodePrefix, add this too)
      4. 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, MobilPhone
    4. Default user identification: MobilPhone
    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>/sms/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>/sms/services/smsSender'
      4. Custom field representing the mobile phone: MobilePhone
  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:
      1. Search members: if you use the Simulator you will need the setting search member true
      2. Perform payments: Select here all TransferTypes created for usage in SMS payments (see Enable SMS by groups)
      3. Manage members: Select here all the groups for which you will enable new member registrations (see OperationSettings->RegisterNewUser->defaultInitialGroup and Cyclos instances->RegisterNewUser->aliasGroups)
      4. Ignore e-mail and custom field validations: Yes
      5. Access account details: Yes
      6. Send SMS messages: Yes
      7. Get info texts: Yes

Enable SMS by groups

Apply in your cyclos the following settings in order to enable a group to operate and/or receive notifications by SMS

  1. Take note of the accounts (associated to groups) for which the service will be enabled. Particularly sketch from which to which account member payments will be allowed (or required).
  2. AdminMenu->Accounts->ManageAccounts - for each account from which SMS payments are going to be enabled you need to create a TransferType allowing it, with the following characteristics:
    1. Enabled: Yes
    2. Channels: SMS
    3. AllowSMSNotification: Yes
  3. For accounts of groups from which it should be possible to debit liquidity by SMS messages, create a TransferType allowing such debit (or take note of an existing one):
    1. In AdminMenu->Accounts->ManageAccounts - from the member account create a TransferType to the account accumulating costs for SMS sending. Configure the following properties:
      1. Name: SMS operation, Notification
      2. Channels: SMS
  4. In AdminMenu->Users&Groups->PermissionGroups - for each one of the groups working with SMS load the following characteristics:
    1. Modify:
      1. in section Access settings:
        1. Accessible channels - check channel SMS
        2. Default channels - if you wish SMS operations to be enabled per default for the members of this group check the SMS channel
      2. in the Notification settings section, load the following characteristics:
        1. SMS allowed messages: - Mark here all notification types available by SMS for group members. Particularly mark the notification type Payment events and do not enable Payments made via external channels.
        2. Default messages sent by SMS - enable here all notifications you wish to be default for members (see Configuring member preferences).
        3. Allow charging for SMS by default - Mark checked if you would like new members to be charged per default when a SMS with fee is sent to them (see Configuring member preferences).
        4. Accept free mailings by default - Mark checked if you wish new members to accept per default SMS mailings free of charge (see Configuring member preferences).
        5. Accept paid mailings by default - Mark checked if you wish new members to accept SMS mailings with fees (see Configuring member preferences).
        6. SMS charge transfer type - select the transferType created for debiting liquidity to a member by sending SMS.
        7. Free SMS - Type the amount of monthly free messages for each member.
        8. Additional charged SMS package - Type the amount of messages sold to members in each package. A package is automatically sold to a member if Free SMS ran out for the current month and there are no messages left from packages acquired before (without expiry, see Additional SMS package expires after) at the moment a notification message is sent (the member needs to authorize these sales selecting the corresponding option in MemberMenu->Preferences->Notifications)
        9. Additional SMS amount - Add here the amount debited to the member every time she will acquire a message package.
        10. Additional SMS package expires after - Messages sold in packages have an expiry, configure here the expiration time span. For example, if a member bought (automatically, trying to send an SMS and having left no Free SMS for the current month) a package of 10 messages, and on the following month she still has 3 messages left from the acquired package, these messages will start to be used (as long as they do not expire) after the Free SMS (for the new beginning month) ran out.
        11. It is recommended to verify the values in the properties Max pin wrong tries and Pin block time after max tries as these can affect the behavior of the system if PIN has been chosen as credential for the SMS channel. Probably these fields are not shown until the group configuration is saved and edited again.
    2. Edit permissions:
      1. In the property Payments.Member payments select the TransferType(s) created for the group enabled to perform payments
      2. In case this group can issue payment requests, in the property Payments.Request payments from other channels check the SMS channel.
      3. If you wish members to see the log of sent SMS, mark the option SMS logs.view
  5. AdminMenu->Settings->WebServicesClients - In the client SMS Controller set the property Permissions.Perform payments to the TransferType(s) created for the group to make payments.
  6. AdminMenu->CustomFields->MemberFields - For the custom fields Provider and MovilPhone, select this group in the field Enabled fields for groups.

Configuring member preferences

A member can redefine default values of his notification preferences. In MemberMenu->Preferences->Notifications, a member can change the values for the following elements:

  1. Cyclos notifications - Cyclos generates notification messages, and notifications can or not be sent by SMS. To configure that an event triggers an SMS message, check the box for the SMS column in the row corresponding to the event for which messages should be received. It is recommended to enable the Payment events notifications, while it is not recommended to enable Payments made via external channels notification events.
  2. SMS operations: The basic operations (payments, invoices, account details) can be performed by SMS. To enable cyclos to allow processing operations via SMS set the option Enable SMS operations. If this option is not set the system will not process operation requests by SMS for the member.
  3. SMS Mailing - The administrator can send a message via SMS to a member or group.
    1. Accept free SMS mailings - A member checking this option will accept messages from the administrator sent free of charge. If not checked and the administrator sends free of charge messages to members, the message will be discarded (unless it is a personal message).
    2. Accept paid SMS mailings - A member checking this option will accept messages from the administrator sent with a fee. If not checked and the administrator sends a message with a fee to the member, the message will be discarded.

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

Monitor

The monitor is a page (servlet) that allows to simulate the incoming messages from a provider and outgoing message to the provider. The IP address list (space separated) allowed to access this servlet are specified in the property white.list.hosts of the file /WEB-INF/classes/monitor.properties.

To access this servlet point your browser to http://<TomcatIp>:<TomcatPort>/cyclos3_sms_driver/restricted/monitor/ (foir AIO use http://<TomcatIp>:<TomcatPort>/<aio-application>)

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

The controller as well as the driver generate their own log files. The default configuration of the log4j.xml file generates two distinct file for each application, the first is a simple log file while the second shows more detail about the operation.

The log files are per default generated in CATALINA_BASE/log and have the following names:

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

When operating with the integrated package AIO, the files SmsControllerDriver.log and SmsControllerDriverDetails.log are generated.

Message text

For security reasons the default configuration does not write the message text to log files. Often it is necessary to have a detailed log and to trace the complete route of execution and processing of a message. To this end the system property log.details.on.messages exists and is true. You can enable the complete entry view in log files putting the argument -Dlog.details.on.messages="true" to tomcat (this configuration also affects the text encryption of messages in the database, for more details refer to the section Security setup).

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

Use case

Simulate: Sms to controller
Country: <empty>
area:<empty>
from: 094590041
to: 8648
Message: pay 7410 094590042 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).

On the screen of the monitor a table can be observed transcribing all which is going to be written to the log. For our example, the screen would show:

Monitor use case

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 local telcos. This section lists some consideration points concerning the gateway services.

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.