Wdk Portlets

WDK Portlets Michael Roth

Date 6/19/2007

Copyright © 2006-2007 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.

WDK Portlets

2

Table of Contents Overview.............................................................................................................. 4 An Introduction to Portals and Portlets ........................................................................................ 4 What is JSR 168? ........................................................................................................................ 4 WDK for Portlets .......................................................................................................................... 5

Working with WDK for Portlets.......................................................................... 5 Out of the Box Portlets................................................................................................................. 5 Creating a Portlet ......................................................................................................................... 5 Refreshing Data in a Portlet ..................................................................................................... 6 Adding Help .............................................................................................................................. 6 Authentication .............................................................................................................................. 6 Manual (Docbase) Authentication / Saved Credentials Authentication.................................... 6 User Principal Authentication ................................................................................................... 6 Ticketed Login .......................................................................................................................... 7 Single Sign On (SSO) .............................................................................................................. 7 Skip Authentication................................................................................................................... 7

Integrating with Various Portal Servers............................................................ 7 Troubleshooting and Miscellaneous Issues..................................................... 8 Tracing ......................................................................................................................................... 8 Support Issues ............................................................................ Error! Bookmark not defined. Specifying Component Options in a URL................................................................................. 8

Additional Resources ......................................................................................... 9

WDK Portlets

3

Overview An Introduction to Portals and Portlets A portal is a way to overcome the limitation of having to access a specific web site or web application one at a time. It allows for developers to present multiple sources of information and applications from a single web location to the user in a simple format unified format. For example, consider the image below

Here we can see several different sources of information/applications being presented to the user, including an RSS Feed, stock quotes and a search widget to search Yahoo! The user is presented a single point of access for a number of different applications – each which is presented in its own windows or Portlet. A Portlet is a self contained pluggable component which generates HTML fragments which are then displayed in the portal server.

What is JSR 168? The Sun Java Specification Request (JSR) 168 is a standard to help promote portability of portlets between various portal server implementations. This is becoming increasingly important given the increasing acceptance of the Web Services for Remote Portals (WSRP) protocol which allows for access to portlet funtionalities using Web Services. The specification defines a set of APIs for portlets and standardizes the following: • Portlet interface • Portlet configuration • Preferences • User information retrieval (user information persistence is portal-specific)

WDK Portlets

4

WDK for Portlets WDK for Portlets is an extension of the exiting WDK and Webcomponent framework where specific support for JSR 168 containers (portal servers) has been added. The eventual goal is to be able to deploy WDK for Portlets in any JSR 168 container, including ones that are not supported by the installer at the moment such as Plumtree and JBoss. WDK for Portlets should provide the same functionality as the WDK product does and will allow components developer for Webtop or WDK to be deployed as portlets with a minimal amount of additional work. In addition, support for portal specific environments is added so that themes, user preferences and authentication is accessible in a transparent manner. Components which are to be deployed as portlets will have a corresponding .portlet file (under /portlets in the application) as well as a entry in the file /WEB-INF/portlets.xml as per the JSR 168 sepecification.

Working with WDK for Portlets Out of the Box Portlets WDK for Portlets provide a number of components that have been wrapped as portlets out of the box which can be used immediately in a portal application. These portlets are: • • • • • • • • • • •

Cabinets Categories Home Cabinet Inbox Login My Rooms Recent Files Search Advanced Search Subscriptions Workflows

The Login portlet will normally not be used directly when deploying a portal but is used by the other portlets to authenticate the user to the content server if needed (see below).

Creating a Portlet Documentum portlets use a single portlet class, com.documentum.web.env.jsr168.DocumentumComponent which extends javax.portlet.GenericPortlet. This class will launch the component that you specify for the portlet as the value of the view mode in portlet.xml and will also provide access to preferences and help for the component using the preferences and help mode values in portlet.xml. When defining a portlet it is important to note that all of the WDK components will define the above class the implementation class. No further portlet specific coding should be needed in order to have a component rendered as a portlet. In order to have the component render properly in a portlet environment as well as in a standard WDK/Webtop one, the standard , and

tags should be replaced with the appropriate dmf: JSP tags. These tags are context aware and will render themselves appropriately to the environment (e.g. in a portlet environment the tag will not render a tag).

