Creating a new portal: Part 4. Portal and component design

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Intermediate

Anthony (Joey) Bernal (abernal@us.ibm.com), Sr. Consulting IT Specialist, IBM
Scott Davis (scottdav@us.ibm.com), Senior IT Architect, IBM
Tim Hanis (hanistt@us.ibm.com), WebSphere Portal Development, IBM
Varadarajan Ramamoorthy (varad@us.ibm.com), Consulting IT Specialist, IBM Raleigh Lab

18 Jan 2006

You have come a long way in the analysis of how to implement your own portal project. In Part 1: Getting started and Part 2: Conducting a portal workshop in this series on Creating a new portal, you learned how to gather a decent set of requirements and to map them to portal capabilities. In Part 3: Estimating and tracking, you broke your project into components, and began the planning and estimation process. In this part, you begin to design your portal, based on best practices. You learn considerations for designing your portal and portlets, see options for content management, and you can download an example design template to document your design.

Introduction

There are a number of very good articles and documents that can help you design and build your portal using WebSphere Portal. Many are available in the developerWorks WebSphere Portal zone; a few are listed in the Resources section. This article complements these other resources; it discusses some of the topics that portal teams sometimes ignore or struggle with. For example, WebSphere Portal makes the creation of pages and navigation very easy; so why does everything seem to end up on the home page? This article provides guidance, from a project point of view, derived from our collective experience working on real and recent portal projects.

Back to top

Designing your portal

The portal design phase includes coming up with a navigation scheme, defining the portal layout, defining access control for the different resources, and determining how to address personalization needs. In previous articles we talked a lot about issues you might face as you refine the requirements, and why it is important to work through these questions early in the project. Now let's look at some of the best practices that use with our customers. You can apply many of these to your own portal project.

Designing navigation and layout

In your design sessions, you decide the navigation scheme that fits your content organization. You need to involve the business person that knows the hierarchy and content, and a usability person that is familiar with the organization's usability policies.

For example, some organizations have a policy of not allowing pop-up windows when clicking on a link, and some do allow them. You could create some wire-frame diagrams that show the navigation. Wire-frame diagrams show structure and navigation in an interface well before the details have been worked out. You draw windows from the interface using boxes and shapes to represent regions of functionality in the window.

Some of the technical considerations you need to consider at this stage include page size and the number of portlets on a page to provide optimum performance, given the types of the portlets on the page.

Deciding on themes and skins

To customize your portal site, you use the themes and skins. Themes provide the navigation and layout of portal; skins provide decoration around components such as portlets. WebSphere Portal ships with sample themes and skins that you could use as a basis for developing your own custom themes and skins. It is not mandatory to have any decoration around portlets. You can use a "No Skin" skin so that the portlet does not have any boxes around them. You can also set the skins on a per-portlet basis. You can use Rational Application Developer to edit the skins and themes.

WebSphere Portal comes with a rich tag library that you can use to create or modify themes. For example, tags are provided that will generate a URL for a single portal page or URLs for all your portal pages. Using these tags you can create customized portal navigations.

If it is not necessary to have a lot of skin customization. If you need to manage performance, then consider using some of the high performance skins that WebSphere Portal provides. The high performance skins are pre-generated Java code that's equivalent to the JSP skin code. You can use style sheets to customize the look and feel to some extent.

Some clients ask, "I want to provide the user with a link in the theme that will allow switching languages". You can do that with a tag library.

<%@ taglib uri="/WEB-INF/tld/portal.tld" prefix="wps" %> 
<a href="<wps:url command="ChangeLanguage" commandParam="de"/>"> Deutsch </a> 

This approach assumes that the portlets have the right translated text, and you are not using WebSphere Translation Server functionality, although you can configure the portal to use the translation server.

Can the portal have too many pages?

Having too many portal pages is not a good idea. Calculating the effective access control for all the pages while building the composition map for the user is an intensive operation for the portal engine. For this reason, limit the total number of pages which can be accessed by the users. Also, from usability point of view, if you have too many pages then users probably does not visit all of them. They might not even know there is a page with valuable information you want them to see. So, it is a good idea not to have too many pages. Working with a good Information Architect (discussed in earlier articles) can help you create a usable design that alleviates some of these issues.

OK, so your next question is, "How many is too many?" Unfortunately, there is no easy answer to that question, but empirically we think that when pages start numbering in the high dozens or hundreds, you probably have too many. Recent updates to the portal code to implement a lazy load of pages for a user have improved the performance of the portal. However, you also need to consider the administration of all these pages, as well as the performance to determine and display the navigation on a user's page layout.

When is a page too crowded?

One of the questions clients always ask is, "How many portlets can I have on a page?" We recommend you limit your pages to about 6 portlets displayed on any single page. This is not the magic number; it depends on a number of factors, including:

1. How much real estate do you have for the portlets?

   Some of the real estate on the page is taken up by the theme which includes the masthead, left navigation, footer, and, possibly, a right navigation area. If these elements take too much space, you have only a limited area for the portlets.

2. How much real estate each one of those portlets is going to take?

   Consider that a portlet can display minimal information for some users, and display a lot of information for others users, if it has personalization or customization built into it.

3. What is the response time of the portlets on a given page?

   This is another important factor in determining the number of portlets on a page. You might have five portlets on a page that takes three seconds total to load. However, if you add a sixth portlet that takes 15 seconds, that portlet could drag down the performance of the entire page. By default, portlets are rendered sequentially, but you could consider parallel portlet rendering if that helps with the total response time of the page.

4. What is the page size?

   Keep an eye on the page size. You can get the size of the page by loading the portal page into the browser and by saving the page source. Controlling page size is especially important for the user who is trying to access it on a slow, dial-up connection. If the page size is too big, the page will tend to load slowly, and you will hear performance complaints.

Make your landing (main) page lightweight, if possible, to enhance the user experience. Consider putting portlets that have a good response time on the first page so that it loads faster. After they land on the page they could click on other pages that have portlets that take more CPU cycles. Another thing to watch for is the size of images that the page contains. Also, if you are rendering pages for a PDA or other wireless devices, limit the page size to take into account the limited memory and connection speed of these devices.

Defining access control and permissions

Authentication in a portal is handled by WebSphere Application Server; authorization, or access control, is handled by WebSphere Portal through WebSphere Member Manager (WMM). Authorization determines whether a user is authorized to access the resources (such as pages, portlets) that he or she requests.

You could use external access control to control the authorization for the portal resources; however, there are some performance impacts, as well as some usability factors, you would need to consider. Our belief is that the portal administration interface is well-designed to enable you to manage permissions and resources within the portal. We call this fine-grained access control. Some external managers are designed with a more generic interface that might not lend itself well to managing the specific components within the portal, or allow for easy delegation of control. Course-grained access control, (that is, the permission to actually access the portal itself), can be managed from an external security manager very easily, and is a worthwhile goal.

Using customization and personalization

Typically, customization and personalization are used interchangeably. However, they are not the same in the portal world.

Customization refers to things that the user does to see the changes; that is, it is something the user decides. It is sort of like a pull model. For example, in a stock portlet, the user could click the Edit icon to customize the list of stocks he or she wishes to see. Or, a user could add additional portlets to a page--therefore, customizing the page.

Personalization refers to things that the portal does knowing who the user is and based on information saved about the user. This is sort of a push model. For example, if the user is a manager, the portal could show one set of content; if the user is a non-manager, then the portal shows a different set of content. You could accomplish this type of functionality using WebSphere Personalization, which is installed along with WebSphere Portal. The business user uses the rule editor to change the criteria for the content selection criteria.

There is a sort of looseness in these terms, however. For example, a user can click Edit to customize personalization data that is pushed to him or her by the Personalization engine.

In general, you can use the user attribute stored within the LDAP or LookAside database for personalization, and use the portlet data or portlet preference for customization.

Back to top

Adding Web content and document management

WebSphere Portal V5.1 includes Web content management functionality called IBM Workplace Web Content Management (IWWCM), and document management, called Portal Document Manager (PDM), integrated with the portal.

This section reviews the Web content and document management capabilities inside of WebSphere Portal V5.1, and some of the best practices involved with the design of each. For those that are interested, there is also a brief history of IWWCM up to its current 5.1.0.1 incarnation to help alleviate any confusion over where the product came from and how it has been named. If you are interested in the Domino version of the product, please refer to the product documentation or to one of the IBM Redbooks that covers the Domino version.

A brief history of IBM Workplace Web Content Management

The history of the current incarnation of IWWCM began in 1996 with a corporation named Aptrix, which was based in Sydney, Australia. Aptrix released a Domino-based version in 1998. By 2000, Aptrix had offices in London, Boston, and Los Angeles. In 2001, Aptrix expanded to EMEA including Germany. In 2001, Aptrix released a Java-based 1.0 version of the product.

IBM acquired Aptrix in July 2003, and originally named the product Lotus Workplace Content Developer. It continued evolving in functionality and in 2004 was renamed to Lotus Workplace Web Content Management (LWWCM). In the first quarter of 2005, the product was released under the name of IBM Workplace for Web Content Management (IWWCM). The current version is 2.5 for the standalone version of IWWCM and V5.1 for WebSphere Portal. A standalone version runs on Domino, and a Java edition runs under WebSphere Application Server, for non-portal based Web sites.

With each version, and with each name change, the product has continued to grow in functionality and market for the Java, WebSphere Portal, and Domino versions.

Designing your document and Web content management system

The following designs and best practices are intended to help you address some of the typical and not so typical design concerns that you need to know about document and Web content management before diving into the design phase. These guidelines and best practices are important because they can affect the remainder of the phases and activities in the solution lifecycle. Also, some of these practices are appropriate for any content management system, while some are specific to the Web content and document management capabilities of WebSphere Portal.

Back to business requirements

In many portal projects, the content and document management systems are often quickly reviewed or glossed over. This is usually because business stakeholders are primarily interested in the requirements for functionality that the portal will give to customers. A small fraction of the business stakeholders (those who need to use the Web content and document management systems) are interested in these requirements.

Our first design best practice is to ensure that the Web content management and document management requirements have not been overlooked during the Conducting a portal workshop or during any other requirements or use-case gathering sessions. Requirements must be collected, reviewed, refined, prioritized, and validated before engaging in the design of the Web content and/or document management systems.

One of the ways that we find useful in our projects is to have a meeting with all of the portal's stakeholders, and to provide mocked-up demonstrations of their Web site with and without content. (If they do not yet have an operational site, then we make one up as best we can at that time.) In the demonstration you do want to mock-up the functional areas of the Web-site to help the users understand which parts of the site are functional and which are content based.

Let's walk through an example of what this might look like. First, we show the customer their Web site with content (Figure 1).

Then, we show the customer their Web site without content (Figure 2).

Obviously, the home page of a site is often mostly content and will have a larger impact than some other pages; however, this method will surely make an impact on the importance of your Web content and document management systems. It is important for everyone to understand that content is equally important as functionality. (Although, some sites are more functionally-based than some that are more content-based).

Creating the information architecture

Depending upon your specific process, the information architecture work related to the content and document management systems could be done before or during the design phase. Removing the aspect of when your information architecture work occurs, it is a critical task that should not be overlooked.

In Getting started, we talked briefly about assessment of your organization's content and starting to take a content inventory. Now, we look at some of the issues around analyzing your content. As a best practice, perform the following tasks in an overall activity called Content Analysis, to ensure that the content on your portal is fully accounted:

1. Create content inventory.
   • Define taxonomy.
   • Identify metadata.
2. Create content governance models.
3. Analyze workflow.

Content analysis is a process by which you collect and analyze the content, as well as the content processes to determine the management and use of the content.

The first step is to perform a content inventory. This task involves collecting all of the content, including Web-content, documents, rich media, and any other content to be managed and to be delivered by the portal. While creating the inventory, you will discover that some content has already been created for other purposes, some existing content needs to be updated, and some content needs to be created. In most cases, you will find that you can track the content inventory in a spreadsheet, however in larger cases; you may require the use of a database to help.

Creating a content inventory is critical for even the smallest project. It will tell you a great deal about your content as well as the things you need to know about that content. For example, as you collect the content, you will probably also want to begin grouping or categorizing the content to help organize it. Grouping or categorizing the content will be of great assistance during the management of the content as well. Just as a library card catalog helps you to find books, or a scientific classification of organisms helps to organize information about those organism, categorizing your content will easily help you to find and manage your content.

Categorization of content is commonly referred to as the content taxonomy. For example, you may find that there is content for your organization's news. The news of your organization could be further sub-divided (classified) into press releases, technical product announcements, and business announcements. Your company or corporation might have an enterprise taxonomy which you can use to classify your content, and thus meet your company's overall goals.

While the construction of a taxonomy is out of the scope of this article, you can find many resources on the Web, in bookstores, or you can pay consultants to help you to build your content taxonomy. Classifying your content will lead to additional questions about including:

• How will the content managers find the content?
• How will the end users find the content?
• When will the content expire?

And so on. This additional data about the content is called the content's metadata.

Without a doubt, the metadata is an essential part of any content analysis activity. The purpose of the metadata is to provide additional data about the content item, which helps you to describe, use, and manage the content item. The most common example of metadata is information about a book.

A book is a content item, but associated with a book is additional data (metadata) such as the title, the publisher, the name(s) of the author(s), the publication date(s), the ISBN code, copyright date(s), and so on. The content you collect might include some of these same items of metadata as well as any custom data that you need for management of delivery of the content item. Some of these other metadata items might include:

• Content expiration date
• Original content author
• Last content update date/time
• Summary or abstract of the content
• Keywords

In fact, there is a committee that is trying to help standardize common metadata attributes called Dublin Core1. If you do a search on the Web for "metadata", you find hundreds of other groups that are undertaking similar efforts. Some of these groups are quite specific, such as the Federal Geographic Data Committee metadata standards, while others are more generic, such as the W3C Metadata Activity (superseded by the W3C Semantic Web Activity).

As you determine the metadata for each of your content item, you will find similarities among the content items, and then you can begin to group the metadata according to a hierarchy or against the taxonomy. In fact, this activity can take place along with creating the taxonomy to help guide its creation. To take this one step further, you will find that you need data for the metadata, that is, metadata about metadata. This additional data will be things such as the type of the metadata, the size of the metadata, and the kinds of values it accepts, and so on.

This can be a bit confusing, so let's take the example of the book a bit further. The book is our content item, and the metadata for the book included the book's title, the copyright date(s), the ISBN code, and so on. While we are identifying the metadata for a book, we also identify additional information about each metadata item. For example, we look at the book title, which is most likely a set of alphanumeric characters, including punctuation, with an undefined format. The copyright date, on the other hand, is most likely numeric with a specific format, such as MM-DD-YYYY or YYYY-MM-DD, where YYYY represents the year, MM represents the month, and DD represents the day of the month.

So, let's call the format of the metadata the type attribute of the metadata. The possible options for the type would be STRING, DATE, NUMBER, or whatever we might determine. You could break a type of NUMBER down into an INTEGER, a REAL number, or CURRENCY, if you choose to think of it that way.

Another metadata item could be the size or length of the metadata item. So, for the book title, the metadata item would be how long you would allow the title to be. For the copyright date, you might define metadata for the length of the date including hyphens. And, another metadata item could be the kinds of values you would accept, or if the metadata item is a multi-valued attribute.

So, as you march along identifying the metadata, you are also collecting additional data about the metadata. This metadata can usually be managed in a spreadsheet, but you might need to store it in a database if it gets too large or if more than one person needs to review it. For a very simple example of two metadata for metadata items, as shown in this table.

As you can tell, the content inventory is an important process of your overall portal project which should not be undertaken lightly. It is an intensive process to collect and analyze your content and how it will be used. It will include (and this list is not all comprehensive):

• A content identifier that uniquely identifies the content
• A description of the content item
• Where that content item can be found (in a database, a file system, or other)
• The filename for the content, if it is a file-based piece of content
• It's classification; that is, how in your taxonomy the content fits. (It could fit into more than one category depending upon its reusability)
• The metadata associated with the content
• How often it changes
• How or where that piece of content is used (such as in a portlet, or on one or more Web pages)

The content inventory is only one of the dimensions we want to analyze in our content. Another dimension to analyze is the content governance model, which is (at minimum) a description of:

• Who manages (creates, modifies, approves, publishes, removes, archives) which content items
• Where that content is managed
• Under what business events the content changes
• How the content affects other content items (which includes content dependencies among content items, as well as organizational business units)
• How the content management system gets changed, deployed, and how new features and functions are added

This information is very close to the information in the content inventory, and, in fact, sometimes all this information is contained in the content inventory. No matter where this information is placed, you need to determine the who, what, where, when, how, and why of the content. Deciding on a content governance model is important is to ensure that every content stakeholder is aware of how the content management system is managed, and knows who is responsible for managing which content items. This is a crucial part of any communication and management plan for content in order to eliminate overlapping managing of content, and to make sure the appropriate issues and processes are defined before the portal and content management systems "go-live". Therefore, making the decision to address the content governance model in the design phase (sooner if possible) increases the likelihood of your project being a success.

Teams typically establish a governing body at this time to make the ongoing operational decisions. This governing body is made up of different parts of the corporation who have a vested interest in the success of the implemented systems. Even though we have briefly described the content governance model here, there is much work to be done in this area that is beyond the scope of this article. If you need additional assistance with developing your governance model, you can find references on the Web, in books (try Amazon.com), or by hiring a competent consulting agency.

One of the outputs of the governance council is the identification of workflows that build up the workflow model, which encompasses the business processes (also identified by the governance council). For example, the governance council could decide that certain types of content (such as documents) need to be routed through the corporation's legal department before that content can be published. Or, it could decide to define an "emergency" workflow to allow the portal to be quickly updated in the event that inaccurate information has been published.

When the governance council establishes a business process, it could decide that the entire business process might or might not be used in the technical solution. To put this in another way, the technology that implements the content and document management systems may only partake in certain parts of the workflow models. This is an important concept because it affects the technical solution design in deciding how the workflows in your technical solution will be invoked, how they will need to work with other systems or human processes, and how they will be completed.

Technical best practices

The following items represent architectural and design decisions and best practices that need to be considered during the design of your Web content and document management systems—specifically if you use IWWCM and PDM. We only discuss these topics at a high-level; each of them is involved enough that each could be a separate article.

Authoring and delivery partitioning

The first topic to address is the IWWCM authoring environment. IWWCM provides the management and delivery of the content within its repository. Through its syndication and subscription model, it can replicate its content to other IWWCM repositories. Because of the syndication capability, you could offload the authoring and management functionality onto one or more separate servers. This drives the practice of partitioning the content authoring and management functions from the delivery functions, as seen in the simple example in Figure 3. You see why this is a good practice in a moment.

The example shown in Figure 3 does not take into account firewalls, staging servers, integration servers, clusters, high-availability, and any other infrastructure components you might need in your implementation. It is only meant to convey at a high-level the functional partitioning described above.

Figure 3 illustrates two possible configurations:

• Figure 3a shows a single server that contains both the IWWCM delivery and portal functions.
• Figure 3b shows the separation of the IWWCM delivery function from the portal server.

So, now that you know to separate the IWWCM content management and authoring environment from the IWWCM delivery environment, let's address why this is a good idea. The simplest and primary reason for separating the environments is because of separation of concerns. By separating the functions of the two servers, it guarantees that anything that the content managers are doing on the authoring system, such as time consuming events like pre-generating HTML content, will not affect the performance of the content delivery on the portal. Another advantage, from an operations perspective, is that the content authoring server can be held against a lower Service Level Agreement (SLA) than that of the delivery component, which can yield lower operating costs. Finally, another advantage is that upgrades or new functionality can be applied to the authoring environment without impacting the delivery environment's SLAs. There could be additional advantages in other areas, such as security, distributed systems, backup and restore operations, and much more than could be fully listed here.

Considering caching options

IWWCM offers multiple options for caching content for delivery, including:

• HTML pre-rendering
• Basic caching
• Advanced caching

Each caching option has its own benefits and drawbacks, which you should carefully consider during system analysis and design. We suggest that you prototype the different options to make sure that the option you choose will best meet your specific project's functional and non-functional requirements.

For example, the HTML pre-rendering option is best used for small, public, and fully static sites that can be pre-rendered and deployed to the edge of the network. The disadvantages of using HTML pre-rendering is that it is quite time consuming and only offers a "snapshot" of the content, taken at the time of pre-rendering. You also need to determine how to deploy the pre-rendered content from the authoring environment out to the delivery site (for example, using sftp, rcp, or another mechanism) where it can be consumed.

For a more detailed discussion of the benefits and drawbacks, please refer to the IBM Redbook IBM Workplace Web Content Management: Web Content Management for Portal 5.1 and IBM Workplace Web Content Management 2.5, SG24-6792-00 (see Resources).

Caching is not limited to content. There are many places where caching can be of value. See developerWorks articles about caching for more information. It is a good idea is to discuss and design caching options early in the project. Whether you are using out-of-the-box portlet caching, adaptive page caching, or building your own custom portlet filter cache, you need to get the right settings implemented early in your project lifecycle.

Syndication

Syndication is a powerful feature which IWWCM provides that enables moving content from one IWWCM server to another. However, you need to address these four common considerations before setting up syndication:

1. Part or all content can be published/subscribed
2. Syndication could be used to copy content to new instances of IWWCM
3. Syndication can only occur between the same IWWCM platforms
4. Infrastructure firewalls for syndication/subscription must be configured

In addressing the first consideration, you can decide between two options for syndicating or subscribing content to and from another server. Either all of the content, which includes the authoring templates, presentation, workflows, and so on can be published/subscribed, or only "live" content can be published/subscribed. At this point in time, you cannot use IWWCM to transfer only certain content types or certain content items in an exchange.

Regarding the second consideration, you should not use syndication for copying content, including content authoring templates, to new instances of IWWCM. Doing so is a lengthy process and will cause poor performance in cases with large amounts of content. Instead, the recommended approach is to copy the data from the source database to the new database. The mechanism by which you copy the data will be specific to your underlying data store. For a more detailed discussion, see the IBM Redbook named IBM Workplace Web Content Management: Web Content Management for Portal 5.1 and IBM Workplace Web Content Management 2.5, (SG24-6792-00), or the IWWCM InfoCenter.

Syndication/subscription should only occur between two similar IWWCM platforms. For example, you would not want to set up your IWWCM authoring environment using the Domino version and syndicate its content to an IWWCM for WebSphere Portal V5.1 on the delivery site or vice versa. Doing so will most likely not work; even if it somehow does, it is not a supported configuration of the software.

The final consideration for syndication is the deployment across firewalls. We have considered in the previous best practices how to separate the authoring environment from the integration, quality assurance (QA), and delivery environments. Typically, the authoring environment is in a safe zone; the content is syndicated across a firewall to a QA server in a pre-production zone; which then syndicates its content across another firewall to a delivery server in the production zone. Consider how much security you want to place around the syndication from each zone to zone. IWWCM uses the Information and Content Exchange (ICE) for syndication/subscription, which helps make addressing the firewall issues much easier. Because ICE binds to the HTTP POST and Response mechanisms, IWWCM's syndication feature should be able to operate within any such existing network infrastructures.

For more detailed information on the ICE protocol, see http://www.w3.org/TR/1998/NOTE-ice.

What the IWWCM API does not allow

With the WebSphere Portal 5.1.0.1 version of IWWCM, the application programming interface (API) offers capabilities for the portlet developer to access content within IWWCM. This capability enables a developer to extend the functionality of IWWCM to accomplish additional business requirements that may not be out-of-the box features. For example, the API enables the content developer to find content items in different ways (via name, type, path, category, workflow stage, and so on), search the content, and to create/delete/save content items, sites, site areas, and some library components.

While it is important to understand what capabilities are available to the developer, it is equally important to understand what is not available to the developer. Currently, the following capabilities are not available to the API developer. The API developer cannot create, update, or delete the following entities:

• Workflows
• Stages of a workflow
• Actions of a workflow
• Authoring templates
• Presentation templates
• Taxonomies
• Categories
• Syndicators
• Subscribers
• Most library components. Some library components can be created, updated, or deleted including File Resources, HTML components, and Image Library components.

Therefore, you can do some interesting things such as building a site framework based off of an XML file, batch importing content, or creating reports on content items. However, you cannot programmatically create, update, or delete some of the structural and technical assets of IWWCM.

Integrating IWWCM and PDM

While IWWCM and Portal Document Manager (PDM) can work together and share content, you need to factor these constraints into your design:

• The two workflow engines are separate and are not yet integrated
• IWWCM is required to run on the same server as PDM in order for the IWWCM PDM Component to be useful
• Assets changed in PDM are not automatically updated in IWWCM components and need to be manually refreshed

These constraints can be significant during the design phase of your project, and should not be overlooked.

IWWCM and PDM in an enterprise content management strategy

IWWCM and Portal Document Manager (PDM) are not intended to be a total software solution for enterprise content management; however, they do fit into an overall enterprise content management strategy.

According to the Association for Information and Image Management, enterprise content management includes the tools and technologies that capture, manage, store, preserve, and deliver content in support of business processes. In an enterprise content management solution, this includes tools and technologies with these capabilities: records management (compliance), document management, Web content management, digital asset management, digital rights management, knowledge management, taxonomy management, Computer Output to Laser Disk (COLD), Enterprise Report Management (ERM), Optical Character Recognition (OCR), forms processing, and much more.

IWWCM and PDM are each targeted to a specific segment of enterprise content management. IWWCM addresses Web content management, and PDM addresses "lite" document management. PDM is considered a lite document management solution because it lacks features of enterprise systems, such as virtual document composition and rendering capabilities that other full-featured systems, such as IBM DB2 Document Manager, include. Therefore, instead of considering IWWCM and PDM as your complete enterprise solution, consider how they can fit into your overall enterprise content management strategy.

Back to top

Designing your portlets

As discussed in Part 1: Getting started , you scope the portal to define the application function and content access that you intend to make available through your portal. By now, you have hopefully determined additional details about the content and application access by considering access control, user interaction model, as well as user and administrator profile configuration, customization, and personalization.

Of course, all application function and content access services are provided to the portal user in the form of portlets. These portlets could come with the WebSphere Portal product, or you could acquire them from a software vendor or from the online WebSphere Portal catalog and install them into your portal after its initial deployment. For any other needed portal function you might need to (or prefer to) develop the portlets.

This section discusses portlet design considerations for those portlets that you choose to develop. If you are already familiar with the programming interface for portlets and you have experience developing J2EE Web applications, then you know that portlet development is very similar to servlet development. Although there are a few differences, a background in Servlet/JSP development provides will really help you when you begin portlet development. See Resources for some resources which can help you write your first portlet.

But what about designing portlets? How well does experience in J2EE Web application design prepare us for Portlet design? In the next sections, we discuss the portlet programming model, application frameworks, and runtime portal services that are available to extend portlet functionality, so that you can see how these can influence portlet design. Finally, we make recommendations for good portlet design.

It's all about components

The portlets that make up the deployed portal configuration are your functional application components. Portlet applications are independently developed, packaged, and deployed. A portlet application is a deployable component, represented in a WAR file, and consists of one or more portlets.

Portlets typically provide a relatively focused user function or set of functions that can often be configured by a portal administrator and customized by the portal user. They participate in the look and feel of the portal, and they adhere to the portal access control mechanism. Portlets can work together in meaningful ways to provide a more complex user interaction model and to provide coordinated behavior in the portal. Portlets that cooperate in this fashion do not necessarily have to be designed, developed, or deployed together.

But portlets and portlet applications are not the complete component story within WebSphere Portal. Other component parts of the portal infrastructure include themes and skins; portal resources, such as pages, users, groups, and URL mappings; portlet services for remote content access, credential vault and property broker services; Web search; and document and content management. Portlets can also be managed as remote component services using Web Services for Remote Portlets (WSRP).

So as you consider the design of a portlet, keep in mind the context of the portlet application in which it will be deployed, and the WebSphere Portal framework and its set of services.

Using common design patterns

The Model-View-Controller (MVC) pattern is one of the most common design patterns to follow when designing a Web application. This pattern for application architecture defines model, view, and controller objects in order to separate presentation and business logic. WebSphere Portal uses this pattern extensively; the framework follows the MVC pattern, and the Portlet API encourages the development of portlets that follow this pattern as well. WebSphere Portal supports two popular Web development frameworks for portlet development that also use the MVC pattern: Struts and Java Server Faces (JSF).

If you choose to implement your portlet using the Portlet API, follow the MVC pattern Using JSPs to represent the view components, the portlet class to represent the controller, and Java beans to represent the business model. The controller acts as the intermediary between the view object and the model object, and conducts the response to user interactions with the portlet. Portlets developed using Struts and JSF will follow this pattern as well because the base framework implementation dictates the component separation.

In general, design patterns enable programmers to leverage well known and well-designed solutions to common application problems. In addition to the MVC pattern, well-designed portlets typically use a number of software patterns such as the Singleton or Factory patterns for object creation; the Adapter, Flyweight, or Decorator patterns for structural creation; or the State, Observer, or Command patterns for object behavior. We will not discuss these patterns in detail here. There are a number of very good resources available for that including the definitive Gang of Four Design Patterns book by Gamma, et al. (see Resources).

The key is that good portlet design will take advantage of good design patterns starting with the MVC pattern and likely to include many others.

Understanding the IBM Portlet API and JSR 168

WebSphere Portal supports several emerging standards. The Java Community Process (JCP) approved the technical specification for interoperability between portals and portlets in October of 2003. The Java Portlet Specification ( JSR 168) defines a set of APIs so that portlets can be written to be independent of the portal vendor on which they will execute. Continued work on this specification to improve upon the base set of spec requirements is underway.

WebSphere Portal supports two APIs for portlet development: the IBM Portlet API (hereafter called the legacy API) and the industry standard JSR 168. The legacy API is a proprietary API that was available with earlier versions of WebSphere Portal prior to the definition of the industry standard. When JSR 168 was defined, support was provided so that WebSphere Portal now supports both APIs.

We discuss both APIs in this article so that readers familiar with the legacy API can get a quick understanding of the standard API. The focus of ongoing WebSphere Portal and portal development tooling efforts are on the standard API; therefore, the recommendation is to use JSR 168 for all future portal development.

The legacy API extends the servlet API for many of the main interfaces (request, response, session). JSR 168 does not extend the servlet API; instead, it provides similar function by wrapping the base servlet container function. Both APIs restrict certain functions that are available with the servlet API to a subset that makes sense for portlets running in the context of a portal. For example, unlike servlets, portlets can not send errors or redirects as a response to a request. Only the portal can do that, because it controls the overall response page.

JSR 168 portlets can specify a scope for session data, to indicate whether session data should be unique to the portlet or can be shared with any other portlet or servlet deployed within the same WAR. Portlet filters, similar to servlet filters, are available in the legacy API but are not currently supported in JSR 168.

Unlike the legacy API, the JSR 168 permits portlets to write the customization data using the available API in any portlet mode. In the legacy API, updates to user customization data were limited to edit mode and updates to configuration data were limited to config mode. With JSR 168 API a portlet can modify this data in any mode.

JSR 168 specification does not provide inter-portlet communication, or messaging, capabilities. In WebSphere Portal, the legacy API provides Property Broker Service has been enhanced to provide this function for the standard API. See Resources for an article which describes how to use this extension.

One of the key differences between servlet execution and portlet execution is the two-phase execution process in WebSphere Portal. Before the portlets of the active page are rendered, an event phase takes place during which the portlets can process events (such as actions and portlet-to-portlet messages) and update their internal state. The portlet programming model assumes that state changes in portlets take place during the event phase and that the subsequent render phase only generates markup based on the current state of the portlets. However, the generated markup could still change between multiple portlet render invocations, even if the portlet state stays the same; for example, a portlet displays information retrieved from a backend system.

This design difference is one area that needs specific attention when migrating servlets to portlets. With potentially many portlets getting executed as a result of a single Web page request, developers need to follow good programming practices to make sure that portlets can re-render themselves correctly, even when there is no user interaction with that portlet.

At the start and end of the event phase, optional listener methods of portlets on the page are invoked. User initiated interaction, portlet messaging, and property broker activities can invoke event phase processing over many portlets on a page. Of course, not all portlets will get invoked during the event phase. Only when all event phase processing has completed will the render phase begin.

Legacy portlets can access the same request and response objects between action and rendering phases. Portlet developers sometimes put objects on the request during the action phase that the subsequent rendering phase would reference. JSR 168 provides unique instances of the request and response for each phase, so you cannot share parameters between phases using those objects; instead, use render parameters. Render parameters are unique to JSR 168 and are encoded in the URL itself, so that action and state are represented in the URL and can be bookmarked. Browsers can then return a portlet to a specific rendering state or view. The portlet developer must properly use render parameters to fully represent the portlet state.

See Resources for additional information about these two APIs.

Considering other frameworks

You could write portlets using either the legacy API or JSR 168; both APIs provide the necessary infrastructure and services needed to create complex portlets. However, even given a complete API, there are portlet development needs that could benefit from a standard application design and supporting infrastructure.

For example, most Web applications require controller code for page navigation, whether those applications involve portlets or servlets. Given the need for managing state transitions between pages (or portlet states) a framework such as Struts could be very helpful. You could also use Java Server Faces (JSF) to simplify the creation of user interfaces for Java Web applications, including portal applications. (These frameworks provide other functionality; these are just two examples of the value of a framework when you develop your portal application.)

In some cases a framework may not be considered essential. If the application is fairly simple and would not benefit substantially, then the additional complexity of using a framework might not be justified.

There are a couple points to keep in mind when considering frameworks such as either Struts or JSF for portlet development. These frameworks have been developed with the servlet programming model in mind. Because portlets closely relate to servlets, the frameworks typically translate to the portal environment very well. However, the framework is not typically aware of any WebSphere Portal-specific constructs. The goal of the WebSphere Portal implementation of JSF and Struts is to enable developers to write a portlet just like they would a servlet and have the resulting code execute in the portal environment. The portlet API, whether it is the legacy API or the JSR 168 API, tends to get masked when using these frameworks.

In general, when you use a framework, you have substantially less interaction with either portlet API, because of the additional abstraction layer . However, you often need to access the underlying API to perform mode and view changes, or for portlet messaging. The transition from the framework API (JSF or Struts) to the portlet API can be less than obvious, and lead to an odd mix of API usage in your code.

When deciding whether to use a development framework and, if so, which one to use, consider:

• The complexity of the portlet application being developed
• The skill set of the development team
• The cost in project development time needed to introduce a new development technology and adopt best practices needed to ensure a successful project
• The relative maturity of the frameworks and associated tooling
• The strengths and weaknesses of the alternatives relative to the needs of the portlet application

Struts

Struts is a Jakarta open source project that provides a servlet-based Web application framework based on the MVC pattern. Struts provides a controller function that is customizable through struts-configuration files and extended through Struts Action classes. You construct views through JSPs using a set of Struts-based custom tag libraries and a close integration with application-specific ActionForm beans.

The goal of supporting Struts in WebSphere Portal is to fully support the application framework so that existing Struts applications can run on WebSphere Portal with little or no change. The Struts Portlet Framework (in WebSphere Portal) enables a Struts application to be packaged and executed as a portlet.

The Struts Portlet Framework creates an execution environment that where the Struts application runs without being directly exposed to the portlet API. The framework also provides a development extension so that Struts portlet developers have full access to the portal environment.

Java Server Faces (JSF)

Java Server Faces (JSF) is also based on the MVC patter for building Web applications. JSF simplifies development of sophisticated user interfaces by defining a user interface component model that is mapped to request processing events.

JSF is a framework standard (JSR 127) with implementations available from IBM and other vendors. It defines a set of UI components which you access through JSP custom tags which are a superset of the standard HTML form elements. It also defines an API so that developers can extend the JSF UI component set.

You can associate validators with the UI components to validate user input, and event handlers to support user actions which can execute server-side application code or can change the state of other components. These event handlers manage state transitions and page navigation. A faces-config configuration file defines navigational transitions as well as the bean classes. The UI component rendering is implemented separately from the component itself so that different renderers can render the same component UI differently (HTML or WML, for example).

The UI components use Java beans to access application data and connect client-side events to server-side event handlers. UI events typically result in a form-based request back to the server through an encoded URI (generated in the portlet context in the case of JSF running in the portal environment).

Using portlet services and common components

You can use portlet services to provide common function that is registered to WebSphere Portal and made available to portlets. The portlet service framework is extensible so that vendors and customers can develop additional services. Then, portlet developers have a consistent method for finding and accessing common services. Good portlet design will take advantage of these defined services and, when necessary, develop and package local common function as a portlet service to be reused throughout the portal.

WebSphere Portal provides several portlet services.

• ContentAccessService enables portlets to access remote systems or to get content from a given URL and return the InputStream.
• CredentialVaultService helps maintain a single sign-on experience for the portal when it becomes necessary to access backend systems that require authentication. Any portlet that needs to access these systems can use CredentialVaultService to retrieve stored user credentials and authenticate on behalf of the portal user.
• PumaHome service is new with Fixpack 1 for WebSphere Portal 5.1 (that is, with WebSphere Portal 5.1.0.1) and provides access to portal user profile information. You can retrieve, update, create, or delete portal user and group information using PumaHome.
• Property Broker enables brokered cooperation for independently-developed portlets. Cooperating portlets exchange information, and portlets can change state as a result of that data exchange. Portlets register their intent to co-operate with a broker, which facilitates the exchanges at runtime. Registration can be done through WSDL files or can be performed programmatically by the portlet. PropertyBrokerService assists with the programmatic registration of brokered properties, and with other functions that can be programmatically controlled, such as activating and deactivating actions.

Portlet design suggestions

Good portlet design follows from an understanding of the WebSphere Portal execution framework and portlet processing. Well-designed portlets should take advantage of the components and services available to them from the WebSphere Portal environment in order to help ensure good design.

Here are some considerations when designing your portlets.

1. Think of portlets in terms of application components that are built either independently or cooperatively and that collectively deliver portal function.
2. Use application development frameworks (Struts or JSF) as appropriate to reduce development effort and to facilitate good design.
3. When coding to the portlet API directly (either legacy API or JSR 168) use a good MVC design approach.
4. Use portlet services instead of developing similar functions. When a service you need is not available, consider writing it as a portlet service that can be reused in a consistent way by other portlet applications.
5. Use Toolkit services as appropriate to avoid custom code to solve problems that are already addressed. For example, use JSP tag libraries such as JSTL and the WebSphere Portal tag library; use available JSF UI components or render kits.
6. Use software design patterns to address common application problems in a way that has proven effective with good design characteristics.

Back to top

Using a component design template

The sample design template in the download consists of nine sections (described below). The first and last sections relate the component to the overall portal project. Very early in the portal project, after the tasks and components have been identified, the team leader creates a set of design documents and assigns them to the component owners. These component owners use the design documents to document component-level requirements, to define the component architecture, to outline test cases, to mock up the UI of the components, and so on. Over time their documents evolve to contain both the high-level and detailed design for their components.

This template is a starting point; please, change it to fit your needs. The important point is to have a design document associated with each component, portlet, service, or other major part of your portal project!

Introduction section

The first section provides a basic introduction to the component or set of components. Any reader of the document (such as managers, team members, coders, testers, marketing folks, related project team members) should be able to easily grasp the purpose of the component, and what it does, without getting too deep into functionality, requirements, or technical details. Think of it as an executive summary.

You could consider adding some tracking information such as:

• Current and previous authors or owners of the document
• Changes or updates that have occurred
• Signoff or review dates by project leadership or customer representatives

Requirements

One more time: Requirements are important. Whether you document them as use cases or user stories, think of requirements as the customer speaking to the team. They state how the function provided by the component should work, and what value the component provides to the overall portal. So, it just makes sense that the requirements which drive a component are documented with its design.

If requirements are gathered before the design document is created, they might be stored in separate documents which are created by the business analysts' team. Rather then linking or referencing another document, we recommend you copy and paste them from the original document into your component design document so that all the information for the component is in a single location. You need to have requirements and any use cases in the your document along with the related user interface design, test scenarios, and other sections so that the developer can easily reference them.

Component Architecture

Use this section to outline the overall architecture of the component, in a format which is appropriate for your project. Here are some examples of what you might include:

• Diagrams of major components of the subsystem and how they interact
• Dependency diagrams showing how your component depends upon APIs within WebSphere Application Server, services from other components, a database, or any LDAP interaction
• High-level sequence diagrams or analysis models
• Context or component diagrams to outline how the component interacts with other components and with the overall system

Detailed Design

For technical specialists, this is the heart of the template. A good detailed design describes how the component(s) are implemented, using class, sequence, and component interaction diagrams. Of course, what you decide to include depends upon the type of component that you are designing and any organization standards you might have for design documentation.

Data Model

Many components have their own database tables or rely on an existing database schema. This section describes the schema and data that the component uses. You could include:

• Logical or physical data models
• Any related data loads or transformations that take place outside of your components. For example, if an ETL process needs to take place in order to manage or merge data, outline this process here
• If any business or object models are created or used for this component, then describe d here also. These could be project-created or industry standards which your project uses

User Interface and Interaction Model

User interface documentation is most often provided by an information architect, human factors engineer, or graphic designer. You might hand off the component design document to the person(s) in that role so that he or she can add the models that describe the user flow. The developers use these models to implement the component.

The reality is that some projects do not have any information architects, human factors engineer, or graphics designers; so, the developers must create the user interface. Whoever ends up creating the portlet mockups should place them in this section of the design document. If you don't have any mockups, then insert a screen shot of the final interface in this section with some descriptive text.

However, user interface design really should not be the developers' responsibility. In very simple cases maybe, but designing a user interface requires a different skill set then implementing the functionality behind the interface. Your team should engage the services of an information architect or user interface designer who can interact with the client to understand, model the task flow, and then design the user interface.

Test Specifications

In the past, testing has often been one of the most overlooked phases in a project. We include this section in the design document to help enforce some testing discipline within the project. With all the different types of testing such as unit, functional, integration, black box, and white box testing, and so on, it can get very confusing about what type of testing should be done, and when. In most projects, unit testing has been a line item in the plan; however, enforcing the elusive unit test has been weak at best. With the advent of agile methodologies, unit testing is becoming a real possibility for many projects.

Tests run by the developer during the development process are usually called unit tests, and they help to insure that the code is correct. Integration and functional testing take place when different components are brought together and are ready to be deployed. (It's mostly a matter of discipline in deciding how those tests are performed, and when they are scheduled.)

Functional testing is very important in the lifecycle of a portal and portal components; regression testing is required when changes are made to the code. In future articles we will focus on performance testing. It is very important for the development team to work closely with the quality assurance (QA) or testing team to insure a smooth transition between development stages, and to promote good communication about potential issues. Throwing code components over the wall to the testers is a sure way to invite problems, rather, have testers and developers sit side-by-side at times so they can go through the scripts. The developers will learn about issues they hadn't thought of, and this practice will help the team members learn to communicate with each other.

If your project has a lot of testing discipline, then this section should be easy. At a minimum, have the developer fill out this section with a simple set of hand-written tests that he or she will go through to make sure the component is working as described in the requirements. These test cases can be as simple as a set of input and result values that can be fed into the component when necessary. Include failure cases as well as passing criteria. This documentation not only insures that the developer understands the component at a deeper level, but also provides an initial set of working tests for future teams to understand and evaluate the component.

Deployment Guidelines

Even the simplest of components has steps that need to be taken during the deployment and configuration process. Use this section to describe how to create data sources, configure parameters, and define the order of deployment. Even though the developer understands this process intuitively, it can get lost in the hand off between development and operations when a project goes into production. So, use this section is intended to help you capture this knowledge over the life of the project.

During a hot and heavy project, developers often scream that they don't have time to keep documentation updated. At a minimum, developers need to keep some basic information about the deployment of the component. The development team leader or the build and deployment manager need to ensure that developers complete the required documentation with the right degree of detail required by the team. This section provides a place to make capturing that information easier for the team; however enforcement cannot be scripted or assumed on any project.

Assumptions, Issues, and Dependencies

This section provides team members a single location to document issues and concerns about a component. The goal is to capture issues in real time, as they arise. Many teams send emails about issues. The problem with this approach is that you'd have to search through a lot of emails to gather all the different issues that are surfaced. Dependencies are another item to list in this section. For example, many portlets and components have back-end dependencies that need to be documented for future reference.

Back to top

Conclusion

In this article, we covered some design points to consider when designing your portal. We focused on design best practices in the main portal areas. A few of these topics can be started in the Portal Workshop and continued as you progress through the design phase of your project. We could not cover everything that could be of interest to a particular application; WebSphere Portal is so full-featured that covering every possible aspect of design would take several books! We believe that the collection we have discussed provides a good starting point that you can use to have productive design discussions and a successful portal implementation.

Finally we have included a component design template that you can download and use to document your design. Alternatively, you can incorporate sections of it into your own design documentation.

Back to top

Download

Description	Name	Size	Download method
Sample design template	Component_Design.zip	12 KB	FTP|HTTP

	Information about download methods

Resources

• developerWorks WebSphere Portal zone: Find more resources to help you develop portals and portlets.
  
  
• Access Control: Product documentation description for using WebSphere Portal's access control feature.
  
  
• Architecting on demand solutions, Part 14: Build portlets using Rational Software Architect State Oriented Portlet Patterns
  
  
• Best practices: Developing portlets using JSR 168 and WebSphere Portal
  
  
• Comparing the JSR 168 Java Portlet Specification with the IBM Portlet API
  
  
• developerWorks WebSphere Portal zone: Provides a wide variety of technical resources to help you develop portals and portlets.
  
  
• Developing JSR 168 compliant cooperative portlets: Describes how to develop JSR 168-compliant portlets, which can exploit the cooperative portlets paradigm in IBM WebSphere Portal V5.1.
  
  
• Design Patterns: Elements of Reusable Object-Oriented Software . by Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides. ISBN: 0201633612. Addison-Wesley Professional. 1st edition, 1995.
  
  
• Hello World, the simplest portlet for WebSphere Portal V5: Part 1. Creating and deploying. Step-by-step instructions for creating your first portlet.
  
  
• IBM Redbook: IBM Workplace Web Content Management for Portal 5.1 and IBM Workplace Web Content Management 2.5, SG24-6792-00.
  
  
• IBM Workplace Web Content Management Information Center
  
  
• Performance considerations for custom portal code
  
  
• Portlet development guide
  
  
• WebSphere Portal production documentation: Provides access to all current product documentation including InfoCenters, release notes, and readmes for all releases of WebSphere Portal.
  
  
• WebSphere Portal in Action: Read Joey Bernal's blog on developerWorks.
  
  
• WebSphere Portal V5.1 Security Overview

About the authors

		Anthony (Joey) Bernal is a Sr. Consulting IT Specialist with IBM Software Services for Lotus (ISSL). Having worked with WebSphere Portal since the initial 1.1release, he has an extensive background in the design and development of portal applications, and has led the implementation of many projects using IBM WebSphere Portal. Joey is an accomplished author, speaker, and instructor in various topics concerning WebSphere Portal and related technologies. He is a co-author of the book Programming Portlets.

		Scott Davis is a Senior IT Architect with the Portals, Content Management, and e-Commerce practice of IBM Global Services. He has been architecting and developing solutions for over 13 years, with the last 5 focused on Portals and Content Management systems. He holds a computer science degree from the University of Colorado at Boulder.

		Tim Hanis is a member of the IBM Software Services for Lotus, Portal Technology Team. He has extensive experience with WebSphere Application Server and Websphere Portal. He has recently returned to work directly with customers after spending two years in WebSphere Portal Development. He co-authored Mastering WebSphere Portal, available from Wiley publishing.

		Varad Ramamoorthy is a Consulting IT Specialist with IBM Software Services for Lotus. He has worked with WebSphere Portal since its initial release, and he uses his expertise to help solve customer issues. He has published numerous articles on WebSphere Portal and related technologies.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top