Overview of Add-on Services in Convergence

14 Overview of Add-on Services in Convergence

This chapter describes the add-on framework, the add-on configuration files, and instructions for adding or removing these third-party services in the Convergence UI.

About the Add-on Framework

The add-on framework provides access from Convergence to the third-party service through the use of an ID. The ID is provided by the service. The method of getting the ID differs from service to service. See the individual services sections for information on how to obtain the ID.

The add-on services are configured through Convergence configuration files. The available add-on services are listed in Table 14-1.

Table 14-1 Add-On Services

Service Name	Description
Advertising (advertising)	Displays banner ads, text ads, and contextual ads in the Convergence UI. See "Configuring the Advertising Add-On Service in Convergence" for more information.
SMS (sms)	Provides one-way SMS through Convergence. See Configuring Convergence for SMS for more information.

About the Add-On Configuration Files

The configuration files for supported add-ons are installed in the /var/opt/sun/comms/iwc/config/ directory. There are three types of configuration files:

add-ons.properties
addon_name.json
addon_name.properties

add-ons.properties

The add-ons.properties file specifies the add-ons that are to be enabled. The following file lists the add-on services that are available in the add-ons.properties file that comes with the installation.

Add on configuration.

A sample entry look like this:

# addons= advertising
addons= advertising

Verify that the service you want to add to your Convergence deployment is in the add-ons.properties file before going onto configuring that service.

addon_name.json

Each add-on has its own addon_name.json file, containing client configuration parameters for the add-on. You must enable the add-on service in addon_name.json in order for the service to be active in your Convergence deployment.

In the following advertising.json file, the advertising service is enabled. The comments describe each parameter:

{
        enabled: true,
        plugin: "c11n.allDomain.js.widget.advertising.Plugin",
        regions: {
                skyscraper: {
                        enabled: true,
                        width: 160,
                        closeEnable: true,
                        events: {
                                enabled: true,
                                adtime : 30,
                                allEvents: {
                                        mail: true,
                                        calendar: false,
                                        all: false
                                }
                        }

                },
                messageViewer:{
                        enabled: true,
                        locations: {
                                TopAd: {
                                        enabled: true,
                                        height: 60
                                },
                                RightAd: {
                                        enabled: true,
                                        width: 250,
                                        height: 250
                                },
                                LeftAd: {
                                        enabled: false,
                                        width: 250,
                                        height: 250
                                },
                                BottomAd: {
                                        enabled: true,
                                        height: 60
                                }
                        }
                }
        }
}

To disable an add-on service, set enabled:false in the addon_name.json file.

addon_name.properties

The addon_name.properties file contains server access parameters for add-on services.

Configuring Convergence for SMS

You can configure Convergence to support one-way SMS.

Configuring One-Way SMS for Convergence

This section describes how to configure one-way SMS so that users can send SMS messages that are 160 characters or less through the Convergence UI. In one-way SMS, senders are unable to receive SMS messages.

Configuring Messaging Server for One-Way SMS

To communicate with Short Message Service Centers (SMSCs), Messaging Server implements an MTA SMS channel which serves as an short message peer-to-peer (SMPP) client.

The following instructions describe how to configure Messaging Server for SMS, using either Messaging Server legacy or unified configuration. The two approaches are treated separately.

Configuring the SMS Add-on Service in the Convergence UI

To configure the SMS Add-On Service in so it displays in Convergence, enable SMS in the Convergence add-on services framework.

Enable the SMS add-on service and set parameters for it in the sms.json file. The sms.json file is in the in the /var/opt/sun/comms/iwc/config/ directory. See the comments in the file for information on each parameter. The contents of the file at installation are:
```
{
    enabled: true,
    twowaysmsenabled:false, 
    channel: "sms-handle",
    folder:"SMS",         
    NDNFolder:'INBOX',     
    numberhintenabled: true
}
```
- Set twowaysmsenabled to false, so it enables one-way SMS.
- The channel parameter requires the name of the MTA channel defined for SMS as part of configuring Messaging Server for SMS.
- Do not change the default settings of the folder and NDNFolder parameters.
Restart Weblogic Managed Server.

Configuring the Advertising Add-On Service in Convergence

This section describes how to configure the advertising add-on service in Convergence.

About the Advertising Add-On Service

The advertising add-on service makes it possible to display banner ads, text ads, and contextual ads in the Convergence UI. A system administrator can determine the events that trigger new ads and the location within the Convergence UI at which ads are displayed.

Ads can be displayed in:

A skyscraper panel that appears on the right side of the Convergence UI. See "Displaying Ads in a Skyscraper Panel" for more information.
An ad box, a box containing an ad that is located within the email-message viewing area and can be positioned above or below email messages or to the right or left of email messages. See "Displaying Ads in an Ad Box" for more information.

Table 14-2 lists the advertising add-on and configuration files.

Table 14-2 Advertising Configuration and Add-on Files

