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

You can use the add-on framework to add third-party services to Convergence. For example:

  • advertising

  • click-to-call service

  • multinetwork instant messaging

  • SMS (both one-way and two-way)

  • social media applications (Facebook, Twitter, and Flickr)

  • video and voice calling capability with WIT

  • video and voice calling capability and screen sharing with WebRTC integration

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 13-1. The names of the add-on services, as used in the configuration files, are given in parentheses. For example, the properties file for configuring the multinetwork instant messaging add-on is imgateways.properties:

Table 13-1 Add-On Services

Service Name Description

Advertising (advertising)

Displays banner ads, text ads, and contextual ads in the Convergence UI. For more information, see "Configuring the Advertising Add-On Service in Convergence".

Click-to-Call (video)

Allows for video and audio/voice calling by clicking contact information in Instant Messaging or Address Book services in Convergence. For more information on WIT integration, see "Configuring WebRTC in Convergence with WIT Software". For more information on WebRTC integration, see "Configuring WebRTC in Convergence with WebRTC Session Controller". With WebRTC, you can also do screen sharing and multiparty video.

Video and audio calling (video)

Provides video and audio/voice calling through Convergence. For more information on WIT integration, see "Configuring WebRTC in Convergence with WIT Software". For more information on WebRTC integration, see "Configuring WebRTC in Convergence with WebRTC Session Controller". With WebRTC, you can also do screen sharing and multiparty video.

Multinetwork Instant Messaging (imgateways)

Provides access to all of a user's instant messaging accounts in a single place. You can currently chat with Facebook buddies when you set up Facebook with the social add-on service. For more information, see "Configuring Multinetwork Instant Messaging Add-On Services".

SMS (sms)

Provides one- and two-way SMS through Convergence. For more information, see "Configuring Convergence for SMS".

Social Media (social)

Provides access to social media, such as Facebook, Flickr, and Twitter, through a Social tab in the Convergence UI. Social media applications can only be added to the Social tab. For more information, see "Configuring Social Add-On Services in Convergence".

Facebook integration with Convergence is not currently working due to changes Facebook made to their APIs, interfaces, and application registration approval. Oracle is exploring potential solutions and will provide an update when a solution is available.

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.

  1. Add on configuration.

  2. A sample entry look like this:

    # addons=social, sms, advertising
addons=social, sms, advertising, video

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 sms.json file, the SMS service is enabled. The comments describe each parameter:

{
    enabled: true,
    twowaysmsenabled:true, // Whether two way SMS is enabled or not
    channel: "sms-handle", // Messaging server SMS channel name
    folder:"SMS",          // Name of the SMS folder, where messaging server keeps all
                                                   // the SMS messages
    NDNFolder:'INBOX'      // Where, Non Delivery Notification messages for SMS will be
}

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. Social add-on services and some video add-on services use an addon_name.properties file: social.properties. The following example shows the authentication configuration for Twitter in the social.properties file:

...
serviceid = twitter

# OAuth related configuration
twitter.oauth.consumer.key=consumer_key
twitter.oauth.consumer.secret=consumer_secret
twitter.oauth.authorize.url=https://api.twitter.com/oauth/authorize
twitter.oauth.request.token.verb=POST
twitter.oauth.request.token.url=https://api.twitter.com/oauth/request_token
...

Configuring WebRTC Services in Convergence

Convergence supports many Web real-time communication (WebRTC) features, including peer-to-peer voice and video chat and screen sharing.

WebRTC is a standards-based API definition that does not require the use of web browser plug-ins or downloads.

You can integrate Convergence with either Oracle Communications WebRTC Session Controller or WIT Communications Server to deliver WebRTC services.

See one of the following sections for more information:

To use the WebRTC services in Convergence, users must be using a supported browser and have a microphone and a webcam.

Configuring WebRTC in Convergence with WebRTC Session Controller

You can integrate Convergence with Oracle Communications WebRTC Session Controller to deliver WebRTC services in Convergence.

Install WebRTC Session Controller according to its documentation.

Convergence uses WebRTC Session Controller as a signaling channel to coordinate the communication between peers and to send control messages to start and end communication between peers and to report errors. WebRTC Session Controller also exchanges network configuration information and media capability with other communication channels. Signaling between peers must be successful before streaming can begin.

WebRTC Session Controller uses the JsonRTC protocol to establish a connection between the clients and to send messages between the Convergence sender and receiver.

Once Convergence and WebRTC Session Controller are integrated, you can enable peer-to-peer (P2P) communication between Convergence clients as well as Session Initiation Protocol (SIP) clients.

Figure 13-1 shows the high-level architecture of WSC and Convergence:

Figure 13-1 WSC and Convergence Architecture

Figure described in the surrounding text

WebRTC Session Controller uses a browser module, RTCPeerConnection, to communicate real time data between the Convergence sender and receiver. The data is sent through the Secure Real-time Transport Protocol (SRTP), which provides enhanced security features for real time transmission of multimedia data.

WebRTC Session Controller also integrates with SIP and the Public Switched Telephone Network (PSTN). For more information, see the WebRTC Session Controller documentation.

