2. Introduction

2.1 Purpose 

The document captures the overall behavior of the Linq2 system and help and support for the LinQ2 System. 

The purpose of this document is to provide the help contents as well as Support of a LinQ2 System. 

The scope of this document covers the help content of the LinQ2 System.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color. To edit the organization details click on the Organization ID.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color. If you don’t select any organization from the menu then the new created organization will add as a sub organization in to the main organization. In add Organization page all the fields are mandatory.

Enter Organization name in provided text box. Enter Department Code in provided text box. Enter Department Location in provided text box. Enter Sender Id in provided text box.
 If you are not providing sender id than sender id will be default sender id. To save this Organization please click save button. To reset field please click reset button. 

In edit Organization page all the fields are mandatory. You can modify Organization Name, Department Code and Department Location, Sender Id in this page. If you are not providing sender id than sender id will be default sender id. To save this Organization please click save button. To reset field please click reset button.

You can view previously saved organization list on this page. In this page you can find organization id and description of particular organization. Please click Org id hyperlink to modify organization detail. If you want to add new organizations then first select main organization from left displayed organization list. If you are not selecting any organization from left displayed organization then this new organization will add as a sub organization in to the main organization. You can recognize selected organization highlighted with red color in the left menu. After performing this step please click Add organization button.

 If you want to delete any/all organization's then please select the check box and click Delete organization button.

Remember that Process Verifier might be applied. “Will be discussed later”

From add quota page you can assign quota to particular organization form available SMS credit balance. First select the organization from left side menu list. You can identify selected organization highlighted in red color. If you want to assign unlimited quota to particular organization then select the organization and check unlimited check box. Otherwise write quota in Quota box. To save please click save button.
 To reset please click reset button.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color. All displayed roles belong to the highlighted organization. 

Users having privilege of Role management can create and define new roles. Roles are specific to an organization.

Only roles belonging to an organization can be assigned to the new users/ existing users of that organization.

To maintain and manage roles, privileged users can navigate to the   HOME-->ORGANIZATION-->ROLES link. Roles List is displayed specific to an organization. By default the list of roles belonging to the logged in user’s organization will be displayed. 

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color. All displayed roles belongs to the highlighted organization. 

Users having privilege of Role management can create and define new roles. Roles are specific to an organization.

Only roles belonging to an organization can be assigned to the new users/ existing users of that organization.

To maintain and manage roles, privileged users can navigate to the   HOME-->ORGANIZATION-->ROLES link. Roles List is displayed specific to an organization. By default the list of roles belonging to the logged in user’s organization will be displayed.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color. Role name is mandatory.

 User can select privilege for this role and later user can change privilege for this role from edit role page. All the users having this role are not authorized for such a privilege which is not assign to this role. Enter the role name, privilege for new role and click save button.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color.

Role name is mandatory. User can change privileges for this role. All the users having this role are not authorized for such a privilege which is not assign to this role. User can update the role name, privilege for this role and click save button.

Note: Changes to the privileges of a role will be in effect once the users belonging to the role re login with their user id.

Select the organization by clicking on the respective organization displayed in the left in hierarchical form. The selected organization will be highlighted in red color.

Note: Before deleting any roles ensure that there are no user/users belonging to those role/roles. 

Users can delete a single or multiple roles at a time. Select the appropriate check box before the role item in the role list.  To delete all roles click on the check box in the table header. Select the roles to delete and click the Delete button. A confirm dialog box will appear to delete the role. To confirm click the ok button or cancel to discard it.

Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color.

 All listed users belong to the highlighted organization. The list displays User name, First name, Last Name, Role Name, Last Login Date, Last Modified Date. 

To add new user click on the add user button. 

To delete specific user select user/users you want to delete then click delete user button. 

To edit specific user, click on user name hyperlink.

• Template is pre-formatted SMS which you can use to send quick message to your customers.
  
  Template is pre-formatted SMS which you can use to send quick message to your customers.
  View previously saved list of templates
  
  Find the template lists which contains template name, language, template type and messages for a particular template.
  To edit the template click on the template name
  click Add button to add new template
   To delete any/all templates then please select the check box and click Delete button.
• Add Templates
• Template is pre-formatted SMS used to send quick message to your customers.
   Following is a brief description of all the fields in the form:
• 1. Template Name: Unique name for the template should be at least 6 characters and should not contain spaces. 
• 2. Language: Language for the template.
• 3. Template Type: The type of the template. 
• a. User: For individual user purpose, users can use these templates for sending messages to customers from the compose screen. 
• b. Application: Corporate administrators and System Administrators can create such type of templates. Once created these types of templates can be used by all the users of the organization.
• c. System: Only System administrators can create such type of templates. System type templates are used by system for internal purposes and for backend integrations. 
• 4. Message: The actual message for the template.
  
  To save this template please click save button.
   To reset field please click reset button.
  
