1.Introduction

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

1.2 Scope of the Document

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

2.Organization

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.

    2.1 Add Organizations

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. 

    2.2 Edit Organization

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.

    2.3 Organization List

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 organizations, then please select the check box and click Delete organization button. 

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

2.4 Add Quota

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.

    2.5 Roles

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. 

            2.5.1. List Roles

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

            2.5.2. Add Roles

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.

             2.5.3. Edit Roles

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.

            2.5.4. Delete Roles

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. 

2.6 Users

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 username hyperlink.

2.7 Templates

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.
To add new template, click on the Add button. 
To delete any/all templates then please select the check box and click Delete button.

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

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

    2.7.3 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 templates 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.

2.8 Campaign

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.

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

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

3.Configuration 

3.1 LinQ2Resources 

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: 

3.2 Services

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

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

3.3 Pull and Push Service Configuration

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

• SQL Query

• Template Value:

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

3.4 Internal and Content Service

In this page you can edit internal or content service. 

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

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

3.5 Providers

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. 

3.5.1 Create Provider

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. 

3.5.2 Edit Provider

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.

 3.5.3 Delete Provider

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. 

        Session Management

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.

Add session

To add a session users need to navigate to the CONFIGURATION->PROVIDERS link first. If there are no providers created users need to create one. Please refer the Provider Management for more details. Without a provider users cannot create a session.

Click on the required 'Add' link in the Sessions Column for the appropriate provider. 

A form will be displayed to collect all the information related to a session.

Following is a brief description of the various fields in the 'Add Session' form: 

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

Edit Session

To edit a session navigate to the 'Session List' first and click on the 'Session Type' for the appropriate session.

A form will be displayed populated with the existing values.

Users can edit the required fields and click on the 'Save' button to save the changes.

Following is a brief summary of all the form fields: 

Delete Session

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.

3.6 Enumeration

• Add Enumeration

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.

•  Edit Enumeration

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.

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.

3.7 Email settings

• Configuration

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:

• Mail server prototocol. This is the protocol for receiving mails. This could be pop3 or smtp.

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

• Receiver email user. 

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

• SMTP server that serves as mail server.

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

• Sender email address. 

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

3.8 Database configuration 

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.

• Server ip which hosts the database is mentioned in connection URL.

                          <connection-url>

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

                        </connection-url> 

• Database username. This can be the user who has full permissions over LinQ2 database

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

• Password of the above user as in database server.

                          <password>password</password>

• The rest of the parameters data should not be modified.

 3.9 Logs management 

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

4.Status Monitor

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.

 5. Failover Mechanism 

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.  

6. Auto-Route Feature

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.

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

• After messages are sent/ rejected from provider/ recycled/ or expired, messages are updated in DB, but not directly. They are also added to a different queue “post processing queue”.

• Direct submit needs to configure minimum priority to be directly submitted. “Direct Submit Priority”

• Database message processor class has to main characteristics period between two DB selects “frequency of handler” and size of results to be fetched each visit.              

• Sessions queues are having the same size; post processing handler has a size, both are configurable; Database message processor parameters are configurable as well. Below are suggested values we expect they are matching and their corresponding uses.

• In case of restarting services please make sure to shut down services in the following order:   

- Instance Manager.

- Database Message Processor

- Post Processing Handler.

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

- Instance Manager.

- Database Message Processor

- Post Processing Handler.