WebSphere Portal and HATS

IBM® WebSphere® Portal gives you a single point of access to Web content and applications, personalized to each user's needs.

HATS integration with WebSphere Portal lets data flow freely between HATS, WebSphere Portal, and other Portal applications. All of the relevant features of WebSphere Portal are also available for exploitation within HATS by built-in tooling or straightforward Java™ development. The majority of HATS functionality is preserved when running HATS in the WebSphere Portal environment. See HATS portlet considerations and limitations for more information.

HATS applications can run directly within WebSphere Portal as portlets, enabling WebSphere Portal and HATS to interact directly. You can develop HATS portlets that comply with the IBM Portlet API, or with the standard Java Portlet Specification API (JSR 168), hereafter referred to as the standard portlet API.

Note:
Throughout this document, HATS portlets that comply with the standard portlet API (JSR 168) are referred to as standard portlets.

HATS Business Logic classes are able to use the WebSphere Portal APIs, and HATS JSPs are able to include WebSphere Portal JSP tag libraries. For more information about programming portlets and advanced portal features, refer to the HATS Web Application Programmer's Guide.

A HATS portlet project is targeted at transformation oriented applications. For adapting Model 1 Integration Object based applications to run in WebSphere Portal, refer to the HATS Web Application Programmer's Guide. For converting Struts Integration Object based applications to run in WebSphere Portal, refer to the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp, and search on Struts.

For more information and help regarding the Portal Tools, select the Help menu on the Rational® SDP toolbar and select Help Contents. Click Developing portal and portlet applications from the help list on the left to access documentation for portlet developers.

Creating HATS portlets

There are two ways in which you can create a HATS portlet:

Creating a new HATS portlet project

To create a new HATS portlet project, launch the Create a Project wizard using one of the following actions:

In the Create a Project wizard, on the HATS Project panel:

  1. Enter a name for the portlet project.
  2. Optionally, enter a description.
  3. Accept the default location.
  4. Select Web to indicate this is a Web project.
    Note:
    If the Web deployment option is disabled, this indicates that no server runtimes are defined. To define server runtimes, go to Window > Preferences > Server > Runtime Environments and add at least one runtime definition.
  5. For the Target server field, select one of the supported WebSphere Portal servers, WebSphere Portal v6.0 or WebSphere Portal v6.1.
    Notes:
    1. Generally, portlets targeted for WebSphere Portal v6.0 can be deployed and run on WebSphere Portal v6.1. For more information refer to the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp and search on Planning for migration.
    2. Standard portlets targeted for either WebSphere Portal v6.0 or v6.1 can also run on WebSphere Application Server v6.1 or v7.0.
  6. For the Enterprise application project field, enter the name of the EAR project to use for testing in the local test environment.
    Note:
    Standard and IBM portlet projects can be added to the same EAR project.
  7. For the Portlet API field, select JSR 168 Portlet or IBM Portlet to indicate with which API this portlet will comply.
    Note:
    If IBM Portlet is selected a warning is displayed that this API has been deprecated.
  8. Select whether to include administrative console support files.
    Note:
    This option is not supported for HATS standard portlets.
  9. Click Next and continue creating your project as normal.

This will generate a single HATS portlet project including an EAR project that can be used for testing with a local test environment.

Generating portlets from HATS Web projects

In order to allow an existing HATS Web project to run as a portlet, the structure and content of the HATS project must be altered to meet the portlet specification. The HATS Toolkit automates the process of converting a regular HATS Web project into a portlet. The Portal Tools feature of Rational SDP is a prerequisite for this conversion process.

To generate a HATS portlet project from an existing HATS Web project, in the HATS Projects view, right-click the Web project and select Generate Portlet Project.

