Architecture - Complete Cyclos Documentation Wiki

download Architecture - Complete Cyclos Documentation Wiki

of 7

Transcript of Architecture - Complete Cyclos Documentation Wiki

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    1/7

    Architecture

    From Complete Cyclos documentation wiki

    Jump to:navigation,search

    Contents

    [hide]

    1 Components

    o 1.1 Controller

    o 1.2 Driver

    o 1.3 All In One package

    o 1.4 Command parameters

    o 1.5 Routing

    o 1.6 Number / short code 2 Web Services

    o 2.1 Controller web services used by Cyclos

    2.1.1 Payment request

    2.1.2 Notifications

    o 2.2 Controller web services used by Driver

    2.2.1 Messaging

    o 2.3 Driver web services used by Controller

    2.3.1 Messaging

    o 2.4 Cyclos web services used by Controller

    Components

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    2/7

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    3/7

    The SMS module is not an internal Cyclos component but is stand alone software, consisting

    of a Controllerand aDriver. The Controller and the Driver are currently combined in the

    main installation package (All In One package). In the future we will publish also separate

    packages for the Driver and Controller.

    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 messages, it

    parses messages, identifies the type of the operation (payment, account info etc), manages a

    session per operation, processes operations and sends return messages (confirmation, error

    etc).

    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 for developing the driver software

    was to decouple the controller from the complexities of different communication channels.

    Medium to large projects will commonly connect via a gateway provider, which offers higher

    security and scalability.

    The GSP normally has contracts with mobile phone providers and will provide 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) which means the receiver cannot reply. The most idealsituation 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

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

    All In One package

    The currently available SMS module for download is provided as an AIO package. The AIO

    package combines the Controller and Driver in a single installation, that is easier to install

    and administer. Another advantage of the AIO package is that controller and driver can

    communicate directly, without slow data exchange. Consequently, the webservice connection

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    4/7

    configurations do not apply. In the future separate Driver and Controller packages will be

    made available. Using separate Controller and Driver (instead of the AIO) is only useful for

    specific cases, for example having physical modems (connected to local Drivers) on different

    locations.

    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 (seeOperations).

    Routing

    In a typical installation of Cyclos + SMS there will be one controller/driver for one Cyclos

    instance. It is however possible to connect more than one Driver and more than one Cycos

    instance to a single controller. Because of this the controller must be able to route incoming

    (Driver > Cyclos) and outgoing (Cyclos > Driver) messages. For each message direction

    (incoming and outgoing) there are two mappings. 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 onDriverId and

    TargetShortNumer, and the second level which, on top of the first level data, adds a prefix in

    textof the message to determine the Cyclos instance with which messages will be processed

    (more details inSMS routing).

    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 ServicesThe communication between the controller and Cyclos is handled by web services. All web

    service are published in the URL/services

    Controller web services used by Cyclos

    Payment request

    Cyclos will invoke this operation to ask the Controller to confirm a payment request. It is

    published on /services/paymentRequestwith the next methods:

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    5/7

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

    o Input parameters:

    cyclosId (string): Cyclos instance identifier.

    ticket (PaymentRequestTicketVO): This ticket contains the paymentinformation and the Controller will associate it to the generated

    session.

    Notifications

    Allow Cyclos to deliver notification messages to members. It is published on

    /services/smsSenderwith the next methods:

    send: Used by Cyclos to send a notification to a member.

    o Input parameters:

    cyclosId (string): The Cyclos instance identification (used by theController to route the message).

    SMS data (SendSmsSenderParameters): Data about sending SMS (like

    destination, text, traceId, etc.)

    o Return: a boolean (true if sending was successful)

    Controller web services used by Driver

    Messaging

    Allow the Driver to send a received message to the Controller. It is published on/services/controllerwith the next methods:

    send: Invoked by the Driver to transfer a received message.

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

    traceData (String): Identification to track messages

    Driver web services used by Controller

    Messaging

    Allow the Controller to send a message to the Driver. It is published on/services/driverwith the next methods:

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    6/7

    send: Invoked by the Controller to send a message.

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

    traceData (String): Identification to track messages e

    Cyclos web services used by Controller

    Details about cyclos webservices used by the controller can be found in the documentation at

    Cyclos 3.6 web service interfaces

    Retrieved from "http://www.cyclos.org/wiki/index.php?title=Architecture&oldid=5303"

    Views

    Page

    Discussion

    View source

    History

    Personal tools

    Log in

    Navigation

    Main page

    Community portal

    Current events

    Recent changes

    Random page

    Help

    Search

    Go Search

    Toolbox

    What links here

    Related changes

    Special pages

    Printable version

    Permanent link

  • 8/13/2019 Architecture - Complete Cyclos Documentation Wiki

    7/7

    This page was last modified on 29 February 2012, at 12:31.

    This page has been accessed 4,892 times.

    Privacy policy About Complete Cyclos documentation wiki

    Disclaimers