IBM WebSphere Host Access Transformation Server (HATS)

Tutorial - Module 3

Customizing HATS Applications

revision b 03/27/03 - jn - modified for WSAD 5

Abstract

This tutorial is designed for anyone who wants to learn how to customize HATS applications. The tutorial is in the form of a lab exercise to a live publicly available host application. This module will cover some customization steps and how to apply different actions based upon recognized screen events. This will demonstrate the rules based engine that is part of HATS and how transformations are applied to screens depending upon certain events.

Assumptions / Requirements

It is assumed that the user has already installed WebSphere Studio 4.03 and the HATS Studio software on a supported platform. The platform requirements were covered in the HATS Tutorial - Module 1. It is also assumed that a network connection can be made to the publicly accessible IBM Demonstration iSeries host at:

Host name: iseriesd.dfw.ibm.com, port: 23, type: 5250

Connectivity to this host can be tested by using any TN5250 emulator configured for the settings above. A WebSphere application server that meets the requirements for HATS needs to be available if you want to deploy the HATS application to a production WebSphere server. It is assumed that you are already familiar with the WebSphere application server console.

Topics covered on this tutorial

Review of basic HATS Application steps
HATS Screen Customization Wizard
Testing the customized application
Screen Customization Events and Actions

Review Basic HATS Application Steps

You can reuse the previously configured HATS application for Module 2 for this tutorial. If you have a previously configured HATS application that you want to use from Module 2, then skip to the next section and start from there. Otherwise follow these steps prior to starting the next section.

1. Launch the HATS Studio

Start > Programs > IBM WebSphere HATS > HATS Studio

2. From the HATS Welcome page , click on "launch the Create HATS Project Wizard" link.

3. The New Project panel will come up.

Provide a project name, for example: boats
Enter a description like "iSeries demonstration applications"
Leave the check boxes checked (default) and click Next

4. On the Connection Settings panel enter the following:

Host name: iseriesd.dfw.ibm.com
Port: 23
Type: 5250
Leave the code page at default (037 United States) and leave the screen size default (24x30). Click the Next button

5. The Select Default Template panel

Select a default template from a list of provided templates in the drop down list box
Click Finish button. The studio will now build the project files, this may take a few minutes

6. When the studio finishes building the project files the HATS Project View will open and you will see the project folders on the left. Expand the folders and examine the files that the studio build for the project. You can now go the next section to start customizing the HATS application.

Customizing the application

This section will introduce you to the HATS customization wizards. You will customize the Main Menu screen of the OS/400 application so that the selection menu is rendered on the browser page as a button table widget. You will also add an input field to the page and then test by running the application in the test server within WebSphere Studio.

1. With the project highlighted in the HATS Project View, right click and select Open Terminal from the list. This will open the terminal window. You will now need to enter a user id and password . In the terminal window type in user: user4boats password: password and press the enter key.

2. The next screen should be the OS/400 Main Menu screen or could possibly be a display messages screen. If the display messages screen appears, press the enter key and the OS/400 Main Menu screen should appear.

3. The OS/400 Main Menu screen is where we will begin the Screen Customizations wizard so we can customize this screen. Notice that this is a menu screen with several choices that can be entered on the command line. You will create a transform JSP that will render the menu as a Selection List - Button Table widget in the next steps and also add an input field for the command line.

4. From the HATS terminal click on the Create HATS Screen Customization wizard. The Screen Customization Name and Destination panel will open.

5. Specify a name and a description for the new Screen Customization.

Accept the pre filled screen name and provide an optional description if desired and click Next.

6. The Select Screen Recognition Criteria panel will come up with a screen capture of the OS/400 Main Menu screen. Here is where you will define the screen recognition criteria.

7. Notice that in the Select a screen box is the choices of Use the terminal screen (selected) and a grayed out choice of Use a previously captured screen. HATS Studio has the capability of using previously captured screens to do customizations with. This is great for working remotely because it allows the application developer to work remotely and do screen customizations without being attached to a network accessing the host application in real time. You just need to have previously captured the screens with the HATS built in screen capture tool, then customize on an iterative basis later.

String Position - Click on At the specified position instead of the default Anywhere on the screen. This will make the screen recognition criteria unique to this specific location for the text: OS/400 Main Menu
Click Next

8. The Select Actions panel will come up.

The Apply a transformation option will be checked by default.
Create new transformation will be also checked by default with the name provided already.
Leave everything as is an click Finish

9. The project files will be built now. The OS_400_Main_Menu.jsp file will be built and the Insert Host Component - Screen Region panel should open up now, shown below. You can sign off the boats application on the iSeriesD host and close the HATS Terminal window now.

10. The Insert Host Component - Screen Region panel should be open. We want to render the screen menu as a GUI widget on the browser page.

To assist you in customizing the screen, there is a check box at the bottom of this panel that when checked will show you highlighted in blue any input fields on the screen. Check this box so you can see the input fields.
With the left button on the mouse held down draw a box around the menu choices on the screen. Make sure you include all the items in the menu list.
Notice that the Start Row and End Row screen coordinates are automatically entered in the input fields at the bottom.
When you have the menu text items included in the box click Next.

Figure 1. Insert Host Component - Screen Region panel

11. The Rendering Option panel will open next, shown below. From here you select what Rendering Option method to use. As you select different options the Component Preview and Widget Preview panels will change and show you how the component will look on the web page.

Select "Selection List" from the Component List and "Button Table" from the Widget list and click on Finish. The widget will be built and added to the OS_400_Main_Menu. Jsp
Click on Full Page Preview button to see a preview of how these changes will render in the browser.
Click Finish - this will add your changes to the OS_Main_Menu.jsp now.

Figure 1. Rendering Option panel - Selection list - Button table widget