Convergence uses the WebRTC Session Controller JavaScript API to obtain access to a user's media (camera/microphone). For more information on the WSC JS API, see WebRTC Session Controller Web Application Developer's Guide.

About Authentication with WebRTC Session Controller and Convergence

Convergence uses Trusted Circle SSO for authentication. First, Convergence sends a request to access a protected resource in WebRTC Session Controller. If the resource request is not protected, Convergence is connected to the WebRTC Session Controller. If WebLogic Server detects that the requested resource is protected, it passes requests to an authentication provider which retrieves userID and token/sessionID from requests. Next, the authentication provider sends a request to the Convergence VerifySSO module. Convergence verifies if the user in the request has a valid session. If authentication succeeds, the request is trusted by WebLogic server the request will be passed to WSC server.

Figure 13-2 shows the trusted circle SSO authentication flow for Convergence with WSC.

Figure 13-2 Trusted Circle SSO Authentication Flow for Convergence with WebRTC Session Controller

Figure described in the surrounding text

Mapping Between Web Identity and IP Multimedia Subsystem Identity

You can customize and implement your WebLogic authentication provider to map web identity with IP Multimedia Subsystem (IMS) identity.

Because customers might have different IMS user repositories, you can use a sample module to fetch mapping identity from your LDAP server. You write your own plug-in to interact with your IP Multimedia Subsystem (IMS) identity to fetch the mapping identity. If you already have an identity assertion system in place, then, you can add a custom authentication provider to the chain so that it looks at the principal returned by the identity asserter. In addition, you can find the SIP credentials for that principal and add the same credentials to the subject. You can follow this same approach if you are using an existing authentication provider.

Once mapping identity information is fetched, you can construct javax.security.auth.Subject and pass it to WebRTC Session Controller.

Figure 13-3 shows the WebRTC Session Controller security architecture for Convergence using the identity mapper.

Figure 13-3 WebRTC Session Controller Security Architecture for Convergence Using Identity Mapper

Figure described in the surrounding text

Enabling WebRTC Services in Convergence

To enable the WebRTC services in Convergence:

  1. Add video to the add-ons.properties file.

    The add-ons.properties file is located in the /var/opt/sun/comms/iwc/config/ directory. To enable the video add-on, add it as a value of the addons parameter, as in the following example:

    addons=sms, imgateways, advertising, social, video

    See "add-ons.properties" for information on the add-ons.properties file.

  2. Edit the video.json file in the /var/opt/sun/comms/iwc/config directory for your WebRTC Session Controller configuration:

    1. Set enabled parameter to true.

    2. Set provider parameter to wsc.

    3. Update the following parameters to point to the WebRTC Session Controller server. URLs to the WebRTC Session Controller server must use the server host name, not the server IP address.

      • wsurl: The WebSocket URI to which Convergence connects. The context (for example, /ws/webrtc/convergence) should be one of application RequestURI in wsc-console.

      • logouturl: The URL used to logout WebRTC Session Controller, the parameter "wsc_app_uri" is mandatory and the value should be the WebSocket context to which Convergence connects

      • isurl: The WebRTC Session Controller JavaScript API URL

      • isextnurl: URL points to WebRTC Session Controller extension Javascript API in Convergence

    4. Update pstnDomain according to PSTN gateway domain if it is configured.

      Note:

      The PSTN gateway is required to initiate calls with PSTN numbers. The PSTN gateway domain information can be obtained from the PSTN gateway administrator.

    5. Add provider information. For example:

      {
    "enabled": true,
    "provider": "wsc",
    "wsc": {
        "enabled": true,
        "jsPackageName" : "iwc.packages.Wsc",
        "jsClassName" : "iwc.service.addon.WSC",
        "logLevel": 2,
        "serviceDetails": {
            "wsurl": "wss://mercury-vm43.example.com:7002/ws/webrtc/convergence",
            "logouturl": "https://mercury-vm43.example.com:7002/logout?wsc_app_uri=/ws/webrtc/convergence",
            "jsurl": "https://mercury-vm43.example.com:7002/api/wsc.js",
            "jsextnurl": "../js/iwc/service/addon/wsc/lib/wsc-extension.js",
            "pstnDomain": "anydomain.com",
        },
    }

  3. Configure Trusted Circle SSO for Convergence Server.

    • Set the SSO parameters using the iwcadmin command.

      iwcadmin -f /space/enable-mssso

      where /space/enable-mssso and must have the following SSO parameters:

      cat /space/enable-mssso
sso.ms.enable = true
sso.misc.IPSecurity = false
sso.misc.CookieAppPrefix = WSCAuthnToken
sso.misc.CookieDomain = .example.com  \\ Convergence and WebRTC Session Controller must be in the same domain, or authentication fails and video service is not possible.
sso.misc.SessionCookie =JSESSIONID
sso.misc.IWC-AppID =iwc
sso.misc.iwc-VerifyURL = http://convergenceHost:Port/iwc_context/VerifySSO?

      Where iwc_context is the Convergence context path.

      Note:

      If the value for sso.misc.iwc-VerifyURL is an HTTPS URL, and if SSO with WebRTC Session Controller does not work, make sure that you have imported the Convergence GlassFish's CA certificate into the WebRTC Session Controller WebLogic Server's trust store.

Configuring WebRTC Session Controller for Convergence

To make the WebRTC Session Controller work with Convergence, you need to run the WLST script configuration and do additional manual configuration:

  1. Copy the wlst directory from /opt/sun/comms/iwc/resources/uc/wsc/scripts/ to either your WebRTC Session Controller or WebLogic Server Home directory.

  2. In wlst/README.txt, for the allowedDomains parameter, provide the complete host name as a value. The domain name is not a valid value. An asterisk is a valid value, meaning for all host names.

  3. Run the WLST script to add the extension in WebRTC Session Controller. Instructions are provided in wlst/README.txt.

  4. Configure Media Engine by adding the Media Engine node through the WebRTC Session Controller Console. See the discussion about signaling properties and media nodes in WebRTC Session Controller System Administrator's Guide for more information.

  5. If the Media Engine is enabled, set DMA_ENABLED to true and set PROXY_SIP_URI (default registrar and router address) in the Script Library through the WebRTC Session Controller console.

  6. Configure the SIP Proxy Server and Registrar IP address to accept all the domains on which Convergence is running.

Configuring the SSO Provider on WebLogic Server

  1. Configure the SSO provider on the WebLogic Server by putting the SSO provider JAR file in WebRTC Session Controller, available with the Convergence installation files.

    1. Copy the WLSIWCIdentityAsserter.jar from the /opt/sun/comms/iwc/lib/jars/ directory to the WebLogic installation directory, WL_HOME\server\lib\mbeantypes.

    2. Restart WebLogic Server if it is already running

  2. Configure the identity assertion provider in the WebLogic administration console for WebRTC Session Controller.

    1. Log into the WebLogic administration console.

    2. In the left pane, select Security Realms and click the name of the realm to be configured, such as myrealm.

    3. Select Authentication from Select Providers and click New.

    4. Enter a name for the provider to be configured such as WLSIWCIdentityAsserter.

    5. From the Type menu, select WLSIWCIdentityAsserter.

    6. On the Common tab of the Configuration page for this authentication provider, make sure that Base64DecodingRequired is set to false and active types has WSCAuthnToken-iwc token type in the chosen list.

    7. On the Provider-specific tab of the Configuration page, set the value of the 'User Group' attribute to the value of Security Group of the WebRTC Session Controller application. The value of WebRTC Session Controller application's Security Group can be found in the WebRTC Session Controller console. The Application tab in the WebRTC Session Controller console shows the value of Security Group, Request URI, allowed domains, and so forth.

      Note:

      If the value of the provider's 'User Group' attribute differs from the Security Group configured in the WebRTC Session Controller application, the user authentication fails and video service is not available in Convergence. For example, if you have configured the Security Group as 'convergence' in the WebRTC Session Controller application, the SSO provider should also be configured with 'convergence' as the user's group name.

    8. Make sure that the authentication provider's list does not contain the guest login, WSCServletAuthenticator.

    9. On the Common tab of the Configuration page for the default authenticator, change the 'Control Flag' to OPTIONAL.

    10. Restart WebLogic Server.

Configuring WebRTC in Convergence with WIT Software

You can integrate Convergence with WIT Communications Server to deliver WebRTC services in Convergence.

Install WIT Communications Server according to its documentation.

The WIT Software provides the following WebRTC features:

  • Browser to Browser Audio Call - caller calls contact in his address book in the Convergence UI; the recipient must have browser to browser audio call enabled. Recipient answers call through browser.

  • Browser to Phone Audio Call - caller calls contact in his address book in the Convergence UI. Recipient answers call on phone.

  • Click-to-Call - caller clicks recipient's phone number stored in his address book the Convergence UI.

  • Skype Call - caller selects option to call recipient by Skype.

  • Video Call - caller does a live video call with recipient through address book or IM in the Convergence UI. Both caller and recipient must have video call enabled.

Convergence integrates with WIT Software's WIT Communications Server to provide back-end support for video and audio call. The WIT Communications Server works with Wowza Media Server to provide streaming. Figure 13-4 shows the WIT integration architecture with Convergence.

Figure 13-4 WIT Integration Architecture

WIT integration architecture

You can integrate WebRTC capabilities to enable voice and video calls and screen sharing through Address Book or IM. For more information, see "Configuring WebRTC in Convergence with WebRTC Session Controller".

Adding WebRTC Services to Convergence with WIT Software

  1. Add video to the add-ons.properties file.

    The add-ons.properties file is located in the /var/opt/sun/comms/iwc/config/ directory. To enable the video add-on, add it as a value of the addons parameter, as in the following example:

    addons=sms, imgateways, advertising, social, video

    See "add-ons.properties" for information on the add-ons.properties file.

  2. Use the video.json file in the /var/opt/sun/comms/iwc/config directory for your WIT configuration.

    • Set the initial line with "enabled" to "true".

    • Change the "provider" value from "wsc" to "wit".

    • Include serverHost, serverPort, proxyHost, proxyPort, and userDomain details from your WIT configuration. For example:

      video.json
{
        enabled: true,
        serviceDetails:{
        locale: 'EN',
                serverHost: '10.178.212.172',
                serverPort: '1935',
                proxyHost: '10.178.212.172',
                proxyPort: '2222',
                backupPort: '1935',
                singleSignOnVerificationUrl: 'http://convergenceHost:Port/iwc/VerifySSO?',
                isSingleSignOn: true,
                ssoCookieName: 'kendo-sso-iwc',
                policyFilePort: '843',
                userDomain: 'wcas.wit-software.com'
        }
}

      Note:

      The video.json file is used for all audio and video add-on services that use the WIT server: video call, audio call, and click-to-call. Do not use the clicktocall.json to enable click-to-call services.

  3. Configure Trusted Circle SSO.

    • Set the SSO parameters using the iwcadmin command.

      iwcadmin -f /space/enable-mssso

      where /space/enable-mssso and must have the following SSO parameters:

      cat /space/enable-mssso
sso.ms.enable = true
sso.misc.CookieAppPrefix = kendo-sso
sso.misc.CookieDomain = .com
sso.misc.IPSecurity = false
sso.misc.iwc-VerifyURL = http://convergenceHost:Port/iwc_context/VerifySSO?

      Where iwc_context is the Convergence context path.

Implementing the Identity Mapper

Identity mappers are used for authenticating WebRTC with video services in Convergence. By default, Convergence implements a default Convergence identity mapper which does mapping using the user/group LDAP store. An identity mapper is a sample authentication provider which can be used to perform Web ID to SIP (IMS) ID mapping for non-LDAP directory configurations.

Convergence uses a plug-in architecture so that you can implement your own custom identity mapper to your unique IMS user repository. The Convergence UI requests mapping values only if mapping is enabled on the Convergence server.

A new protocol command and Java interface in the Convergence server can be used to plug in your own implementation. The Convergence client uses this protocol to get mapping IDs. The new protocol's command handler has its own configuration; it is used as part of the video service configuration. The configuration has the capability to plug in a custom implementation that should adhere to the new Java interface.

See "Creating a Custom Identity Mapper" for information about creating a custom identity mapper.

Enabling Sound Alerts in Firefox

A sound alert audibly notifies a user when there is an incoming or outgoing WebRTC voice or video call. This section describes how to get sound alerts to work in Firefox.

Because of an issue with the mp3 MIME type that is returned by GlassFish Server, sound alerts do not work by default with Firefox browsers.

Use the following workaround to turn on sound alerts in Firefox:

  1. Modify the default-web.xml file in Convergence_Domain/config.

  2. Search for the MP3 extension and replace the x-mpeg mime_type with mpeg so it looks like the following example:

    <mime-mapping>
<extension>mp3</extension>
<mime-type>audio/mpeg</mime-type>
</mime-mapping>

  3. Restart the GlassFish server.

Creating a Custom Identity Mapper

You can create you own identity mapper for Convergence to deliver WebRTC services.

By default, Convergence uses User/Group LDAP directory server (that contains user information such as display name, time zone, telephone number, and so on) for identity mapping for WebRTC video services. The connection is performed by a Convergence identity mapper that is enabled by default.

You can use a custom identity mapper to look up routeable IDs in RDBMS, flat file, or HSS databases. Custom identity mappers are not intended to be used with Oracle Communications User/Group LDAP directory servers. The Convergence server provides an interface that enables you to create a custom identity mapper for WebRTC video services. This custom identity mapper is not available for WIT services.

Before designing a solution, you need to plan the following:

  • The Convergence identity mapper framework is the default framework that is designed to work with Oracle Communications User/Group LDAP Directory Server.

  • A custom identity mapper must be implemented for use with a non-LDAP user/groups directory.

  • The custom identity mapper uses the com.sun.comms.client.addon.video.IdentityMapper Java interface that needs to be followed by custom identity mapper Java class This interface defines set of methods. For example, public String getMappedValue(String sourceValue) throws Exception;.

  • The custom identity mapper library JAR file should be in the class path that is accessible by Convergence.

  • While implementing the custom identity mapper, iwc.jar should be available in the classpath of development environment. The iwc.jar defines the interface that needs to be implemented by custom identity mapper.

Developing Sample Custom Identity Mapper Data Files

This section describes the files that are created for the custom identity mapper to work. Use this information as a reference to create other custom identity mappers to suit your needs. This sample identity mapper uses file based look-ups to perform the identity mapping.

The following file (idmappinginfo.txt) is a sample set of data that could be used to retrieve mapped values:

hari@idmappersample.com=123@idmappersamplesip.com
abhi@idmappersample.com=456@idmappersamplesip.com
alice@idmappersample.com=789@idmappersamplesip.com

In idmappinginfo.txt, attributes are separated by an equal (=) characters. For example, the first record in the file provides information about the user hari@idmappersample.com whose routeable ID is 123@idmappersamplesip.com.

The custom class should implement the interface com.sun.comms.client.addon.video.IdentityMapper. This interface has the following two methods that should be implemented by the implemented class:

  • public void init(Properties ConfigProps): Store configuration properties so that these configuration properties can be used by other methods.

  • public String getMappedValue(String sourceValue) throws Exception: Returns the mapped value for the specified source value, or null if neither one is found.

FileBasedCustomIdentityMapper.java below describes the classes that are used to implement the custom identity mapper using a file-based mapping store. The following is the core class:

package com.sun.comms.client.services.sample.identitymapper;
 
import com.sun.comms.client.addon.video.IdentityMapper;
import java.io.BufferedReader;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.Properties;
 
public class FileBasedCustomIdentityMapper implements IdentityMapper {
 
    private static String mappingInfoFile;
    private Properties configProps;
 
    @Override
    public void init(Properties configProps) {
        this.configProps = configProps;
 
        mappingInfoFile = (String) this.configProps.get("idmappinginfofile");
    }
 
    @Override
    public String getMappedValue(String sourceValue) throws Exception {
        String mappedValue;
 
        mappedValue = getFromFile(sourceValue);
 
        return mappedValue;
    }
 
    private String getFromFile(String source) {
 
        if (source == null) {
            return null;
        }
 
        FileInputStream fis = null;
        BufferedReader reader = null;
 
        try {
            fis = new FileInputStream(mappingInfoFile);
            reader = new BufferedReader(new InputStreamReader(fis));
 
            String line = reader.readLine();
            while (line != null) {
                String[] keyValue = line.split("=");
                if (source.equals(keyValue[0])) {
                    return keyValue[1];
                }
                line = reader.readLine();
            }
 
        } catch (FileNotFoundException ex) {
            System.out.println("Mapping information file '" + mappingInfoFile + "' not found.");
        } catch (IOException ex) {
            System.out.println("Unable to read from '" + mappingInfoFile + "' due to:" + ex.getMessage());
 
        } finally {
            try {
                if (reader != null) {
                    reader.close();
                }
                if (fis != null) {
                    fis.close();
                }
            } catch (IOException ex) {
                System.out.println("Exception during file operation. Error:" + ex.getMessage());
            }
        }
 
        return null;
 
    }
 
    // Test the custom implementation
    public static void main(String[] args) throws Exception {
        FileBasedCustomIdentityMapper idMapper = new FileBasedCustomIdentityMapper();
 
        Properties properties = new Properties();
        properties.put("idmappinginfofile", "/export/IdentityMapper/idmappinginfo.txt");
        idMapper.init(properties);
 
        String sourceValue = "hari@idmappersample.com";
        String mappedValue = idMapper.getMappedValue(sourceValue);
 
        System.out.println("Source value: [" + sourceValue + "]");
        System.out.println("Mapped value: [" + mappedValue + "]");
    }
 
}

Compiling the Sample Custom Identity Mapper

The custom identity mapper must be on a system that can be accessed by the GlassFish server. Place the JAR archive in a location outside of the Convergence installation or deployed directories.

To compile the sample custom identity mapper:

Note:

The paths used in this section may differ for your installation.

  1. Create a sample directory for the source code, such as sample_dir/src.

  2. In sample_dir/src, create an Java file named FileBasedCustomIdentityMapper.java.

  3. Copy the core class from FileBasedCustomIdentityMapper.java into FileBasedCustomIdentityMapper.java. See "Developing Sample Custom Identity Mapper Data Files" for more information about the core class.

  4. Compile the Java class files.

    cd sample_dir/src
javac -classpath /opt/sun/comms/iwc/web-src/server/WEB-INF/lib/iwc.jar -d build src/FileBasedCustomIdentityMapper.java

  5. Create a JAR.

    cd /sample_dir/src
cd build
jar -cvf ../FileBasedCustomIdentityMapper.jar *
cd ..

    Note:

    If your custom authentication module requires any additional JAR files or classes, they must be bundled along with the JAR file.

  6. Add the JAR file to the deployed Convergence libraries with the GlassFish Server asadmin command.

    asadmin set applications.application.iwc.libraries=path/file.jar

    Note:

    Depending on your version of GlassFish Server, the asadmin command may fail. If this happens, you can copy the JAR file into the Convergence library folder: Convergence_domain/applications/Convergence/WEB-INF/lib.

Configuring the Sample Custom Identity Mapper

To configure the custom identity mapper with Convergence:

  1. In video.json, verify that the service provider is configured and enabled.

  2. Edit video.properties and add the service provider name from video.json for the serviceid parameter. For example:

    serviceid = wsc

  3. Add the following parameters to video.properties:

    wsc.identitymapper.enabled = true
wsc.identitymapper.idmappinginfofile = /export/sample/identitymapper/idmappinginfo.txt
wsc.identitymapper.handler = com.sun.comms.client.services.sample.identitymapper.FileBasedCustomIdentityMapper

  4. Restart the GlassFish server.

Verifying the Custom Identity Mapper

You can verify the custom identity mapper by checking that the identity mapper look-up is performed on the local file as expected and is the returning correct values:

  1. Create a few entries in idmappinginfo.txt with a Convergence user's email ID as key and the value as a sample SIP ID.

  2. Use any SIP client which is connected to same SIP Proxy Server and Registrar IP that is used by Convergence.

  3. From SIP client, call the user by using mapped ID, for example 123@idmappersamplesip.com. The call should establish successfully with the user hari@idmappersample.com.

Configuring Multinetwork Instant Messaging Add-On Services

This section describes how to configure multinetwork instant messaging (IM) add-on services in Convergence.

About Multinetwork IM Add-on Services in Convergence

You can configure multinetwork IM capability within Convergence. Currently, Convergence can be configured with Facebook Chat. In addition, you can connect with federated XMPP IM networks, which maintain an open directory that allows other IM networks to communicate with one another. See http://xmpp.net/directory.php for a list of public domains that allow XMPP S2S federation.

To configure multinetwork instant messaging in Convergence you must have Oracle Communications Instant Messaging Server release 9.0.1.4 or later.

Enabling Facebook Chat in Convergence

Enabling Facebook Chat in the Convergence UI allows you to chat with your Facebook friends. A Facebook user logs into his account in Convergence. Buddies are added to the Convergence Buddy List automatically. Facebook credentials are not saved in Convergence.

To enable Facebook Chat in the Convergence UI, you need to do the following:

  1. Ensure that the Facebook gateway is configured in the Instant Messaging server. See your Instant Messenger documentation for more information.

  2. Enable the Facebook Social add-on service. For more information, see "Configuring Social Add-On Services in Convergence".

  3. Enable the multinetwork IM add-on service. Enable the imgateways add-on service for Facebook in the imgateways.json file; the imgateways.json file is in the /var/opt/sun/comms/iwc/config directory. To enable the imgateways add-on, set the enabled parameter at the top of the file to true. The following example shows a Facebook configuration:

    {
    enabled: true,
    gateways: [
        {
                {
                        type: "facebook",
                        category: 'gateway',
                        enabled: true //Should be enabled only when Facebook gateway in IM server is enabled
                }
    ]
}

  4. Add imgateways to addons.properties located in the /var/opt/sun/comms/iwc/config/ directory as in the following example:

    addons=sms, imgateways, advertising, social

  5. Restart GlassFish Server for your configuration changes to take effect.

Enabling Federated XMPP IM Networks in the Convergence UI

Enabling federated XMPP IM networks in the Convergence UI allows you to chat with your buddies on other XMPP IM networks. To enable federated XMPP IM networks in the Convergence UI, you need to do the following:

  1. Ensure that XMPP Server Federation is configured in the Instant Messaging server. See your Instant Messenger documentation for more information.

  2. Enable the multinetwork IM add-on service. Enable the imgateways add-on service for federated XMPP IM networks in the imgateways.json file; the imgateways.json file is in the /var/opt/sun/comms/iwc/config directory. To enable the imgateways add-on, set the enabled parameter at the top of the file to true. The following example shows a federated XMPP IM networks configuration:

    {
  enabled: true,
  gateways: [
    {
      type: "groupone",
      category: 'federated',
      name: "Group One",
      domain: "groupone.com",
      serverurl: "example.groupone.com:5222",
      enabled: true
    },
  ]
}

    Change the type, name, domain, and server_url to the XMPP IM network service details.

  3. Add imgateways to addons.properties located in the /var/opt/sun/comms/iwc/config/ directory as in the following example:

    addons=sms, imgateways, advertising, social

  4. Restart the GlassFish server.

  5. To display the IM icons of the XMPP federated service in the Convergence Instant Messaging window, you need to customize the Convergence UI. See Convergence Customization Guide for more information.

Configuring Convergence for SMS

You can configure Convergence to support either one-way or two-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.

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

Restarting GlassFish Server

Use the asadmin command-line utility to restart the GlassFish server on which Convergence is deployed, so that your configuration changes can take effect. By default, Convergence_Domain is domain1.

asadmin stop-domain Convergence_Domain
asadmin start-domain Convergence_Domain

Configuring Two-Way SMS for Convergence

This section describes how to configure two-way SMS, where users can use the Convergence UI to send and receive SMS messages that are 160 characters or less.

Configuring Messaging Server for Two-Way SMS

To communicate with SMSCs, Messaging Server uses an MTA SMS channel which serves as an SMPP client. For two-way SMS, you also need to configure the SMS gateway server. The SMS gateway server is installed with Messaging Server.

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

Configuring Instant Messaging Server for Two-Way SMS

You configure Instant Messaging Server for two-way SMS so that you receive pop-up notifications of SMS messages.

To configure the Instant Messaging Server for SMS:

  1. Configure the Event Notification Service (ENS) that sends SMS notifications to the Instant Messaging server, which then forwards notifications on to the appropriate end user. Use the imconfigutil command-line utility to configure ENS:

    imconfutil add-component --config /opt/sun/comms/im/config/iim.conf.xml id=ens jid=kendo-ensjid password="xxx"

  2. Using the imadmin command-line utility, stop and then restart the Instant Messaging server:

    imadmin stop
imadmin start

Configuring GlassFish Server for Two-Way SMS

Convergence is deployed on GlassFish Server; before Convergence can be used for two-way SMS, GlassFish must be configured for two-way SMS.

To configure GlassFish Server for two-way SMS:

  1. Create a Java Message Service (JMS) connection factory, and set connection-factory properties (see Oracle GlassFish Server administrator documentation for more information). The following example uses the asadmin command to create the connection factory (jms/ConnectionFactoryMS) and set properties. You can use the GlassFish Administration Console for the same purpose. The settings for Username and Password must be the same as the JMQ notification settings for jmqnotify.jmqUser and jmqnotify.jmqpwd).

    asadmin -p 5858 -u admin --passwordfile /var/tmp/aspass create-jms-resource --restype javax.jms.ConnectionFactory --description "a JMS connection factory" --property "AddressList=yyy.india.example.com\:7777:Username=user1:Password=xxx" jms/ConnectionFactoryMS"

  2. Specify a destination for connections by creating a JMS destination resource and setting properties for it, as in the example that follows.

    asadmin -p 5858 -u admin --passwordfile /var/tmp/aspass create-jms-resource --restype javax.jms.Queue --property "Name=ucsms1:Description=ucs ms desc" ucsms1"

    In this example, javax.jms.Queue was set, because the earlier example of setting JMQ notification parameters the JMQ notification destination type was queue. If the destination type had been topic, then javax.jms.Topic would have been set.

Configuring ENS Support for Convergence

To configure ENS support for Convergence:

  1. Edit /var/opt/sun/comms/iwc/config/httpbind.conf and set the following ENS parameters:

    • ens.server_url: the ENS Server URL

    • ens.component_jid=kendo-ensjid: the ENS JID

    • ens.component_password: the encrypted ENS password

    The following are examples of the settings:

    ens.server_url=IM_HOST:5269
ens.component_jid=kendo-ensjid
ens.component_password=rE9ZIq6H0r49RgsQrKHXsw==

  2. Set ENS and notification-related parameters by using the iwcadmin command:

    iwcadmin -o notify.service.enable -v true
iwcadmin -o notify.mq.[serv1].enable -v true
iwcadmin -o notify.mq.[serv1].connection -v jms/ConnectionFactoryMS
iwcadmin -o notify.mq.[serv1].destinationname v ucsms1
iwcadmin -o notify.mq.[serv1].destinationtype -v QUEUE
iwcadmin -o notify.mq.[serv1].resourcetype -v consumer
iwcadmin -o notify.mq.[serv1].filter -v "JMSType='NewMsg' AND msgflags LIKE 'sms%'"
iwcadmin -o ens.service.enable -v true
iwcadmin -o ens.[mail].enable -v true
iwcadmin -o ens.[mail].datasource -v ucsms1

    Alternatively, you can create a file that contains the notification-related parameters and run the following command:

    iwcadmin -f ens_iwc_settings_file

    Contents of the ens_iwc_settings_file can be in the following format:

    notify.service.enable = true
notify.mq.[serv1].enable = true
notify.mq.[serv1].connection = jms/ConnectionFactoryMS
notify.mq.[serv1].destinationname = ucsms1
notify.mq.[serv1].destinationtype = QUEUE
notify.mq.[serv1].resourcetype = consumer
notify.mq.[serv1].filter="JMSType='NewMsg' AND msgflags LIKE 'sms%'"
ens.service.enable = true
ens.[mail].enable = true
ens.[mail].datasource = ucsms1

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.

Edit sms.json in /var/opt/sun/comms/iwc/config/ to enable the SMS add-on and set required parameters, as in the following example, where channel must be set to the SMS channel name assigned in Messaging Server configuration and folder must be set to SMS. See the comments in the file for information on each parameter. The contents of the file at installation are:

{
    enabled: true,
    twowaysmsenabled:true,
    channel: "sms-handle",
    folder:"SMS",
    NDNFolder:'INBOX',
    numberhintenabled: true
}

Note:

The folder parameter can be changed, however, it has to match the folder value specified in the Messaging Server configuration, specifically the fileinto folder specified in the sms.filter.

Restarting GlassFish

Restart the GlassFish server on which Convergence is deployed, so that your configuration changes can take effect. You will need to specify the GlassFish domain in which Convergence is deployed. In the following example, the domain is domain1:

/root/glassfish3/bin/asadmin stop-domain domain1
/root/glassfish3/bin/asadmin start-domain domain1

Configuring Social Add-On Services in Convergence

This section describes how to configure the social add-on service.

Facebook integration with Convergence is not currently working due to changes Facebook made to their APIs, interfaces, and application registration approval. Oracle is exploring potential solutions and will provide an update when a solution is available.

Note:

Third-party parameters described in this configuration documentation might change as new versions of Facebook, Twitter, and Flickr are released. Always refer to the third-party developer documentation for the most up-to-date information on third-party parameters.

About Social Add-on Services in Convergence

The social add-on service provides access to Facebook, Twitter, and access to Flickr's public photos through the Social tab in Convergence. To integrate the social add-on services in the Social tab, you enable and configure each service separately.

Twitter authentication and access is performed through the Twitter REST API. See the Twitter developer web site for more information about their API:

https://dev.twitter.com/docs/api

Because of cross-domain access restriction in web browsers, the REST calls are tunneled through Convergence Server.

Figure 13-5 shows the Twitter integration architecture.

Figure 13-5 Twitter Integration Architecture

Twitter Integration Architecture

For Facebook and Twitter, when a user performs a login, it is considered the session for access.

Enabling Add-On Services Through the Convergence Social Tab

To enable the social add-on service and make the individual services available through the Social tab, follow these steps:

  1. Make sure that the social add-on is enabled in the add-ons.properties file; by default, the social 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 social add-on, if it is not currently enabled, add it as a value of the addons parameter, as in the following example:

    addons=sms, imgateways, advertising, social

  2. Enable the social add-on service in the social.json file; by default, the add-on is not enabled. The social.json file is in the /var/opt/sun/comms/iwc/config directory. To enable the social add-on, set the enabled parameter at the top of the file to true, as in the following example:

    {
    enabled:true,
    service:[
        {
                     ...

  3. To access Twitter in Convergence through the Social tab:

    1. Create a Twitter app and specify a minimum of "read and write" access, so that the Convergence user is able to send a tweet through the Convergence UI. In addition, the OAuth access token should be created by clicking the "Create my access token" button in the app to allow logging into Twitter from Convergence. For information on creating the Twitter app ID and on obtaining the OAuth-related configuration parameters for your configuration, see the Twitter developer documentation.

    2. Set parameters for Twitter in social.json. The parameters that need to be set for Twitter, as listed in the installed social.json file, are:

      id:'twitter',
enabled:true,
param: {
    tokens:{
        storetoken:'$storeToken-twitter',
        defaultStoreToken:true

    3. The parameters that need to be set for Twitter, as listed in the installed social.properties file, are:

      serviceid = twitter

# OAuth related configuration
twitter.oauth.consumer.key=consumer_key
twitter.oauth.consumer.secret=consumer_secret
twitter.oauth.authorize.url=https://api.twitter.com/oauth/authorize
twitter.oauth.request.token.verb=POST
twitter.oauth.request.token.url=https://api.twitter.com/oauth/request_token
twitter.oauth.access.token.verb=POST
twitter.oauth.access.token.url=https://api.twitter.com/oauth/access_token
twitter.oauth.callback.url=http://host_name:port/iwc/oauth/consumer/callback/twitter
twitter.oauth.version=1.0a

# HTTP proxy related configuration
twitter.http.enablessl=true
twitter.http.host=api.twitter.com
twitter.http.port=443
twitter.http.socket-timeout=180
twitter.http.connection-manager-timeout=240
twitter.http.max-connections=100

      The only OAuth-related configuration parameters you need to enter or change are:

      • twitter.oauth.consumer.key Enter the consumer key.

      • twitter.oauth.consumer.secret Enter the consumer secret.

      • twitter.oauth.callback.url Enter a callback URL for your implementation.

    4. Set HTTP-proxy related parameters as appropriate for your site:

      /opt/glassfish3/bin/asadmin create-jvm-options "-Dhttp.proxyHost=proxy_host" -p admin_port
/opt/glassfish3/bin/asadmin create-jvm-options "-Dhttp.proxyPort=proxy_port" -p admin_port

  4. To access Facebook through the Social tab, set the parameters for Facebook in social.json.

    1. Create and add a Facebook app for your environment. Point the Facebook app's Canvas or website URL to the Convergence URL.

      From the apps menu, select Status & Review and answer "yes" to "Do you want to make this app and all its live features available to the general public?" Enabling this setting allows Facebook to work within the Convergence UI. Refer to Facebook developer documentation for more information.

    2. The parameters that you need to set for Facebook, as listed in the installed social.json file, are:

      id:'facebook',
enabled:true,
param: {
    key:'',
    tokens:{
        accesstoken:'$accessToken-facebook',
        storetoken:'$storeToken-facebook',
        defaultStoreToken:true

      For key, enter the AppID.

  5. To access Flickr through the Social tab, set the parameters for Flickr in social.json:

    1. To access Flickr through the Social tab, obtain your Flickr API key. For more information, see the flickr web site:

      http://www.flickr.com/services/api/misc.api_keys.html.

    2. The parameters that you need to set for Flickr, as listed in the installed social.json file, are:

      {
     id:'flickr',
     enabled:true,
     key:''
}

      Make sure Flickr is enabled (enabled:true) and that you insert your Flickr API key in the key field.

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 add 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 13-2 lists the advertising add-on and configuration files.

Table 13-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:

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

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

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

  4. 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 13-6 Upper Portion of the Skyscraper Panel in Convergence

This figure shows the skyscaper panel

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 13-7 Message Ad Box in Convergence

Figure shows the ad box inside an email

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.