Migrating to HATS V7.5.1

If you are a Host Publisher V4, HATS V4 LE, HATS V5 LE, HATS V4, V5, V6, V7.0, or V7.1 user, you can migrate your projects to HATS V7.5.1.

For information about migrating from HATS LE see Migrating from HATS LE.

If you are using a Host Publisher version before V4.0, you must first follow the instructions for migrating your Host Publisher applications to Host Publisher V4.0. Go to http://www.ibm.com/software/awdtools/hats/support/index.html and enter the search string "How to migrate Host Publisher". For more information, see HATS for Host Publisher users.

HATS migration

Migrating a HATS project from a previous release of HATS is a two step process.

  1. Import the project as project interchange file, or check it out from a code repository (such as CVS), into your HATS V7.5.1 workspace.
  2. Migrate the project using the HATS migration wizard.

Importing a HATS project

If you have a previous release of HATS installed, you must first export your project to either a zip file or a project interchange file before you can import and migrate it to HATS V7.5.1. See the documentation for your previous release of HATS for information about exporting HATS projects.

After you have exported your project from a previous release of HATS, then you must import it as a project interchange file into your HATS V7.5.1 workspace. For more information about importing HATS Web and rich client projects see Exporting and importing HATS Web projects and Exporting and importing HATS rich client projects.

Note:
A HATS V4 project exported as a zip file from WebSphere® Studio Application Developer (WSAD) V4 cannot be imported as a project interchange file and therefore cannot be subsequently migrated. A HATS V4 project exported as a zip file from WSAD V5 can be imported and migrated to HATS V7.5.1.

If you have stored your HATS projects in Rational® ClearCase®, you should create a snapshot view containing these projects and then import them into your HATS V7.5.1 workspace using File > Import > General > Existing Projects into Workspace. During the import, do not select the Copy projects into workspace option. After the projects are imported into your HATS V7.5.1 workspace, you have the option to migrate them to HATS V7.5.1. During migration, files that need updating are automatically checked out of Rational ClearCase.

Rational SDP workspace migration

The Rational SDP Workspace Migration wizard displays when a project is imported into the workspace and needs some level of Rational SDP migration. This wizard performs some basic Rational SDP project migration and if the project targets an unsupported runtime, forces you to choose a supported target runtime. In preparation for running the HATS Migration wizard, you should first run the Rational SDP Workspace Migration wizard.

Using the HATS Migration wizard

When you switch to the HATS perspective, if you have a project created from a previous HATS release in your HATS V7.5.1 workspace, you will get a message stating that the workspace contains a HATS project that needs to be migrated.

You should use the HATS Migration wizard to migrate this project to HATS V7.5.1 before investigating any errors shown in the Problems view because migration may eliminate some or all of these errors.

To use the HATS Migration wizard follow these steps:

  1. In the HATS Projects view, right-click on the project and select Migrate Project.
  2. If you have other projects from a previous HATS release that are associated with the HATS project you have selected to migrate, those projects will also be migrated, as well as any associated HATS .ear projects.
  3. Click OK to begin the migration.
  4. If the project does not have an associated .ear project, you must associate the .war project after the migration. To associate the .war project with an .ear project, see Moving HATS Web projects to a different .ear file.
Notes:
  1. After migration check the details on the Migration Report.
  2. If a HATS Web or portlet project being migrated has an unsupported target runtime (if the Rational SDP Workspace Migration wizard has not been run) or unsupported WebSphere facets, the HATS Migration wizard sets the target runtime and facets to the lowest supported WebSphere Application Sever level for Web projects and to the lowest supported WebSphere Portal server level for portlet projects. A message is displayed and logged stating the fact that the change was made.
  3. If, after migration, you receive an error indicating that the target runtime is not defined, edit the properties for the project and select the appropriate target runtime. To do this, right-click on the project and select Properties. From the Properties window select Targeted Runtimes. From the Runtimes list, select the appropriate runtime.
  4. Migrating your project from a previous HATS release to HATS V7.5.1 cannot be undone.

Migrating HATS transformations

When you migrate HATS projects from a previous release of HATS to HATS V7.5.1, transformations in the projects are migrated as well. Changes made to the transformations depend on the release of HATS you are migrating from. All transformations are saved in the MigrationBackup folder before being migrated.