In the Generate Portlet Project wizard, on the Portlet Project Generation Options panel:

  1. Enter a name for the portlet project.
  2. For the Target server field, select the target WebSphere Portal server, WebSphere Portal v6.0 or WebSphere Portal v6.1.
    Notes:
    1. When generating a HATS portlet project from a HATS Web project, the target server of the Web project determines the target server options for the portlet project. If the target server of the Web project is WebSphere Application Server v6.0, the target server options for the generated portlet project are either WebSphere Portal v6.0 or v6.1. If the target server of the Web project is WebSphere Application Server v6.1, the target server option for the generated portlet is WebSphere Portal v6.1. If the target server of the Web project is WebSphere Application Server v7.0, there is no option to generate a portlet.
    2. Generally, portlets targeted for WebSphere Portal v6.0 can be deployed and run on WebSphere Portal v6.1. For more information refer to the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp and search on Planning for migration.
    3. Standard portlets targeted for either WebSphere Portal v6.0 or v6.1 can also run on WebSphere Application Server v6.1 or v7.0.
  3. For the Enterprise application project field, enter the name of the EAR project to use for testing in the local test environment.
    Note:
    Standard and IBM portlet projects can be added to the same EAR project.
  4. For the Portlet API field, select JSR 168 Portlet or IBM Portlet to indicate with which API this portlet will comply.
    Note:
    If IBM Portlet is selected a warning is displayed that this API has been deprecated.
  5. Select from this list the types of files to be automatically converted:
  6. Click Finish.

A HATS portlet project will be created from the selected Web project. Once the portlet is created, additional customization can be done. For more information about modifying HATS projects, see Modifying a HATS project.

Notes:
  1. If you convert a HATS Web project to a HATS portlet project, you may have to manually modify the Web Express Logon (WEL) configuration file (hatswelcfg.xml) if the plug-ins configured for the Web project are not supported for the portlet project. It is recommended that you use the WEL configuration user interface to add supported plug-ins so that the WEL configuration file (hatswelcfg.xml) is updated properly.
  2. After generating a HATS portlet project from a HATS Web project, changes made to one project are not reflected in the other. You can always generate a new HATS portlet project from a changed HATS Web project to reflect changes made in the Web project.
  3. You cannot convert a HATS portlet project back into a HATS Web project.
  4. If you have an existing HATS V4, V5, V6, V7.0, or V7.1 application, you must migrate your application to HATS V7.5.1 before generating a portlet project. For more information about migrating to HATS V7.5.1 see Migrating to HATS V7.5.1.

Migrating IBM portlets to standard portlets

Migrating a HATS IBM portlet to a HATS standard portlet must be done manually. The steps involve:

  1. Migrating project facets.
  2. Migrating Web and portlet deployment descriptor files.
  3. Migrating transformations, templates and macro handlers.
  4. Migrating HATS specific files.
  5. Migrating other portal functions (optional).

Migrating projects facets

  1. If it is included, remove the Struts facet since HATS standard portlets do not support Struts.
    1. In the HATS Projects view, right-click the portlet project and select Properties.
    2. On the Properties page, select Project Facets.
    3. If selected, clear the check box for Struts for IBM portlets.
    4. Click OK.
  2. Replace the IBM Portlets facet with the JSR Portlets facet.
    1. In the HATS Projects view, right-click the portlet project and select Properties.
    2. On the Properties page, select Project Facets.
    3. Clear the check box for IBM Portlets and select the box for JSR Portlets. In the Version column, be sure 1.0 is displayed. If not, click the drop-down icon next to the version number and change it to 1.0.
    4. Click OK.

Migrating Web and portlet deployment descriptor files

  1. In the Navigator view, edit the Web deployment descriptor (Web Content/WEB-INF/web.xml) and perform the following steps:
    1. On the Servlets tab, remove yourportlet and HATSAdminServlet (if present) servlets and mappings.
    2. On the Variables tab in the Tag Lib References section, remove the admin.tld tag lib reference if present.
    3. On the Variables tab in the Tag Lib References section, add an std-portlet.tld tag lib reference using the following settings:
      URL: http://java.sun.com/portlet
      Location: /WEB-INF/tld/std-portlet.tld	
  2. In the Navigator view, edit the portlet deployment descriptor (Web Content/WEB-INF/portlet.xml) and perform the following steps:
    1. Migrate to a standard compliant portlet deployment descriptor. For how to do this, refer to the section, Migrating from the IBM Portlet API, in the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp.
    2. Remove the EntryPortlet (your portlet) and all its references in the portlet deployment descriptor.
    3. Add the Jsr168EntryPortlet to the portlet deployment descriptor. See the portlet deployment descriptor from a sample HATS JSR 168 portlet.