• Edit Template
• Template is pre-formatted SMS which you can use to send quick message to your customers.
  
  You can modify previously entered values for template you can modify previously entered Template name in provided field. This name should not contain any spaces.
  You can modify template language from Language option.
  
  Modify template Type from Template type list.
  
  You can modify template message in MESSAGE box.
  To save these templates please click save button.
   To reset field please click reset button. After clicking this button you will get previously saved value for this template.
• List Template
• Template is pre-formatted SMS which you can use to send quick message to your customers.
  
  You can view previously saved list of template on this page.
  
  You can find template list which contains template name, language, template type and messages for particular template.
  Please click template name hyperlink to modify saved template.
  If you want to add new template then please click Add button.
   If you want to delete any/all templates then please select the check box and click Delete button.

LinQ2 provides capability for business users to send promotional messages to customers. The campaign Management screen provides capability to add a new campaign, update an existing campaign, delete campaigns and send campaigns to a group of customers.

A response from Customers for these promotional messages are received and stored for reporting using Campaign Log report.

Campaign Management functionality is also available to Business Users only.

Campaign List

Campaign is a series of advertisements and other marketing efforts sharing a common element and getting feedback from the customer.
Select the organization by clicking on the required organization list displayed in the left. The selected organization will be highlighted in red color.
You can find list of campaign belongs to highlighted organization on this page.

You can view campaign code, campaign name, campaign text, campaign language.
You can Add, delete, update any campaign from this page. To add new campaign click add button. To update an existing campaign, click campaign name.
 To delete campaigns select check box and click delete button.

Send Campaign

Messages will be created based on the options provided in the campaign creation section. To send a campaign message, Users need to click on the send link next to campaign in the campaign list. The users are presented with generated campaign message and list of groups available in the system. Users can select multiple groups and send campaign messages to these groups.

Overview

Modern systems have one or more back-ends. The back-end holds the data which represents the system state or works as a data resource. There are many types of back-ends, for example databases, queues, and others. LinQ2 has five predefined back-end types that the user can not delete, or modify from user interface. He cannot add a new backend type as well. One of these types is the SYSTEM type, which is used to represent LinQ2 configuration parameters. This type has only one predefined instance, whereas other types could have as many instances as the user needs.

LinQ2 backend types

As mentioned, LinQ2 has five predefined back-end types. These types are not editable. Bellow is the table of these types:

In this version of LinQ2, available operations on backend type are: add, and show list. 

The user can add a new instance to any type where add operation is allowed. If the add operation is allowed for a specific type, an add link will be displayed next to that type's name. The user can also browse all instances of a specific type by clicking on the show list link. For more details about editing instances, refer to (See also) section in this page.

The user can list the instances of any type by clicking on the show list link that is next to the type's name. By listing instances, all instances of the selected type will be displayed, and the information displayed about each instance contains its name, and one of its major parameters. This major parameter changes in respect of the backend type of the instance, for example when listing database instances, it will be "host",  and when listing  file instances it will be "Source" and so on. The user can click on either the instance name or its major parameter to go to the editing page. He can also delete one or more instances, or add a new one.

In this version of LinQ2, available operations on backend instances are: add, delete, and edit. 

The user can add a new instance through instance editing page. He can go to this page by clicking on either add link that is next to backend type's name, or the add button that appears when the instances list for a specific type is displayed. The user can also edit any instance through the editing page by clicking on its name or its major parameter. Instance Deletion is done by checking the instance(s) that user wants to delete, then clicking delete button. An exceptional case is the SYSTEM type instance, which is named linq2. The user is not allowed to add a new instance or delete this instance, but he can configure its parameters.

Backend Instance Configuration

Overview

LinQ2 is a middleware between client's back-ends and SMSC. LinQ2, using the client back-end, gets the client content and delivers it to the customers. Database is an example of a backend, assuming that the client`s content is provided across many databases and the client expects LinQ2 to access his different databases independently. LinQ2 has this facility which allows the user to define as many back-ends as he needs, and these defined back-ends will be accessible independently and simultaneously. Back-ends are varied, each type of them needs to be configured differently, and LinQ2 provides four common types of back-ends. These types are database, file, queue, and email. In a subsequent section, we will see how to configure each type.

User Operations

In this version of LinQ2, available operations on instances configuration are

• Change the instance's name 
• Change its parameters values. 