WDK Portlets

5

Refreshing Data in a Portlet If it is required to refresh the data presented in the portlet, the underlying WDK component should implement the following method: public void onRefreshData() This method should be called via a link or button on the component JSP page. Be sure to call super.onRefershData(); from within your implementation.

Adding Help You can amend the help that is installed by WDK for Portlets in your portal application and add new help files for your custom portlet components. To add help for your portlet, add a value for the help mode preference. For example, for the portlet DocumentumDrilldown, the help mode is set to the value cabinets: <preference> help cabinets This help value maps to an HTML file that must be located in /app_root_directory/language_code/cabinets, for example, /PORTAL_APP_HOME/help/en/DocumentumPortlets/cabinets/default.htm.

Authentication WDK for Portlets uses the same authentication mechanism that is used by WDK and Webtop. All calls to authentication are handled by the AuthenticationService class which will invoke the specified authentication schemes. For more information on configuring this please refer to the WDK Developer’s Guide. Specific issues with the authentication schemes and portlets are discussed below.

Manual (Docbase) Authentication / Saved Credentials Authentication For a default deployment, the first time a user accesses the portlets the WDK portlet will be rendered with a link prompting the user to log in. On click the link the portlet will render with the Login component (the DocbaseLoginAuthenticationScheme) and the user will enter their username, password and select the repository they wish to use. Prior to being able to log in however the user will need to authenticate themselves to the portal server (please see the WDK Portlets Installation guide for details on how to accomplish this with WebSphere and BEA)/ Once the user has been authenticated, they will not need to authenticate again as their login information will be stored in the portals user preferences store for the duration of their portal session. During the login procedure, the user has the option of storing the login credentials, in which case for the next portal session these stored credentials (from a cookie) will be used to authenticate the user automatically.

User Principal Authentication J2EE Principal Authentication is configured the same way as it is for other WDK applications. For details please refer to the WDK Developer’s Guide on how to configure this.

WDK Portlets

6

There are two additional steps that need to be done to ensure that J2EE authentication is working for the portlets: 1.

The file /WEBINF/classes/com/documentum/web/portal_server/portal_serverEnviron ment.properties file will need to be edited (where portal_server is the vendor of portal being using). The following value will need to be added to this file: AuthenticationMode=trusted

2.

Though it is not mentioned in the WDK Developer’s Guide at the time of this writing, the value for ..<docbase> will need to be set to specify the default repository to authenticate users against.

Using J2EE authentication, the user will have to authenticate themselves to the portal server. The means by which this is done is portal server and implementation specific and should work as long as the user name which the portal server stores matches that of the user in the repository. The passwords do not have to match as the trusted authenticator credentials are used to create a session on behalf of the user.

Ticketed Login It is possible to refer a user to a portlet using a login ticket from another WDK/DFC application. The details of the URL which needs to be used can be found in the WDK Portlets Developer’s Guide.

Single Sign On (SSO) SSO (Netegrity) is currently not supported with WDK for portlets though should work as described in the WDK Developer’s Guide.

Skip Authentication By default, whenever a WDK component (portlet) is invoked and there is not a valid session with the repository, the user will need to be authenticated. If there is a custom component for which a session with the repository is not needed, it is possible to configure it so that authentication is skipped. This can be configured in the resource file Environment.properties, which is located in the directory /WEBINF/classes/com/documentum/web/formext. To add a component that skips authentication, add a line with the key value non_docbase_component. In the following example, the custom component bluesheet does not require a repository session: non_docbase_component.6=bluesheet

Integrating with Various Portal Servers If the portal server which WDK for Portlets is being deployed on is one of the supported ones, then nothing further is needed to get it working. If, however, deployment is on an uncertified (by EMC|Documentum) JSR168 environment then it will be necessary to provide some additional support. This support takes the form of extending (sub-classing) the Jsr168Environment class for the portal server in question. This extension should provide access for writing user preferences using the portal server API. If this is a non-JSR168 environment, the in addition to the above the custom class will also need to provide the methods to read the user preferences as well as write them. Details on how this can be accomplished with regards to using the environment class as well as registering the custom environment class can be found in the WDK Portlets Developers Guide.

WDK Portlets

7