12. Examine the code added to the JSP, shown below. Notice that the SelectionListExtract component has been added with the HATS tag on the JSP.

Go ahead and delete the HATS:HostKeypad by highlighting and pressing the delete key. This will remove the keypad from the displayed web page for the user. We also want to show an input field on the page so that the user can enter "boats" on the command line to load the boats application.

Figure 3. OS_400_Main_Menu.jsp in HTML editor

13. Move the blinking cursor on the OS_400_Main_Menu.jsp so that it is located below the HATS:Component tag on the page.

Click on the Insert HATS Component Icon on the menu bar at the top to define a new widget. Note: If you are using WSAD 5, then click on HATS Tools on the top toolbar and select Insert HATS component or with the cursor focus below the <HATS:Form> tag then click the right button on mouse and select HATS Tools, Insert HATS component.
Click the check box "Highlight input fields" to see the input fields on the screen.
Draw a box around the input field area of the screen and click
Next

14. Make this a Input Field - Text Input widget and click on the Full Page Preview button. Preview the page, then close the Preview page. Click Finish. Then go to File > Save the JSP or CTRL S to save the changes to the JSP.

Close the HATS terminal if you still have it up.

Figure 4. Preview of OS_400_Main_Menu.jsp.

15. Highlight the application in the HATS Project View.

Click on the Preview your HATS project using Run on Server link on the Welcome to HATS page.

16. After a while the WebSphere Test Server will load in the Server Perspective and then a browser will start to open the URL to the application. When the first page is in the browser go ahead an sign into the application and press the enter key and navigate through the application to see your screen customization changes.

17. The next page should come up with the transformation applied so that the menu is rendered as a button table widget and no keypad showing and the input field is shown at the bottom.

Type in boats on the command line and press the enter key. Go ahead and navigate through the application to verify it is functioning as designed. Notice that with the button table widget, if you click on the last button (90) Sign off, the application will enter the 90 for you and sign you off the application.

18. You can also test run the HATS application from a browser while the WebSphere Test Server is running the application in the WebSphere Studio. Simply copy the URL from the browser in the WebSphere Test Server and then open a browser outside WebSphere Studio and then paste the URL into the browser and press the enter key. The entry servlet for the application should load after a bit and you should see the first screen of the application in the browser and you can work with the application from here. This way you can view the application like a web user would see the application running on WebSphere.

19. Summary - the above section has stepped you through generating a screen customization and generating a transformation for one screen that had a menu and input field host component, from which you rendered these as a Selection List - Button Table and an Input field for the web page. These steps have demonstrated to the developer the steps necessary to customize screens. These steps can be applied in a similar manner and used to build other screen customizations and transformations for host screens that the developer might want to customize.

Screen Customization Events and Actions

1. Now we will look at the screen customization pages for the screen customization we just did in the previous steps. We will also examine what further customizations might be done for a specific screen event in the next section.

2. In the HATS Project View, expand the Screen Customizations folder. You should see the OS_400_Main_Menu screen customization. Double click on it which will open OS_400_Main_Menu.evnt and present you with the Overview page.

3. The Overview page - This page displays basic summary information for this event. Notice on the left under Actions that only the "Apply transformations" is Yes and all other actions are No.

4. At the very bottom notice that you have several tabs besides the Overview page

Screen Recognition Criteria
Actions
Source

5. We will take a look at the Screen Recognition Criteria page now.

Click on the Screen Recognition Criteria tab.

6. Screen Recognition Criteria - You should see the screen recognition information for the screen already in the table in the center. You could use the Add button on the left to add new screen recognition criteria if needed from this page. Leave the screen recognition criteria as is and click on the Actions tab.

7. Actions - On this page you can specify which actions to perform when this OS_400_Main_Menu screen "event" occurs. Currently the only action type specified is "Apply a transformation" . This will apply the OS_400_Main_Menu.jsp using a default template that we have chosen for the project. You could add other Actions for this event by clicking on the Add button. We will examine actions further in the next section. Click on Source tab.

8. The Source page shows you the actual XML configuration source for the screen customization for OS_400_Main_Menu. Notice that the type of event is type="screenRecognize". Actions are to apply a transformation of "OS_400_Main_Menu.jsp" and the description of the screen is shown.

9. Keep the Screen Customizations pages open and go to the next section.

Actions and Rules Sets for Screen Recognition Events

In the following section you will examine the type of actions that are possible for a specific screen recognition event. This is key to the use of the HATS rules based engine. This is where rule sets can be applied based on specific screen recognition events.

1. Go back to the Actions page and click on the Add button. With the Action drop down list box, select each one of the choices and look at what specific actions are available to be applied for this screen event. Look at the actions below for each panel.

2. Action - Apply Transformation

Allows you to select a transformation and template to apply to the host screen.

3. Action - Execute Business Logic

Allows you to specify a Java class, and the method in that class to execute.

4. Action - Extract Global Variable

Allows you to specify a global variable to extract , and the region of the host screen to extract.

5. Action - Insert Global Variable

Allows you to specify a global variable to insert, and the position of the screen to insert into. You can use an existing global variable or insert a fixed string.

6. Action - Set Global Variable

Allows you to specify the value for the global variable. You can overwrite or append to an existing global variable or set a new variable.

7. Action - Show URL

Allows you to specify a URL to be shown.

Conclusion

In this tutorial you were shown how to use the screen customization wizard to transform a screen to use a widget based upon a menu host component, and also added an input field for the same page.

The next tutorial (Module 4) will be a lab exercise using a macros as an action when a screen recognition event occurs.

Copyright: Licensed Materials - Property of IBM
             (C) Copyright IBM Corp. 2002 All rights reserved.
             U.S. Government Users Restricted Rights -
             Use, duplication or disclosure restricted by
             GSA ADP Schedule Contract with IBM Corp.