Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter
11g Release 1 (11.1.1.5.0)

Part Number E10148-16
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

34 Integrating the Instant Messaging and Presence Service

This chapter explains how to integrate the Instant Messaging and Presence (IMP) service in a WebCenter Portal application at design time.

For more information about managing and including instant messaging and presence, see:

This chapter includes the following sections:

34.1 Introduction to the IMP Service

The IMP service enables you to observe the presence status (online, offline, busy, or away) of other authenticated application users. It provides instant access to interaction options, such as instant messages and mails. Additionally, if your enterprise presence is unavailable (for example, when you are traveling), you can connect to a 3rd-party network presence service, such as Yahoo! Messenger.

WebCenter services that have user names with the same identity can integrate with the IMP service; for example, Discussions, Documents, or Mail.

This section provides an overview of IMP features and requirements. It includes the following subsections:

34.1.1 Understanding the IMP Service

Figure 34-1 shows the Presence icon indicating a user who is online.

Figure 34-1 Presence Icon (Online)

Presence icon

Wherever a user is indicated, for example as the author of a document in the document library, you can click the icon to invoke a context menu (Figure 34-2).

Figure 34-2 Presence Icon Context Menu

Description of Figure 34-2 follows
Description of "Figure 34-2 Presence Icon Context Menu"