File Name	Directory	Description
add-ons.properties	/var/opt/sun/comms/iwc/config/	Add-ons are added to this file to enable specific services.
advertising.json	/var/opt/sun/comms/iwc/config/	Provides file path to plug-in file and allows enabling of Skyscraper and Message Box ad placement, height of ads, and other characteristics in the display area
Plugin.js	c11n_Home/allDomain/js/widget/advertising	Sample configuration on how to create and configure ads. File can be renamed. Provides call back methods for each type of ad (Skyscraper and Ad Box). You can fill in each callback with code to retrieve ad images, assign them to the innerHTML of the supplied object and return.
Skyscraper.js and Skyscraper.html	c11n_Home/allDomain/js/widget/advertising/ and c11n_Home/allDomain/js/widget/advertising/templates/	Sample configuration that's specific to Skyscraper ads. Provides examples on how to receive events from Convergence, what actions can be taken, controlling splitters, and mechanisms for displaying ads. These configuration files are specific to Skyscraper files and cannot be used in combination with Ad box ads.
Sample Ad Images	iwc_static/layout/images/ads	Sample ad images

Configuring Advertising for Convergence

See the plugin.js, Skyscraper.js, and Skyscraper.html samples to create and configure advertising for the Convergence UI.

Enabling the Advertising Add-On Service

To enable the advertising add-on:

Make sure that the advertising add-on is enabled in the add-ons.properties file; by default, the advertising add-on is enabled. See "add-ons.properties" for more information. The add-ons.properties file is located in the /var/opt/sun/comms/iwc/config/ directory. To enable the advertising add-on, if it is not currently enabled, add it as a value of the addons parameter, as in the following example:
```
addons=advertising
```
Enable the advertising add-on service in the advertising.json file; by default, the add-on is not enabled. The advertising.json file is in the /var/opt/sun/comms/iwc/config directory. To enable the advertising add-on, set the enabled parameter at the top of the file to true.
Verify that the c11n_Home directory exists. If it does not, create it by copying the c11n_sample directory. See Convergence Customization Guide for more information.
Enable the Convergence Server for customization. Use the iwcadmin command to set the client.enablecustomization parameter to true. For example:
```
iwcadmin -o client.enablecustomization -v true
```

Displaying Ads in a Skyscraper Panel

Skyscraper panels are displayed on the right side of the Convergence UI, as in the following example:

Figure 14-1 Upper Portion of the Skyscraper Panel in Convergence

Description of "Figure 14-1 Upper Portion of the Skyscraper Panel in Convergence"

To configure an ad to display in a skyscraper panel, you edit the plugin.js file. To configure the characteristics of skyscraper panels, you set parameters in the advertising.json file.

Parameters for Configuring Skyscraper Panels in the advertising.json File

The advertising.json file contains the following parameters for configuring skyscraper panels:

enabled: If set to true (the default), a skyscraper panel is added to the right side of the Convergence UI.
width: The width, in pixels, of the skyscraper panel. By default, width is set to 160 pixels.
closeEnable: If set to true (the default), the user can close the skyscraper panel by clicking a bar tab containing an arrow that appears. Once a user closes the panel, the panel is not displayed again until the user refreshes the Web page, opens Convergence in a new window, tab, or browser, or logs in again.
events: Event parameters:
- enabled: If set to true, ads can be displayed for specific events: adtime, mail, or calendar actions.
- adtime: The duration of an ad, in seconds. The default is 30 seconds.
- mail: An email action, such as opening a new mail tab or clicking through the email message grid can cause a refresh that replaces the current ad with a new ad. you cannot configure which mail actions trigger an ad refresh. You can only determine the frequency of ads, what ad to display, or which events to receive from Convergence (mail or calendar or both).
- calendar: User actions involving the calendar can trigger an ad refresh. The calendar actions that can trigger a refresh are configured in the skyscraper.js file. Calendar events are similar to mail events in that you cannot configure which calendar actions trigger an ad refresh. You can only determine the frequency of ads, what ad to display, or which events to receive from Convergence (mail or calendar or both).
- all: If set to true, any event within Convergence can be configured in advertising.json to trigger an ad refresh. By default, the all parameter is set to false.

Displaying Ads in an Ad Box

Boxes containing ads can be displayed above or below an email message, or to the left or right of an email message.

Figure 14-2 Message Ad Box in Convergence

Description of "Figure 14-2 Message Ad Box in Convergence"

To configure an ad to display in an ad box, you edit the plugin.js file. To configure the characteristics of ad boxes, you set parameters in the advertising.json file.

The advertising.json file contains the following parameters for configuring ad boxes:

enabled: If set to true (the default), enables ads in ad boxes.
TopAd: A banner ad displayed above an email message. Parameters:
- enabled: If set to true (the default), TopAd banner ads are enabled.
- height: The height of the banner ad, in pixels. The default is 60.
RightAd: An ad box displayed to the right of an email message. Parameters:
- enabled: If set to true (the default), enables ad boxes to the right of the message area.
- width: The width of the RightAd ad box, in pixels. The default is 250.
- height: The height of the RightAd ad box, in pixels. The default is 250.
LeftAd: An ad box displayed to the left of the message area. Parameters:
- enabled: If set to true, enables ad boxes to the right of the message area. The default is false.
- width: The width of the LeftAd ad box,in pixels. The default is 250.
- height: The height of the LeftAd ad box,in pixels. The default is 250.
BottomAd: A banner ad displayed below an email message. Parameters:
- enabled: If set to true (the default), BottomAd banner ads are enabled.
- height: The height of the banner ad, in pixels. The default is 60.