Architecture

From Complete Cyclos documentation wiki
Revision as of 14:08, 25 November 2011 by Fabio (talk | contribs) (Routing)
Jump to: navigation, search

Components

Architecture

The SMS module does not come as an internal Cyclos model but is stand alone software, consisting of an 'Controller' and a Driver. The controller and the Driver can run as separate services. There is also a deploy that runs both Driver as Controller as one application. This is the preferable setup if you connect to a gateway provider (and to directly to a physical modem)

Controller

The controller receives the messages (sent by users) and will also pass messages (the actual sending and receiving is handled by a 'Driver', explained below. The Controller serves as a bridge between Cyclos and the Driver software. It handles the processing of the messages, it will parse the messages, identify the type of operation (payment, account info etc), mangage a session per operation and will process the operation and send return messages (confirmation, error etc).

Driver

The single task of the Driver is to handle the communication with a (physically attached) modem or an SMS Gateway provider (GSP). The reason of developing Driver software was to isolate the Controller from the complexities of different communication channels. Medium to large projects will commonly connect via a gateway provider, which offer higher security and scalability.

The GSP normally has contracts with mobile phone providers and will provides a single communication channel for message delivery and routing. The GSP will commonly provide additional services like delivery guarantee and a unique number for various operators. The outbound number will typically be an alphanumeric number (combination of numeric and alpha characters 0-9, a-z, A-Z) what means the receiver cannot reply. The most ideal situation would be a contract with one GSP that provides a single number (short code) for all TELCO's that operate in a country. In case the GSP does not offer messaging services for all TELCO's, additional communication channels and drivers can be configured. The Driver will need to be adapted to apply to the protocols and instruction set (API) of the GSP. The SMS module comes with a basic Driver that can be extended.

There are several driver 'Engines', a ModemDriverEngine that can be used for communication using a GSM modem, and a HttpGatewayEngine for communication with a gateway provider. You can also connect to a TELCO talking SMPP. You can add more Engines as you need them. The actual version of driver supports GSM modem through SMSLib and the other engines can work with HTTP or HTTPS connections.

The technical structures for messaging are available in most countries. Aside of the technical issues there are also juridical issues to consider. Every country has its own laws concerning communication services and messaging. The GSP's are usually aware of the technical and juridical issues. It will be therefore a matter of negotiating with the GSP's.

Command parameters

The part of the system that carry out an action is based on the idea of commands. A command is an entity able to carry out some task at the time a message arrives. It can take an action against a Cyclos instance, although it can answer the message by itself. There are different types of commands you can setup for every Cyclos instance. Each command is developed for a specific use case (see [Operations]).

Routing

The routing is done in the Controller module. To be carried out there are two mappings, one from Cyclos to the Driver and one from the Driver to Cyclos. The Cyclos to Driver mapping is done based on two custom fields defined for every member. One of those custom fields defines what the TELCO is. The other custom field defines the member's cellphone number. The mapping from the Driver to Cyclos has two levels, the first based on DriverId and TargetShortNumer, and the second level which, on top of the first level data, adds a prefix in text of the message to determine the Cyclos instance with which messages will be processed


TODO: A) Explicar aqui el concepto de Comandos Globales, y Ruteo con Prefijo. B) referenciar la configuracion config_xm.globalSettings.responseInvalidMessages. C) Plantear problemática de que no es posible saber por que cyclos responder si se utilizan rutas globales y no matchea el comando, o si se utilizan prefijos y no matchea con el comando recibido. D) Explicar comportamiento del sistema (en cuanto a ruteo driver->cyclos) cuando se utilizan mezclas de Rutas con prefijos y comandos globales, ver CC-187 para considerar todos los posibles casos.

Number / short code

An organization or company that implements SMS operations will typically have one phone number for outbound messages and one for inbound messages. The outbound number is used for messages generated by the Cyclos system, for example payment confirmations and mailings. The inbound number will 'listen' to the client messages, these are normally operations like payments or request for information. In order to provide easy memorizable numbers (and faster typing) the organization could contract 'short code' numbers.

Web Services

The communication between the controller and Cyclos is handled by web services. All web service are published in the URL <applicationURL>/services

Controller web services used by Cyclos

TODO: revisar parametros de las acciones de los WS (y tambien los objetos de respuestas) en especial lo referido a CC-194

Payment request

Cyclos will invoke this operation to ask the Controller to confirm a payment request. It is published on <applicationURL>/services/paymentRequest with the next methods:

  • requestPayment: Send the payment request message to the member. The Controller will generate a session in order to match the member confirmation response, otherwise the session will expire (there is a parameter to specify the expiration time).
    • Input parameters:
      • cyclosId (string): Cyclos instance identifier.
      • ticket (PaymentRequestTicketVO): This ticket contains the payment information and the Controller will associate it to the generated session.

Notifications

Allow Cyclos to deliver notification messages to members. It is published on <applicationURL>/services/smsSender with the next methods:

  • send: Used by Cyclos to send a notification to a member.
    • Input parameters:
      • cyclosId (string): The Cyclos instance identification (used by the Controller to route the message).
      • memberVO (MemberVO): The target member that will be notified.
      • text (string): The notification's text.
    • Return: a boolean (true if the send was successful)

Controller web services used by Driver

Messaging

Allow the Driver to send a received message to the Controller. It is published on <applicationURL>/services/controller with the next methods:

  • send: Invoked by the Driver to transfer a received message.
    • Input parameters:
      • message (DriverMessage):
        • driverId: The driver identification. This parameter is used together with the message.to parameter.
        • message (Message):
          • from (String): The source cellphone number. This data is used by the controller to find the associated member.
          • to (String): The driver endpoint where messages arrive (the short number). This data plus the driverId are used by the Controller to find the Cyclos instance to work with.
          • text (String): The message's text.

Driver web services used by Controller

Messaging

Allow the Controller to send a message to the Driver. It is published on <applicationURL>/services/driver with the next methods:

  • send: Invoked by the Controller to send a message.
    • Input parameters:
      • message (ControllerMessage):
        • message (Message):
          • from (String): The source short number.
          • to (String): The target cellphone number.
          • text (String): The message's text.
          • provider (String): The provider must be used to deliver message.

Cyclos web services used by Controller

Puede encontrar detalles de los web services de cyclos utilizados por el controller en la documentación Cyclos 3.6 web service interfaces