Migrating transformations, templates and macro handlers

In the HATS Projects view, edit all of the transformation, template, and macro handler JSP files and on the Source tab:

  1. Add the following code:
  2. Convert response.encodeUrl("...") to renderResponse.encodeUrl(renderRequest.getContextPath()+"...").
  3. Convert all instances of request to renderRequest.

Migrating HATS specific files

  1. Import all the files from the <shared_install_directory>\plugins\com.ibm.hats_nnn\predefined\ projects\portlet\jsr folder to their corresponding folders in the portlet project (where shared_install_directory is the shared resources directory where you installed the HATS offering using IBM Installation Manager, and nnn is the version and build level of HATS).
  2. In the Navigator view, delete the following files and folders, if present:
    1. The HATSApplet.cab and HATSApplet.jar files in the Web Content folder.
    2. The hatsadmin folder in the Web Content folder.
    3. The hatsadmin.tld file in the Web Content/WEB-INF/tld folder.

Migrating other portal functions

  1. If using Web Express Logon (WEL), you may need to change the WEL plug-in classes because some plug-in classes for IBM portlets and standard portlets are different.

    For example, WEL plug-in classes used in IBM portlets are:

    WEL plug-in classes used in standard portlets are:

  2. If you implement credential vault in your portlet application, you must migrate the code that accesses the credential vault service. For more information, see the section, Portlet authentication, in the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp.
  3. If you implement portlet communication, you must convert the communication mechanism used. For more information, see Portlet communication.

Working with HATS portlets

A HATS portlet project is still a HATS project, meaning all the HATS wizards and editors can continue to be used on the project. A HATS portlet project is also a portlet project which also means all the Portal Tools editors and runtime configuration can be used on the project. A HATS portlet project appears in the tree with a different icon portlet folder icon.

Connection parameter and global variable overrides

You can allow connection parameters and global variables for your portlets to be overridden by customizing the project settings. For more information, see Connection parameter overrides and Global variable overrides.

IBM portlets

For HATS IBM portlets, if you allow overrides in the project settings, then overriding can be performed by extending the EntryPortlet class and overriding the doView() method. For more information about extending the EntryPortlet class see the HATS Web Application Programmer's Guide.

Standard portlets

For HATS standard portlets, if you allow overrides in the project settings, then the user can override connection parameters and global variables by switching to edit mode from the portlet's toolbar. For WebSphere Portal V6.0 and V6.1, select Personalize from the portlet menu on the toolbar.

Note:
HATS does not support portlet edit mode on WebSphere Application Server V6.1 or V7.0. If you deploy your HATS standard portlet to run directly on WebSphere Application Server V6.1 or V7.0, instead of using portlet edit mode, the user can override connection parameters and global variables in the URL used to access the portlet.

Once in portlet edit mode, a settings page is displayed for the user. This page allows the user to override connection parameter and global variable settings. These functions are equivalent to the HATS functions for Web applications that allow a user to override settings using the URL when the application is first accessed.

On the settings page, in the connection parameter section, the connection parameter drop-down lists the Host On-Demand session parameters that you allow to be overridden in the project settings. The user sets an override by selecting a parameter from the drop-down list, entering a value in the Value field, and clicking Add. By default, the override setting is enabled when first added. It can be disabled by selecting false from the Enabled drop-down. An override can be deleted by selecting the check box next to the parameter name and clicking Delete.

In the global variable section, the user sets an override by entering a global variable name and value, and clicking Add. After adding an override, the global variable can be identified as a shared global variable by selecting true from the Shared drop-down. By default, the override setting is enabled when first added. It can be disabled by selecting false from the Enabled drop-down. An override can be deleted by selecting the check box next to the global variable name and clicking Delete.

