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

Services in WebCenter Portal 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:

35.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 Microsoft Lync).

When a service in WebCenter Portal interacts with an application that handles its own authentication, you can associate that application with an external application definition to allow for credential provisioning. An external application is mandatory.

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

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.

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

User Profiles - If the user has not supplied preferences and WebCenter Portal cannot fetch the IM address from the external application, then WebCenter Portal reads the IM address from LDAP (that is, the user's profile). The default LDAP property read is the BUSINESS_EMAIL attribute. Users can change this default with im.address.profile.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 35-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.

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

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

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

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.

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

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

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 35.2.3, "Setting Security for the IMP Service."

Click Test Connection to confirm that the connection is good.

Click Next to create the connection.

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

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

35.2.1.3 How to Set Up Microsoft OCS and Microsoft Lync Connections for the IMP Service

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

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

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

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.

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

The URL is the location of your Microsoft OCS or Lync 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 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 or Lync. This parameter is mandatory.

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

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

For Microsoft OCS and Microsoft Lync 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 35.2.3, "Setting Security for the IMP Service."

Click Test Connection to confirm that the connection is good.

Click Next.

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

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.

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.

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

Figure 35-10 shows the runtime Presence component with the display name of user Monty Montasaurus111.

Figure 35-10 WebCenter Portal Presence Icon - Online

35.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 - Framework Application template. For information about configuring ADF security, see Section 69.3, "Configuring ADF Security."

Credentials are 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 Framework 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, OCS, and Lync support external application connections. With a secured application, users get presence status. The Change Credentials option works as an alternative to using an external application. Logged-in users can click their own Presence context menu and select Change Credentials. Security should be on a private trusted network.

To use an external application for authentication:

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.

On the Name page:

For Application Name, enter a unique name to identify the application. This name must be unique within the Framework 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.

Click Next.

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

Login URL

User Name/ID Field Name

Password Field Name

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.

Click Next.

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

Note:

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

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

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

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

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.

Click Finish to register the external application.

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

35.3.1 Enabling Network Presence

When WebCenter Portal 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 Portal supports Yahoo! Messenger on network presence. However, the network presence model can be extended to include other providers, such as ICQ.

35.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 Framework application.

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

35.3.1.2 Setting Up Other Network Presence Providers

To use a different network presence provider, deploy your application that contains the PresenceNetworkAgent implementation class for that service and an imp-pna.config file listing that implementation class into a jar file.

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.

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"/>

35.3.2 Customizing IMP Views

Table 35-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 35-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.xmland 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.

35.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 Framework 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 Framework 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 35-5 shows an example.