- 1 -

IBM® WebSphere ® Portal Page Derivation Concepts Jan Engehausen, WebSphere Portal Developer Christian Krafft, WebSphere Portal Developer Michael Menze, WebSphere Portal Performance Analyst IBM Development Lab, Boeblingen, Germany Pages are one cornerstone of any IBM® WebSphere® Portal installation, in which content and collaboration elements are placed as portlets into pages, with different page setup possibilities. Learn about the different page setup options, with special focus on the concept of page specialization and customization, also known as page derivation. Learn how to administer and operate these pages, using the administrative portlets, the scripting client, and XML Access in WebSphere Portal version 5.1. The user experience for derived pages is also explained in detail, and use cases and hints and tips for applying page derivation are presented. This document is applicable to all WebSphere Portal versions 5.x, unless otherwise noted.

- 2 -

Table of Contents Introduction........................................................................................................................................... 3

Use Cases.......................................................................................................................................... 3 Technical Definitions............................................................................................................................ 4 Administering Derived Pages ............................................................................................................... 7

WebSphere Portal Administrative Portlets ....................................................................................... 7 WebSphere Portal Scripting Client................................................................................................. 11 XML Access ................................................................................................................................... 12

Experiencing Derived Pages............................................................................................................... 12 Visibility of Pages........................................................................................................................... 12

Use Cases and Hints & Tips ............................................................................................................... 17 Delegated Administration ............................................................................................................... 17 Customization ................................................................................................................................. 19 Hints & Tips.................................................................................................................................... 19

Summary............................................................................................................................................. 20 Download............................................................................................................................................ 20 Resources............................................................................................................................................ 20

- 3 -

Introduction IBM® WebSphere® Portal provides a single point of access to the applications its users need every day. For example, a company establishing an “Employee Portal” can provide access to (1) all business-critical applications like mail and calendar, (2) backend systems from vendors such as SAP or Siebel, and (3) content like company news, project documentation, or content management systems via WebSphere Portal. Users can log into the system using a Web browser, work with the provided applications, and navigate through the portal installation as with every other Web site. The applications are encapsulated in so-called portlets on each Web site page. WebSphere Portal provides the framework for managing access control to the portal and its resources like pages and portlets, and assumes the task of rendering the portal pages. Customers can easily enhance WebSphere Portal by providing their own portlets, themes, and skins and by setting up a custom content hierarchy. Pages are one fundamental concept of WebSphere Portal, with content and collaboration elements placed within portlets onto pages. This document provides an overview of the page layout options available for WebSphere Portal and discusses page derivation. The WebSphere Portal Information Center (linked below in the Resources section) describes page elements and derivation. Here, we attempt to enrich this information with detailed walk-throughs of administrative actions, user experience, and use cases. This document is directed to a broad readership. WebSphere Portal administrators will find it helpful when setting up page derivation hierarchies and understanding the resulting user experience in the portal. WebSphere Portal architects may find information on how to use page derivation to achieve a desired behavior with regard to delivering responsibility delegation as required by the portal and content governance. Finally, WebSphere Portal users will gain a deeper understand of what the portal actually does when they work with their customized pages.

Use Cases Before delving into the technical details, let’s briefly discuss the benefits and use cases that are covered here: • Delegated Administration -- With large portal installations, administration might be delegated to

multiple teams working with different scopes and responsibilities. It is possible to delegate the administration of pages or parts of pages to sub-administrators. IBM WebSphere Portal introduces the notion of page specialization to facilitate this idea.

• Customization -- Delegated administration modes enable administrators to create portal page

definitions that are close to the end user’s productivity needs. However, the ultimate knowledge of the most efficient way of doing work is with the people actually doing this work every day. So beyond delegated administration, end users can customize their portal experience. For this reason, WebSphere Portal provides a mechanism called page customization, which allows users to modify existing portal pages by adding or modifying existing content, or to create new per-user pages.

- 4 -

But before we can dive into more details on the use cases, let’s understand the concepts behind pages and page derivation that enable us to realize these cases.