Special considerations for HATS V4 components and widgets

HATS V5 introduced new components and widgets. HATS V4 components and widgets were supported but deprecated in both HATS V5 and V6. HATS V4 components and widgets are not supported in HATS V7.5.1. If you have HATS V4 components and widgets in your projects, during migration you are given the choice of migrating them to HATS V7.5.1 components and widgets or cancelling the project migration. If you choose to migrate, your project may render differently. Be sure to thoroughly test your migrated projects.

If you have HATS V4 subfile components and widgets, they are migrated to HATS V5 subfile components and widgets. If you have HATS V5 subfile components and widgets, they are left alone. There are new (more rich in function) subfile components and widgets for HATS V6 and later. You may want to investigate using the new components and widgets instead of the older ones. For more information, see Subfile.

In HATS V4 if you chose a function key component and rendered it with either a drop-down (selection) or a radio button (selection) widget, you had a choice either to use auto submit or to show a submit button. If you chose to show a submit button, when you migrate the HATS V4 project to HATS V7.5.1, the submit button no longer appears. In HATS V7.5.1 the capability to show a submit button has been removed.

All HATS V4 DefaultExtract/DefaultWidget pairs are migrated to HATS V7.5.1 Default Rendering. Because this mapping may not produce the originally intended results, HATS V7.5.1 migration displays and logs a message stating that a DefaultExtract/DefaultWidget pair was migrated to Default Rendering. In this case you should review the transformation and make any necessary adjustments.

Custom components and widgets that extend, or are paired with, HATS V4 components and widgets can not be migrated and maintain the original results. When HATS V7.5.1 migration detects this, it displays and logs a message stating that the transformation contains HATS V4 components and widgets that can not be migrated. In this case you must review the transformation and manually migrate it.

Special migration considerations

Auto advance

If in previous versions of HATS you enabled the auto advance function by adding the line turnAutoTabOn(); to the lxgwfunctions.js file, you must now use the Enable automatic field advance setting in the Client Settings section of the Other tab in the Project Settings editor. For more information, see Client settings.

Backup files

HATS migration creates a backup folder in the project directory called MigrationBackup. This folder contains copies of the files from the old project before they were overwritten by the migration process. These files are saved allowing you to compare and merge them with your new HATS V7.5.1 files. Do not worry if problems occur; these files are no longer used by the application. When you are satisfied that all the saved files have been compared and merged, you can delete the MigrationBackup folder.

Note:
Before you delete the MigrationBackup folder, you can publish a migrated project to WebSphere Application Server to test how it behaves. However, errors in the task list caused by the MigrationBackup folder may create problems when publishing to WebSphere Application Server. To avoid this, you can either remove the MigrationBackup folder from the project or allow applications containing errors to be published on a server. To allow applications containing errors to be published on a server, select Window > Preferences > Server > WebSphere Application Server from the Rational SDP menu bar and select Allow applications containing errors to be published on a server.

Button widget

If you migrate a project created prior to HATS V7.0.0.2, and you choose to implement the Enable foreground colors option, if you use a template that uses the blacktheme.css style sheet, you must manually update the blacktheme.css style sheet in one of the following ways:

  1. Remove the following line from the input.HATSBUTTON declaration:
    color: lime;
    This enables foreground colors to be rendered on function keys; however it causes other buttons generated by a HATS widget to render in a default color.
  2. Combine the color-related CSS declarations for each color. For example, change:
    .HBLUE {
           color: #3c9dff;
    }
    input.HBLUE {
           white-space: normal;
           letter-spacing: normal;
    }
    to
    .HBLUE, input.HBLUE {
            color: #3c9dff;
            white-space: normal;
            letter-spacing: normal;
    }
    Repeat this change for each color.

An alternative to manually editing the blacktheme.css style sheet is to create a new dummy project and copy the theme CSS files from this project into your project. Be aware that any changes you have made to your CSS files are overwritten.

EJB access beans

If you have existing HATS V5 projects that have EJB Access Beans, you may have compile or runtime errors that begin with "HPubReqCompleteEvent cannot be resolved." To correct this, regenerate the EJB Access Beans.

Field widget

If you want to use the Render using monospace font setting for the Field widget, and your project was originally created in a release earlier than HATS V7.0, you must update your CSS files as follows:

  1. Add the following class to the whitetheme.css, graytheme.css, monochrometheme.css, tantheme.css, and blacktheme.css files:
    .HF {
      font-family: courier new, monospace;
    }
  2. Remove font-family: monospace from all of the H-color (HATS color) classes of all CSS files.

Global rules

A new setting, enforceImmediacy, is added to any global rule imported into HATS V7.5.1 from HATS V5. When this setting is true, the global rule behaves as it did in HATS V5 when Nearest input field only is selected for the Transform option of the Find input fields by surrounding text pattern. When this setting is false, the default, the global rule behaves as it does in HATS V7.5.1.

To make newly defined global rules behave as the HATS V5 global rules did, you must add and set the enforceImmediacy setting to true. To do this, on the Source tab of the Project Settings editor, add the following setting to the globalRules componentSettings tag:

<setting name="enforceImmediacy" value="true"/>

Global variables

Before HATS V7, the value of a global variable, entered into a prompt inserted onto a transformation using the Prompt for global variable with input box option, might have been truncated because some characters were not escaped properly.

In this HATS version, global variable values prompted for by a transformation are properly escaped to prevent truncation. Global variables inserted onto a transformation using the Display global variable value as static text option are not affected by this change. Global variable prompts inserted onto a transformation in a version of HATS before HATS V7 are not automatically updated during migration, so they are not affected by this change.

HTTP compression

If you want to use HATS support for HTTP compression in projects migrated from HATS V5.0.x, V6.0, and V6.0.1, you must manually add the compression filter to the Web Deployment Descriptor file (web.xml). To add the compression filter to the web.xml file:

  1. From the HATS Toolkit, switch to the Navigator view of the HATS perspective.
  2. Open the web.xml file located in the Web Content\WEB-INF folder of your project.
  3. Click the Source tab to view the source of this file.
  4. Copy the following statements after the last defined servlet mapping (search for the last </servlet-mapping>).
    <filter>
       <description>Provides compression for output from HATS entry
                    servlet</description>
       <display-name>CompressionFilter</display-name>
       <filter-name>CompressionFilter</filter-name>
       <filter-class>com.ibm.hats.runtime.filters.CompressionFilter</filter-class>
    </filter>
       
  5. Copy the following statements after the last defined filter mapping (search for the last </filter-mapping>).
    <filter-mapping>
       <filter-name>CompressionFilter</filter-name>
       <servlet-name>EntryServlet</servlet-name>
       <dispatcher>ERROR</dispatcher>
       <dispatcher>FORWARD</dispatcher>
       <dispatcher>INCLUDE</dispatcher>
       <dispatcher>REQUEST</dispatcher>
    </filter-mapping>
    <filter-mapping>
       <filter-name>CompressionFilter</filter-name>
       <url-pattern>/</url-pattern>
    </filter-mapping>
    <filter-mapping>
       <filter-name>CompressionFilter</filter-name>
       <url-pattern>/index.jsp</url-pattern>
    </filter-mapping>
       
  6. Save the file.
Note:
If you have already run this project on the server, you will need to republish the application for WebSphere Application Server to pick up the change to the web.xml file.

IBM Tivoli License Manager

HATS, WebFacing, and HATS/WebFacing linked applications that are migrated to HATS V7.5.1 must be redeployed to the production environment to pick up IBM® Tivoli® License Manager support for the new HATS V7.5.1 signature file.

WebFacing Web applications

ITLM detects Web applications deployed as Enterprise Archives (EARs) to supported WebSphere Application Servers. Since WebFacing Web projects are created independently of associated EARs, the ITLM signature file must be included manually. Follow the steps below to enable the ITLM detection of WebFacing Web applications.

  1. Create a folder named itlm directly under your WebFacing project's associated EAR.
  2. Locate the signature file named HATS0705.sys2 in the HATS plugin directory
    <shared_install_directory>\plugins\com.ibm.hats_nnn\
    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.
  3. Copy the signature file from the plugin to the itlm folder you created earlier.
  4. Export your project as an EAR and redeploy. ITLM will now be able to detect your application.

If you enabled ITLM detection for an old WebFacing project and migrate that project to V7.5.1, you must remove the existing signature file (for example, WDHT0700.sys2 if the old WebFacing project is from V7.0) from project's associated EAR and add the V7.5.1 signature file (HATS0705.sys2) before redeployment.

Note:
WebFacing portlets are not detected because they cannot be deployed as EARs.

Java 2 security

During migration to HATS V7.5.1, the WebSphere Application Server Java™ 2 security was.policy file is overwritten. If you have customized the was.policy file in a pre-HATS V7.5 project, then you must re-customize the file after migration.

Keyboard mappings

In earlier versions of the HATS host terminal, the Pause key was mapped to the host's [clear] action. In the HATS V7, and later, host terminal, the Esc key is mapped to the host's [clear] action.

In versions of HATS earlier than HATS V6, Ctrl+R was used in bidirectional sessions to reverse the screen. In HATS V6 and later, Ctrl+R is mapped to a host RESET for both bidirectional and non-bidirectional sessions, and Alt+Enter is mapped to reverse for bidirectional sessions.

Rich client applications

Lotus Notes keyboard bindings

If you migrate to HATS V7.5.1 a pre-HATS V7.5 rich client project that is targeted for Lotus® Expeditor, the keyboard mappings for Lotus Notes® are added to the project. These keyboard mappings are also added to projects targeted for Lotus Expeditor if you update your HATS V7.5.0.x installation to V7.5.1 using IBM Installation Manager.

Launch configurations

After migrating a rich client project, if you are unable to launch it in the test environment, create a new launch configuration to use in the test environment. To do this, in the HATS Projects view, right-click the project and select either Run or Debug. The Run (or Debug) Configurations window is displayed. If the project is targeted for Eclipse RCP, right-click on Eclipse Application and select New. If the project is targeted for Lotus Notes or Lotus Expeditor , right-click on Client Services and select New. Modify the launch configuration name and location if desired. You can delete old launch configurations from this window as well. Click Run (or Debug) to launch the project in the test environment.

Themes

Rich client applications that use the Classic terminal emulator theme will have the Arrow key navigation setting enabled after migration.

Non-US English strings in templates and transformations

Non-US English strings included in templates and transformations of a HATS rich client project built with HATS V7.0 or V7.0.0.1 are not compiled correctly when the project is exported as a feature. To work around this problem, after migrating the project to HATS V7.5.1, edit the build.properties file located in the root folder of the project. Add the following line at the bottom of the build.properties file:

javacCustomEncodings.library.jar = src/rcpproject/templates/[UTF-8],
 src/rcpproject/transformations/[UTF-8]

Where rcpproject is the name of the rich client project.

Runtime enablement

To fully enable the HATS V7.5.1 runtime for production, you must specify your license settings using the License Settings wizard. You must do this even for projects whose runtimes were fully enabled in previous versions of HATS. For information about specifying license settings, see Enabling HATS runtime and license settings in HATS Getting Started

Note:
HATS Web applications whose runtimes are not fully enabled are restricted to just two runtime host connections. HATS rich client applications whose runtimes are not fully enabled allow unlimited host connections in the local test environment but no host connections in a deployed production environment.

Secure Sockets Layer (SSL)

During migration, HATS V7.5.1 converts SSL certificate class files, CustomizedCAs.class files, to PKCS12 keystore files with the names appname-CustomizedCAs.p12 and passwords of hats, where appname is the project name. After migration, you should use the Certificate Management tool (also known as IBM Key Management or iKeyMan) to change the passwords for the new keystore files and verify them using the connection editor. For more information, see Security.

Testing modes

Starting with HATS V7, the Run on Server (for Web projects) and Run (for rich client projects) testing modes can be used to modify and test the runtime settings that are deployed to the production environment. Be aware that any changes made to the runtime settings while testing in this mode are retained and become effective when you deploy the HATS application to a production environment.

The Debug on Server (for Web projects) and Debug (for rich client projects) testing modes can be used to modify and test the runtime settings without modifying the settings that are deployed to the production environment.

For more information about changing runtime settings for Web projects, see Starting the administrative console while in HATS Toolkit. For more information about changing runtime settings for rich client projects, see Administering HATS rich client applications.

URL host component

Before HATS V7, the URL host component searched within both input and protected fields. Starting with HATS V7, the URL host component searches only within protected, non-hidden fields.

Web Express Logon (WEL)

When a HATS Web project is migrated to HATS V7.5.1 with no associated EAR, Web Express Logon (WEL) does not function properly. The WEL configuration information for a Web project is kept in its associated EAR project. If the associated EAR project is not imported and migrated then this information is lost.

If you import the Web and EAR projects as Project Interchange files into the workspace and migrate the Web project, the associated EAR project is also migrated and the WEL configuration information is not lost.

Starting with HATS V7, Java Secure Socket Extension (JSSE) is used by both the HATS DCAS/RACF/JDBC and certificate-based DCAS/RACF credential mapper plug-ins for secure connections to the DCAS server. As a result, consider the following changes to the plug-in initialization parameters.

CMPI_DCAS_KEYRING_FILE
This parameter is deprecated and should not be used. However, if used, it is supported in HATS V7.5.1 in conjunction with deprecated parameter, CMPI_DCAS_KEYRING_PASSWORD, and with the assumption that the keyring type is pkcs12. Use CMPI_DCAS_TRUSTSTORE instead. For more information see Initialization parameters.

This parameter specifies a keyring database. A keyring must be specified to provide access to the DCAS client certificate as well as the DCAS server's certificate. The certificates establish a client authenticated secure connection with the DCAS server. This parameter is a file reference to the keyring to be used. The DCAS plug-in is the DCAS client. The keyring file must be stored in the .ear file.

CMPI_DCAS_KEYRING_PASSWORD
This parameter is deprecated and should not be used. However if used, it is supported in HATS V7.5.1 in conjunction with deprecated parameter, CMPI_DCAS_KEYRING_FILE, and with the assumption that the keyring type is pkcs12. Use CMPI_DCAS_TRUSTSTORE_PASSWORD instead. For more information see Initialization parameters.

This parameter specifies the password for the keyring database.

HATS V4 portlets

Migrating HATS V4 portlets is not supported. If you want to use an existing HATS V4 Web project as a portlet, you must first migrate it to HATS V7.5.1. After migrating the project, you can generate a HATS V7.5.1 portlet project from it. For more information, see Generating portlets from HATS Web projects.

Migrating from HATS LE

If you currently have HATS LE installed, you must first export your application before you can import it into HATS V7.5.1. To export the HATS LE application from the HATS LE Administrative Console into a .zip file:

  1. Start the HATS LE Administrative Console by entering the following URL in your Web browser: http://<server_name>/HATSLE/admin where <server_name> is the name of the server where your HATS LE application runs.
  2. Select Advanced.
  3. Select Package.
  4. Download and save the package as a .zip file

After the HATS LE application has been exported as a .zip file, import it into HATS V7.5.1 by following these steps:

  1. Click File > Import to open the Import wizard.
  2. Select HATS > HATS LE Application and click Next.
  3. In the Zip file name field, type the location and name of the .zip file. You can also browse for and select the .zip file by clicking Browse.
  4. In the New project name field, specify a project name or accept the one provided.
  5. Set the location for the project or accept the default location.
  6. In the Enterprise application project field, specify a name for the .ear project or select an existing one from the drop-down list.
  7. Click Finish.
Notes:
  1. If your HATS LE application has SSL enabled on the connection, you receive a warning message when migrating it to HATS V7.5.1, and the SSL certificate is not migrated.

    To make the SSL certificate usable in HATS V7.5.1, you must create a PKCS12 keystore file and add the SSL certificate to it. If you no longer have the SSL certificate, you should contact your Telnet server administrator for it. For more information, see Enabling SSL security.

  2. The multiple connection functionality of HATS LE V5 is lost after migrating to HATS V7.5.1. The default connection in the HATS LE V5 application becomes the default connection in the HATS V7.5.1 project. The other connections configured in HATS LE V5 become background connections in the HATS V7.5.1 project.

HATS for Host Publisher users

If you are an experienced user of IBM WebSphere Host Publisher, you will need to adjust your approach in order to develop projects with HATS. Here are some key differences between the HATS and Host Publisher approaches to developing projects:

Note:
If you created Host Publisher Integration Objects using a modified template, you will need to re-create the Integration Objects by making similar modifications to the HATS Integration Object template, and then regenerating the Integration Objects from macros. For more information about using templates to customize Integration Objects, refer to the HATS Web Application Programmer's Guide.

If you are importing a Host Publisher V4.0 application (versus a Host Publisher V4.0.1 application):

Migrating from Host Publisher Version 4

If you are currently a Host Publisher V4 user, you can migrate whole projects or just the Integration Objects from your existing projects. When you import Host Publisher .ear files, the Integration Objects remain packaged in the .jar file.

If the Integration Object was in a Web Module, the .jar file is in the WEB-INF/LIB directory. If the Integration Object is in an EJB module, the .jar file is in the imported_classes\IntegrationObject directory. The EJB Access Beans also remain packaged in the .jar file in the WEB-INF/LIB directory of the Web Module.

If you import an .ear and modify the macro for which an Integration Object has been created, you will have the original Integration Object .jar that was imported, as well as the Java source. After you have regenerated the Integration Object for HATS, you can delete the imported .jar file.

Below is a list of considerations when migrating from Host Publisher V4:

Import Host Publisher EAR wizard

You can import Host Publisher V4 projects into HATS as new HATS projects, or as part of an existing HATS project.

  1. Click File > Import > HATS > Host Publisher V4 EAR to open the Import Host Publisher EAR file wizard.
  2. Specify the EAR file you want to import in the EAR file name field.
  3. Decide whether the EAR file is to be used for a new HATS project or an existing HATS project.
  4. In the Options section, you can set Overwrite resources without warnings by selecting the check box.
  5. If you are using encryption in Host Publisher, you can enter your encryption key in the User list encryption key text box.
  6. Click Finish.

Import Host Publisher Integration Object

You can also import individual Host Publisher Integration Objects into an existing HATS project.

  1. Click File > Import > HATS > Host Publisher V4 Integration Object to open the Import Host Publisher Integration Object wizard.
  2. Specify the location of the Integration Objects you want to import in the Host Publisher Integration Objects directory field.
  3. Select which Integration Objects you want to import in the Select Integration Object(s) to import field.
  4. Select the HATS project in the Select HATS project drop-down box.
  5. You can Overwrite resources without warnings and Regenerate imported Integration Object(s) by selecting either check box.
    Note:
    If you have chained Integration Objects, you should be sure to select the Regenerate imported Integration Object(s) option. This ensures that the chaining information is preserved. After you have imported the chained Integration Objects, the state information is in the Java source and will be prefilled when you use the Create Chaining Integration Object wizard. For more information about chained Integration Objects, see Integration Object chaining.
  6. Click Finish.
Note:
When importing Integration Objects, the connection configuration that is associated with the Integration Object is added to the HATS project

Migrating Host Publisher V4 portlet

The clipping portlet that ships with WebSphere Portal Server V6.x is equivalent in functionality to the Host Publisher V4 portlet. You can create a clipping portlet pointing to an Integration Object-based HATS application, or an application that was migrated from Host Publisher V4, and replace the Host Publisher V4 portlet with it. The Host Publisher V4 portlet is no longer supported.

For information about integrating Integration Object-based applications more closely with WebSphere Portal, refer to the HATS Web Application Programmer's Guide.

J2EE migration

If you want to migrate the level of J2EE support in your HATS projects, perform the following steps:

  1. In Rational SDP switch to the Navigator view.
  2. Right-click the .ear project that contains your HATS projects, and select Java EE > J2EE Migration Wizard.
  3. On the Welcome Page panel, click Next.
  4. On the Enterprise Application panel, select the appropriate J2EE version and clear the Migrate all module projects box.
    Note:
    Clearing this box allows you to individually check which projects to migrate. If a HATS EJB project is contained in the .ear project, you must not select it in order to migrate the .ear project successfully.
  5. On the EJB Module panel (if one appears), do not select any HATS EJB projects.
  6. On the Web Projects panel, select all of the HATS Web projects.
  7. Click Finish.