When the user clicks Save and Exit, the settings are saved in the portlet preferences.

Notes:
  1. The values entered by the user are not validated.
  2. The user must disconnect and restart the portlet application before the new values take effect.

In addition to allowing users to set overrides, you can programmatically provide connection parameter and global variable overrides by extending the HATS JSR 168 entry portlet. For more information, see the section, Extending the Entry portlet, in the HATS Web Application Programmer's Guide

Note:
If you supply connection parameter or global variable overrides through the extended portlet class and the user provides the same overrides using portlet edit mode, then the values provided by the user in edit mode override the values you supply in the extended portlet class.

.

Portlet communication

WebSphere Portal supports multiple ways for portlets to exchange or share information. For more information see the section, Portlet communication, in the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp.

This section describes the HATS support for WebSphere Portal portlet communication.

IBM portlets

HATS IBM portlets support the Click-to-Action implementation for providing a portlet communication solution. For more information, see the section, Cooperative portlets, in the HATS Web Application Programmer's Guide

Standard portlets

HATS standard (JSR 168) portlet support uses the WebSphere Portal cooperative portlet mechanism for providing a portlet communication solution.

JSR 168 portlets use properties to communicate with each other. A HATS JSR 168 portlet supports the ability to send properties to and receive properties from other JSR 168 portlets, HATS or non-HATS. Portlets must be wired in order to communicate.

Sending a property from a HATS JSR 168 portlet
  1. Create a global variable containing the value of the property to send. You can do this in several ways including: executing an Extract global variable action or a Set global variable action. Only global variables that can contain zero or more strings (no other type) can be used in JSR 168 portlet communication. Global variables can be thought of as wrappers for the values of JSR 168 properties.
  2. Add a Send global variable action to a HATS screen event or to an unmatched screen application event to send the value of the global variable as a property. For information about how to do this, see Send global variable action.

    This action can be used in conjunction with the Extract global variable action to send input entered by the user from one portlet to another. For example, you can add an Extract global variable action between the Apply transformation action and the Send global variable action to capture data the user enters and send it to other portlets.

  3. When the HATS JSR 168 portlet project is run and the Send global variable action is executed, the property name and the string contents of the specified global variable are passed to WebSphere Portal which then notifies the portlets wired to this HATS JSR 168 portlet to receive the property.
Receiving a property in a HATS JSR 168 portlet
  1. Use portlet settings to define property names and the corresponding global variables to contain the property values that can be received by this portlet. Access portlet settings from the Project settings editor by clicking the Other tab then Portlet. For more information about how to do this, see Portlet settings.
  2. Once WebSphere Portal has received a property from a source portlet, the target portlet is notified. The HATS JSR 168 portlet runtime service retrieves the property value from WebSphere Portal and stores it in the specified global variable. Again, only global variables that contain a string (or strings) can be used with JSR 168 communication.
Communicating with non-HATS JSR 168 portlets

Rational SDP provides GUI support to implement cooperative portlets. When configuring non-HATS JSR 168 portlets to communicate with HATS JSR 168 portlets, perform the following steps:

  1. Open the Project Explorer view from the Rational SDP menu bar by selecting Window > Show View > Other > General > Project Explorer.
  2. From the Project Explorer view, right-click the Portlet Deployment Descriptor node under the portlet project.
  3. Select Cooperative > Enable this Portlet to Send Data (Source) or Cooperative > Enable this Portlet to Receive Data (Target) to start the wizard to enable cooperative portlet support for the selected portlet.
  4. Ensure the following settings are correct in this wizard:
Editing the Data Type URI