Technical Definitions Pages are aggregation components for content that a WebSphere Portal user can see. They are also used to deliver markup content that is the result of contributions from several portal artifacts. These are, foremost, portlets that provide their content based on their application code. Other elements that contribute markup are the themes and skins of the page or its elements, as well as view-specific JSPs that provide, for example, navigational information. WebSphere Portal pages usually are managed entities, meaning that they can be administered and managed using established techniques such as the administration UI of portal, XML Access, or the scripting client. With WebSphere Portal, pages can be grouped logically in a content hierarchy that applies access control on single or grouped pages. This hierarchy, included with the current WebSphere Portal versions 5.x, also directly represents navigational information, i.e., a tree of nodes that is used to present the user choices on where to navigate in the portal. Hence, when creating a page, you must always decide where to put it in the navigation hierarchy of pages. The hierarchy can also hold other structuring elements such as labels. For example, the label “My Portal” might group the pages accessible to a certain set of users. Labels do not carry any displayable content in the form of layout; they are a structuring element only. Elements of the page hierarchy are protected by the Access Control component. Using the access control features, an administrator can define the pages that WebSphere Portal users can view and potentially modify. Users can be either unauthenticated or authenticated, and if they have not yet authenticated to WebSphere Portal, they see a set of pages referred to as the “public pages”. In a default installation, all pages that reside under a Uniform Resource Identifier (URI) containing the string /portal/ are public pages. If a user logs in and authenticates to the portal, he can see the “protected pages”, which again can be identified through the URI of a default portal if the string /myportal/ is contained in it. Portal users are able to perform different actions, depending on their access control roles. Roles can grant view access to pages only, or grant the right to edit, create, or even delete pages. Users who are allowed to create or delete pages are usually administrators of the portal. Their role in terms of the programming model is that of a Portal Application Developer. Users may also be able to create and delete pages visible only to them (so-called private pages). As stated above, pages have portlets on them, and with these portlets is included information on how they are laid out for rendering. In WebSphere Portal version 5.1 this information is a tree of horizontal and vertical containers and portlets, which are always leafs in this tree. Figure 1 is a screenshot of a page that has two adjacent portlets, while the layout tree for this page is shown in figure 2.

- 5 -

Figure 1. WebSphere Portal page with two portlets

Figure 2. Layout tree for example page

Operations can be performed on this tree that can change the layout of the page. For example, moving the “About” portlet into the second vertical container would cause both portlets to be stacked vertically on the page, while deleting one of the portlets or their vertical container would remove it from the page. The concept of page specialization--one form of page derivation--comes into play when defining pages as well as when modifying pages. Users who have the “Privileged User” role on a page are allowed to customize the page. Their changes are private; no one else will see the modifications. For example, a user might swap the portlets so that the reminder portlet is rendered first. This is done by the creation of a derivation of the original page that is associated with the user, a process called creating a customized page or an implicit derivation. Page derivation can also be performed explicitly. In that case, a user with appropriate permissions chooses a page that will serve as the base layer of layout information. A new page is created that will

Horizontal container

Vertical container Vertical container

Reminder portlet About portlet

- 6 -

use the layout information of the base page. All base pages and their specializations can be administered separately. Figure 3 shows the dependencies if a new portlet is added to the second vertical container (the figure is true for implicit and explicit derivations), and figure 4 is the derived page with the weather portlet added.

Figure 3. Layout tree for derived page

Horizontal container

Vertical container Vertical container

Reminder portlet About portlet

My Weather portlet

Derived page layout

Additional page layer

Base page

- 7 -

Figure 4. Derived page with My Weather portlet

Administering Derived Pages In this section you will learn how to set up a three-level page specialization, or page derivation hierarchy, employing three additional features available for specializing content: WebSphere Portal administrative portlets, the WebSphere Portal Scripting Client, and XML Access. The set of pages we create also serves as the baseline for the rest of our discussion.

WebSphere Portal Administrative Portlets In the portal admin user interface, you can manage page derivations mostly by using the Manage Pages portlet. First, log into WebSphere Portal as an administrative user. You will be creating portal pages; hence, the user must have access rights to the “Administration” area and must be able to use the “Manage Pages” portlet and several others. The WebSphere Portal Information Center describes in detail how to assign those access rights to portal users. All content in this example will be created under a new label, so that it does not interfere with other portal content. To do this, create a new label under “My Portal” and assign “User” rights on that new label to all “authenticated portal users”. Below this new label we can now create and customize the first page.

- 8 -

To allow other pages to share the content of a new page, select the option “Other pages can share the contents of this page”. Now select a three-column layout and specify a proper page name; here we use “Non-specialized Page” (figure 5).

Figure 5. Non-specialized, shareable page

Once the base page is created, you can add content to it by adding some portlets to the container on the left-hand side of the page. Furthermore, by choosing the Locks tab in the “Manage Layout” portlet, you can enable locks for this container and its content, so that no user can modify the container and its portlets. Employing locks together with page specialization is a common practice, as we describe below in the “Use Cases and Hints & Tips” section. Note that, up to this point there is not yet a specialization hierarchy, and portal users and administrators will see a page that appears like all others in the portal. Now you can create a second page that is derived from the first one (figure 6). The new page uses the content of another shared page (see the lower arrow) and is also shared so that another page can specialize this one. Once again, add some content to the page by placing two portlets in the middle container. The page layout in the administrative portlet now looks similar to that shown in figure 7.

- 9 -

Figure 6. First specialized page

- 10 -

Figure 7. Layout of the first specialized page

As described above, the left-hand container and its content are locked, so that a user can edit portlet properties, but no longer add, remove, or move portlets in this container. In the middle container are the newly added portlets. You can now change the skins for the portlets in the left-hand container. Finally, also lock the middle container and its content (figure 8).

- 11 -

Figure 8. Inherited portlets with modified skins

Now, for the first time, the user experience for administrative users and regular portal users will differ with regard to the new pages. Specifically, users with at least Edit rights on the new pages will see the pages “Non-specialized Page” and “1st Level Specialization” in their navigation, whereas a user with lesser access rights will see only the latter page. The third step now is quite simple: Create a new page, “2nd Level Specialization”, which inherits its content from “1st Level Specialization”. Once again, add some portlets, this time to the container on the right-hand side. Until now we’ve only touched on inheriting the content of a page and modifying it by adding or removing content, or changing other page attributes such as locks or skins. To include the concept of page customization, we must give portal users the ability to customize a page. To do this, assign the “Privileged User” right to “All authenticated portal users” for the final page. If a user now navigates to the new label, he will see only the page “2nd Level Specialization” but will be offered the option to edit the page--for example, using the “Edit Page” link--by adding new portlets to the right-side container.

WebSphere Portal Scripting Client The scripting client offers roughly the same functionality as the administrative portlets from a scripting environment based on the Application Server wsadmin tool. The wsadmin tool supports multiple scripting languages, for example JACL and JPython, while IBM WebSphere Portal currently supports the JACLS scripting language.

- 12 -

The scripting interface, along with all its components and properties, is described in the WebSphere Portal Information Center. This script (available as a companion download file) can be used to model exactly the same navigation structure as presented in the example above.

XML Access XML Access is typically used to deploy content to and export content from WebSphere Portal installations. This is also true for pages and their derivations. Typically, you start by creating some pages and their content in the UI via the administrative portlets, export parts of the configuration, and then take those XML Access scripts and propagate them, for example, to another system. Hence we start with the pages created with the admin portlets above. Complete navigation hierarchies can be easily exported by use of the XML Access export feature available with IBM WebSphere Portal version 5.1 in the “Manage Pages” portlet. Using the example stated above, you can retrieve this XML export (also available as a companion download file).

Experiencing Derived Pages In this section we discuss the rules used when calculating the visibility of derived pages. We also explain the motivation behind these rules and how to take advantage of them.

Visibility of Pages In the previous section we created a derived pages scenario. Administrators have a different view of such a scenario than other portal users. WebSphere Portal hides the complexity of the derivation concept from normal users; that is, a WebSphere Portal page is hidden if a specialization is visible for the current user, unless the user has Manage permission on that page. This leads to our first rule:

Rule 1: A page with a visible specialization is hidden to all users who do not have Manage permission on that page.

Let’s look at the example three-level derivation setup. For the base page, “Non-specialized Page”, there are specializations visible to all users. Hence the base page is hidden for a non-admin user, and the most specialized page is shown. According to Rule 1, “Non-specialized Page” and “1st Level Specialization” are hidden, with only the “2nd Level Specialization” shown (figure 9).

- 13 -

Figure 9. Example in which only the “2nd Level Specialization” is shown

The pages will not be hidden for users with Manage permissions, so they can customize each level separately (figure 10).

- 14 -

Figure 10. Example in which pages are not hidden for users with Manage permissions

Now let’s look further at what “visible” and “hidden” mean in this context. A page is visible, if the user has view permission to that page. The page and all pages above that page in the content hierarchy must support the markup requested by the user’s client. Finally, the page and all pages above must be active too. Hidden pages will normally not be visible at all. As you might already have discovered, this is not always true, because there might be visible content below hidden pages. This content must be shown to the user. This is why those pages will be shown in the navigation hierarchy; i.e., to allow users to navigate to their pages. However, there is no content associated with those hidden pages, which leads to our second rule:

Rule 2: A hidden page is shown as a label, if there is visible content beneath it.

We can demonstrate this behavior by using our scenario above. As an administrator, mark “2nd Level Specialization” in the Manage Pages portlet, navigate to “Non-specialized Page”, and move the marked page here. You can still access all pages from the navigation; however, for regular users logging in, the label “Non-specialized Page” is now visible in the navigation tree, but the page is not selectable. Only the page “2nd Level Specialization” is selectable, and its visible content is still derived from its derivation parent (figure 11).

- 15 -

Figure 11. Example in which a hidden page appears as label when visible content is under it

We now know about the visibility of pages that are the parents for specialized pages. But what do we know about the visibility of the specialized pages? Because the specialized page is using the content of its parent pages, it is clear that its visibility depends on the visibility of the parent pages. A derived page re-uses most of the attributes from the base page in the derivation hierarchy. Without that first page, no layout can be calculated for a derived page, which leads to the third rule:

Rule 3: Derived pages can be rendered only if the base page is active and if the base page supports the requested markup.

In our example, both the “1st Level Specialization” and “2nd Level Specialization” pages will disappear, if the page “Non-specialized Page” is deactivated (figure 12). This also occurs if the support for a requested markup is removed from that page. Pages not shown in the navigation because of this are still visible in the administration portlets. Pages can be deactivated in the Manage Pages portlet, with markup support controlled within the page properties.

- 16 -

Figure 12. Example in which specialized pages cannot be rendered when base page is inactive

On the other hand, a specialized page can still be rendered, even if parts of the page are inactive. This is where the last rule comes into play:

Rule 4: A page with several layers is assembled until an inactive layer is met. The page content will consist of the information from the layers processed thus far.

As you can see in figure 13, only those layout containers that are derived from the base page are displayed. This is because the page “1st Level Specialization” has been deactivated, and since the customizations of the “2nd Level Specialization” page are based on that page (and not on the “Non-specialized Page”), they cannot be shown.

- 17 -

Figure 13. Example of a warning displayed when not all parts of the page are active

Use Cases and Hints & Tips In this section we show how to take advantage of the derivation concept.

Delegated Administration It can be useful to delegate the administration of the content, especially for portals with many pages. Using this pattern, you will be able to set up your pages in such a way that modifications on top-level pages will influence all other pages as appropriate. For example, suppose a company sets up an employee portal in which most but not all pages are modifiable to the users. There is a fixed section at the top of the page, in which there is a company news ticker portlet, and on the right-hand side of the page, essential information such as the bookmarks portlet is displayed. The rest of the pages can be modified by administrators of different departments. The base page would look like that shown in figure 14.

- 18 -

Figure 14. Base page with all layout elements: Modifiable (orange) and fixed (white)

The most important requirement for this setup is that all pages will be updated if the news ticker portlet or the bookmarks portlet is updated. On the other hand, it should be possible for administrators of different departments to modify pages as appropriate. For example, let's assume the employees of the Finance department are more interested in stocks than the employees in the Engineering department. It is quite easy to set up a derivation scenario for such a case. First, it must be clear what content comes from whom. In the following example, we use the scenario diagrammed in figure 15.

Figure 15. Modifiable layout elements and their editors

Banner

Navigation Page Content

Company News Ticker Bookmarks

Department Content

Page Content

Company News Ticker Bookmarks

Department Administrators

Enterprise Administrators

- 19 -

Let’s create the scenario, following these steps: 1. As an Administrator, create the shareable page “Company Base”. 2. Create a column on the right-hand side, and add the bookmarks portlet. 3. Create a second column, and create a row in that column by configuring the Manage Pages portlet

to show the layout tools. 4. Put the news ticker portlet into that row. 5. Lock both the left-hand column and the newly created row container. 6. Assign “Manager” and “Security Administrator” roles to the group of department administrators. 7. Log in as a department administrator. 8. Create a page that derives from the page “Company Base”. 9. Add layout containers and portlets as appropriate. 10. Assign the “Privileged User” role to the group of users that are members of the department. Note:

To do this, the department administrator must be a delegator for the groups of his department users. He also must be a user to the Resource Permission portlet and the Administration pages.

Now let's look at this scenario from the following perspectives: • The Administrator will not be bothered by pages created by delegated administrators. If the

administrator needs access to those pages, he needs to assign access explicitly. The administrator will also be able to define the portlet settings, for instance, for the news portlet.

• Delegated Administrators will see both the base page and the specialized pages. Locked layout elements cannot be changed. However, the delegated administrator will be able to change the portlet settings. This is useful for specializing bookmarks, for example.

• Department Users will see only the specialized page. The portlets will be rendered via the portlet settings defined by the administrators.

Customization Let’s modify the above scenario, to allow the department users to customize their page. Specifically, as the delegated administrator, assign the “Privileged User” role to the users of the department for the specialized page. Note that the delegated admin needs to be a security admin for that page. Lock parts of the layout as appropriate. You now find that Privileged Users will be able to modify the layout, except for locked parts of the page, and the delegated administrator will not see customizations made by privileged users.

Hints & Tips • Be careful when modifying or deleting derivation base pages. Keep in mind that deleting a base

page implies that all derived pages will be deleted, including all user modifications. • Performance-related issues may arise due to the depth of the derivation parents in the content

model’s hierarchy. WebSphere Portal must check for all derived pages whether they are visible or not, up to the derivation base pages. The “farther away” those base pages are in the content hierarchy tree, the more processing needs to be done internally, and log-ins and page navigation

- 20 -

can take more time. In general, try to keep base pages and their derivations “close together” in the content hierarchy.

• Choose recognizable titles for shareable pages so that you can easily identify them in the Manage Pages portlet.

• Use the scripting client to create derivation setups automatically and repeatedly. Instead of creating the complete navigation structure by hand, you can simply modify a script, run it and, if necessary, make some modifications in the administrative portlets.

Summary IBM WebSphere Portal version 5.1 features a powerful and versatile page concept. Portal pages form one part of the Web page served by WebSphere Portal. The main content is delivered through portlets, along with additional elements such as navigational information and branding aspects. Pages are protected through the standard WebSphere Portal access control mechanism. WebSphere Portal pages can be specialized and customized. Hierarchies of pages can be built that share common content, and different parts of a page can be specialized and administered separately. Individual users can customize pages to their needs and taste, without affecting other users of the portal. Through their powerful administration concept, portal pages can be easily created and managed in the UI. Administration capabilities, in the form of scripting support and XML Access export and import, complete the picture for managing portal pages.

Download To download the script and xml export files, see the cover page for this article: http://www.ibm.com/developerworks/websphere/library/techarticles/0604_engehausen/0604_engehausen.html

Resources • WebSphere Portal Product Information

http://www-306.ibm.com/software/genservers/portal

• WebSphere Portal Information Center http://www-106.ibm.com/developerworks/websphere/zones/portal/proddoc.html

The Authors Jan Engehausen is the technical team lead of the WebSphere Portal Engine component, located in the IBM Development Laboratory in Boeblingen, Germany. He holds a Master of Science degree from the Technical University of Clausthal, Germany. He joined IBM in 2000, working on an object-oriented scripting language before joining the Portal Development Team in late 2002. Before becoming the technical lead, his major area of focus was the Engine's model implementation and its interfaces. You can reach Jan at jan.engehausen@de.ibm.com.

- 21 -

Christian Krafft works at the IBM Development Lab in Boeblingen, Germany. He enjoys computer games, such as Linux, and in the winter he might be snowboarding, too. You can reach Christian at krafft@de.ibm.com. Michael Menze joined IBM development in 2002 after studying with IBM for three years. He works in the Boeblingen development team for WebSphere Portal and is responsible for WebSphere Portal performance analysis and introduction of performance improvements. You can reach Michael at michael.menze@de.ibm.com.

- 22 -

®

© Copyright IBM Corporation 2006 IBM United States of America Produced in the United States of America All Rights Reserved The e-business logo, the eServer logo, IBM, the IBM logo, OS/390, zSeries, SecureWay, S/390, Tivoli, DB2, Lotus and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries or both. Lotus, Lotus Discovery Server, Lotus QuickPlace, Lotus Notes, Domino, and Sametime are trademarks of Lotus Development Corporation and/or IBM Corporation. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries or both. Other company, product and service names may be trademarks or service marks of others. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This document is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this document. Nothing contained in this document is intended to, nor shall have the effect of, creating any warranties or representations from IBM (or its suppliers or licensors), or altering the terms and conditions of the applicable license agreement governing the use of IBM software. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. [do we refer to any non-IBM sites? If not, you can remove this paragraph] IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents.