Migrating to HATS Version 6.0

If you are a previous HATS V4, HATS V5, HATS V4 LE or HATS V5 LE user, you can migrate your projects to HATS Version 6.0 projects.

If you are using a Host Publisher version prior to Version 4.0, follow the instructions for migrating your Host Publisher applications to Host Publisher Version 4.0. Go to http://www.ibm.com/software/webservers/hats/support.html and enter the search string "How to migrate Host Publisher". For more information, see HATS for Host Publisher users.

HATS migration

The following sections describe how you can migrate your HATS, HATS portlets and HATS EJB projects as well as HATS LE applications to HATS Version 6.0 projects. It also explains how to migrate previous HATS projects within a HATS V6 workspace.

There are two migration paths you can follow:

If you have a HATS V4 project in a code repository, you have to check out the project in HATS V4, and then follow the instructions for Migrating from a previous HATS version.

HATS migration creates a backup folder in the project directory called MigrationBackup. This folder contains all of the modified files that were overwritten by the migration process. These files are saved so that you can compare and merge them with your new HATS V6 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.

HATS V5 introduced new components and widgets. If you have components and widgets created in HATS V4, it is recommended that you migrate them. However, your migrated project may render differently. Be sure to thoroughly test your migrated projects.

Note:

  1. If you have a HATS V4 subfile it is recommended you migrate to a HATS V5 subfile. If you have a HATS V5 subfile it will be left alone. There is a new subfile component and widget for HATS V6. For more information, see Subfile.

  2. In HATS V4 if you chose a function key component and rendered it as radio buttons (selection) or a drop-down (selection) widget you had a choice to use auto submit or have a submit button. If you migrate a HATS V4 project that has a submit button to HATS V6, the submit button will no longer appear if you selected to use the radio buttons (selection) or drop-down (selection) widget with the function key. In HATS V6 the capability to have a submit button has been removed.

  3. In earlier versions of the HATS Host Terminal, the Pause key was mapped to the host's [clear] action. In the HATS V6 Host Terminal, the Esc key is mapped to the host's [clear] action.

Migrating from a previous HATS version

If you currently have a previous version of HATS installed, you first need to export your project into a .zip file before you can import it into HATS V6. Select only one WAR project for export and export only WAR projects, not EAR projects. Imported WAR projects can use a newly created HATS V6 EAR project or an existing HATS V6 EAR project.

To export the HATS project from your HATS Studio into a .zip file:

  1. From the HATS perspective, click File > Export to open the Export wizard.

  2. Select Zip file, and click Next.

  3. Select the check box for the project you wish to export (select only one WAR project).

  4. In the Zip file field, type the destination you want to export the file to. You can also select an export destination by clicking Browse.

  5. Click Finish.

When you have successfully exported your HATS project, you will then need to import it into HATS V6. Using the HATS V6 Studio:

  1. Click File > Import > HATS Project to open the Import wizard.

  2. Browse for the HATS zip file you want to import in the Zip file name field.

  3. Decide where you want to import the resources of the .zip file. You can select Import to existing HATS project or Create a new HATS project.

  4. Select a project name for either one. If you chose Create a new HATS project, you will also need to either use the default location and Enterprise Application name or create your own.

  5. If the HATS project zip file that you entered in the Zip file name field is from a previous release of HATS, it will be migrated during the import. If the project contains transformations with HATS V4 components and widgets, you will get a message asking you if you wish to migrate these to the new version 6 components and widgets. HATS V4 components and widgets are deprecated and will not be supported in future releases of HATS. For more information see, Migrating existing HATS transformations.

Migrating legacy HATS projects in the HATS V6 workspace

If you have a HATS project created from a prior release in your HATS V6 workspace, you will get a message informing you that HATS V6 has detected a HATS project from a previous release of HATS and that it should be migrated. This can occur if you check out a HATS project from a code repository (such as Rational Clearcase or CVS) in to your HATS V6 workspace.

Note:
It is recommended you use HATS migration to migrate these projects to HATS V6 before investigating any errors shown in the Problems view, as HATS migration may eliminate some or all of these errors.

To migrate the previous HATS project:

  1. Click the Hats Project View tab of the HATS Studio

  2. Right-click on the HATS project and select Migrate Project.

  3. If you have other legacy HATS projects that are associated with the HATS project you have selected to migrate, you will be forced to migrate those projects as well as any associated legacy HATS .ear projects.

  4. Click OK to begin the migration.

  5. If the project does not have an associated .ear project, you need to associate the .war project after the migration. To associate the .war project with an .ear project, see Moving a project.

    If an .ear project was migrated, you might see a task warning about incompatible J2EE levels. If this occurs, do the following:

    1. Go to the Navigator view of your HATS perspective.

    2. Right-click the .war project.

    3. Select Migrate > J2EE Migration Wizard.

    4. Click Next.

    5. Make sure that only Migrate project to J2EE specification level is selected. Select the J2EE version, then click Finish.
Note:
Migrating your project from a previous HATS version to HATS V6 cannot be undone.

Migrating from a previous HATS LE version

If you currently have HATS LE installed, you will first need to export your application before you can import it into HATS V6. To export the HATS LE application from the HATS LE Administrator 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 machine where your HATS LE application runs.

  2. Select Advanced.

  3. Select Package.

  4. Download and save the package as a .zip file
    Note:
    If you originally created your HATS LE application with SSL enabled on the connection, you may experience an error after importing the application as a HATS V6 project. When you attempt to start the terminal or run on server, you will get a message informing you that the certificate is not a trusted certificate and the connection will fail.

    To avoid this error, you will need to import the original certificate into the HATS V6 project. If you no longer have the original certificate, you should contact your TN Server administrator for one.

When the HATS LE application has been successfully exported, import it into HATS V6. Using the HATS V6 Studio:

  1. Click File > Import > HATS Project to open the Import wizard.

  2. Browse for the HATS zip file you want to import in the Zip file name field.

  3. Decide where you want to import the resources of the .zip file. You can select Import to existing HATS project or Create a new HATS project.

  4. Select a project name for either one. If you chose Create a new HATS project, you will also need to either use the default location and Enterprise Application name or create your own.

  5. If the HATS project zip file that you entered in the Zip file name field is from a previous release of HATS, it will be migrated during the import. If the project contains transformations with HATS V4 components and widgets, you will get a message asking you if you wish to migrate these to the new version 6 components and widgets. HATS V4 components and widgets are deprecated and will not be supported in future releases of HATS. For more information see, Migrating existing HATS transformations.
Note:
The multiple connection functionality of HATS LE V5 is lost after migrating to HATS V6. The default connection in the HATS LE V5 application will be main (default) connection in the created HATS V6 project. The other connections configured in HATS LE V5 will be maintained in the HATS V6 project as background connections.

Migrating existing HATS transformations

When you import HATS projects from a previous release of HATS into HATS V6, your existing transformations are migrated to use the HATS V6 components and widgets. If you chose to not migrate your existing transformations during import, you can do this later by right-clicking on your previous HATS project and selecting Migrate transformations. Be sure to back up your previous HATS transformations before migrating your applications to HATS V6.

The following occurs when you migrate your transformations:

  1. The component and widget attributes of each <HATS:Component> tag in each of your transformations is migrated to use the new component and widget.
    Note:
    If either the component or widget that is specified in the tag is a custom component or widget, the tag is not migrated and the tag continues to work as it did before migration. Also, if a tag references the HATS V4 default widget, but is using default project settings (such as no settings are specified in the tag), this tag is converted into a <HATS:DefaultRendering> tag. If the tag does contain settings, the tag is not changed.

  2. All HATS V4 components and widgets are removed from this project's ComponentWidget.xml (registry) file. You will no longer see HATS V4 components and widgets (except for ones you have written) in the HATS Studio when editing transformations or modifying application settings.

  3. Each of your existing, imported templates are updated to include a reference to one of the new CSS style sheet files. This enables your updated tags to appear correctly when viewing your application. See Templates and style sheets for more information.

It is recommended that you migrate your transformations to use the HATS V6 components and widgets. Some component and widget settings might require minor changes after migrating HATS V4 applications to HATS V6. The HATS V6 components and widgets might have different behavior and appearance, and you should test your application after migration to ensure your transformations behave and appear as you expect. For more information, see Component and widget descriptions and settings.

Note:
The Migrate transformations operation cannot be undone. Transformations can contain a combination of HATS V4 and HATS V6 tags. However, a tag cannot specify a HATS V4 component with a HATS V6 widget (or vice versa).

Migrating a HATS V4 portlet

When your HATS application has been migrated to HATS V6, you can generate a portlet project from it. This portlet project can then be deployed directly to WebSphere Portal, obviating the need for the HATS portlet to point to the deployed original HATS application. Because this HATS portlet project will have more functionality than the HATS V4 portlet that points to the original application, the HATS V4 portlet will no longer be supported. For more information, see Generating portlets from HATS applications.

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:

  • There is no HATS server install. The HATS executable code, known as the HATS runtime, is embedded in each HATS .ear when it is assembled in HATS Studio. HATS projects also allow you to have multiple .war files within an .ear file.

  • Host Publisher does not transform host screens or present them to the user; rather it retrieves specific information from host applications and displays that information. While you can create a HATS project that performs this function, the basic function of HATS is to transform host screens and present them to the end user. Of course, you can enhance your HATS project to combine or skip screens, and combine data from multiple host applications. HATS enables you to work from the ground up, and makes it easy to add to your project over time.

  • The functions of your Host Publisher project were configured explicitly; you controlled the behavior of your users by specifying the host interactions that they could perform. In the rules-based approach used by HATS, you configure rules by which your HATS project transforms whatever host screens the user accesses, and processes the user's interactions with those screens. Where your Host Publisher project enabled the user to perform a limited set of host interactions, your HATS project applies its rules to handle any sequence of interactions your user performs. HATS enables you to define how freely the end user can interact with the host; interaction can range from a free-form host emulator experience to a completely dictated screen navigation.

  • In Host Publisher, all host interactions are performed within macros that are encapsulated into Integration Objects. In HATS, you can use macros for many purposes, but they are not required for the basic transformation of host screens. In Host Publisher, an Integration Object requires a connect macro and a disconnect macro, as well as the data macro that is used to extract data from the host project. In HATS, a macro can be run on a host to which the HATS project is already connected. Thus, in HATS V6, Integration Objects do not always require connect and disconnect macros.

Note:
If you created Host Publisher Integration Objects using a modified template, you will need to recreate 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 Programmer's Guide.

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

  • Remote Integration Object (RIO) support has been removed. All Host Publisher V4 applications contained the RIO servlet. If you import a Host Publisher V4 application that contains RIO support, the RIO servlet is removed, and you will receive a migration message that this has been done. If you used RIO to access Integration Objects remotely, you need to modify those applications to use Web Services. Refer to the HATS Programmer's Guide for more information.

  • If you try to import Host Publisher applications that contain EJB 1.0 support, you receive an error message that indicates that the application contains EJB 1.0 support. If you wish to import the application, go back to Host Publisher Studio and regenerate your EJB Access Beans using the EJB 1.1 specification level, and repackage the application using Host Publisher Application Integrator.

Migrating from Host Publisher Version 4

If you are currently a Host Publisher V4 customer, 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 V6, you can delete the imported .jar file.

Note:
The following is a list of considerations when migrating for Host Publisher V4:

  • If you have Integration Objects or EJB Access Beans with Web service support, you need to regenerate the Web services. For information on regenerating Web services, refer to the HATS Programmer's Guide.

  • Database Access Integration Objects are deprecated in HATS V6. If you import a Host Publisher application that contains Database Access Integration Objects, the Integration Objects are preserved in a .jar file. However, you cannot create new Database Access Integration Objects in HATS V6. You can use the relational database tools in Rational Studio to access your relational databases.

  • Defined XML Gateway connections are not migrated. You can define HATS V6 applications using the default transformation to achieve the same function as the XML Gateway connections.

  • The XML Legacy Gateway SDK is not available in HATS V6.

  • Host Publisher Express Logon is not supported in HATS V6. Integration Objects that were configured to use Express Logon need to be configured to use HATS Web Express Logon. If you import an Integration Object that contains Express Logon Feature support, the Integration Objects is migrated without error, but a warning is issued that ELF is not supported and that WEL must be used to achieve the equivalent function. You must re-record your connect macros so they are recorded using WEL actions, associate the Integration Object connections with the new WEL macros, and also do the WEL configuration. See Using Web Express Logon (WEL) for more information. The Integration Objects will not perform as intended unless this is done.

  • Neither encrypted nor scrambled user lists are supported in HATS V6. Importing an encrypted user lists requires supplying the encryption key that was used to encrypt the user list. The user list is decrypted or unscrambled during import. You must use file system security and physical security measures to protect any sensitive data.

  • If you have Integration Objects that were created using a modified template, the following is the recommended sequence for migrating the Host Publisher application that contains these Integration Objects:

    1. Import the Host Publisher EAR. You will receive warnings that you are importing Integration Objects that contain a modified template.

    2. If any of the Integration Objects that you imported contained data that was extracted as a table, import those individual Integration Objects.

    3. Modify the Integration Object templates that are provided with HATS V6 to achieve the same customizations you defined in Host Publisher. Refer to the HATS Programmer's Guide for more information

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 > Host Publisher EAR to open the Import wizard.

  2. Select 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 choose 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 > Host Publisher Integration Object to open the Import wizard.

  2. Select the location of the Integration Objects you want to import in the Host Publisher Studio install directory field.

  3. Select which Integration Objects you want to import in the Select Integration Objects 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. Aftr 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 on 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 V5 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 will no longer be supported.

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