The context menu can include the following actions:

  • Send Mail (This opens a compose window for the mail client set, either WebCenter Mail service or a local mail client.)

  • View Profile (This opens the selected user's profile page, with information such as mail ID and contact numbers.)

  • Send Instant Message (This opens the instant message client running on the computer, Microsoft Communicator.)

  • Change Credentials (This works as an alternative to using an external application, visible only to the current user.)

  • Start Phone Conference (For presence servers that support the phone facility, this initiates a call between you and the selected user.)

Next to a contact name is an icon that indicates the presence state of each contact.

For detailed information about the IMP service at runtime, including screen shots and descriptions of the presence status options, see Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

34.1.2 Requirements for IMP

The IMP service requires a back-end presence server. WebCenter is certified with Microsoft Office Live Communications Server (LCS) 2005, and Microsoft Office Communications Server (OCS) 2007, and it can integrate with other presence servers. Oracle WebLogic Communications Services (OWLCS) 11g is available for download on Oracle Technology Network (OTN) at http://www.oracle.com/technetwork/index.html.

34.2 Basic Configuration for the IMP Service

This section describes the steps required for adding the IMP service to your application. It includes the following subsections:

34.2.1 Setting up Connections for the IMP Service

After the presence server is properly installed and running, you must add a connection to it. This section describes how. It includes the following subsections:

34.2.1.1 IMP Service Connections

The IMP service requires an Instant Messaging and Presence connection to the presence server (Microsoft LCS, Microsoft OCS, or OWLCS).

When a WebCenter service interacts with an application that handles its own authentication, you can associate that application with an external application definition to allow for credential provisioning. For Microsoft LCS and OCS connections, an external application is mandatory. For OWLCS connections, use identity propagation (instead of an external application). This set up enables you to configure additional security with Web Services Security (WS-Security).

Note:

While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.
34.2.1.1.1 Mapping User Names to IM Addresses

The im.address.resolver.class handles the resolver implementation used to map user names to IM addresses and IM addresses to user names. This implementation looks for IM addresses in the following places and order:

  1. User Preferences - If the user has entered his or her IM address in the Presence service Preferences page, then the user's IM address is found in the user's preferences.

  2. User Credentials - If an external application is configured, then an account field provides the user's IM address.

  3. User Profiles - If the user has not supplied preferences and WebCenter cannot fetch the IM address from the external application, then WebCenter reads the IM address from LDAP (that is, the user's profile). The default LDAP property read is the BUSINESS_EMAIL attribute.

To use your own resolver implementation, extend from IMPAddressResolver class and implement two methods: resolveAddress and resolveUsername.

  • The resolveAddress method takes in user name and returns the corresponding IM address.

  • The resolveUsername method takes in the IM address and returns the corresponding user name.

To plug in the new resolver class, change the service property im.address.resolver.class from the default oracle.webcenter.collab.rtc.IMPAddressResolverImpl to your resolver implementation. Example 34-1 shows a sample IMPAddressResolver implementation, where the resolver appends the domain string @example.com to the user name to construct the address and removes the same domain string from the address to construct the user name.

Example 34-1 Resolver Implementation

public class SampleAddressResolver extends IMPAddressResolver
{
  private String DOMAIN = "@example.com";
 
  public SampleAddressResolver()
  {
    super();
  }
 
  //Append DOMAIN to the username to construct the IM address
  public String resolveAddress(String username)
  {
    String imAddress = username;
    if(!imAddress.endsWith(DOMAIN))
    {
      imAddress = imAddress + DOMAIN;
    }
 
    return imAddress;
  }
 
  //Remove DOMAIN from the IM address to construct the username
  public String resolveUsername(String imAddress)
  {
    String username = imAddress;
    if(username.endsWith(DOMAIN))
    {
      int index = username.indexOf(DOMAIN);
      username = username.substring(0, index);
    }
   
    return username;
  }
}

34.2.1.2 How to Set Up Microsoft LCS Connections for the IMP Service

To set up the connection to the LCS presence server:

  1. In Oracle JDeveloper, open the WebCenter Portal application in which to consume the Instant Messaging and Presence service.

  2. In the Application Navigator, under Application Resources, right-click Connections, then select Instant Messaging and Presence from the list.

  3. In the Create Instant Messaging and Presence connection dialog box, select to create the connection in Application Resources.

    A connection in Application Resources is available only for that application, while a connection in IDE connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE connections to avoid having to re-create it.

  4. On the Name page, for Connection Name, enter a unique name for your connection.

    No other connection should have the same name.

  5. From the Connection Type list, select Microsoft Live Communication Server 2005.

  6. Select the Set as default connection checkbox to use this as the default connection, as shown in Figure 34-3.

    Figure 34-3 Create LCS Instant Messaging and Presence Connection, Step 1

    Description of Figure 34-3 follows
    Description of "Figure 34-3 Create LCS Instant Messaging and Presence Connection, Step 1"

  7. Click Next

  8. On the General page (Figure 34-4), enter the information for your Microsoft LSC instance.

    Figure 34-4 Create LCS Instant Messaging and Presence Connection, Step 2

    Description of Figure 34-4 follows
    Description of "Figure 34-4 Create LCS Instant Messaging and Presence Connection, Step 2"

    For example:

    • The Url could be http://host:port/RTC where RTC is the virtual directory name under which the server side module is deployed. (See the Microsoft Live Communications Server 2005 documentation for more information.)

    • The Domain property is maintained for backward compatibility. It should be left blank.

    • The Connection Timeout property is optional. It represents the time (in seconds) the service should wait for the server to respond while making the connection. If the presence server does not respond in the given time, then it aborts the connection and reports an error.

    • For PoolName, enter the name of the pool under which Microsoft Communications Server components are deployed. (See the Microsoft Live Communications Server documentation for more information.)

  9. On the same page, select an External Application to leverage the authentication mechanism (user names and passwords) on the presence server.

    For LCS connections, an external application is mandatory. The application maps the presence server user to the application user such that end users do not have to enter their user names and passwords each time they need information. For detailed information about configuring an external application for the IMP service, see Section 34.2.3, "Setting Security for the IMP Service."

  10. Click Test Connection to confirm that the connection is good.

  11. Click Next to create the connection.

  12. On the Additional Properties page (Figure 34-5), you can optionally add parameter.s

    Figure 34-5 Create LCS Instant Messaging and Presence Connection, Step 3

    Description of Figure 34-5 follows
    Description of "Figure 34-5 Create LCS Instant Messaging and Presence Connection, Step 3"

  13. Click Finish.

You can see the new IM and presence connection under Application Resources - Connections.

34.2.1.3 How to Set Up Microsoft OCS Connections for the IMP Service

To set up the connection to the Microsoft OCS presence server:

  1. In Oracle JDeveloper, open the WebCenter Portal application in which you plan to consume the Instant Messaging and Presence service.

  2. In the Application Navigator, under Application Resources, right-click Connections, then select Instant Messaging and Presence from the list.

  3. In the Create Instant Messaging and Presence connection dialog box, select to create the connection in Application Resources.

    A connection in Application Resources is available only for that application, while a connection in IDE connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE connections to avoid having to re-create it.

  4. On the Name page, for Connection Name, enter a unique name for your connection.

    No other connection should have the same name.

  5. From the Connection Type list, select Microsoft Office Communications Server 2007.

  6. Select the Set as default connection checkbox.

    The service requires that one connection be marked as the default connection, as shown in Figure 34-6.

    Figure 34-6 Create Microsoft OCS Instant Messaging and Presence Connection, Step 1

    Description of Figure 34-6 follows
    Description of "Figure 34-6 Create Microsoft OCS Instant Messaging and Presence Connection, Step 1"

  7. Click Next.

  8. On the General page (Figure 34-7), enter the parameters for your Microsoft OCS instance.

    Figure 34-7 Create Microsoft OCS Instant Messaging and Presence Connection, Step 2

    Description of Figure 34-7 follows
    Description of "Figure 34-7 Create Microsoft OCS Instant Messaging and Presence Connection, Step 2"

    For example:

    • The URL is the location of your Microsoft OCS instance. This could be http://host:port/RTC where RTC is the virtual directory name under which the server side module is deployed. (See the Microsoft Office Communications Server 2007 documentation for more information.)

    • The Domain property is maintained for backward compatibility. It should be left blank.

    • The Connection Timeout property is optional. It represents the time (in seconds) the service should wait for the server to respond while making the connection. If the presence server does not respond in the given time, then it aborts the connection and reports an error.

    • The User Domain is the Active Directory domain on Microsoft OCS. This parameter is mandatory for Microsoft OCS connections.

    • For Poolname, enter the name of the pool under which Microsoft Communications Server components are deployed. This parameter is mandatory for Microsoft OCS connections. (See the Microsoft Office Communications Server 2007 documentation for more information.)

  9. On the same page, select an External Application to leverage the authentication mechanism (user names and passwords) on the presence server.

    For Microsoft OCS connections, an external application is mandatory. The application maps the presence server user to the application user such that end users do not have to enter their user names and passwords each time they need information. For detailed information about configuring an external application for the IMP service, see Section 34.2.3, "Setting Security for the IMP Service."

  10. Click Test Connection to confirm that the connection is good.

  11. Click Next.

  12. On the Additional Properties page (Figure 34-5), you can optionally add parameters.

    Figure 34-8 Create Microsoft OCS Instant Messaging and Presence Connection, Step 3

    Description of Figure 34-8 follows
    Description of "Figure 34-8 Create Microsoft OCS Instant Messaging and Presence Connection, Step 3"

  13. Click Finish.

You can see the new IM and presence connection under Application Resources - Connections.

34.2.1.4 How to Set Up OWLCS Connections for the IMP Service

To set up the connection to the OWLCS presence server:

  1. In Oracle JDeveloper, open the WebCenter Portal application in which you plan to consume the Instant Messaging and Presence service.

  2. In the Application Navigator, under Application Resources, right-click Connections, then select Instant Messaging and Presence from the list.

  3. In the Create Instant Messaging and Presence connection dialog box, select to create the connection in Application Resources.

    A connection in Application Resources is available only for that application, while a connection in IDE connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE connections to avoid having to re-create it.

  4. On the Name page, for Connection Name, enter a unique name for your connection.

    No other connection should have the same name.

  5. From the Connection Type list, select Oracle WebLogic Communication Server.

  6. Select the Set as default connection checkbox.

    The service requires that one connection be marked as the default connection.

  7. Click Next (Figure 34-9).

    Figure 34-9 Create OWLCS Instant Messaging and Presence Connection, Step 1

    Description of Figure 34-9 follows
    Description of "Figure 34-9 Create OWLCS Instant Messaging and Presence Connection, Step 1"

  8. On the General page (Figure 34-10), enter the information for your OWLCS instance. For example, Url could be http://host:port.

    Figure 34-10 Create OWLCS Instant Messaging and Presence Connection, Step 2

    Description of Figure 34-10 follows
    Description of "Figure 34-10 Create OWLCS Instant Messaging and Presence Connection, Step 2"

    The following properties are optional:

    • Domain: This property is maintained for backward compatibility. It should be left blank.

    • Connection Timeout: The time (in seconds) the service should wait for the server to respond while making the connection. If the presence server does not respond in the given time, then it cancels the connection and reports an error.

    • Policy URI: URI to the security policy that is required for authentication on the OWLCS.

    For Authentication Method:

    • Select Identity Propagation to provide secure identity propagation with WS-Security.

      Note:

      Identity propagation is the recommended authentication method for the IMP service. For more information about identity propagation, see Section 67.16, "Identity Propagation Mechanisms."
    • Select External Application to leverage the authentication mechanism (user names and passwords) on the presence server. The application maps the presence server user to the application user such that end users do not have to enter their user names and passwords each time they need information. For more information on configuring an external application for the IMP service, see Section 34.2.3, "Setting Security for the IMP Service."

  9. Click Test Connection to confirm that the connection is good, then click Next to create the connection.

  10. On the Additional Properties page, add any additional, optional parameters (Figure 34-11).

    Figure 34-11 Create OWLCS Instant Messaging and Presence Connection, Step 3

    Description of Figure 34-11 follows
    Description of "Figure 34-11 Create OWLCS Instant Messaging and Presence Connection, Step 3"

    Additional properties are necessary only for changing the default configuration of the Click2Dial call service.

    Note:

    If values should be secured, then add them with Add Secured Property.

    You can add the following parameters:

    • presence.url: URL to the presence service. This must be supplied if the presence service is deployed on a separate server.

    • contacts.url: URL to the contact management service. This must be supplied if the contact management service is deployed on a separate server.

    • call.url: URL for the third-party call server. If no value is supplied, then this uses the same value as base.connection.url.

    • call.method: Supports values sip and pstn:

      • When set to sip, the IMP service forwards the user's SIP address to the third-party call service. The third-party call service must decide on the routing of the call.

      • When set to pstn, the user's phone number is based on the user's profile attribute (BUSINESS_PHONE). You can use the connection property call.number.attribute to change this default profile attribute (BUSINESS_PHONE) to any other attribute.

    • call.domain: The domain name of the pstn gateway. If no domain name is supplied, then this uses the domain value specified when the connection was created. Supply a domain name only when call.method is set to pstn.

    • contact.number.attribute: The attribute used to read users' phone numbers from the user profile. The default is BUSINESS_PHONE. Supply this attribute value only when call.method is set to pstn.

    • recipient.alias: Alias used to import the OWLCS certificate. The value must be unique and must not be used by another service. If no alias name is supplied, then the application uses the default value webcenter_owlcs.

  11. Click Finish.

You can see the new IM and presence connection under Application Resources - Connections.

34.2.2 Adding the IMP Service at Design Time

This section explains a basic incorporation of the IMP service into your application. It includes the following subsections:

34.2.2.1 IMP Service Task Flows

The IMP service does not include any task flows.

34.2.2.2 How to Add the IMP Service to your Application

To add the IMP service to your WebCenter Portal application:

  1. Follow the steps described in Chapter 3, "Preparing Your Development Environment" to create a customizable page in your application.

  2. Open the page on which you want to add the IMP service.

  3. Ensure that you have configured your application to connect to the presence server. See Section 34.2.1, "Setting up Connections for the IMP Service."

  4. In the Component Palette, drag and drop the Presence component to the page to add the Presence icon (Figure 34-12).

    Figure 34-12 Component Palette - IMP Service Components

    Description of Figure 34-12 follows
    Description of "Figure 34-12 Component Palette - IMP Service Components"

    Use the Presence icon anywhere you want to display a user, for example, as the author of a discussion topic, the sender/recipient of a mail, or the owner of a document.

  5. In the resulting dialog box, enter the user name of a user that exists in the back-end server that is linked to in the IM and Presence connection.

    You can add numerous presence components to the application page.

    For information about optional Presence component parameters, see Section 34.3.2, "Customizing IMP Views."

  6. Click Finish.

  7. From the Component Palette, drag and drop Presence Data to the end of the page (that is, before the <af:document> tag).

    This component does not have any attributes.

    The Presence Data component provides the status information for all Presence components on the page, such as online, offline, or busy. It verifies that all presence information corresponding to the user on the whole page shows consistent status information. Without this component, all users appear offline.

    Because the Presence Data component makes a call to the back-end server, for best performance, ensure that this is the last tag on the page. To avoid adding this tag to every page in your application, consider using a page template with Presence Data as the last component; that is, before the end of the </af:form> tag.

    Note:

    You can create new pages at runtime on which you can add components, such as forums, mail, or documents. Many components have Presence tags, but users do not have a handle to add the Presence Data tag to the page. To see presence on custom pages, you must manually add the Presence Data tag to the underlying template.
  8. If External Application in IDE connections was selected when you created the connection, then drag and drop the External Application - Change Password task flow into your application from the Resource Palette or Component Palette.

    This task flow enables the end user to set the appropriate user name and password for the external application.

  9. Save your project, and then run your page to a browser to see the Presence component.

    Figure 34-13 shows the runtime Presence component with the display name of user John Smith.

    Figure 34-13 WebCenter Presence Icon - Offline

    John Smith offline icon

34.2.3 Setting Security for the IMP Service

The IMP service requires user identity. ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

The user name you use to log on to the application is also used to log in to the presence server. If you have an external application configured, then credentials can be read from the external application (public credentials) and used to log on to the presence server. If you do not apply ADF security or if you do not have an external application configured, then users cannot authenticate and do not see any content at runtime.

Note:

The presence server and the WebCenter Portal application should point to the same identity store. The identity store must be LDAP-based; that is, not file-based with jazn-data.xml.

To access the presence server, the IMP service can use an external application with dedicated user accounts.

  • Microsoft LCS and OCS support external application connections. With a secured application, users get presence status. Microsoft LCS and OCS provide an option for changing external credentials, which works as an alternative to using an external application. A logged-in user can click any Presence context menu and select Change Credentials. Security should be on a private trusted network.

  • OWLCS supports both identity propagation and external application-based connections. With OWLCS, user creation and deletion is manual. Any time a user is added to (or removed from) the application's identity store, the same user must be created in (or removed from) the OWLCS user store.

To use an external application for authentication:

  1. On the General page of the Create Instant Messaging and Presence connection wizard, click the + icon next to External Application.

    This brings up the Register External Application wizard. The application maps the presence server user to the application user such that end users do not have to enter their user names and passwords each time.

    Note:

    External application credential provisioning is built into the IMP connection. You do not need to drop External Application - Change Password task flow on a page.
  2. On the Name page:

    • For Application Name, enter a unique name to identify the application. This name must be unique within the WebCenter Portal application, and among other connections as well. Note that you cannot edit this field afterward.

    • For Display Name, enter a name for the application that end users see in the credential provisioning screens.

  3. Click Next.

  4. On the General page, leave the following properties with the default values.

    • Login URL

    • User Name/ID Field Name

    • Password Field Name

  5. From the Authentication Method list, select POST. This submits login credentials within the body of a form. The external application for the IMP service requires this authentication method.

  6. Click Next.

  7. On the Additional Fields page:

    Click Add Field, and add an extra field with the name "Account." Make sure to select the Display to User checkbox, as shown in Figure 34-14.

    Note:

    The external application for the IMP service requires this additional field. It must be displayed to users.

    Figure 34-14 Account Additional Field

    Description of Figure 34-14 follows
    Description of "Figure 34-14 Account Additional Field"

  8. The External Application service allows different types of credentials to be associated with a connection:

    • When shared credentials are specified, every authenticated user uses the same credentials to access the external application; that is, the user name and password you can define here. A single presence session is created for all logged-in users. This is not accessible to public users.

    • With public credentials, without authenticating your WebCenter Portal application, you can view presence from a certain presence ID for all unauthenticated (public) users. Public credentials are used whenever an application is not secured or the user has not yet logged in. A single presence session is created for all public users.

    • With private credentials, each user must authenticate to an individual ID (that is, each application user must specify his own credentials). One presence session is created for each user.

  9. Click Finish to have the external application use private credentials, or click Next to set up shared or public credentials.

  10. For Shared Credentials Only: On the Shared Credentials page, ensure that Specify Shared Credentials is selected, then enter the shared user credentials and ID.

  11. For Public Credentials Only: On the Public Credentials page, ensure that Specify Public Credentials is selected, then enter the user credentials and ID for public use.

  12. Click Finish to register the external application.

  13. In the IMP connection wizard, ensure that this newly-created external application connection for IMP is selected.

For information about using external applications, see Section 67.13, "Working with External Applications."

34.3 Advanced Information for the IMP Service

This section describes optional features available with the IMP service. It includes the following subsections:

34.3.1 Enabling Network Presence

If Oracle WebCenter presence is not available (for example, if your enterprise uses a Jabber/XMPP presence server or has federated presence servers with users distributed across identity management systems), you can connect to a 3rd-party network presence service.

Out-of-the-box, WebCenter supports Yahoo! Messenger on network presence. However, the network presence model can be extended to include other providers, such as ICQ.

This section includes the following subsections:

34.3.1.1 Setting Up Yahoo! Messenger Presence

WebCenter Portal Framework allows end users to set their IM preferences to their Yahoo! Messenger presence. Portal developers enable this functionality by leveraging the rtcPresenceHandler bean.

Follow these steps to include Yahoo! Messenger presence in your WebCenter Portal application.

  1. On the Source tab for your JPSX page, add the user interface for users to enter their Yahoo! Messenger credentials: Display Name and IM Address input boxes and a Save IM Preferences button.

    Example 34-2 shows the two af:inputText components for users to enter Display Name and IM Address and an af:commandButton component for users to save the preferences.

    Setting the inputText value with this EL sets the displayName and imAddress in the preferences bean. To save the values, users click the button, which invokes a method from the bean to save the preferences.

    Example 34-2 User Interface for Yahoo! Messenger Presence

    <af:inputText label="Display Name" 
    value="#{rtcPreferenceHandler.displayName}" id="it1"/>
          <af:inputText label="IM Address" 
    value="#{rtcPreferenceHandler.imAddress}" id="it2"/>
           <af:commandButton text="Save IM Preferences" id="cb1"
    actionListener="#{rtcPreferenceHandler.savePreferences}"/>
    

    Example 34-3 shows the full source code for the page, with the user interface included.

    Example 34-3 Source Code for the Page with Yahoo Presence

    <?xml version='1.0' encoding='UTF-8'?>
    <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
              xmlns:f="http://java.sun.com/jsf/core"
              xmlns:h="http://java.sun.com/jsf/html"
              xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
              xmlns:rtc="http://xmlns.oracle.com/webcenter/collab/rtc">
      <jsp:directive.page contentType="text/html;charset=UTF-8"/>
      <f:view>
        <af:document id="d1">
          <af:form id="f1" usesUpload="true">
            <af:panelStretchLayout id="psl1">
              <f:facet name="bottom"/>
              <f:facet name="center">
                <af:panelGroupLayout layout="scroll"
                                     xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
                                     id="pgl1">
                  <rtc:presence username="#{rtcPreferenceHandler.imAddress}" displayName="#{rtcPreferenceHandler.displayName}" id="p1"/>
                  <rtc:presenceData id="pd1"/>
                  <af:inputText label="Display Name" value="#{rtcPreferenceHandler.displayName}" id="it1"/>
                  <af:inputText label="IM Address" value="#{rtcPreferenceHandler.imAddress}" id="it2"/>
                  <af:commandButton text="Save IM Preferences" id="cb1"
                                    actionListener="#{rtcPreferenceHandler.savePreferences}"/>
                                    
                </af:panelGroupLayout>
              </f:facet>
              <f:facet name="start">
                <af:spacer width="10" height="10" id="s1"/>
              </f:facet>
              <f:facet name="end">
                <af:spacer width="10" height="10" id="s2"/>
              </f:facet>
              <f:facet name="top"/>
            </af:panelStretchLayout>
          </af:form>
        </af:document>
      </f:view>
    </jsp:root>
    
  2. Run the JPSX page to see that now users can enter their Yahoo! Messenger credentials (Figure 34-15).

    Figure 34-15 User Interface to Enter Yahoo! Messenger Credentials

    Description of Figure 34-15 follows
    Description of "Figure 34-15 User Interface to Enter Yahoo! Messenger Credentials"

    Presence tags for that user shows their Yahoo presence, either online (Figure 34-16) or offline (Figure 34-17).

    Figure 34-16 Yahoo Presence Icon - Online

    Description of Figure 34-16 follows
    Description of "Figure 34-16 Yahoo Presence Icon - Online"

    Figure 34-17 Yahoo Presence Icon - Offline

    Description of Figure 34-17 follows
    Description of "Figure 34-17 Yahoo Presence Icon - Offline"

    Figure 34-18 shows a sample page that includes the Discussion Forums task flow, where Yahoo! Messenger presence and WebCenter presence are shown together.

    Figure 34-18 Sample Page with WebCenter Presence and Yahoo! Messenger Presence

    Description of Figure 34-18 follows
    Description of "Figure 34-18 Sample Page with WebCenter Presence and Yahoo! Messenger Presence"

34.3.1.2 Setting Up Other Network Presence Providers

To use a different network presence provider, create a jar file with the PresenceNetworkAgent implementation class for that service and an imp-pna.config file listing that implementation class.

For example, suppose the new Presence Network Agent is called SamplePNA. You must create two files: the Project1.SamplePNA class file and the imp-pna.config file.

  • Project1.SamplePNA.java: This class implements oracle.webcenter.collab.rtc.PresenceNetworkAgent. It must implement three methods:

    • isSupported(PNAContext context): The method should return true if the PNA supports the user for which presence is requested. The PNAContext object supplied contains the user information. For example, if the PNA supports all IM addresses with the domain example.com, then it can get the imAddress from the PNAContext object and check for the domain example.com.

    • getURL(PNAContext context): The method should return the fully qualified URL to reach to the user's Presence icon. Again, it gets the user information from the PNAContext object.

    • getChatURI(PNAContext context): The method should return the browser compatible URI to invoke the chat client (for example, sip:user@example.com).

    Example 34-3 shows this SamplePNA class file.

    Example 34-4 SamplePNA Class File

    public class SamplePNA implements PresenceNetworkAgent
    {
    private String DOMAIN = "@example.com";
     
    public SamplePNA()
    {
    super();
    }
     
    //Returns true if the imAddress ends with DOMAIN
    public Boolean isSupported(PNAContext context)
    {
    String imAddress = context.getIMAddress();
    if(imAddress.endsWith(DOMAIN))
    {
    return true;
    }
     
    return false;
    }
     
    //Returns the URL to the icon representing the current status of a user
    public String getURL(PNAContext context)
    {
    String imAddress = context.getIMAddress();
    Strung url = "http://www.example.com?address=" + imAddress;
    return url;
    }
     
    //Returns the browser compatible chat uri to invoke the thick client
    public String getChatURI(PNAContext context)
    {
    String imAddress = context.getIMAddress();
    String chatURI = "sip:" + imAddress;
    return chatURI;
    }
    }
    
  • META-INF/imp-pna.config: This file lists the available PNAAgent classes. In this case, it contains only the following line:

    Project1.SamplePNA
    

Make sure the generated jar file contains the Project1.SamplePNA class file and the imp-pna.config file. To activate the new Presence Network Agent, deploy the jar file at the oracle.webcenter.framework shared library location, then restart the server.

Whenever a Presence tag is encountered with an IM address as user@example.com. The URL configured appears on the user interface as the Presence icon.

<rtc:presence username="user1@example.com" resolveAddress="false"/>

34.3.2 Customizing IMP Views

Table 34-1 lists the attributes supported by the Presence component. Only the username attribute is required; all other attributes are optional. You can update these attributes in the Property Inspector.

Table 34-1 Presence Component Description

Attribute Description

username

The user whose presence information you want to add to the application page. This attribute is required.

display

How the component should display. Takes one of the following values:

  • icon: Display only the Presence icon; do not render the name.

  • name: Display the user name; do not display the Presence icon.

  • both (default): Display both the icon and the user name.

displayName

By default, the Presence component displays the user name.

If the flag get.display.name.from.user.profile is set to true in service-config.xml and if this displayName attribute is not supplied, then the Presence component tries to look up a user's display name from the User Profile.

iconPosition

The position for the icon. Possible values are begin and end. The default value is begin.

controlsEnabled

A Boolean value that defines whether the component should provide rich interactions to the end user. If this attribute is set to false, then the Presence component does not do anything when clicked.

id

A unique identifier for the component on the page. The identifier must follow a subset of the syntax allowed in HTML:

  • Must not be a zero-length String.

  • First character must be an ASCII letter (A-Z, a-z) or an underscore ('_').

  • Subsequent characters must be an ASCII letter or digit (A-Z, a-z, 0-9), an underscore ('_'), or a dash ('-').

smallIcon

A Boolean value that defines whether to use the small 12x12 icon set (true) or to use the default 16x16 icon set (false). The default value is false.

rendered

A Boolean value that defines whether to render this component. The default value is true.

binding

An EL reference to store the component instance on a bean. Use this to give programmatic access to a component from a backing bean or to move creation of the component to a backing bean.

inlineStyle

The CSS styles to use for this component. Manually enter any style in compliance with CSS version 2.0 or later, or expand this node to specify style elements. This is intended for basic style changes.

styleClass

A CSS style class to use for this component.

resolveToAddress

A Boolean value that defines whether to resolve the supplied username to an IM address. The default value is true.

However, if the supplied username is an IM address, then you can set this value to false, and the IMP service uses username as the IM address.


34.3.3 Troubleshooting the IMP Service

This section describes common problems and solutions for the IMP service.

Problem

The Presence icon is not visible in your WebCenter Portal application.

Solution

Ensure that an IMP connection exists in your application and has been set as active.

Problem

Changes in the presence status of users are not visible in your WebCenter Portal application.

Solution

For each logged-in user's session, the IMP service fetches the presence information from the presence server and stores it in the presence cache. For presence requests, the service returns the data from the cache until the cache expires. The default cache expiry period is 60 seconds.

To view the updated presence status, you can wait for the cache to expire and retrieve the latest presence status.

You can also change the cache expiry time by setting the rtc.cache.time service configuration property to the desired value (in seconds). Update adf-config.xml to include the highlighted entry, which shows the sample value as 30 seconds. Example 34-5 shows an example.

Example 34-5 Setting the rtc.cache.time Expiration Value in adf-config.xml

<adf-collaboration-config xmlns="http://xmlns.oracle.com/webcenter/collab/config">
<service-config serviceId="oracle.webcenter.collab.rtc">
<property name="rtc.cache.time" value="30"/></service-config>
</adf-collaboration-config>

Problem

A number of options, such as Start Phone Conference and Send Instant Message, are not available in the context menu of the IMP service in your WebCenter Portal application.

Solution

Ensure that IMP service is configured in your WebCenter Portal application. Also, ensure the following settings for the various context menu options:

  • Start Phone Conference option unavailable: Ensure that you are using the OWLCS connection type. For Microsoft LCS and Microsoft OCS, this option is not supported.

  • View Profile option unavailable: Ensure that your application is secured.

  • Send Instant Message option unavailable: Ensure that the IMP service is configured in the application.

Problem

You are unable to send a message from your WebCenter Portal application. Clicking the Send Instant Message option returns an error.

Solution

Ensure that your SIP client is supported by the presence server and you have logged on as an authenticated user. For Microsoft LCS and Microsoft OCS, the supported SIP client is Microsoft Communicator. For OWLCS, the supported SIP client is Oracle Communicator.

Problem

You are not able to start a phone conference. Clicking the Start Phone Conference option does not initiate any action.

Solution

Ensure the following:

  • Ensure that you are starting the phone conference with a user other than the logged-in user. The caller and the user being called up should be different users, with different phone numbers.

  • Ensure that you have provided correct telephone numbers, in the supported format, in the user profile.

  • If you specified the contact.number.attribute attribute in the IMP connection, then ensure that the contact numbers are indeed provided under this attribute for users. Otherwise, ensure that contact numbers are provided under the BUSINESS_PHONE attribute.