The user can define a new instance and configure it (see Backend Type Instances page). When the add link is clicked, the user will be directed to an edit page. This edit page suggests a name for the new instance; the user can accept the suggested name or change it. The parameters need to be entered with valid values. The user can enter them during creation process, or later by editing the instance. The new instance will not be saved unless the user clicks the save button. 

For editing a created instance, the user has to list all instances and then click on the instance that is required to be edited. Going to the edit page is done by either clicking on the instance's name, or on its major parameter that is next to its name. Editing page allows the user to edit the entire instance's related information, name and any other parameter. The user modifications will not be updated unless the user clicks the update button. 

Note: when the cancel button is clicked, the user will be returned back to the previous page, and the operation will not be completed.

Configuration Details

Following are more details about how to configure an instance of each LinQ2 backend type.

SYSTEM Type:

DATABASE Type:

FILE Type:

QUEUE Type:

EMAIL Type: 

In this page you can select service type which you would to add. 

• Select service type from drop down list. 
• To continue click next. 

In This page you can add parameters SQL query and Templates to complete pull and push services. 

Service Parameters: In this section you can add or remove parameters. 

1. To add new parameter click on add button.
2. To remove parameter click on Remove it link.
3. All parameters include name, value and type. Name and value dependence type as follows: 
   • Mandatory
     • The name is mandatory and must be correspond with same name and order in the SQL statement. 
       • The value is optional.
   • Optionally
     • The name optional.
   • SMPP-Mob
     • The param name is “mobile”. And the value mobile number is retrieved from SMPP Protocols.
   • SMPP-Shortcode
     • The param name is “shortcode”. And the value of shortcode is retrieved from SMPP Protocols.
   • SMPP-language
     • The param name is “language”. And the value of language is retrieved from SMPP Protocols.
   • SMPP-Keyword
     • The param name is “keyword”. And the value of keyword is retrieved from the pull messages as first token.
   • Fixed
     • The name is mandatory and must be correspond with same name and order in the SQL statement.
     • The value is mandatory.
4. 
   
   1. Example
      • Parameter

• Source Information: In this section you can select(database source, templates) and entered(SQL query  and templates value).
  1. Database Source is mandatory and selected from drop down list. 
  2. SQL Query is mandatory. 
  3. Template is mandatory and selected from drop down list. 
  4. Template value is read only and appears when template is selected from template list drop down. 

Notes

• Fields name and order and length must correspond in all of sql Query (column ) and Template value (column). 
• Parameter name and order and length must correspond with parameter in Template value. 

In this page you can edit internal or content service. 

• Internal Service: 
  • The Service Name is mandatory. 
  • Frequency is optionally. 
  • Handler is optionally. 
  • Processor is optionally. 
  • Active default is checked. 
  • To complete click save button.
• Content Service: 
  • The Service Name is mandatory. 
  • Short Code is mandatory and must be in digits. 
  • English Keyword is mandatory. 
  • Arabic Keyword is mandatory. 
  • Handler is optionally. 
  • Processor is optionally. 
  • Active default is checked. 
  • To complete click save button.

Providers are SMS Gateways where SMS are forwarded by LinQ2 for futher forwarding to the mobile devices. 

LinQ2 can support different types of SMS Gateways: SMPP,HTTP, CIMD2, GSM. 

Currently LinQ2 supports SMPP gateways. You can add any number of providers. But only one will be a default provider.

After creating a provider you can 'add' a new session or view the 'session list' for a provider by clicking on the respective links. 

To add a new provider, click on the 'Create' button in the provider list form.

Note: This configuration should be done by system administrators only. 

Following is a description of the form fields:

1. Provider Name: Any suitable name for identification purpose.

2. Default Provider: Whether this provider is a default provider for the system. The system will not accept a default provider if already one has been defined. 

3. Type: The type of provider.

a. SMPP - Used to connect to the Telco's SMSC.

b. HTTP - Used when the SMS Gateway is hosted over internet.

c. MMS - When the gateway is MMS. 

d. CIMD2 - Used to connect to mobile devices. 

e. GSM- Used to connect to GSM Modems.

4. Class: The handler class for the Gateway. (Applicable if the provider Type is not SMPP.) 

After filling the mandatory fields users need to click on the 'Create' button to save it. 

To edit a provider, click on the required provider name in the provider list form.

Note: This configuration should be done by system administrators only. 

Following is a description of the form fields:

1. Provider Name: Any suitable name for identification purpose.

2. Default Provider: Whether this provider is a default provider for the system. The system will not accept a default provider if already one has been defined. 

3. Type: The type of provider.

a. SMPP - Used to connect to the Telco's SMSC.

b. HTTP - Used when the SMS Gateway is hosted over internet.

c. MMS - When the gateway is MMS. 

d. CIMD2 - Used to connect to mobile devices. 

e. GSM- Used to connect to GSM Modems.

4. Class: The handler class for the Gateway. (Applicable if the provider Type is not SMPP.) 

After filling the mandatory fields’ users need to click on the 'Create' button to save it. 

Caution: Deleting a provider will automatically delete all the sessions associated with a provider. 

To delete a provider navigate to the provider’s list page. Select the appropriate provider by clicking on the check box on the left side. 

Click the 'Delete' button on the bottom of the form. 

A final confirmation dialog will be prompted. Click 'OK' to confirm or 'Cancel' to stop. 

Sessions are basically channels to communicate with providers, especially when the provider is of type SMPP. More number of sessions more will be the throughput of the system. 

A SMPP provider can have any number of channels, provided they are registered with the SMSC provider. If they are not registered LinQ2 will not be able to connect using the channel. 

To view the list of sessions for a provider, click on the 'Show List' link for the appropriate session. 

Caution: This configuration should be made by system administrators. 

 Once you press “Save”, your session is saved and you will see :  

To delete a session navigate to the 'Session List' first and click on the appropriate checkbox in the left for the appropriate session. 

Click on the 'Delete' button in the bottom of the form.

A final confirmation dialogue will be displayed. Click on the 'ok' button to delete or 'cancel' to stop.

Please enter Enumeration Name, Enumeration Type Enumeration Value and select language for this Enumeration.

Note: - All the fields are mandatory. 

To save Enumeration please clicks save button.

To reset entered details please click Reset button.

You can edit Enumeration values this page. You can view old values for this Enumeration.
 You can modify Enumeration Name, Enumeration Type Enumeration Value and selected language for this Enumeration.

Note: - All the fields are mandatory. To save Enumeration please clicks save button.
 To reset entered details please click Reset button.

This is for the system to receive SMS messages as mails. Mail Configuration is done in 

Mail-service.xml file.   This is found in (Jboss server dir)/deploy directory

<mbean code="org.jboss.mail.MailService” name="jboss:service=Mail">

     <attribute name="JNDIName">java:/Mail</attribute>

     <attribute name="User">nobody</attribute>

     <attribute name="Password">password</attribute>

     <attribute name="Configuration">

         <configuration>

           <!-- Change to your mail server prototocol -->

           <property name="mail.store.protocol" value="pop3"/>

           <property name="mail.transport.protocol" value="smtp"/>

           <!-- Change to the user who will receive mail  -->

           <property name="mail.user" value="nobody"/>

           <!-- Change to the mail server   -->

           <property name="mail.pop3.host" value="pop3.nosuchhost.nosuchdomain.com"/>

           <!-- Change to the SMTP gateway server -->

           <property name="mail.smtp.host" value="smtp.nosuchhost.nosuchdomain.com"/>

           <!-- Change to the address mail will be from  -->

           <property name="mail.from" value="nobody@nosuchhost.nosuchdomain.com"/>

           <!-- Enable debugging output from the javamail classes -->

           <property name="mail.debug" value="false"/>

        </configuration>

        <depends>jboss:service=Naming</depends>

     </attribute>

   </mbean>

Changes to be made to the XML file:

                         <property name="mail.store.protocol" value="pop3"/>

                        <property name="mail.user" value="nobody"/>

                         <property name="mail.smtp.host"                                                    value="smtp.nosuchhost.nosuchdomain.com"/>

                        <property name="mail.from"                                                               value="nobody@nosuchhost.nosuchdomain.com"/>

Configuration of the system database is done in a linq2-ds.xml file. 

This is found in (Jboss server dir)/deploy directory.

The configuration explained here is for MSSQL database.

<datasources>

    <local-tx-datasource>

     <jndi-name>jdbc/reach</jndi-name>

     <connection-url>jdbc:sqlserver://localhost;databaseName=LinQ2</connection-url>

     <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>

     <user-name>sa</user-name>

     <password>password</password>

     <min-pool-size>10</min-pool-size>

     <max-pool-size>100</max-pool-size>

   </local-tx-datasource>

</datasources>

Changes to be made for the database configuration.

                          <connection-url>

                                    jdbc:sqlserver://server-ip;databaseName=LinQ2

                        </connection-url>

                         <user-name>sa</user-name>

                          <password>password</password>

Logs directory is defined in Backend type “System”.  By default log files are written in to this directory. User can also check the logs of previous dates. 

File name is appended with the date. Date format is “YYYY-MM-DD”

            Example:      test.log.2009-01-12 

