Collaborative Services API

Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

Collaborative Services API

Lotus^® Collaborative Services provide Java API methods and tags for JavaServer Pages (JSP files) for extending the functionality of collaborative portlets such as the Domino and Extended Products Portlets, People Finder, and Common PIM portlets.

Collaborative Services defined

Collaborative Services are a set of methods and JavaServer Page tags that allow developers who are writing portlets for WebSphere Portal Express or other application servers to add Lotus collaborative functionality to their portlets. The services may be used to develop new custom portlets, or to add collaborative functionality (for example, menus or person links indicating online status) to existing portlets.

The services are designed to provide naming, authentication, portal and custom services for portlets that use the Domino and Extended products configured for the portal. As such, the methods provided by the services complement - not replace - the APIs of the individual Domino and Extended products such as the Domino Java API.

Application developers using Collaborative Services can design and implement functional extensions in portlets that incorporate the features of Domino and Extended Products, including IBM^® Lotus QuickPlace^®, IBM Lotus Sametime^®, and Domino Document Manager.

Benefits of Collaborative Services

The services provide standardized access to applications, easy-to-use APIs that are optimized for a collaborative portal, and a consistent security model across all Domino and Extended products.
The services enhance many aspects of operation of a collaborative portal site, including:

Authentication/Single Sign-On. The services handle token management for different SSO methods (such as IBM Tivoli^® Access Manager for e-business, Computer Associates eTrust SiteMinder, or Lotus Sametime tokens) and are extensible to other SSO methods. The services also handle Notes session creation, Web access authentication, and other session types such as Lotus Sametime.
Directory services. Collaborative Services manage connection between dual user directories even when they use different dn structures, and use the correct directory for queries.
Other features. Collaborative Services manage automatic lookups for user's mail files and Sametime server, global user settings across the portal, and awareness.

All of the Collaborative Services, except the people and menu tags, are user interface-neutral; that is, the portlet developer can design the user interface for the collaborative features being implemented. The goal of Collaborative Services is to provide the data necessary for rendering the user interface and to allow the developer to execute actions on the Domino and Extended products that have been installed and enabled in the portal environment.

The Java APIs in the services contain no platform-specific code. Because the components are UI-neutral and are not dependent on implementation details, they can be used to implement pervasive applications for mobile and wireless devices.

In addition, because the services hide the configuration details of the Domino and Extended products that are installed within an enterprise, collaborative functionality can be added to a portlet in a generic way - regardless of the physical requirements and machine-dependent details of portal configuration.

Details of operation

The Collaborative Services program runs in the cs.jar file in the following location:
Windows:
portal_server_root\shared\app\
Linux:
portal_server_root/shared/app/
i5/OS:
portal_server_root_user/shared/app/
The program is configured through the CSEnvironment.properties file in the following location:
Windows:
portal_server_root\shared\app\config\
Linux:
portal_server_root/shared/app/config/
i5/OS:
portal_server_root_user/shared/app/config/
Running any one of the WPSconfig batch files described in topics available under Configuring WebSphere Portal Express to use Domino and the Extended Products installs cs.jar and CSEnvironment.properties to the WebSphere Portal Express server.

The Collaborative Services program also requires configuration changes to the CSEnvironment.properties file. For information on the properties file, see Collaborative Services environment properties

Javadoc

The Javadoc HTML documentation for the services (called CS Javadoc), if available on the portal server, is installed in the following location:
Windows:
portal_server_root\doc\Javadoc\
CollaborativeServicesAPI\index.html
Linux:
portal_server_root/doc/Javadoc/
CollaborativeServicesAPI/index.html
i5/OS:
portal_server_root_user/doc/Javadoc/
CollaborativeServicesAPI/index.html
Tip: To view the JavaDoc, open a browser on the server and navigate to the file location above, or navigate to the index.html file through the operating system and launch it into a browser.

Java objects and tags provided

Collaborative Services comprise the following Java infrastructure objects and service objects:

Infrastructure objects

CSEnvironment
CSCredentials
CSFactory

Java service objects

DominoService
QPService
PeopleService
SametimeService
CSBaseService (base class for all the service objects)
Person tag

The services also provide certain tag language descriptors, most importantly the Person tag used for people awareness, including Lotus Sametime functionality

Service object example

Collaborative Services service objects (Java classes) operate in a framework of helper objects that are not themselves service objects but which provide the infrastructure for all service object methods.

For example, the following code snippet illustrates how infrastructure objects construct the Lotus QuickPlace service object (QPService):
<%
...
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
QPService quickplaceService = (QPService)CSFactory.getService(cred, 
    CSFactory.QUICKPLACE_SERVICE);
if (quickplaceService != null)
{
		 ... (for example, use the quickPlaceService 
          to create QuickPlaces)
		 quickplaceService.cleanup();
}
...
%>
In this example, the first object, called CSEnvironment, gets and sets the configuration options of the collaborative portal environment, including the server information for the installed and enabled Domino and Extended products (for example, Domino Directory, Lotus Sametime, and QuickPlace). For more information, see CSEnvironment object.

The second object, CSCredentials, is required by most of the Collaborative Services methods because it contains the credentials for the each authenticated user (including user, password, and SSO token, if available). User credentials are stored in an HTTP session object and are obtained by the CSEnvironment object, for the method CSEnvironment.getCredentials. For more information, see CSCredentials object.

The service object is created, or constructed, by the third infrastructure object, CSFactory, which instantiates the type of service object called (in this example, QuickPlace). The CSFactory object creates the requested service and initializes a connection with the worker server, the server that handles the service requests for the requested service object (in this example, the QuickPlace server). The object can also maintain the server configuration information for reuse. For more information, see CSFactory object.

Each service object requires a call to the cleanup() method at the end of its use.

Infrastructure objects

The following infrastructure, or helper, objects support the Collaborative Services service objects (Java classes and methods):

CSEnvironment object
CSCredentials object
CSFactory object

CSEnvironment object

The CSEnvironment object is created with the request object as follows:
CSEnvironment environ = CSEnvironment.getEnvironment(request);
The CSEnvironment object provides information about the servers of any Domino and Extended Products, for example Lotus Sametime or QuickPlace, that are installed and enabled to work with WebSphere Portal Express.

Collaborative Services are administered through configuration settings in WebSphere Portal Express. In addition, the portal administrator may edit certain configuration settings for Collaborative Services manually in the CSEnvironment.properties file. The portal administrator may use either or both of these resources to control the portal environment configuration for Domino and Extended Products servers. For more information, see Collaborative Services environment properties

Server Type constants

Server Type constants are used for retrieving configuration information for a specific Domino and Extended product.
public final static String CS_SERVER_WEBSPHERE_PORTAL_EXTEND
public final static String CS_PERF_PROP_USEWMM
public final static String CS_SERVER_QUICKPLACE
public final static String CS_SERVER_DOMINO_DIRECTORY
public final static String CS_SERVER_SAMETIME
CS_PERF_PROP_USEWMM is a performance tuning option for the Person tag. It provides a choice of enabling Domino LDAP queries for e-mail addresses instead of Member Manager lookup. Bypassing Member Manager lookup and preferring an existing Domino LDAP service for search and retrieval of e-mail addresses can significantly boost performance of person links developed with Collaborative Services.

Server Property Name constants

Server Property Name constants are used when retrieving configuration information about a specific Domino and Extended product server.
public final static String CS_PROP_ENABLED
public final static String CS_PROP_HOSTNAME
public final static String CS_PROP_PROTOCOL
public final static String CS_PROP_VERSION
CSCredentials object

The CSCredentials class (obtained from the CSEnvironment.getCredentials method) is required by most of the Collaborative Services methods because it contains the credentials for the authenticated user: user ID, password, and SSO token, if available.

A CSCredentials object is created as follows:
CSEnvironment environ = new CSEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
This object provides the following methods:
public String getUserLoginName
Returns the name used by the current user to log in to the application.
public String getUserName
Returns the distinguished name for the currently logged in user.

CSFactory object

