JBoss.orgCommunity Documentation

JBoss Portal 2.7.1

User Guide

January 2009

JBoss Portal - Overview
Feature List
Target Audience
1. JBoss Portal Basics
1.1. Portal Concepts - Illustrated
1.1.1. Portal Instances
1.1.2. Pages
1.1.3. Portlet Windows
1.2. Default Portal installation
1.2.1. Default Portal Pages
1.2.2. Logging in to the Portal
1.2.3. Home Page
1.2.4. News Page
1.2.5. Weather Page
1.3. Personal Dashboard
1.3.1. Configuring your personal dashboard
1.4. Admin Portal
2. Administration - Portal Object Management (Dynamicity)
2.1. Introduction
2.2. Management Portlet
2.2.1. Managing Portal Objects
2.2.2. Managing Portlet Instances
2.2.3. Managing Portlet Definitions
2.2.4. Managing Dashboards
2.2.5. Wizard mode
3. Administration - Content Management System
3.1. Introduction
3.2. Actions
3.2.1. Viewing Directories
3.2.2. Viewing File Properties
3.2.3. Copying Files/Directories
3.2.4. Moving Files/Directories
3.2.5. Deleting Files/Directories
3.2.6. Creating Directories
3.2.7. Creating Text/HTML Files
3.2.8. Uploading Files
3.2.9. Uploading Archives
3.2.10. Exporting folders
3.2.11. Editing Text/HTML Files
3.2.12. Securing Resources
3.2.13. Content Publish/Approval Workflow
4. Administration - Users and Roles
4.1. Managing Users
4.1.1. Actions
4.2. Managing Roles
4.2.1. Introduction
4.2.2. Actions

Many IT organizations look to achieve a competitive advantage for the enterprise by improving business productivity and reducing costs. Today's top enterprises are realizing this goal by deploying enterprise portals within their IT infrastructure. Enterprise portals simplify access to information by providing a single source of interaction with corporate information. Although today's packaged portal frameworks help enterprises launch portals more quickly, only JBoss® Portal can deliver the benefits of a zero-cost open source license, combined with a flexible and scalable underlying platform.

JBoss Portal provides an open source and standards-based environment for hosting and serving a portal's Web interface, publishing and managing its content, and customizing its experience. It is entirely standards-based, and supports the JSR-168 Portlet Specification (Portlet 1.0) and JSR-286 Portlet Specification (Portlet 2.0) , which allows you to easily plug-in standards-compliant portlets to meet your specific portal needs. JBoss Portal is available through the business-friendly LGPL open source license, and the JBoss Enterprise Portal Plarform is supported by JBoss Enterprise Middleware Professional Support and Consulting. JBoss support services are available to assist you in designing, developing, deploying, and ultimately managing your portal environment. JBoss Portal is currently developed by JBoss Enterprise Middleware developers, and community contributors.

The JBoss Portal framework and architecture include the portal container, and support a wide range of features, including standard portlets, single sign-on, clustering, and internationalization. Portal themes and layouts are configurable. Fine-grained security administration -- down to portlet permissions -- rounds out the security model.

JBoss Portal Resources:

The JBoss Portal team encourages you to use this guide to install and configure JBoss Portal. If you encounter any configuration issues or simply want to take part in our community, we would love to hear from you in our forums.

The following list details features found in this release of JBoss Portal. For a technical view of the JBoss Portal features, refer to the Project Roadmap and Task List .

Technology and Architecture

  • JEMS: leverages the power of JBoss Enterprise Middleware Services: JBoss Application Server, JBoss Cache, JGroups, and Hibernate.

  • Database Agnostic: works with any RDBMS supported by Hibernate.

  • Java™ Authentication and Authorization Service (JAAS): custom authentication via JAAS login modules.

  • Caching: utilizes render-view caching for improved performance.

  • Clustering: cluster support allows the portal state to be clustered for all portal instances.

  • Hot-deployment: leverages JBoss dynamic auto-deployment features.

  • SAR Installer: browser-based installer makes installation and initial configuration a breeze.