Logs are also posted to the database. Database configuration is done in log4j.xml for the logs to be posted in database. 

Administrator can view the logs from sub menu

                        Operations>Daily Message Log

From this page you can monitor message statistics, mms statistics, email statistics, session status, services status and some recent lines of error.

 Message Statistics:- 
You can view total number of successfully delivered message, total number of rejected message, total number of pending message, total number of received messages for current date and pending messages.
   

MMS Statistics:-
 You can monitor sent, rejected and pending MMS messages.

Email Statistics:-
 You can monitor sent, rejected and pending Emails.

Services Status:- 
You can view available services and the current status of the service. If the service is running and currently processing then you can find red/blue sign for that particular service.
If the service is up and idle then you can find green right sign for that particular service. Otherwise it will show red cross sign.
 You can change status of running service from service action.

 Session Status:- 
You can view available list of session and session provider, status of session and the name of the session.

Error Monitor:-
 You can view 20 lines of last error occurrence from message logs.

System Tools is a module built in LinQ2 to enhance performance and usability.

It is divided in three categories depending on the purpose of them.

Archiving process is aimed to enhance the performance of LinQ2 in case that too many records were inserted in the table MESSAGE_OUT.

Purging process is aimed to enhance the performance of LinQ2 by deleting old records in the table ERROR_LOG.

Resending process is aimed to help resending the records kept in status "picked" in the table MESSAGE_OUT if a sudden crash occurred before trying to send them.

Accumulated records in the table Message_Out make the system hangs due to extra overload.

To start the process you should set the following parameters:

1. Type(s) of messages that are going to be archived.
2. Archiving cycle: this is the max size of DB batch executing the archiving process.

Then you should hit the “Start Archiving” button.

The mechanism of archiving is done as cycles each in three steps:

1. Finding the records to be archived.
2. Inserting these records in the archiving table Message_Out_Bkp.
3. Deleting these records from Message_Out.

Some notes about the archiving process:

• The archiving processor will rollback the transaction In case any of the previous steps of archiving process failed the system to guarantee no records will be missed.
• Archiving is a heavy process as it deals with large number of records in more than one table, so that we recommend to be started 30 minutes before the end of office time.
• The progress of the process is shown in the table. It needs to press the button “Refresh Archiving” to refresh archiving progress table.
• In case the button “Stop Archiving” was hit, the system will finish the current cycle then it will quit. That is the reason we recommend (5000) cycle size.
• You can NOT run more than one archiving process.
• A complete separate log file will be corresponding to each process can be downloaded by pressing on the “Download File” in the archiving process table. 

Purging process is responsible for deleting old records from the Table “Error_Log”, this process is done as a delete SQL statement on DB side. So that, this process cannot be stopped once it started.

To start purging process you should set the time/date of the oldest log you are planning to keep in the table “Error_Log”, then you should hit the button “Purge”.

Just like archiving process, purging process has a progress table to view the history of purging processes and to download the log file for each process as well.

In case the system has crashed that caused “picked” messages to be lost before sending to the SMSC, the resend process is the way to handle this issue.

When you provide the time before and after the crash the crash in the date/time fields, then pressing “Resend”, the system will change the status of each message that has “picked” status between these two date/time values from “picked” to “new”.

 Also, resending process has a progress table to view the history of resending processes and to download the log file for each process as well.

Failover mechanism in LinQ2 is done by grouping providers. In other words it is done on group level. For example, please check table below. Here you will notice that providers (A, B) are in the same group. In such case, if provider (A) goes down all its messages will be sent through provider (B). But in case provider (C) or (D) fails their messages will be kept without sending. 

You can configure multiple providers in groups in window of Configuration-> Providers

You can configure a provider to be in a group by choosing it, or in creation step.

Once you add a provider to a group you should find postfix of provider name with the group number. 

To allow message to go through a specific provider according to its mobile prefix number, LinQ2 has to be configured mainly in two points:

• Provider pattern 
• Active flag of Auto route feature. 

You should start by activating Auto Route feature by making its value in 

Configuration->Linq2 Resources-> System-> LinQ2

Provider Auto Route = 1

After that messages will be routed to providers according to provider pattern configured in each provider. 

9. Direct Submit Enhancement 

• Direct submit refers to sending messages methodology. Instead of inserting messages in DB tables, waiting for processes to pick them, and finally sending them, direct submit refers to submitting messages directly to provider(s) sessions “to session queues to be more specific”. Inserting messages in db is also done though.

- Instance Manager.

- Database Message Processor

- Post Processing Handler.

  Also, you should follow the same order to start them:

- Instance Manager.

- Database Message Processor

- Post Processing Handler.