The CSFactory.getService call is responsible for constructing a service object. This results in a connection being established with a worker server. This connection is saved within the service object for reuse in future calls within the JSP file that renders the portlet. For example, the QuickPlaceService object is constructed with a specific server. The QuickPlaceService object may then be used to create one or more QuickPlaces on that server.

Service Type constants

Service Type constants are used when constructing a service object.
public final static String QUICKPLACE_SERVICE
public final static String DOMINO_SERVICE
Methods

To construct a Collaborative Services service object, use one of the following methods:
CSFactory.getService(CSCredentials credentials, 
String serviceType)
This method is used when you want to use the server that is configured in the portal environment.
CSFactory.getService(CSCredentials credentials, 
String serviceType, String server, String protocol)
This method is used when you want to override either the server that is configured in the environment or a server has not yet been configured in the portal environment.

The getService method returns a Collaborative Services service object, depending on serviceType, for example, CSFactory.DOMINO_SERVICE.

Summary of collaborative Java service objects

The following Java service objects provide the classes and methods of Collaborative Services. Refer to the Collaborative Services Javadoc HTML documentation for all details on the components of these service objects.

DominoService
QPService
PeopleService
SametimeService

In addition, see the CSEnvironment.properties file for a complete description of the settings that supply values to these APIs. The CSEnvironment.properties file is located in the following directory:
Windows:
app_server_root\lib\app\config\
Linux:
app_server_root/lib/app/config/
i5/OS:
was_profile_root/lib/app/config/
DominoService

The Domino Service is a set of methods that provide standardized access to all releases of Domino from Domino 4.6 through 7.0, making Domino release differences transparent for portal and portlet development. The DominoService objects support any Domino capabilities that are needed for Notes-based repositories that work with the portal, such as data from Notes views and capabilities for selection of data in databases.

QPService

The QuickPlace Service (QPService) provides methods to display and manage QuickPlace team spaces.

PeopleService

The People Service retrieves information about a specified person from the user directory configured to work with WebSphere Portal Express.

SametimeService

The Sametime Service is a set of methods that provide standardized access to the Lotus Sametime server configured to work with WebSphere Portal Express. The methods manage and display contact lists for chat and collaboration.

Certain SametimeService methods - getServerappPort(), getNameFormat(), and getNameSeparator(), and all the "Reconnect" and "Timeout" methods - pertain to the server-to-server connection between WebSphere Portal Express and the Sametime Instant Messaging server. This connection exists for the sole purpose of obtaining Sametime Instant Messaging authentication tokens for users. The tokens are then used to log users into Sametime Instant Messaging from their web browsers.

Person tag

The Collaborative Services include a JavaServer Page tag language descriptor (TLD) for a person tag.

When added to your custom portlet, the person tag causes people's names to appear as hyperlinks, and also generates the HTML that renders a drop-down person menu on any aware name within your portlet that a user clicks. For more information, see Providing online awareness for a custom portlet.

By default, the person menu includes the action Send E-mail. If Lotus Sametime is installed and enabled to work with the portal, then the person tag adds a menu item showing online status for the person link (an indicator such as I Am Active), as well as the following actions:

Chat
Add to Instant Contacts

The person tag provides only default actions, but you can add a custom actions to the person menu in any portlet. For more information, see Customizing person menu actions.
The tag library for Collaborative Services that includes the person tag is installed on the portal server in the following location:
Windows:
portal_server_root\shared\app\
web-inf\tld\people.tld
Linux:
portal_server_root/shared/app/
web-inf/tld/people.tld
i5/OS:
portal_server_root_user/shared/app/
web-inf/tld/people.tld
Keep in mind that there is no need to copy or move the .tld file anywhere within the portal project; you need only refer to its location in the portal installation. You need a reference to it in the JSP file for every portlet you deploy that uses the person tag. In addition, because the person tag generates HTML, it requires Java and JavaScript to be enabled on the client.

Parent topic:
Reference topics for collaboration

Related concepts
Collaborative Services environment properties Overview of cooperative portlets

Related tasks
Providing online awareness for a custom portlet Customizing person menu actions Logging for Collaborative Services Configuring contact information on person links

Related reference
Troubleshooting Lotus Domino and the Extended Products Troubleshooting Domino and Extended Products Portlets