Troubleshooting and Miscellaneous Issues Tracing In addition to the standard WDK, DFC and DMCL traces which are available, there are some additional WDK tracing options that are of specific importance for WDK for Portlets. These are enabled via the standard WDK trace mechanisms.

Trace Flag

Function

DISPATCHER

Traces the Component Dispatcher. The dispatcher is an internal Documentum tool that does not have any public tracing capabilities.

ENVIRONMENT

Traces current environment, properties file, environment class, environment creation, and environment-specific calls.

HTML_PAGE_PROCESSOR

Traces tags rewritten for portlets.

HOOK

Traces environment lookup, user name, and repository.

PUBLISHED_CONTENT

Web Publisher portlet specific flag used to trace searching in the Published Content portlet. If this flag is turned on it displays an error for invalid entries in the XML configuration file for example, invalid attribute name and invalid object type name. This flags helps determine why containers are not displaying in the portlet, and displays the DQL used to search the portlet for each container.

SEARCH

Web Publisher portlet specific flag used to trace searching in the Published Content and Submit Content portlets. If this flag is turned on it displays an error for invalid entries in the XML configuration file in which the search component is used for example, invalid object type name, or invalid attribute name.

VIRTUALJS

Traces HTTP request and response including response status 304 and 200.

WDK_API_TRACE

Traces the local path for multi-part HTML file upload.

Support Issues Specifying Component Options in a URL In a standard WDK application, a component can take parameters from the URL to help configure the default operation. This is not an option in WDK Portlets as the components/portlets are not URL addressable (i.e. you cannot directly access a portly via a URL). The parameters for the component can be exposed as a user preference in tools such as BEA Workshop, however these preferences will have a USER scope and will be set on a per user basis. Alternately, if it is required that the value be set globally from an application such as the BEA Portal Administrator, this will not work as the scope assigned to these preferences is that of PORTLET - which relates to a specific instance of the portlet and not a general preference.

WDK Portlets

8

In both of the above cases (URL addressability and the preference scoping) this is not considered a bug as this is conforms to the JSR 168 specification for portals. If there is a requirement to set a global preference for a WDK portlet it is possible to customize the component to have this. In the component definition XML file, a new node can be added to the file with the parameter name and value. This should enforce a default value for this parameter. e.g. if in the Drilldown Portlet it is required that it defaults to a specific folder, the following entry can be added to the drilldown_component.xml file: /temp/my_folder

Additional Resources • • •

Web Development Kit for Portlets Development Guide Web Development Kit and Client Applications Development Guide JSR 168 Specification - http://www.jcp.org/en/jsr/detail?id=168

WDK Portlets

9

Appendix A – Questionnaire 1. 2. 3. 4. 5. 6. 7. 8. 9.

What is JSR-168? What does it define? What portlets are provided out of the box? What class is used for all Documentum portlets? How do you turn an existing component into a portlet? What are the different authentication mechanisms available for portlets? How does Manual Authentication work? How do you configure J2EE authentication for portlets? How to do you configure a portlet to not use authentication? What customization is needed to support additional JSR-168 portal servers? For non JSR-168 servers? 10. What tracing options are available for troubleshooting?

WDK Portlets

10

About EMC EMC Corporation (NYSE: EMC) is the world leader in information storage systems, software, networks, and services, providing automated networked storage solutions to help organizations get the maximum value from their information, at the lowest total cost, across every point in the information lifecycle. Information about EMC’s products and services can be found at www.EMC.com About Documentum Software from EMC Documentum software from EMC Corporation includes enterprise content management solutions that enable organizations to unite teams, content, and associated business processes. With a single platform, EMC Documentum software enables people to collaboratively create, manage, deliver, and archive the content that drives business operations, from documents and discussions to e-mail, Web pages, records, and rich media. The Documentum enterprise content management platform makes it possible for companies to distribute all of this content in multiple languages, across internal and external systems, applications, and user communities. As a result of deploying Documentum, thousands of the world’s most successful organizations are harnessing corporate knowledge, accelerating time to market, increasing customer satisfaction, enhancing supply chain efficiencies, reducing operating costs, and improving their overall competitive advantage. For more information about Documentum enterprise content management, visit www.emc.com/documentum or call 800.607.9546 (outside the U.S.: +1.925.600.5802).

WDK Portlets

11