Migrate to HATS Version 5.0

Migrate to HATS Version 5.0

If you are a previous HATS or HATS LE customer, you can migrate your projects to Version 5.0 projects.

If you are a Host Publisher Version 4.0 or Version 4.01 customer, you can migrate whole applications, or just the Integration Objects. If you are on a Host Publisher version prior to Version 4.0, download Host Publisher migration tools from the HATS Web site http://www.ibm.com/software/webservers/hats to convert your applications to Host Publisher Version 4.0 applications and then migrate to HATS Version 5.0.

Migration from HATS

The following section describes how you can migrate your HATS projects and HATS LE applications to HATS Version 5.0 projects. It also explains how to migrate a HATS V4 project within a HATS V5 workspace.

If you have a HATS V4 projects in a code repository, it is recommended that you check out the project in HATS V4, and then follow the instructions for Migrate from HATS Version 4.

HATS migration will 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/merge them with your new HATS V5 files. Do not concern yourself should task errors occur; these files are no longer used by the application. Once you are satisfied that all the saved files have been compared/merged, you can delete the MigrationBackup folder.

Be sure to thoroughly test your migrated projects. The migrated HATS V5 project may render slightly different than the HATS V4 project. This is a result of the new components and widgets for HATS V5.

If you migrate a HATS V4 project that has a submit button to HATS V5, the submit button will no longer appear if you've selected to use the Radio Buttons (selection) or Drop-down (selection) widget with the Function Key.

Migrate from HATS Version 4

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

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

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

Select Zip file, and click Next.

Check the box for the project you wish to export (select only one WAR project).

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

Click Finish.

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

Select File > Import > HATS V4 or HATS LE V4 Project to open the Import wizard.

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

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.

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.

The Migrate transformations check box is checked by default. If you choose to clear this box, your host components and widgets will not be converted to HATS V5 components and widgets. For more information see, Migrate HATS V4 transformations.

Migrate existing HATS V4 projects in the HATS V5 workspace

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

To migrate the HATS V4 project:

Click the Hats Project View tab of the HATS Studio

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

If you have other projects associated with the HATS V4 project you have selected to migrate, you will be forced to migrate those projects as well as the associated .ear project. You also have the option of migrating your transformation by checking the Migrate transformations check box. If you select this options, transformations in all listed projects will be migrated.

Click OK to begin the migration.

If the project does not have an associated .ear project, you will 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 may see a task warning about incompatible J2EE levels. If this occurs, do the following:

Go to the Navigator view of your HATS perspective.

Right-click the .ear project.

Select Migrate > J2EE Migration Wizard.

Click Next..

Make sure that only Migrate project from version level J2EE 1.2 to J2EE 1.3 is checked and click Finish.

Migrating your project from HATS V4 to HATS V5 cannot be undone.

Migrate from HATS LE Version 4

If you currently have HATS LE V4 installed, you will first need to export your application before you can import it into HATS V5. To export the HATS LE V4 application from the HATS LE Administrator Console into a .zip file:

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.

Select Advanced

Select Package

Download and save as a .zip file

Once you have successfully exported you HATS LE V4 application, you will then need to import it into HATS V5. Using the HATS V5 Studio:

Select File > Import > HATS V4 or HATS LE V4 Project to open the Import wizard.

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

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.

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.

The Migrate transformations check box is checked by default. If you choose to clear this box, your host components and widgets will not be converted to HATS V5 components and widgets. For more information see, Migrate HATS V4 transformations.

Migrate HATS V4 transformations

When you import your HATS V4 projects into HATS V5, you are given the option to migrate your transformations. If you select this option, your existing transformations will be migrated to use the new HATS V5 components and widgets. If you choose to not migrate your transformations when you import your project, you can do so later by right-clicking on your project and selecting Migrate transformations.

The following occurs when you migrate your transformations:

The component and widget attributes of each <HATS:Component> tag in each of your transformations is migrated to use the new component and widget.
If either the component or widget specified in the tag is a custom component or widget, the tag will not be migrated and the tag will continue 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 will be converted into a <HATS:DefaultRendering > tag. If the tag does contain settings, the tag will not be changed.

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.

Each of your existing, imported templates will be updated to include a reference to one of the new CSS stylesheet files. This will allow your updated tags to appear correctly when viewing your application. See New Templates and Stylesheets for more information.

Because of the numerous benefits to using the new components and widgets (see Component and widget redesign for more information), it is highly recommended that you migrate your transformations to use the HATS V5 components and widgets. However, new components and widgets recognize and render differently so you may be required to modify some of your transformations after migration.

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

Migrate a HATS V4 portlet

Once your HATS V4 application has been migrated to HATS V5, 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 V4 portlet pointing to the deployed original HATS application. Since this HATS portlet project will have more functionality than the HATS V4 portlet pointing 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 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 V5, Integration Objects do not always require connect and disconnect macros.

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 will be 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 contained EJB 1.0 support, you will get an error an 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.

Migrate 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 will 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. Once you have regenerated the Integration Object for HATS V5, you can delete the imported .jar file.

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 will 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 V5. If you import a Host Publisher application that contains Database Access Integration Objects, the Integration Objects will be preserved in a .jar file. However, you cannot create new Database Access Integration Objects in HATS V5. You can use the relational database tools in WebSphere Studio to access your relational databases.

Defined XML Gateway connections will not be migrated. You can define HATS V5 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 V5.

Host Publisher Express Logon is not supported in HATS V5. 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 will be migrated without error, but a warning issued that ELF isn't supported and that WEL must be used to achieve the equivalent function. You will have to 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 Use 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 V5. Importing an encrypted user lists requires supplying the encryption key used to encrypt the user list. The user list will be 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, this is the recommended sequence for migrating the Host Publisher application that contains these Integration Objects:

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

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

Modify the Integration Object templates provided with HATS V5 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.

Click File > Import > Host Publisher EAR to open the Import wizard.

Select the EAR file you want to import in the EAR file name field.

Decide whether the EAR file is to be used for a new HATS project or an existing HATS project.

In the Options section, you can Overwrite resources without warnings by selecting the check box.

If you are using encryption in Host Publisher you can enter your encryption key in the User list encryption key text box.

Click Finish.

Import Host Publisher Integration Object

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

Click File > Import > Host Publisher Integration Object to open the Import wizard.

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

Select which Integration Objects you want to import in the Select Integration Objects to import field.

Select the HATS project in the Select HATS project drop down box.

You can Overwrite resources without warnings and Regenerate imported Integration Object(s) by selecting either check box.
If you have chained Integration Objects, be sure to select the Regenerate imported Integration Object(s) option. This will ensure that the chaining information is preserved. Once 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.

Click Finish.

When importing Integration Objects, the connection configuration associated with the Integration Object is added to the HATS project

Migrate Host Publisher V4 portlet

The clipping portlet which 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 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, please refer to the HATS Programmer's Guide

Applying maintenance to imported HATS projects

A HATS project (when exported as a .zip file from WebSphere Studio) does not contain information about the specific build level under which it was created. This level information is stored as part of the assembled .ear file, but is not stored in the project itself, so it is not possible to tell what CSD level a zipped project was created under. If you are in doubt as to whether a project you are importing was created at the same HATS maintenance level as that currently installed on the HATS Studio, it is recommended that you follow the instructions below to reapply the latest maintenance to all projects (imported and current) in the HATS workspace.

Maintenance is applied to your HATS projects when the HATS perspective is opened the first time after applying the maintenance to your HATS Studio. Once the maintenance has been applied to all projects, it will not be applied again unless you follow the following steps.

If you import a HATS project created under a different level of HATS, the imported project will not be automatically updated.

To apply the current HATS Studio level of maintenance to these projects you can edit the file workspace_dir\.metadata\.plugins\com.ibm.hats\pref_store.ini (where workspace_dir is your HATS workspace directory) and remove the ProjectBuildDate and ProjectBuildLevel keywords.

WebSphere Studio must be closed while editing the pref_store.ini file.
This will alert the HATS project maintenance application process to automatically apply maintenance to your projects. The next time you start HATS Studio, the current HATS Studio level of maintenance will be applied to ALL of your projects. If you don't want the maintenance to be applied to a certain HATS projects close that project while in WebSphere Studio before making changes to the pref_store.ini file.

Home