Thursday, September 24, 2009

Additional steps needed after updating wps.ear

Problem

After an effort to update the wps.ear to include new configuration for IBM® WebSphere® Portal, the deployment completes successfully, but browsing to the Portal to verify the update results in errors on the page.

Symptom

You will see content errors on the Portal page in the browser.

Errors logged for this issue:

[date/time] 0000002e Helpers W NMSV0605W: A Reference object looked up from the context "java:" with the name "comp/env/jdbc/customizationDS" was sent to the JNDI Naming Manager and an exception resulted. Reference data follows:
Reference Factory Class Name: com.ibm.ws.util.ResRefJndiLookupObjectFactory
Reference Factory Class Location URLs:
Reference Class Name: java.lang.Object
Type: ResRefJndiLookupInfo
Content: com.ibm.ws.util.ResRefJndiLookupInfo@19d6388 ResRefJndiLookupInfo: Look up Name="jdbc/customizationDS";JndiLookupInfo: jndiName="jdbc/wpdbDS"; providerURL=""; initialContextFactory=""

Exception data follows:
javax.naming.NameNotFoundException: Context: /clusters/PortalCluster, name: jdbc/wpdbDS: First component in name wpdbDS not found. [Root exception is org.omg.CosNaming.NamingContextPackage.NotFound: IDL:omg.org/CosNaming/NamingContext/NotFound:1.0]
at com.ibm.ws.naming.jndicos.CNContextImpl.processNotFoundException(CNContextImpl.java:4392)
..........
Caused by: javax.naming.NameNotFoundException: Context: /clusters/PortalCluster, name: jdbc/wpdbDS: First component in name wpdbDS not found. [Root exception is org.omg.CosNaming.NamingContextPackage.NotFound: IDL:omg.org/CosNaming/NamingContext/NotFound:1.0]
at com.ibm.ws.naming.jndicos.CNContextImpl.processNotFoundException(CNContextImpl.java:4392)
..........
Caused by: org.omg.CosNaming.NamingContextPackage.NotFound: IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
at com.ibm.ws.naming.ipcos.WsnOptimizedNamingImpl.do_resolve_complete_info(WsnOptimizedNamingImpl.java:543)
.........
[date/time] 0000002e NamingService E com.ibm.wps.services.naming.NamingServiceImpl lookup EJPFD0006E: Cannot find object java:comp/env/jdbc/customizationDS in JNDI context java:comp/env/jdbc/customizationDS.
com.ibm.websphere.naming.CannotInstantiateObjectException: Exception occurred while the JNDI NamingManager was processing a javax.naming.Reference object. [Root exception is javax.naming.NameNotFoundException: Context: /clusters/PortalCluster, name: jdbc/wpdbDS: First component in name wpdbDS not found. [Root exception is org.omg.CosNaming.NamingContextPackage.NotFound: IDL:omg.org/CosNaming/NamingContext/NotFound:1.0]]
at com.ibm.ws.naming.util.Helpers.processSerializedObjectForLookupExt(Helpers.java:952)
at com.ibm.ws.naming.urlbase.UrlContextHelper.processBoundObjectForLookup(UrlContextHelper.java:191)
.........

Cause

There are missing steps in the following section of the InfoCenter:


http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.ent.doc/wps/dgn_dpycst.html

Resolving the problem

Following the InfoCenter link above, after completing Step 6 of 'Deploying themes and skins in a production environment', please substitute these steps for Step 7:

Complete the following tasks:

    Note: When using a cluster environment use the primary node to invoke the commands.
      1. Locate the directory portal_server_root/config/
      2. Type the following configuration task appropriate for your operating system on a command line:
        o Windows: WPSconfig.bat action-modify-attributes-ear-wps
        o UNIX: WPSconfig.sh action-modify-attributes-ear-wps
      3. Synchronize all the nodes
      4. Restart WebSphere Portal on the stand-alone server or on each cluster member if using a cluster environment

How to restore WebSphere Portal back to the out-of-the-box security configuration


Question
Sometimes you may encounter a problem when you configure IBM WebSphere Portal security (standalone or federated). This problem can cause the system configuration files to be in an inconsistent state. Can you revert back to the original file registry configuration if the security task fails?

Answer

It is now possible to revert back to the out-of-the-box security configuration for WebSphere Portal 6.1.0.1 You must populate the wkplc.properties file with the parameters stated below and then run the wp-restore-default-repository-configuration task.

NOTE: If you are on WebSphere Portal 6.1.0 you need to install PK73815 and update the Portal configuration per the APAR details for this task to work properly. This APAR is included in WebSphere Portal 6.1.0.1 or later, but if you originally installed WebSphere Portal 6.1.0 and then upgraded to 6.1.0.1 or later, you still need to reference the APAR details for the instructions necessary to use the task successfully.

The wp-restore-default-repository-configuration task allows you to return to the default VMM setup with a federated file repository. The task will create a new realm, delete all existing repositories, and configure a file repository in VMM. The file repository itself must exist (fileRepository.xml) before calling this task.

A new user and a new user group will be created and set to the WebSphere Portal and WAS administrators.

If you want the admin user to be added to the admin group, this must be done manually after restarting the portal by calling the wp-restore-default-repository-add-group-member task. This task will use the admin user and group set for wp-restore-default-repository-configuration in the wkplc.properties file.

Parameters in wkplc.properties:
#########################################################
##
##
## Restore VMM security
##
## wp-restore-default-repository-configuration
##
#########################################################
#########################################################

# The realm name to be used. A realm with this name will be created.
restore.file.realm=federatedRealm
restore.file.delimiter=/

# Portal and WAS admin UID (short name) and password
restore.file.primaryAdminId=adminUID
restore.file.primaryAdminPassword=adminPWD

# CN of portal admin group (short name)
restore.file.primaryPortalAdminGroup=adminGroupCN

#########################################################
##
##
## Restore VMM security
##
##
#########################################################
#########################################################


Wednesday, September 23, 2009

Use IBM Workplace Web Content Management 6.0



Use this training path to see the courses you need to take to achieve this skill or certification. Click on the course boxes to access a course description, view its schedule, and enroll.

PDF PDF version (103KB)

Training Path for Use IBM Workplace Web Content Management 6.0 Proceed to Training Path: IBM WebSphere Portal 6 System... Prerequisites: HTML and Web site development experience WP440 Classroom (3 days) WP010 e-Learning (6 hours)

Audience
This roadmap is for you if you are an Portal or Web site and content developer who is new to IBM® WebSphere® Portal and will use IBM Workplace Web Content Management to develop Portal or Web sites.

Skills
To develop Portal or Web sites and content, you need the following skills:

  • Navigate and use the development user interface.
  • Implement and manage workflows.
  • Implement and manage library access and item security.
  • Design and create a site information architecture, including the site framework, site areas and a category taxonomy.
  • Create content items.
  • Create components such as images and style sheets.
  • Add navigators to the site.
  • Create menus.
  • Implement search functionality.
  • Manage item versions and restore items.
  • Use the Web Content Management API.

System Administrator Skills for WebSphere Portal V6.1



Use this training path to see the courses you need to take to achieve this skill or certification. Click on the course boxes to access a course description, view its schedule, and enroll.

PDF PDF version (30KB)


Training Path for Use IBM Workplace Web Content Management 6.0 IBM Certified System Administrator – IBM WebSphere Portsl V6.1 WP711 OR Classroom (3 days) WPV71 Instructor-led online (3... WP721 OR Classroom (2 days) WPV72 Instructor-led online (2... Setup more sophisticated environments, like virtual portals,... Install and configure a WebSphere Portal Learn the basics about WebSphere Portal Install and configure a WebSphere Portal and setup a... Proceed to: Integrate IBM Lotus Domino WP731 Classroom (5 days) WP015 eLearning (6 hours) Proceed to: Extend IBM Tivoli Directory Server Skills Proceed to: Extend IBM DB2 Administration Skills Proceed to: Extend IBM WebSphere Skills Develop WebSphere Portal Applications


Skills for WebSphere Portal V6.1

Application Development


Use this training path to see the courses you need to take to achieve this skill or certification. Click on the course boxes to access a course description, view its schedule, and enroll.

PDF PDF version (31KB)

Training Path for Use IBM Workplace Web Content Management 6.0 WP621 OR Classroom (2 days) WPV62 Instructor-led online (2... WP611 OR Classroom (3 days) WPV61 Instructor-led online (3... WPC41 Classroom (3 days) WP015 eLearning (6 hours) Proceed to: Java and J2EE Java and WebSphere Training Path Proceed to: WebSphere Portal System Administrator WPC70 Classroom (2 days) Develop custom, full-function portlets using Rational... Integrate Lotus Forms Rapidly develop portlets or dashboard portlets using WebSphere... Also interested in Web 2.0 and AJAX?




How to Update the Database Administrator Password on Portal 6.0 and 6.1


Question
I have to change the database administrator password. Now how do I update Portal with the new DB password?

Answer
You can update the database administrator passwords for Portal by changing the datasource, as noted in the Portal infocenters:

Portal 6.0 -
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.ent.doc/wpf/sec_pswds.html#sec_pswds__dbase

Portal 6.1 -
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/topic/com.ibm.wp.ent.doc_v6101/config/db_passwords.html

This works fine as long as you don't run any Portal configuration tasks in the future. If you do run a configuration task that requires the database administrator password, however, the task will use the old value in the properties file instead of the new password, and the task will fail.

The recommended way to change database administrator passwords used by Portal, is to change them in the Portal properties file and run the connect-database task. This updates the datasources while maintaining current properties in the Portal configuration files:

Portal 6.0:

  1. For a cluster, start the deployment manager and node agent if they are not already running.
  2. Stop Portal
  3. Update the properties file with the new password(s) for each domain:
    PortalServer/config/wpconfig_dbtype.properties
  4. Navigate to the following directory:
    PortalServer/config/
  5. Start the connect-database task:
    Windows:
    WPConfig.bat connect-database
    AIX, Solaris, Linux, Unix:
    ./WPConfig.sh connect-database
  6. Start Portal

Portal 6.1:
  1. For a cluster, start the deployment manager and node agent if they are not already running.
  2. Stop Portal
  3. Update the properties file with the new password(s) for each domain:
    /ConfigEngine/properties/wkplc_dbtype.properties
  4. Navigate to the following directory:
    /ConfigEngine/
  5. Start the connect-database task:
    Windows:
    ConfigEngine.bat connect-database
    AIX, Solaris, Linux, Unix:
    ./ConfigEngine.sh connect-database
  6. Start Portal

How to configure the portlet for different settings for different users?

How to configure the portlet for different settings for different users?

Need:
Need to configure portlet for individual users

Solution:
If the Portal Administrator sets the Shared Settings for the Rendering Portlets, then later attempts to configure the portlet with the "Configure" option, they will receive this Informational Message:
The shared settings of this portlet have been edited. Configure mode settings will not be observed.

These settings are mutually exclusive. If you need use the "Configure" option, do not set the "Shared Settings" for that portlet. If you have already set the Shared Settings, you will need to remove the portlet from the page then add it back to reset the shared settings so the "configure" option will work.

Note also that if the user tries to personalize the portlet they need at least User Role on the library they are attempting to use, or they will receive this error message:

"You do not have the required access rights to view this content"

Monday, September 21, 2009

Support Content Highlight for WebSphere Portal/WCM (September 2009)

Introduction


This document contains links to technical support documents for IBM WebSphere Portal that are frequently requested or identified by IBM as valuable for the time period covered by this notification. This is key information to help you derive the most value from your software licenses, find answers to common questions, and work through current issues that might affect your environment.

This list reflects a small portion of our knowledge base. If your problem or question is not featured here, perform a keyword search on the WebSphere Portal Support page to find any relevant documents. If you need more help, you can review the WebSphere Portal Zone on developerWorks and the WebSphere Portal User Forum for additional support options.

Contents:

  • Announcements
  • Recent favorites
  • Recent wiki and developerWorks articles
  • Continual favorites
  • Consumability survey
  • Electronic Support Resources
  • Subscription information
Announcements
Recent favorites

1. Steps required for JSP precompile on Portal 6.0 and 6.1 (1389639)
What are the steps necessary to run a JSP precompile on a WebSphere Portal installation?

Software version: all 6.1 versions; all 6.0 versions

2. Silent Install - Installing with a response file (1385738)
Steps for doing a silent install.

Software version: 6.1.0.1, 6.1

3. Key Content Resources for WebSphere Portal (7013542)
Key content resources such as system requirements, product documentation, best practices wikis, discussion forums, support and education resources, are available for WebSphere Portal.

Software version: 6.1, 6.0, 5.1

4. Configuration Wizard fails on LDAP validation due to incorrect bind user name (1382100)
When configuring standalone security with Lotus Domino LDAP using the Security Configuration Wizard, the process fails due to an error during LDAP validation.

Software version: 6.1

5. CWWIM4520E error when logging in due to invalid base entry in VMM configuration (1368224)
You are unable to log into IBM WebSphere Portal or the Integrated Solutions console after configuring security using the federated repository.

Software version: 6.1

6. Additional configuration required for PK62794 (1397911)
What additional configuration is required for PK62794?

Software version: 6.1, 6.0

7. MustGather: Upgrade failures for WebSphere Portal 6.1 (1396293)
This technote covers collecting data for upgrade failures with WebSphere Portal 6.1. Gathering this MustGather information before calling IBM support will help to understand the problem and save time analyzing the data.

Software version: 6.1

8. Default themes and skins will be overwritten by refresh pack 1 (6.0.1) installation (1255697)
Previously, the default "out of the box" themes and skins for WebSphere Portal have remained untouched by the automated portion of a fix pack installation and required manual steps to deploy the updated code. Beginning with refresh pack 1 for WebSphere Portal version 6.0 (6.0.1), the update will replace the default themes and skins if updates are provided, and any customized content will be replaced.

Software version: 6.0.1

9. Limit on the number of Content items that can be created with Workplace Web Content Management (1398425)
Is there any limit on the number of Content Items that can be created with Web Content Management?

Software version: all 5.1

10. ConstraintViolationException while saving large Personalization rule (1398966)
While saving a large Personalization rule, an EJPVP00000E error appears on the portlet.

Software version: 6.1.0.2, 6.1.0.1
Recent wiki and developerWorks articles

Continual favorites
  • The Featured Documents for IBM WebSphere Portal and Web Content Management page contains a list of documents that consistently prove useful to WebSphere Portal administrators and users.
  • Direct Fixes Download Links are available from "Download links for APAR interim fixes to a specific version of WebSphere Portal and Lotus Web Content Management" (1253233).
  • Recommended fixes and updates for WebSphere Portal and Web Content Management page. Updated PK92696 (V6.1.0.x WCM CF17) and added new Recommended Group for 6.1.0.1
  • Consumability Survey

    Would you help us by responding to the consumability survey for the latest version of the products you work with?

    Go to http://www.ibm.com/survey/oid/wsb.dll/studies/consumabilitywebform.htm?icode├║Q

    The survey is available in 10 major languages and invites both multiple choice and free format responses, all of which we review. There is no option to save a partially completed survey and return later, so you need to finish the survey in one session and hit the final Submit button for the data to reach us. Please plan 30-40 minutes to respond. You do not need to identify yourself or your company; that is optional. This is an opportunity to influence future releases of our products and to save you time by helping to make our systems easier to use. Thank you.
    Electronic Support resources


    Here are links to other ways that you can access WebSphere Portal and Web Content Management self-help support information on the web:

    Portal Resources
    General Resources



    Image:Support Content Highlight for WebSphere Portal/WCM (September 2009)



    Wednesday, September 16, 2009

    Nested URL opens in new browser window instead of current window

    How do i do :
    In IBM WebSphere Portal, when creating a new external URL using the Manage Pages administration portlet, it behaves differently depending on which the level used.

    * Example 1: If you go to Content Root --> Home --> Level 2 URL (mapped to www.ibm.com) and leave Portal administration, when you click the new URL, it opens www.ibm.com in the same window.

    * Example 2: If you go to Content Root --> Home --> Welcome --> Level 3 URL (mapped to www.ibm.com) and leave Portal administration, when you click the new URL, it opens a new browser window for www.ibm.com.

    Cause
    The behavior is working as designed.


    Resolution
    In Example #2, the navigation exists on the left side of the page as opposed to across the top of the page as in Example #1.
    To allow the links on the left navigation to open in the same window, remove any references in the page's theme to "target+"_blank"". This reference causes the link to open in a new window.

    If using the default IBM theme, do the following:

    -- Stop WebSphere Portal.
    -- Remove the reference in the following files: Default.jsp and sideNav.jspf
    -- Remove the temporary files for the IBM theme in/temp/cellname/WebSphere_Portal/themes.
    -- Start WebSphere Portal.
    -- Click the link again. It should open in the same window.

    How to modify theme so that all URL links open in a new window


    You create a new URL link using the Manage Pages portlet in IBM® WebSphere® Portal version 6.0. When a user clicks on this new URL link, it displays the target page in the same window as opposed to opening a new Web browser window. How can you force it to open a new browser window when clicking the URL link?

    How do i do
    In this scenario, the customer was working on a page copied from the default IBM theme which implements top navigation. In order to have URL links open in a new window, it is necessary to perform the following steps:

    1) Edit the topNav.jspf located in /installedApps//wps.ear/wps.war/themes/html/ as follows:


      FirstRow">

      <% boolean openInNewWindow = com.ibm.portal.content.ContentNodeType.EXTERNALURL.equals(wpsNavNode.getContentNode().getContentNodeType()); %>

      <% boolean isNodeSelected = wpsSelectionModel.isNodeSelected(wpsNavNode); %>

    • id="portalSelectedNode" onmouseover="showPageAffordance(); return false;" onmouseout="hidePageAffordance(); return false;" <% } %> >
      "
      <% if (openInNewWindow) {%>target="_blank"<% } %> <% if (isNodeSelected) { %>onfocus="showPageAffordance()" <% } %> >


      . . . . . . .



    • "
      <% if (openInNewWindow) {%>target="_blank"<% } %>>





    • 2) "Touch" the Default.jsp for the theme (located in the same directory) by editing the file (nature of edit does not matter) and then saving the file.
      3) Remove any temp files for the theme in /temp//WebSphere_Portal/wps/wps.war/themes/html/.
      4) Start WebSphere Portal.
      5) Click on the URL link and it should now open a new window.

    Tuesday, September 15, 2009

    Portlet configuration preference layers and portlet modes

    Portlet configuration preference layers and portlet modes
    Type of configuration Description Portlet mode
    Deployment descriptor preferences They are associated with a deployed portlet, represented by a tag in portlet.xml. They apply to all occurrences of that portlet on all pages for all users.
    Administrator preferences They are associated with a portlet definition, that is a particular copy of a portlet. They apply to all occurrences of that portlet definition on all pages for all users. The administration portlets allow you to create multiple copies of the same portlet with different configurations on the administrator level. config
    Shared preferences They are associated with a particular occurrence of a portlet definition on a page and apply to all users who view the portlet on that page edit_defaults
    Personalized preferences They are associated with a single user and apply only to that particular user who views the portlet on the page. edit, view, help

    Sunday, September 6, 2009

    Using WSRP for distributing load

    One of the common gripes that I hear from portal customers is that it’s very expensive to scale portal. This can be true especially if the portlets suffer from ‘bloat’ and carry out more processing than they should. I know of one organisation here in the UK that was seriously considering abandoning WebSphere Portal to return to straightforward servlet development because of this.

    So it was with great interest that I attended a presentation today by Andreas Brunnert from the Boebligen lab about the portlet container that’s now part of WAS 6.1 and, soon, WAS 7. This offers an interesting solution to the above problem. The portlet container in WAS could be used to distribute load from (expensive) portal servers to (inexpensive) application servers.

    Another interesting consequence of having the portlet container in WAS is that stand-alone web applications can now be developed against the portlet API. That means that developers who don’t want portal can have their cake and eat it – all of the richness of Portlets’ state and context plus not having to worry about where the application will be deployed – portal, WSRP or stand-alone.

    The portlet container in WAS also provides an interesting option for unit testing new portlets, at least partially. Maintaining developer workstations with the right level of WAS and WebSphere Portal is quite a challenge, and there’s always someone in the team who can’t compile this or that portlet. Having a WAS image and using the URL Addressibilty to access the test portlet would simplify the platform that the developers have to handle.

    On a related note, I spent a very short time looking for a WSRP producer for .NET. I’ll have to ask my .NET colleagues but I wonder if wrappering .NET applications using WSRP might not be a way to handle migration and coexistence between the platforms.

    From Andreas’s presentation, I also noted that portal is moving towards being a more “traditional” WebSphere Application (much in the way that, say, Process Server is). That’d be nice, too.

    Saturday, September 5, 2009

    Apache + Active Directory Authentication How To

    Overview

    Use Kerberos integration to fetch valid users and their passwords from the Active Directory to authenticate access to a web directory served by Apache.

    System

    AD Server: correlads
    Web Server: correlprod
    Web Service: Apache2 + mod_auth_kerb
    Protected directory: /var/www/mrtg

    Configuration

    Apache + Kerberos

    • Verify that mod_auth_kerb is available on the system (/usr/lib64/httpd/modules/). If not install it: yum install mod_auth_kerb
    • Apache configuration /etc/httpd/conf.d/mrtg.conf:
    LoadModule auth_kerb_module modules/mod_auth_kerb.so
    Alias /mrtg /var/www/mrtg

    Order allow,deny
    Allow from all


    AuthName "Kerberos Login"
    AuthType Kerberos
    Krb5Keytab /var/www/html/mrtg/auth_kerb.keytab
    KrbAuthRealm CORRELSENSE.COM
    KrbMethodNegotiate off
    KrbSaveCredentials off
    KrbVerifyKDC off
    Require valid-user

    • Create a Kerberos keytab file and make it readable by all /var/www/html/mrtg/auth_kerb.keytab:
      HTTP/correlnx.correlsense.com@CORRELSENSE.COM
    • Kerberos configuration /etc/krb5.conf:
      [logging]
      default = FILE:/var/log/krb5libs.log
      kdc = FILE:/var/log/krb5kdc.log
      admin_server = FILE:/var/log/kadmind.log

      [libdefaults]
      clockskew = 300
      default_realm = CORRELSENSE.COM
      dns_lookup_realm = true
      dns_lookup_kdc = true

      [realms]
      CORRELSENSE.COM = {
      kdc = correlads
      default_domain = correlsense.com
      kdc = correlads
      }

      [domain_realm]
      .correlsense.com = CORRELSENSE.COM
      correlsense.com = CORRELSENSE.COM

      [kdc]
      profile = /var/kerberos/krb5kdc/kdc.conf
    • Restart Apache. When accessing mrtg page an authentication in front of the Active Directory is required.

    Portal JSR

    Portlet JSRs

    The Portlet specification will define a Portlet API that provides means for aggregating several content sources and applications front ends. It will also address how the security and personalization is handled.

    Portlets are web components -like Servlets- specifically designed to be aggregated in the context of a composite page. Usually, many Portlets are invoked to in the single request of a Portal page. Each Portlet produces a fragment of markup that it s combined with the markup of other Portlets, all within the Portal page markup.

    The Portlet specification will define the different components for Portal Computing, their interaction, lifecycle and semantics. These components will comprise -but they will not be restricted to-: Portlets, Deployment descriptor, Portlet APIs. In addition, APIs for vendor extensions, APIs for security, user customization and layout management will be considered. Also, it will define the minimum set of possible window states for a Portlet such as normal, minimized, maximized, etc.-, the valid state transitions and Portlet modes (such as view, edit, help, configure) per markup language.

    This first version of the Portlet specification will concentrate in the following design goals:

    • Client agnostic
    • Support for multiple types of clients (multi-device)
    • Simple Portlet API
    • Support for Localization and Internationalization
    • Hot deployment and re-deployment of Portal applications
    • Declarative security (same as to the mechanism found in Servlet and EJB specs)
    • Architected to support remote execution of Portlets
    The Portlet specification will be based on the Servlet specification. It is envisioned that the developer API will be similar to the Servlet API. The Portlet specification will restrict the use of functions provided by the Servlet API to a subset that makes sense for components providing fragments of a markup page. Portlets would be able to obtain from their context -via the Portlet API- functions like access to user profile information for the current user, participation in the portal window and action event model, access to web client information, sharing of information with other Portlets and a standard way of storing and retrieving per-user/per-instance Portlet data persistently. The API will provide a URL-rewriting mechanism for creating links to trigger actions within a Portlet without requiring knowledge on how URLs are structured in the particular web application. Portlets would be grouped in a Portal Application by bundling them in a single WAR with a Portlet deployment descriptor file. In addition, the API will provide a mean for sharing data among Portlets of the same Portal Application. Like the Servlet specification, the Portlet specification will allow access to Enterprise Information Systems without imposing restrictions on the type of protocols. It is an important goal that the design of the Portlet specification would allow implementations to support remote Portlet execution. This design would not address the transport protocol for the remote execution of Portlets, leaving to the specific Portal implementations the support for Portlet remote execution. For example, a proxy Portlet could be used to invoke a remote Portlet.
    JSR 168

    The Java Portlet Specification V1.0 introduces the basic portlet programming model with:

    • two phases of action processing and rendering in order to support the Model-View-Controller pattern.
    • portlet modes, enabling the portal to advise the portlet what task it should perform and what content it should generate
    • window states, indicating the amount of portal page space that will be assigned to the content generated by the portlet
    • portlet data model, allowing the portlet to store view information in the render parameters, session related information in the portlet session and per user persistent data in the portlet preferences
    • a packaging format in order to group different portlets and other J2EE artifacts needed by these portlets into one portlet application which can be deployed on the portal server.

    JSR 286

    JSR-286 is the Java Portlet specification v2.0 as developed under the JCP and created in alignment with the updated version 2.0 of WSRP.[1] It was developed to improve on the short-comings on version 1.0 of the specification, JSR-168. Some of its major features include:[2]

    • Inter-Portlet Communication through events and public render parameters
    • Serving dynamically generated resources directly through portlets
    • Serving AJAX or JSON data directly through portlets
    • Introduction of portlet filters and listeners

    Best Practices – Build and Deployment

    Table of Contents
    1. Introduction 1
    2. Lessons Learned 1
    3. Web Services Standards Gap 3
    4. Tools Gap 3
    5. Design Constraint Implications 3
    6. Best Practices & Recommendations 4
    6.1 Using open source tools ANT and DPTK 4
    6.1.1 Ant 4
    6.1.2 Design Pattern Toolkit (DPTK) 4
    6.2 Deployable Portal Artifacts 4
    6.3 The Build and Deploy Sequences 7
    6.4 Interaction between the Architecture Layers 12
    7. Conclusion 13 5/24/2005 10:15 AM


    1. Introduction
    One of the goals of the IE Pilot project was to demonstrate building and deploying the various development artifacts in a repeatable way. This was accomplished using a process that was developed to ensure quality by automating as many of the build and deploy processes as possible. The high level procedure can be described as follows:
    • Developers check-in various artifacts into a version control system (java code, JSPs, deployment descriptors, etc.)
    • Developers also check-in build and deployment scripts for each artifact. (The creation of the build and deploy scripts is automated with a pattern-based toolkit.)
    • For build and deployment, the system operator of a target environment (such as an integration, QA, or production system) will then request a specific version of artifacts from the version control system, and make a local copy.
    • The system operator will then update any properties (in the build properties file) and invoke the build and deployment scripts (which were included with the code).
    • The system operator then checks-in to version control the log files which contain the build and deployment execution results.
    This process ensures that build and deployment can be repeated easily on different platforms, and there is an audit trail. If a problem occurs, developers can look at the build log and assist with problem determination.
    2. Lessons Learned
    During the IE Pilot, we have acquired deep knowledge with the tools and their capability, as well as the run into road-blocks of which we have overcome. These are very lessons that should be captured and shared with the development, and are listed as follows:
    • Developers develop using specific server names or IP addresses, but when you deploy you must specify a different target server. These server names should be set as properties (e.g. portlet init parameters).
    • Model Driven Architecture (MDA) works well for build & deploy automation. Using MDA we were able to quickly automate the process of creating build and deploy scripts (batch files, UNIX script files, ANT files, XMLAccess command files, etc.). We leveraged the features provided by Eclipse and the Design Pattern Toolkit (DPTK), and built reusable patterns for generating the following artifacts:
    o Portlet scripts to: add/delete/update/export/activate/deactivate portlets
    o Portal Page scripts to: add/delete/update/export pages
    o Portal Theme scripts to: package and un-package the theme files
    • Use Interaction Diagrams to model build & deploy processes. Interaction diagrams provide a way to capture the sometimes complex interactions between people and systems. Also, this kind of diagram helps to identify opportunities for automation (new patterns).

    • Use Portal’s “Custom unique names” feature for portlets and pages. The Portal product includes an administrative portlet for assigning custom names to system elements, such as pages and portlets, which are easier to remember than the system-generated IDs. When developing a script to export a page definition, for example, you can use the custom unique name you assigned to the page, and this name can be the same across environments.

    • Be aware of user Distinguished Names (DNs) in exported files. Some deployment files (such as page definitions) contain LDAP DNs of users. The ‘owner’ of the page, for example, is part of the page definition when a page is exported to an xml file. These may be different between environments. An extra step may be needed to switch out the DNs in an exported file, before importing into a different system, if the new system is pointing to an LDAP that contains a different set of users.

    • The XMLAccess examples provided with Portal are useful for developing scripts. We used several of the example XMLAccess scripts in the directory: \doc\xml-samples to create our own scripts, and to create design patterns for use with the Design Pattern Toolkit which generate scripts for specific pages, portlets, themes, etc., based on a simple model file that described the unique things about those artifacts.

    • Create handy diagrams We found it very useful to create diagrams when faced with complex deployment relationships, for example, the relationships described in a portlet.xml deployment descriptor file are important to understand when creating deployment scripts, so we created the following chart, and color-coded parts according to whether they were needed during deployment, export, or delete operations: UIDPortletApp NameWARPortal AppDefConcretePortletPortlet App(web-app)PortletConcretePortletApp*hrefid*11WAR StructureDeployDeleteExportUIDName

    • It’s important to have several Portal installations to perform various kinds of testing and development:

    • Developers often need a full Portal installation (not just the Portal Toolkit that runs inside of Eclipse). Due to differences in the Toolkit and full-Portal environments, such as Java JVM version differences, most developers should install a full copy of Portal on their own workstations, to use in conjunction with the Portal runtime environment that runs inside Studio.

    • It’s useful to have an environment for configuring Global Security in the various Application Servers, and connect to the LDAP server to test schema and filter settings, as well as user and group access.

    • Another environment is required for Load and Stress Testing (LaST). It’s important to have a dedicated LDAP server and database server in this environment that mimic the production environment as much as possible.
    3. Web Services Standards Gap

    4. Tools Gap
    The WebSphere Portal Server administration can be accomplished in two ways. First is through the graphical admin console, and the second is using WPSConfig and XMLAccess.
    The graphical admin console is meant to be used by the portal administrator and he/she can use the graphical interface to interact with the portal components such as page, theme, and portlets. With the graphical admin console, you can also manage the portal security.
    XMLAccess is the XML configuration interface that allows you to import, export, and update (management) of portal components. XMLAccess can be use to perform any of the operations on the graphical admin console.
    XMLAccess complements the graphical admin console of portal and WAS. The operation on the graphical admin console is prone to errors. With the XMLAccess, the fully tested scripts can be easily repeated over and over again. However, XMLAccess has its limitation. The configuration as well as the command xml files for XMLAccess normally contains ‘static’ information. That means the administrator has to still perform manual changes to the configuration/command files in their management tasks, so that also is prone to error.
    The issue of reliability and duplicable can be resolved by the Design Pattern Toolkit (DPTK). See section 6.1.2 for more information on DPTK.

    5. Design Constraint Implications
    There were several design constraints that we limit us in design the build and deployment process for the IE Pilot. Mainly they are:
    Can’t automate the code generation of BPEL processes – Currently there is a known issue with the WSADIE’s code generation engine. The issue is that when trying to invoke the codegen engine, the activity will terminate with an exception – it is an internal but with the system. We’ve captured it and opened a defect with our tools vendor (IBM). Until it is addressed in future fix-packs, the build engineer has to invoke the codegen from within WSADIE and has the option of compiling and packing the artifacts inside the Studio or run the conventional Ant build script from the command line (on the generated classes).
    Because of the inability to fully automate some aspects of the build & deploy process, only the portal deployment/management is fully implemented using Ant and DPTK.

    6. Best Practices & Recommendations

    6.1 Using open source tools ANT and DPTK
    We recommend using Ant and DPTK together as the new build and deployment paradigm.

    6.1.1 Ant
    Ant is an open source build tool that is very popular in the development community. Ant is popular because it is extended using Java classes. Instead of writing shell commands, the configuration files are XML-based, calling out a target tree where various tasks get executed. Each task is run by an object that implements a particular Task interface.
    The latest version of Ant, version 1.6.2 has been exported to support the checking/checkout of Clear Case that enables you to perform all activity of build with just one call.

    6.1.2 Design Pattern Toolkit (DPTK)
    When performing build and deployment, our goal was to create a repeatable, automated process. Since there are several artifacts that require step-by-step procedures, we desired a way to automatically create the build and deployment scripts for each artifact, given just the minimum information required. We used the Design Pattern Toolkit, an Eclipse plug-in, in order to achieve these goals.

    • The DPTK is based on MVC pattern. The model is the .appdef that the controller is driving off from. The controller will iterate through the XML tags defined in the .appdef and perform the appropriate view. Together, they form a particular pattern.
    A set of ‘patterns’ were developed, which follow Model Driven Architecture (MDA) principles, and allow us to generate build and deployment scripts for each artifact.

    6.2 Deployable Portal Artifacts
    There are several Portal components that require a build process, a deployment process, or both. The following table describes each artifact:
    Artifact Name
    Description
    Packaging
    Build Needed?
    Deployment Process
    Portlet
    The java code, JSPs, image files (gifs), and deployment descriptors (web.xml, portlet.xml) needed to render a Portlet
    Web Application Archive (WAR)
    Yes (java compile, WAR packaging)
    XMLAccess (a portal-specific xml-based deployment program)

    Page
    A Portal Page definition, which contains the layout design of portlets on the page, as well as permissions (ACLs) for the page, and a Distinguished Name of the ‘owner’ of the page, and a ‘theme’ that will be used for the page.
    An XML file.
    No, page definitions are built with the Portal’s page creation tools (using a web based GUI) and exported as a single XML file.
    XMLAccess
    Theme
    A Portal artifact that provides the ‘outer shell’ of the page display. This includes navigational elements (tabs for pages), the branding, and really anything that isn’t provided by portlets. The top two page levels in the portal page hierarchy can be associated with a theme. All sub-pages inherit the theme of the parent.
    A directory tree, containing image files and JSP files. (WAS_ROOT/installedApps/ NODE/wps.ear/wps.war/ themes/THEME_NAME)
    Yes. The themes are a part of the Portal’s own EAR file. Therefore, if you want to add new themes, you must repackage and redeploy the wps.ear file.
    EarExpander
    Skin
    A portal artifact that provides the shell around a portlet. Each portlet on a page can have a different skin. Skins control the look of the buttons, the title bar, and the border around the portlet (if any).
    A directory tree, containing image files and JSP files. (WAS_ROOT/installedApps/ NODE/wps.ear/wps.war/ skins/SKIN_NAME).
    Yes. The skins are a part of the Portal’s own EAR file. (Requires repackage and redeploy of wps.ear.)
    EarExpander
    Screens
    Standalone pages that don’t contain portlets. The Login page, the Self Care pages, and the Error page are examples.
    One or more JSP files. (WAS_ROOT/installedApps/ NODE/wps.ear/wps.war/ screens/html/ SCREEN_NAME.jsp).
    Yes. The screens are a part of the Portal’s own EAR file. (Requires repackage and redeploy of wps.ear.)
    EarExpander
    Portlet configuration
    There are several roles related to portlet usage and management that can be assigned to users and/or groups. These roles are assigned to portlet applications (not instances.) Typically these ACLs are assigned
    Can be exported to an XML file. (The runtime ACLs are stored in the Portal’s admin repository, eg. Oracle).
    No.

    XMLAccess

    using the Portal Admin GUI, and then exported to an xml file.
    In addition, the deployment order of these artifacts is important. There are dependencies among them, so it’s important to deploy them in the following orders:

    Artifact
    Dependencies
    Portlet
    none
    Page
    Portlets, theme, owner, other users based on assigned ACLs
    Theme
    none
    Skin
    none
    Screen
    none
    Portlet Config
    Owner, other users based on assigned ACLs
    For the IE Pilot, we have identified the followings as the need to be generated and tracked.:
    Script Name
    Description
    XMLAccess command file
    The Portal deployment tool, XMLAccess, requires a command file in order to perform an operation. This command file describes the type of action to perform (import, export, etc.) and the specific page, portlet, etc. to act upon.

    ANT file
    We found it convenient to use ANT (a popular scripting tool available on apache) to kick off the XMLAccess task. Portal provides a tools.jar file that contains an XMLAccess ANT task, making it easy to call XMLAccess from within ANT. Other operations, such as copying files, echoing status, and version control system calls are often easier to perform in ANT. ANT scripts are portable across Windows and UNIX platforms.

    ANT .properties files
    The .properties file stores information about paths, user names, passwords, and URLs. Since these settings are often different across environments (testing, QA, Load And Stress Test, production), having a properties file for each makes script easier to maintain.
    .BAT and .SH scripts
    These are used to kick off the ANT tasks. The ‘setupCmdLine” script from WebSphere App Server is first called, to ensure that the proper environment is set up for Java and ANT.
    The following diagram depicts the relationship between the programs, properties file, and the output file:

    environment
    DOS Batch file
    ANT script
    Unix Shell file
    results.out
    XMLAccess
    xmlAccess.command.x
    Portal Admin Servlet
    Portal Admin Repository DB

    6.3 The Build and Deploy Sequences
    In order to visualize the interaction between the activities involved in building and deploying Portal artifacts, it’s helpful to model the steps using an interaction diagram.

    The deployment operations performed by a Deployment Engineer would follow this series of steps to gather files, publish them to a target server, and execute the scripts that will perform the deployment:
    : Deploy Engineer : Build Area : ClearCase : Target Area Areaget: artifactsartifacts (EAR, WAR, JAR)get: scriptsftp: artifacts & scriptsexecute scriptsscripts

    The following diagram shows how two actors, a Developer and a Build Engineer, cooperate to prepare for deploying a portlet:
    : Portlet Developer : WSAD : ClearCase : Build Engineer : Build Area Areaportlet codeweb.xmlportlet.xmlcheck in: portlet codecheck out: portlet codeweb.xmlJSP, Java, images, and descript...buildapply patternportlet scriptscheck in: portlet scripts.warPortlets now ready to be deployed to the design server. WAR file and scripts will be FTP and executed.
    Figure 1 - Portlet Check-in and Preparation for Build

    Theme development and deployment is depicted below:
    : Theme Developer : WSAD : Design Server : ClearCase : Build Area : Build Engineer Engineercreate projectimport base themecustomize themeexport "project to filesystem"add theme in Admin Portal (name, location)use theme in a test pagetest themegenerate scriptscheck in: themes and scriptscheck out: themes and scriptsthemes and scriptsftp: theme & scriptsre-package wps.warwps.warThe re-packaged wps.war will contain the new theme(s) under the appropriate fol...
    Figure 2 Theme Development and Deployment

    Page Development is performed by a Site Designer, who works with a Business Expert to place and organize Portlets on the page. Once the layout is complete, the page definition is checked-in to version control:
    : Site Designer : Use Cases Guy : Design Server : WSAD : ClearCase ClearCaseget: layoutpage layout, ACLcreate page (theme, name in different language)place portlets on pageadjust page settingsassign ACLassign unique name for pagecreate projectFile -> New -> Other -> DPTK -> SampleAppdefset name, uniq name, and version in Appdefapply patterngenerate scriptscheck in: scriptsscriptsftp: page export scriptexecute scriptpage.xmlcheck in: page.xmlPage now ready to be deployed on target server. To deploy, need to ftp the scripts, as well as the page.xml to the target and execute the script using the generated .bat or sh script.

    Figure 3 - Page Development and Check-In

    Sometimes artifacts that have been deployed previously just need to be updated. For example, a page might have a portlet added to it by a developer in an integration environment, and the updated page xml file needs to be loaded into a production environment. The following diagram shows how a Site Designer could work with a Use Case (business requirements) person to update a page definition and check-in the file to the version control system:

    : Site Designer : Use Cases Guy : Design Server : ClearCase ClearCaseUpdated page now ready to be deployed. To deploy, ftp the scripts as well as the page.xml to the target server and run the generated .bat or sh script.get: layoutpage layout, ACLplace portlets on pageadjust page settingsassign ACLassign unique name for pageftp: page export scriptexecute scriptpage.xmlcheck in: page.xmlextract scriptpage export script

    Figure 4 - Page Update

    6.4 Interaction between the Architecture Layers
    In order to understand the build and deployment environment of the IE Pilot, it is important to understand that there are three main components of the system which interact with each other:
    1. Portlets – these are applications that users interact with directly on the web.
    2. Web Services – implement the business logic and access back-end systems.
    3. Business Processes – these run inside Process Choreographer’s Business Process Engine, which models and executes business workflows.
    The following diagram shows how these components work together at a high level:

    7. Conclusion
    In this white paper, we shared the lessons we learned from developing the build and deployment process and DPTK pattern generation. We also have a discussion on the artifacts for the components of which we are using to help us plan and implement the deployment templates.

    How do you display additional attributes on the Person Card?



    You have configured the People Finder portlet. You then search for a user, and you have the ability to display the Person Card by hovering over the search results. You are able to see the Person Card but want to display additional attributes on the Person Card. How can this be achieved?

    Answer
    To display additional attributes for the Person Card, perform the following actions:
    1. Modify the CSEnvironment.properties file (/PortalServer/config/config)

    2. Locate the CS_SERVER_PERSONTAG.businessCardItems property.

    3. Modify the string after the property with valid Member Manager attributes separated by commas (,).
      The attributes appear when a person card link is clicked, top to bottom, in the same order in which you type them.

      Example:
      CS_SERVER_PERSONTAG.businessCardItems=ibm-primaryEmail, ibm-jobTitle, telephoneNumber
    4. Save the properties file.

    5. Restart the portal server.

    You should now see these additional attributes on the Person Card.