Single Sign On

  • Leverages Apache Tomcat and JBoss Single Sign On (SSO) solutions.

  • Integrates with Java Open Single Sign-On (JOSSO) and Central Authentication Service (CAS) out of the box. Experimental support for the Open Web SSO project (OpenSSO).


  • Connect to virtually any LDAP server.

  • Integrates with Sun™ Active Directory and OpenLDAP out of the box. Experimental support for Microsoft® Active Directory®.

Supported Standards

  • Portlet Specification and API 1.0 (JSR-168).

  • Portlet Specification and API 2.0 (JSR-286).

  • Content Repository for Java™ technology API (JSR-170).

  • JavaServer™ Faces 1.2 (JSR-252).

  • JavaServer™ Faces 2.0 (JSR-314).

  • Java Management Extension (JMX™) 1.2.

  • Web Services for Remote Portlets (WSRP) 1.0: refer to WSRP support in JBoss Portal for further details.

  • Full J2EE™ 1.4 compliance when used with JBoss Application Server.

Portal and Portal Container

  • Multiple Portal Instances: the ability to have multiple portal instances running inside one portal container.

  • IPC: the Inter-Portlet Communication API enables portlets to create links to other objects, such as pages, portals, and windows.

  • Dynamic: the ability for administrators and users to create and destroy objects such as portlets, pages, portals, themes, and layouts at runtime.

  • Internationalization: the ability to use internationalization resource files for every portlet.

  • Pluggable Services: with authentication performed by the servlet container and JAAS, it is possible to swap the authentication scheme.

  • Page-based Architecture: allows the grouping and division of portlets on a per-page basis.

  • Existing Framework Support: portlets utilizing Apache Struts, Spring Web MVC, Sun JSF-RI, AJAX, and Apache MyFaces are supported.

Themes and Layouts

  • Swapping Themes and Layouts: new themes and layouts containing images can easily be deployed in WAR archives.

  • Flexible API: the Theme and Layout APIs are designed to separate the business layer from the presentation layer.

  • Per-page Layout Strategy: different layouts can be assigned to different pages.

User and Group Functionality

  • User Registration and Validation: configurable registration parameters allow user email validation before activation.

  • Workflow: ability to define your own jBPM workflow on user registration.

  • User Log In: makes use of servlet container authentication.

  • Create and Edit Users: ability for administrators to create and edit user profiles.

  • Create and Edit Roles: ability for administrators to create and edit roles.

  • Role Assignment: ability for administrators to assign users to roles.

  • CAPTCHA Support: distinguish between humans and machines when registering.

Permissions Management

  • Extendable Permissions API: allows custom portlet permissions based on role definition.

  • Administrative Interface: allows permission assignments to roles at any time for any deployed portlet, page, or portal instance.

Content Management System

  • JCR-compliant: the CMS is powered by Apache Jackrabbit, an open source implementation of the Java™ content repository API.

  • Database and File System Store Support: configure the content store for either a file system or an RDBMS.

  • External Blob Support: configurable content store, allowing large blobs to reside on a file system, and content node references and properties to reside in an RDBMS.

  • Version and History Support: all content edited and created is auto-versioned with a history of edits, that can be viewed at any time.

  • Content Serving Search-engine-friendly URLS: http://your-domain/portal/content/index.html (does not apply to portlet actions).

  • No Long Portal URLS: serve binaries with simple URLs (http://your-domain/files/products.pdf).

  • Multiple HTML Portlet Instance Support: allows extra instances of static content from the CMS to be served under separate windows.

  • Directory Support: create, move, delete, copy, and upload entire directory trees.

  • File Functions: create, move, delete, copy, and upload files.

  • Embedded Directory-browser: when creating, moving, deleting, or copying files, administrators can navigate the directory tree to find the collection they want to perform the action on.

  • Ease-of-use Architecture: all actions to be performed on files and folder are one mouse-click away.

  • Full-featured HTML Editor: the HTML editor contains a WYSIWYG mode, preview functionality, and HTML source editting mode. HTML commands support tables, fonts, zooming, image and URL linking, flash movie support, bullet and numbered list, and dozens more.

  • Editor Style Sheet Support: to easily chose classes, the WYSIWYG editor displays the current portal style sheet.

  • Internationalization Support: content can be attributed to a specific locale, and then served to the user based on his or hers Web browser settings.

  • Workflow Support: basic submit for review and approval process.

This document is intended for those using JBoss Portal as End-Users. This is a "Where do I Click?" Guide.

For Portlet developers, Portal administrators, and those wishing to implement/extend the JBoss Portal framework, there is a Reference Guide available from our documentation page .

We would like to thank the developers that participate in the JBoss Portal project.


Contributions of any kind are always welcome. You can contribute by providing ideas, filing bug reports, producing code, designing a theme, writing documentation, and so on. If you think your name is missing from this page, please let us know.

This section will introduce the reader to some basic portal concepts and terms, used within JBoss Portal and this document.

Portlet Windows are found on Portal Pages and contain the HTML markup for a specific portlet instance.

The diagram above, shows the default JBoss Portal page with certain window-related items highlited (in red). Lets look at these items:

This section will take a quick look at the default Portal installation and the pages and portlets that come with it.

Three pages are available in the default Portal: Home, News and Weather. You can access pages either by entering the page URL in your browser location bar, as shown in Section 1.1.2, “Pages”, or by clicking the tab associated to the page in the Navigation Tabs at the top of the page.


Navigation tabs support sub-page navigation as well. By hovering over a tab with child Pages, it will display a flyout menu for those subpages:

There are no pages with subpages in the default Portal installation.

While you can use a Portal anonymously, it is much more interesting to do so while logged in, as you get the opportunity to customize the content you want to see or even create your own personal Dashboard, as explained in Section 1.3, “Personal Dashboard”.

Displays hard-coded links to downloading JBoss Portal, downloading portlets from PortletSwap, and the live online JBoss Portal demo. It also contains default authentication information on loging in, as well as a link to the official Portal documentation.


Administrators should view Section 4.1, “Managing Users” for managing the portal user base. Only user operations are covered in this section...

Once successfully logged in, the user will have additional functionality at his disposal, that is covered in the following sections.

The Identity User Portlet allows a user to:

  • Create a new account

    Create a new account by clicking on the "Register" link in the navigation of the portlet, when not logged. A User can then fill in the necessary information to create an account on the system:

  • Lost password

    Already registered users can request a new password by clicking on the "Lost password" link in the navigation of the portlet. Therfore the user needs to fill in his user name to receive an e-mail with his new login credentials.

  • View profile

    The default page after login is the view profile, which shows a summary of the most important properties of a user.

  • Edit personal information

    A user has the ability to edit his personal information, change his password and e-mail address at any time by clicking on the "Edit profile" link, when logged in.

Once logged in, all users/administrations of the portal can access a personal dashboard by clicking the Dashboard link at the top-right of the portal page. Note how the links changed.

The personal dashboard allows users to customize their portal pages however they like, and all changes will be persisted... so the next time the user logs in to his dashboard, he will see the previous changes he made. While navigating any of the dashboard pages, a user will be able to drag and drop portlet windows to any location, if the administrator allows this functionality. Changes made in this fashion will also be persisted.

It is also possible to copy the content of a shared page to your dashboard so you can customize it to your liking. Just click the 'Copy to my dashboard' link at the top right of the page. This will clone the page and add it to your personal dashboard as a page with the same name.

The concept of dynamicity refers to the fact all portal objects can be dynamically modified at runtime, eliminating the need to struggle with large xml files, or restarting the application server for changes to take effect. In the scope of dynamicity, Portal objects are defined and can be altered as follows:

  • Portal Instances: Multiple Portal instances can be launched at any time, secured, and skinned.

  • Pages: Multiple pages, composed of windows, can coexist inside a portal instance, secured and each could have its own theme applied, if desired.

  • Portlets: Can be hot-deployed and will instantly register with the portal, appearing in the management portlet.

  • Portlet Instances: Instances can be created/destroyed. Their preference variables can be modified at runtime, instances assigned to windows and secured.

  • Windows: Windows can be secured, created/destroyed, and assigned to specific pages.

  • Themes/Layouts: Can be hot-deployed and will register with the portal, appearing the management portlet, allowing for dynamic customization of any of the above components.

The management portlet provides a two-part interface: tabs, at the top, corresponding to the different sections that can be managed; and the main area under it, displaying the current information for the selected tab.

The tabs are:

We will look at each of these tabs and their functionality in the following sections.

The Portal Objects brings the administrator to a page showing the list of the available portal instances defined for this Portal server. Several points are of particular interest. First, a navigation indicator or "breadcrumbs" is located right beneath the tabs. This provides context as to where in the hierarchy of portal objects the current screen is located as some of the screens can be found at several levels of the hierarchy. If you are lost, take a look at the breadcrumbs for context! When you first click on the Portal Objects tab, the context is the list of portals as shown in the picture above.

A link to access server-wide portal properties is located right beneath the breadcrumbs. This allows the administrator to set server-wide property and configure how errors should be handled:

Please refer to the Error handling chapter of the Reference Guide for more information on this point.

A form allowing administrator to create new portal instances is located beneath the Properties link. Enter the name of the new portal (which, of course, should be different from any of the already existing one) and click on Create portal and the portal instances list will be refreshed to display the newly created portal instance.

The last element at this level is a table listing all the available portal instances along with possible actions on them. Clicking on the portal name will display a screen showing the information for this given portal instance, thus drilling down the hierarchy of available portal objects. Clicking on an action name will execute the specified action on the associated portal instance. These actions are available on each individual portal screen as we shall see. The notable exception is the Make Default/Default action which is only available in this listing as it is more of an action across portals than specific to a portal thus benefiting from being seen at this level. This action allows users to specify which portal instance is displayed when Portal is first being accessed. Clicking on Make Default will specify that the associated portal will be displayed to users by default. The portal list will be refreshed and the selected portal status will be refreshed, its action now showing its Default status.

In the next sections we will demonstrate the functionality of the management portlet by drilling progressively further down this hierarchy to look at the default portal, one of its pages, show how to configure content on a page and, finally, look at a specific window information.

If you click on the default portal in the list of available portal instances on the top-level Portal Objects page, you'll be taken to a page showing the information for the portal instance named "default", as shown below:

Note the breadcrumbs at the top of the screen indicating where in the hierachy you currently are. In this case, we are looking at the default portal.

Links to more information and operations that affect this portal instance are located beneath the breadcrumbs. We will look at them in turn later, excluding the Destroy operation, which as its name implies, allows an administrator to destroy the current portal instance. Note that these links mirror the links that were available in the portal instances list on the top level page, Make Default/Default excepted.

It is possible to create new pages using the page creation form located under the portal-wide operation links. Enter the new page name and click on Create page and the new page will appear in the pages list, ready to be configured.

Finally, a table displaying the list of available pages for this portal instance is located at the bottom of this screen. The first column shows the page name, which you can click to drill down the hierachy and display the information specific to that particular page. The second column, on the other hand, provides a list of action links on the associated page. These links will be also appearing on individual page screens, as we shall see, just like portal action links appearing in the portal instances list also appeared on individual portal pages. Once again, the Make Default/Default action, which behaves as its portal counterpart, only appears in this list: this is where you specify which page should be the default one when users first access the portal instance.

Let's now look at the default portal's Security information screen. This can be accessed by clicking the Security action link on the portal page. Here, an administrator can configure the default policy for security on objects for this portal instance:

Please refer to the Security chapter of the Reference Guide for more information about how to secure portal objects.

The Properties action link displays the currently configured properties for this portal instance and allows you to modify them, as well as configure the error handling strategy:

The Theme action link displays a screen where the administrator can configure theme, layout and render set for this portal instance:

Please refer to the Layouts and Themes chapter of the Reference Guide for more information about themes and layouts.

The Display Name action link displays a screen where the administrator can configure different names for different languages:

The different names will be used as page display names for the preferred locale of the logged-in user. This is used by the default tab navigation of the default layouts.

Now that we have looked at portal level information, let's drill down the hierachy again and look at a page, more precisely the default page, by clicking its name in the pages list.

The layout of this screen should start feeling familiar. The information for a page looks a lot like the information for a portal instance. Note the breadcrumbs indicating that you are indeed looking at a page. Again, we find the action links at the top of the page, mirroring the ones that were available for each page in the pages list of the portal instance screen. Once again, you can configure the page's security, theme and properties. You can also destroy it if so desired.

Similarly to other screens in the portal objects hierarchy, a page configuration screen also provides a list of all windows for that page. This list contains two columns: the first one contains the name of the window, while the second one provides a list of action links for that specific window. As usual, clicking on a window name will display information about that window.

Just like a portal instance can contain several pages, a page can contain several subpages. As such a page defines means to create subpages and set which subpage to display when a user is first directed to the page. These operations work similarly to the same operations at the portal instance level.

You can also rename the page if desired:

Of specific interest, though, is the Page Layout link. This is where you need to go to configure which portlet instance will be displayed in which window on which region on the page. Let's take a look at this screen and how it works:

This screen is structured in two parts, flowing from left to right, following the natural process involved in displaying content on a page. First, you need to identify which content you want to display: this is what the Content Definition section is for. Then, you need to figure out where on the page should this content be displayed, hence the Page Layout section.

Let's add a window named test displaying the content of the portlet instance named NewsPortletInstance to the center region, beneath the already existing CMSWindow. First, we need to enter our new window name in the Window name field and select the portlet content type from the drop down menu:

Once this is done, we can select the portlet instance by clicking its name in the instances list:

Note that this displays some information about the portlet instance. Finally, we can add our window to the center region of the page by clicking on Add button located left to the windows list for the region:

Note that we could move the window up or down in the region by selecting it in the list and using the button to the right of the list, or even destroy it if desired.

We can repeat this process to add content of different types. Let's add a window using a Google widget game. First, give a name to your window (we'll use "google" here) and select widget/google from the content type drop-down menu:

Note how the instances list is replaced by a list of Google widgets. The widget we want to use is located in the Fun & Games category, so select it from the category drop-down menu:

Press Search Gadgets and the widget list will be refreshed. The widget we want is Bejeweled:

You can now add the new window to the desired region.

Let's repeat this process again, this time with content from CMS. Enter a new window name (we'll use "cms" here) and select cms from the content type drop-down menu:

Once again, the instances list was replaced by a directory listing showing the available content roots. Click on default and select project.html:

You can now add the window to the desired region.

We've added three new windows to the default page using different content types. We added a window displaying the content of a portlet (displaying the content of an RSS feed in this case). Another one displaying a Google widget and yet another one some CMS-issued content. We decided to remove the existing CMSWindow, add the cms window below the test one in the center region, while the window showing the Google widget was added to the left region, below the existing content:

If all went well, logging out of the Admin portal, you should see:

You can read more about Content Integration in the Reference Guide. More details on how to setup content roots in CMS are available in Section 3.1, “Introduction”.

This section describes common actions an administrator can perform from within the AdminCMS Portlet. All actions are available using the flyout menu. Note that the Pending Items action is only available if the workflow mechanism has been activated.

This chapter covers the administrator functions made available by the User management portlet. For end-user operation, see: Section, “Identity User Portlet”. Administrative functions are available once you are logged in with the proper credentials (admin/admin), then going to the Section 1.4, “Admin Portal” and then the Members Page tab. You can change between user and role management by clicking on the corresponding links in the top of the portlet.

This section covers the user management of the IdentityUserManagementPortlet which is displayed by default. For role management please see Section 4.2, “Managing Roles”.

The Members page in the Section 1.4, “Admin Portal”.

The first page of the user management portlet displays some user related actions (eg. Search users, Create new user account) and some additional information (e.g. Registered users and Subscription mode). The registered users represent the count of all registered users and the subscription mode describes the required tasks for registering a user (i.e. first e-mail validation and then approval by the administrator). The Subscription mode symbolizes the mode used in the User portlet. The Admin subscription mode represents the mode used in the User management portlet.

The User management portlet is also responsible to create and edit roles and it is accessible once logged in - as described in previously - when clicking on the role management link in the User management portlet.