When you configure a Send global variable action or a Portlet setting to receive a property, HATS defaults the Data Type URI for the property to be http://com.ibm.hats.portlet.pb#<property_name>Type. This URI is only used when you wire the source and target portlets. WebSphere Portal requires that the source and target portlets use the same URI in order to send and receive the property. If for any reason you need to configure the URI differently than the default, you can modify the URI for a property using the Portal toolkit by following these steps:

  1. Open the Project Explorer view from the Rational SDP menu bar by selecting Window > Show View > Other > General > Project Explorer.
  2. In the Project Explorer view, expand the project to the property that you want to modify. The properties can be found under the Portlet Deployment Descriptor node.
  3. Right click on the property and select Edit Data Type.
  4. Modify the Data Type URI in the Edit Cooperative Source or Edit Cooperative Target wizards.

Wiring portlets for communication

Portlet wires are used to direct the information flow between portlets that communicate using the WebSphere Portal Cooperative portlets API. Portlet wiring refers to connecting two portlets using the portal server's wiring tool for the purpose of sending and receiving a cooperative portlet property. Portlets are wired for only a single property and both portlets must give this property the same name although the associated global variable names can be different. In other words, if two portlets are going to send and receive two properties, they need two wires connecting them, one for each property. Without completing the wiring step, data is not transmitted.

Custom PDTs and custom tables

Before deploying a portlet project with a custom printer definition table (PDT) or custom tables to a portal server, you must copy files or folders to the \Web Content directory of the HATS portlet project. The files or folders for each type of addition are shown below:

Web Services for Remote Portlets

Web Services for Remote Portlets (WSRP) is a standard that portals can use to provide portlets, applications, and content as WSRP services, and other portals can integrate the WSRP services as remote portlets for their users. Standard and IBM HATS portlets can be provided as remote portlets that can be consumed by other portals. For more information, see the WebSphere Portal Information Center at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp and search on Using WSRP services.

Testing HATS portlets

If a WebSphere Portal Test Environment is configured in Rational SDP, you can use it to test your HATS standard or IBM portlets before you deploy them to a production Portal server.

You can also test your HATS standard portlets using the WebSphere Application Server V6.1 or V7.0 local test environment, as appropriate, before you deploy them.

To test a HATS portlet project, use the same procedure used for testing HATS Web projects. For more information see Overview.

Exporting HATS portlets

To export a HATS portlet for deployment, from the HATS Projects view right-click the portlet project and select Export Project. Enter the target file name for the exported .war file in the Destination drop-down, and click Finish. Only the .war file is exported. The .ear file is used only for testing in the local test environment.

Once you have exported your HATS portlet .war file, you install it into WebSphere Portal using the WebSphere Portal administration tools.

If installing a standard portlet into WebSphere Application Server V6.1 or V7.0, use the WebSphere Application Server administrative console and consider the following instructions:

Administering HATS portlets

You can administer HATS portlets using the HATS administrative console. HATS standard portlets, whether installed on Portal Server or WebSphere Application Server, can be administered using a stand-alone HATS administrative application. HATS IBM portlets can be administered using either a stand-alone HATS administrative application or using administrative console support included in the portlet itself.

Using a stand-alone HATS administrative application

To administer HATS standard and HATS IBM portlets using a stand-alone HATS administrative application, follow these steps:

  1. Create a stand-alone HATS administrative project in the HATS Toolkit by selecting File > New > Project > HATS > HATS Administration Project. The HATS administrative project only appears in the HATS Toolkit on the Navigator tab.
  2. Export the HATS administrative .ear project to an .ear file by right-clicking the .ear project and selecting Export > Java EE > EAR.
  3. Deploy the .ear file for the stand-alone HATS administrative application to WebSphere Application Server using the WebSphere Application Server administrative console.
    Notes:
    1. Install the .ear file to the same WebSphere Application Server system as the WebSphere Portal server. Where a standard HATS portlet is installed directly to WebSphere Application Server, install the .ear file to the same server.
    2. Ensure the module is mapped to the WebSphere Application Server, for example, server1, and not WebSphere Portal Server.
    3. For WebSphere Application Server V6.x, ensure the All Authenticated option on the Map security roles to users/groups panel is checked for the HATS Administrator role. For WebSphere Application Server V7.x, ensure the All Authenticated in Application Realm option is selected using the Map Special Subjects drop-down on the Map security roles to users/groups panel.
  4. The user id used to administer the portlets must be defined as a WebSphere Application Server administrative console user with Administrator authority. To do so, follow these steps:
    1. From the WebSphere Application Server administrative console, select Users and Groups > Administrative User Roles > Add (before WebSphere Application Server V6.1, select System Administration > Console Settings > Console Users > Add).
    2. Enter the user id used to administer the portlets and map the user id to the Administrator role.
    Note:
  5. Start the HATS administrative application using the WebSphere Application Server administrative console.
  6. Access the stand-alone HATS administrative console. For example, use the URL, http://<washostname>/<hatsadminprojectname>/hatsadmin/admin.
    Note:
    When accessing the HATS administrative console, you must use a different browser than the one being used to access the portlets.
    1. Select Getting Started > Management Scope.
    2. Click New.
    3. In the Host field enter the same host name as your target WebSphere Application Server host.
    4. In the Port field enter the BOOTSTRAP_ADDRESS port for your target server. To find the BOOTSTRAP_ADDRESS port for your target server, access the WebSphere Application Server administrative console and follow these steps:
      1. Select Servers > Application Servers.
      2. Click your target server (either WebSphere Portal server, or WebSphere Application Server, for example server1, in the case where a standard HATS portlet is installed directly to WebSphere Application Server.
      3. On the Configuration tab under Communications expand Ports.
      4. Note the BOOTSTRAP_ADDRESS port for your target server.
    5. Click OK.
    6. Select the newly added host.
    7. Do not select Manage all applications within the scope selected above.
    8. You can now see a list of HATS portlets. Use the HATS Administrative console to administer one portlet application at a time by selecting one from this list.

Using administrative support included in the portlet

To administer HATS IBM portlets using a portlet that includes HATS administrative console support, follow the steps below.

Note:
This option is not supported in HATS standard portlets.

  1. Create a HATS IBM portlet project in the HATS Toolkit by selecting File > New > HATS Project. In the Create a Project wizard for your IBM portlet select the option, Add administrative console support.
  2. Export the portlet project to a .war file by right-clicking it in the HATS Projects view and selecting Export Project.
  3. Deploy the .war file for the HATS IBM portlet to your WebSphere Portal server.
  4. Access the WebSphere Application Server administrative console where your WebSphere Portal server is installed.
    1. Select Applications > Enterprise Applications.
    2. Click the name of your HATS administrative portlet, then click View Deployment Descriptor.
    3. Note the PA_value in the deployment descriptor, for example, PA_#uaj0rfu (WebSphere Portal V6.0) or PA_projectname (WebSphere Portal V6.1).
    4. Select Servers > Application Servers.
    5. Click your WebSphere Portal server, on the Configuration tab under Communications expand Ports.
    6. Note the BOOTSTRAP_ADDRESS port for your Portal server.
  5. Access the HATS administrative console included in your portlet using the PA_value you noted above in the deployment descriptor. For example, use the URL, http://<portalhostname>/wps/PA_value/hatsadmin/admin.
    Note:
    When accessing the HATS administrative console, you must use a different browser than the one being used to access the portlets.
    1. Select Getting Started > Management Scope.
    2. Click New, in the Host field enter the same host name as your WebSphere Portal server host, and in the Port field enter the BOOTSTRAP_ADDRESS port for your WebSphere Portal server that you noted above. Click OK.
    3. Select the newly added host.
    4. Do not select Manage all applications within the scope selected above.
    5. You can now see a list of HATS portlets. Use the HATS Administrative console to administer only the portlet application in which the console is included.

HATS portlet considerations and limitations

Common considerations and limitations

Following is a list of considerations and limitations when working with either HATS IBM portlets or HATS standard portlets:

IBM portlet considerations and limitations

Following is a list of considerations and limitations when working with HATS IBM portlets:

Standard portlet considerations and limitations

Following is a list of considerations and limitations when working with HATS standard portlets: