Collaborative Services API

 

+
Search Tips   |   Advanced Search

 

Content

  1. Overview
  2. Collaborative Services defined
  3. Benefits of Collaborative Services
  4. Java objects and tags provided
  5. Service object example
  6. Infrastructure objects
  7. Summary of collaborative Java service objects
  8. Tags examples
  9. Logging

 

Overview

Collaborative Services provide Java API methods and tags for Java Server Pages (JSPs) for extending the functionality of Lotus collaborative portlets. Application developers using Collaborative Services can design and implement functional extensions in portlets that incorporate the features of Domino and Extended Products, including:

Note that Lotus Discovery Server is no longer included with WebSphere Portal 5.1, but the Collaborative Services API continues to support Discovery Server and the DiscoveryServerService.

The Collaborative Services program runs in...

PORTAL_ROOT/sharedapp/cs.jar

...and is configured using...

PORTAL_ROOT/sharedapp/config/CSEnvironment.properties

Run WPSconfig batch files that configure WebSphere Portal to use Domino and the Extended Products installs cs.jar and CSEnvironment.properties to the WebSphere Portal server. The Collaborative Services program also requires configuration changes to the CSEnvironment.properties file.

The Javadoc for Collaborative Services is installed on WebSphere Portal in... 

PORTAL_ROOT/doc/Javadoc/CollabServices/index.html

You may also deploy standalone samples (JSPs) of Collaborative Services.

 

Collaborative Services defined

Collaborative Services are a set of methods and JSP tags that allow developers who are writing portlets for WebSphere Portal or other appservers to add Lotus collaborative functionality to their portlets. Collaborative Services may be used to develop new custom portlets or to add collaborative functionality (menus or people links indicating online status, for example) to existing portlets.

Collaborative Services are designed to provide access to the functionality of Domino and Extended products that are enabled to work as companion products to WebSphere Portal. As such, the methods provided by Collaborative Services complement - not replace - the APIs of the individual Domino and Extended products such as the Domino Java API and the Discovery Server KDSAPI.

 

Benefits of Collaborative Services

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

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 they are implementing. 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 Collaborative Services contain no platform-specific code. Consequently, the components are UI-neutral and are not dependent on implementation details. Because they are UI-neutral, the Collaborative Services can be used to implement pervasive applications for mobile and wireless devices.

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

 

Java objects and tags provided

Collaborative Services comprise the following Java infrastructure objects, service objects, and tag language descriptors for custom tags for JSPs:

 

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.

The following example illustrates how infrastructure objects construct the QuickPlace service object: 

<%
...
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 Instant Messaging and Web Conferencing, Lotus Team Workplace, and Lotus Discovery Server). 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 Lotus Team Workplace server). The object can also maintain the server configuration information for reuse. For more information, see CSFactory object.

Important 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

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 Instant Messaging and Web Conferencing or Lotus Team Workplace, that are installed and enabled to work with WebSphere Portal.

Note: Collaborative Services are administered through configuration management tools in WebSphere Portal. 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 Planning for collaboration under See also.

While Collaborative Services support Lotus Discovery Server 1.1 and QuickPlace 2.0.8, the APIs assume that the newer versions of Lotus Discovery Server and Lotus Team Workplace (QuickPlace) are installed and in use: 

CS_SERVER_DISCOVERY_SERVER_1.version=2.0
CS_SERVER_QUICKPLACE_1.version=3.0

 

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_DISCOVERY_SERVER
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 WebSphere Member Management (WMM) lookup. Bypassing WMM lookup and preferring an existing Domino LDAP service for search and retrieval of e-mail addresses can significantly boost performance of people 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 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 Team Workplaces on that server.

 

Service Type constants

Service Type constants are used when constructing a service object. 

public final static String DISCOVERY_SERVER_SERVICE
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 wish 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 wish 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 for details such as parameters and specific return values.

 

DominoService

The Domino Service is a set of methods that provide standardized access to all versions of Domino from Domino 4.6 through 6.0, making Domino version 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. The DominoService methods are many, and they are classified by their function:

  • Directory-related methods
  • Document-related methods
  • View-related methods

Note: The Notes and Domino portlets that are installed with WebSphere Portal are not implemented with the DominoService object. Therefore, do not refer to those portlets as examples. Instead, refer to the samples that are installed with the Collaborative Services enterprise application (cs.ear).

Some of the more important methods are described in the following sections.

 

Server methods

java.util.HashMap getServers()

Returns a list of Domino servers in the domain that have the http-hostname attribute set.

 

Database methods

boolean addACL()

Adds a single ACL to an existing database. 

boolean createDatabase()

Creates a new Domino database from a database template. 

java.util.HashMap getDatabases()

Returns a list of Domino database names and directory names in the specified start directory.

 

View methods

ViewInfo getViewInfo()

Returns view information about a view, encapsulated in a ViewInfo object. 

java.util.HashMap getDatabaseViews()

Returns a list of views in a specified Domino database.

 

User Name and Person information methods

java.lang.String getDistinguishedName()

Returns the distinguished name of the user. 

java.lang.String getDominoName()

Converts a distinguished name into a Domino name (also referred to as the Abbreviated name) For example, "OU=Acme,O=Operations" is converted to "/Acme/Operations"

Note This is simply a helper method - there is no LDAP query made. 

java.lang.String getEmailAddress()

Returns the e-mail address of the user. 

java.lang.String[] getMailServerFile()

Returns the names of the Domino mail database file and mail server for a valid user in the domain.

 

Methods related to QuickPlace

java.lang.String[] getQuickPlaceComponents()

Returns a list of Workplace components in a Team Workplace. 

java.lang.String[] getQuickPlaceDatabases()

Returns the list of Team Workplace databases. 

java.lang.String getCompleteQuickPlaceComponents()

Returns a list of Workplace components in a Team Workplace.

 

Initialization/Cleanup methods

void init()

Do not call the init() method. 

void cleanup()

Always call the cleanup() method when finished with the Service object.

 

QPService

The QuickPlace Service (QPService) is much expanded in this release of Collaborative Services. It provides the following methods: 

public java.util.HashMap getPlacesForMember()

Returns a list of Team Workplaces the authenticated user is a member of on all Team Workplace servers in the QuickPlace service. This method works with QuickPlace 3.0 only. 

public java.lang.String create(java.util.Hashtable ht)

Creates a Team Workplace on the remote server and returns the URL that references it. This method works with QuickPlace 2.0.8 and QuickPlace 3.0. 

public Vector search()

Performs a full-text search across all Team Workplaces in the QuickPlace service. 

public String createPlace()

Creates a Team Workplace on the remote server and returns the URL that references it. The initial Team Workplace manager will be the authenticated user. 

public String [] getPlaces()

Retrieves a list of placetypes, with their descriptions, that are available on this server. 

public HashMap getPlaceTypes()

Retrieves a HashMap of placetypes, with their descriptions, that are available on this server. 

public HashMap [] getMemberAccess()

Returns the distinguished names and access rights of all members and groups to a room of a Team Workplace. 

public boolean addMember()

Adds a member and assigns access rights to a room of a Team Workplace. 

public boolean addGroup()

Adds a group and assigns access rights to a room of a Team Workplace. 

public boolean removeMember()

Removes a member from a room of a Team Workplace. 

public boolean removeGroup()

Removes a group from a room of a Team Workplace. 

public boolean updateMetaData()

Updates the Team Workplace title and passes in meta data name value pairs. Meta data is stored in the placecatalog under the quickplace name. 

public boolean removePlace()

Removes the entire Team Workplace from the server 

public boolean lockPlace()

Locks the specified Team Workplace. Access to the Team Workplace is prohibited until the Team Workplace is unlocked. 

public boolean unlockPlace()

Unlocks the specified Team Workplace. Access to the Team Workplace is allowed after the Team Workplace is unlocked. 

public HashMap getRoomStructure()

Returns a hashmap of all elements of a room in a Team Workplace. 

public TreeMap getPlaceStructure()

Returns a treeMap representing the room hierarchy of the Team Workplace. 

public boolean doesPlaceExist()

Verifies the existence of a Team Workplace.

 

PeopleService

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

public HashMap getPersonInfo

 

Property Name constants

public final static String CS_PERSON_FULLNAME
public final static String CS_PERSON_EMAIL
public final static String CS_PERSON_DOMINONAME
public final static String CS_PERSON_DOMINOMAILSERVER
public final static String CS_PERSON_DOMINOMAILFILE
public final static String CS_PERSON_DEPARTMENT
public final static String CS_PERSON_JOBTITLE
public final static String CS_PERSON_LOCATION
public final static String CS_PERSON_PROFILEURL
public final static String CS_PERSON_SUMMARY

 

DiscoveryServerService

The Discovery Server Service is a set of methods that provide Discovery Server functionality, specifically the following methods:

  • Search APIs

    Provides functionality for WebSphere Portal to discover, search for, and retrieve Categories, People, Places, and Documents that have been mined by Discovery Server.

  • APIs that return URLs for use in the user interface

    Provides the URLs to Knowledge Map (K-map), Person Profiles, and the Discovery Server Administration UI.

  • APIs that return core Discovery Server objects

    Primary Discovery Server objects include Full Text Search, Metrics, Repositories, Taxonomy Editor, and the Content Catalog.

The DiscoveryServerService supports APIs available in Lotus Discovery Server 1.1 and 2.0. APIs for Lotus Discovery Server (Knowledge Discovery System(KDS)), are available in KDSW.jar and kdsapi.jar. By default, the DiscoveryServerService assumes that Lotus Discovery Server 2.0 is installed and will use the newer API methods. Lotus Discovery Server 1.1 is supported if the version information specified in the CSEnvironment.properties file indicates this version: 

CS_SERVER_DISCOVERY_SERVER_1.version=1.1

In this case, the DiscoveryServerService will use the deprecated KDS APIs available in Lotus Discovery Server 1.1.

The following DiscoveryServerService methods vary for different versions of Lotus Discovery Server that are distinguished by a version suffix: 

getProfileURL_DS11
GetProfileURL_DS20

Other new DiscoveryServerService methods work only with Lotus Discovery Server 2.0 and are annotated in the Javadoc: 

getMetrics
getTaxonomyData
getWorkQueueReader
getWorkQueueWriter
getKMapURL(java.lang.String categoryId)

 

SametimeService

The Sametime Service is a set of methods that provide standardized access to the Lotus Instant Messaging and Web Conferencing server configured to work with WebSphere Portal.

See the WebSphere\AppServer\lib\app\config\CSEnvironment.properties file for a complete description of the settings that supply values to these APIs. 

public String getServer()

Returns the Lotus Instant Messaging and Web Conferencing server hostname, for example, my.server.com. 

public String getVersion()

Returns the Lotus Instant Messaging and Web Conferencing server version. 

public String getProtocol()

Returns the Lotus Instant Messaging and Web Conferencing server protocol. 

public String getFullURL()

Returns the Lotus Instant Messaging and Web Conferencing server's full URL, for example, http://my.server.com:80. 

public String getPort()

Returns the Lotus Instant Messaging and Web Conferencing server port. 

public String getServerappPort()

Returns the Lotus Instant Messaging and Web Conferencing server application port, which is the port that the Lotus Instant Messaging and Web Conferencing server application should connect through. The default connection is configured to connect through the Sametime MUX. If you want to connect directly to the server, set the port explicitly in CSEnvironment.properties. 

public String getReconnect()

Returns the Sametime reconnect interval (in seconds), which specifies how often to attempt to reconnect to the Lotus Instant Messaging and Web Conferencing server after being disconnected, or not connected. The default.interval of 30 seconds is used when this value is not set. 

public String getTimeout()

Returns the Sametime timeout value (in seconds). The timeout is the maximum amount of time to wait for a response from the Lotus Instant Messaging and Web Conferencing server. Without a timeout setting, the internal default of 60 seconds is used. 

public String getNameFormat()

Returns the name format to use when resolving the WebSphere Portal authenticated user with the Lotus Instant Messaging and Web Conferencing server. 

public String getNameSeparator()

Returns the character to use to separate distinguished names. This character is used when resolving names with the Lotus Instant Messaging and Web Conferencing server, and also for the name used to log in to Lotus Instant Messaging from the browser. 

public String getUseLTPAToken()

Returns whether to use the LTPA token for logging into Lotus Instant Messaging from the browser. If the CS_SERVER_CUSTOM_CRED is enabled and the ssoTokenAttrib is specified, the SSO token is used instead of the LTPA token. By default an internal Sametime token is used. This option should be enabled only if your Lotus Instant Messaging server supports tokens produced by WebSphere Portal. 

public String getDefaultTimeout()

Returns the internal default Sametime timeout value (in seconds), which is the maximum amount of time to wait for a response from the Lotus Instant Messaging server. This value is used only if the timeout is not specified in the CSEnvironment.properties file. 

public int helperGetTimeout()

Returns the Sametime timeout value (in milliseconds as an integer), which is the maximum amount of time to wait for a response from the Lotus Instant Messaging server. This value is calculated using the timeout specified in the CSEnvironment.properties file, or the default timeout if not specified, and converted into the number of milliseconds as an integer. This value can then be directly used in Java calls that require a time length in that format. 

public String getDefaultReconnect()

Returns the internal default Sametime reconnect interval (in seconds), which is how often to attempt to reconnect to the Lotus Instant Messaging server after being disconnected, or not connected. This value is used only if the reconnect is not specified in the CSEnvironment.properties file. 

public int helperGetReconnect()

Returns the Sametime reconnect interval (in milliseconds as an integer), which is how often to attempt to reconnect to the Lotus Instant Messaging server after being disconnected, or not connected. 0 indicates that there should be no attempt to reconnect.

This value is calculated using the reconnect interval specified in the CSEnvironment.properties file, or the default reconnect interval if not specified, and converted into the number of milliseconds as an integer. This value can then be directly used in Java calls that require a time length in that format.

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

 

Tags examples

Collaborative Services include Java Server Page (JSP) tag language descriptors (TLDs) for custom Person and Menu tags that can be used with certain service objects. The tag libraries for Collaborative Services are installed on WebSphere Portal in the following location:

installation_drive:yourPortalServer\shared\app\web-inf\tld\people.tld

installation_drive:yourPortalServer\shared\app\web-inf\tld\menu.tld

Keep in mind that there is no need to copy or move the .tld files anywhere within your portal project; you need only refer to their location in your portal installation. You need a reference to them in the JSP for every portlet you deploy that uses them.

To use these tags within your JSP, add the following lines to your page: 

<%@taglib uri="/WEB-INF/tld/people.tld"prefix="peopleservice"%>

<%@taglib uri="/WEB-INF/tld/menu.tld"prefix="menu"%>

The following example illustrates how the person tag can be used to provide person link menus for named persons.

In this example, the bolded portions interact with Collaborative Services. The first two % statements are references to the Collaborative Services tag libraries. The last % statement uses the Collaborative Services person tag to display a person's name as an instant messaging link. 

<%@taglib uri="/WEB-INF/tld/people.tld" prefix="pa" %>



<%@taglib uri="/WEB-INF/tld/menu.tld"prefix="menu"%>


<%@taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<
Hello example
<h1>Collaborative Components Hello JSP</h1>
<BR>
<H2>Hello, <pa:person value="wpsadmin@acme.com" valueType="EMAIL" />!<H2>

 

Person tags

The Person (also sometimes known as People or People Awareness) tags provide contextual collaboration functionality related to a named person. Use them to generate a link menu of collaborative actions, such as sending e-mail to a named person. The tag library contains the tag language descriptors for the following tags:

  • person
  • peopleinit
  • peopleend

The Person tags generate HTML and require Java and JavaScript to be enabled on the client.

 

person

Displays person link menu items according to the Domino and Extended products that are installed and enabled in the portal environment

Added to a person's name string, the person tag generates the HTML that renders the Person menu that provides the following basic actions for collaborating with the named person:

  • Send E-mail

If Lotus Instant Messaging is installed and enabled to work with WebSphere Portal, then the person tag also provides online status for the person link and the following additional actions on the Person menu:

  • Chat
  • Add to Instant Contacts

The following example shows how to use the person tag: 

<pa:person value="CN=John Smith,OU=SALES,O=ACME" valueType="LDAPDN" displayName="John Smith" />

The displayName attribute is optional.

The supported types for valueType are:

 

peopleinit

Determines whether Lotus Instant Messaging and Web Conferencing is enabled to work with WebSphere Portal and generates the HTML and JavaScript for initializing Lotus Instant Messaging and Web Conferencing both. Establishes the server connections between WebSphere Portal and the Lotus Instant Messaging and Web Conferencing server, and provides automatic log-in to all servers.

Note The peopleinit tag is included in the HeadInclude.jsp of a collaborative portal; it is not for use inside any portlets.

 

peopleend

Finalizes the people functionality.

Note The peopleend tag is included in the PageEndInclude.jsp of a collaborative portal; it is not for use inside any portlets.

 

Menu tags

The Menu tags allow developers to add menus to their Collaborative Services applications. Menus may be associated with mouse events for icons, hrefs, and other UI elements on a portal page. Menu items and associated actions may be defined, and the Resource service may be used to internationalize the menu items. Action code (callback functions) is written in JavaScript.

The Person tags use the Menu tags to display person link menus next to a person's name.

The MenuService tag library contains the tag language descriptors for the following tags:

menuinit: Initializes the menu service.
menucontext: Allows a set of menus to be defined. May also hold a parameter specified by the menudisplay tag.
menu: Nested within a menucontext tag, defines a menu.
menuitem: Nested within a menu tag, defines a menu item, its name and associated Java Script callback function. The Resource service may be used here to internationalize menu items. It offers enable (black/gray) and show (show/hide) optional attributes.
menudisplay: Shows the menu. Through the use of paramName/paramValue attributes, sets a context variable for use in callback functions.

 

Logging

Collaborative Services use the WebSphere JRAS facility for logging to the WebSphere Administrative Console or to log files.

For Diagnostic Trace, specify the following value to log information related to the Collaborative Services: 

com.lotus.cs.cslog=all=enabled:com.lotus.ap.portlets.*=all=enabled:com.ibm.wkplc.*=all=enabled

The trace file can be found at this location: 

PORTAL_ROOT/log/trace.log

For more detailed information on logging, see Troubleshooting the Collaboration Center under See also.

 

See also

Home | Support | Terms of use | Feedback

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.