Edit a screen customization

A screen customization is a HATS resource with two parts: a set of screen recognition criteria used to match host screens, and a list of actions to be taken when a host screen matches the screen recognition criteria.

When you create your project in HATS Studio, you use the Create a Screen Customization wizard to define screen customizations. You can access the wizard a number of ways, such as:

The recognition criteria and the actions you define for the screen customization are saved in a screen customization (.evnt) file. Use the screen customization editor to view and modify those criteria and actions.

You can see the screen customizations you have created by expanding the Screen Customizations node of the HATS Project View tab of the HATS Studio. You can invoke the screen customization editor by double-clicking on the name of the screen customization.

The following sections describe each tab of the screen customization editor.

 

Overview

The Overview tab of the screen customization editor summarizes all of the information you specified when you created the screen customization. It contains the name and description of the screen customization, the name and an image of the screen that was used to create the screen recognition criteria, a summary of the screen recognition criteria, and a summary of the actions to be taken when the screen is recognized. On this tab, you can modify the description of the screen customization, and you can select a different screen to associate with the screen customization. The selected screen is used whenever you make changes to the screen customization, such as modifying the screen recognition criteria, or adding actions.

 

Screen Recognition Criteria

You set screen recognition criteria that HATS uses to match host screens. Host screens can be recognized by any combination of criteria including how many input fields or total fields are on the screen, the coordinates of the cursor's position, and text strings on the screen within a defined rectangle or anywhere on the screen. The Screen Recognition Criteria tab of the screen customization editor displays the screen recognition criteria that you set for the screen customization. You can add, edit, or remove criteria on this tab.

 

Fields criteria

Use the Total number of fields on a screen, the total Number of input fields on a screen, or both as screen recognition criteria. These are the first two criteria shown on the Screen Recognition Criteria tab.

If you select the check box for these criteria, they are used to recognize the screen. The fields next to each field criterion show the number of fields and input fields for the screen specified on the Overview tab. If you change the screen being used for this screen customization, click Refresh to update the values for the screen you choose.

If you are using field criteria to recognize screens that have a certain number of fields, and another screen does not contain the same number of fields, that screen is not recognized. For example, one screen might have a list of 10 files with 10 fields. If the host displays a screen with only eight files in the list and eight fields, the second screen does not match the number of fields criterion of the screen customization that matched the first screen.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

 

Cursor position criteria

To use the initial position of the cursor as a screen recognition criterion, either by itself or in conjunction with other criteria, select the Cursor position check box. The fields next to the cursor position criterion shows the row and column of the cursor position for the screen specified on the Overview tab. If you change the screen being used for this screen customization, click Refresh to update the values for the initial cursor position row and column on the screen you choose.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

 

Optional versus non-optional screen recognition criteria

You can choose whether the screen recognition criteria you set is optional or non-optional. If you do not select the Optional check box, the recognition criterion is considered non-optional. How you use the Optional check box corresponds to the Host On-Demand screen descriptor attribute, optional.

If you have both optional recognition criteria and non-optional recognition criteria, HATS checks the non-optional criteria first. If all the non-optional criteria match, the screen matches. If at least one of the non-optional criteria does not match, HATS checks the optional criteria. For a screen to match the criteria, HATS must find all non-optional criteria, or at least one optional criterion. Otherwise, the screen fails to match. The following example explains this concept in greater detail.

Non-optional does not mean required.

Suppose you defined cursor position location and two text strings with the values shown in the following example:

Cursor position recognition  Optional     
                             Row: 1   Column: 1

String recognition           Non-optional   
                             String 1: Welcome
                             Start position: Row: 1   Column: 6
                             End position:   Row: 1   Column: 12

                             String 2: Username
                             Start position: Row 20   Column 10
                             End position:   Row 20   Column 17

In this example, HATS must find both text strings or the cursor position for the screen to match. Because HATS checks non-optional criteria first, HATS looks for the text strings first. If HATS cannot find both text strings in the specified regions of the host screen, then it checks to see whether the optional criterion (cursor position) can be found.

 

Inverted match of screen recognition criteria

You can choose whether the screen recognition criteria you set matches or does not match the host screen. If you select the Invert check box, the recognition criterion must not match the screen for the criterion to be considered true.

Conversely, if you clear the Invert check box, the recognition criterion must match the screen for the criterion to be considered true.

How you use the Invert check box corresponds to the Host On-Demand screen descriptor attribute, invertmatch.

 

Additional criteria

String criterion

Text string location criteria are shown at the bottom of the Screen Recognition Criteria tab. If you have set a string location as a screen recognition criterion, it is shown in the table. The table shows what part of the screen contained the string, shows some of the characters of the text selected, and whether the text is case sensitive, optional or invert.

If you highlight a row of the table that defines a string criterion and click Edit, or if you click Add, the Screen Recognition Criterion dialog appears. In the dialog panel, you can either modify or specify text string information. You also can select attributes for the string (case sensitive, optional or invert). The panel shows the screen selected on the Overview tab.

You can select any text on the screen by drawing a rectangle around the text. Place your cursor at any point on the screen, click and hold the left mouse button, and move the cursor to another location on the screen to draw the rectangle. The fields on the right of the dialog show the text you selected and the starting and ending row and column numbers of the rectangle. You can specify the part of the screen that should contain the text by clicking one of the radio buttons for Anywhere on the screen, At a specified position, or Within a rectangular region. If the text you selected must be case-sensitive to be recognized as matching the screen recognition criteria, select the Case sensitive check box.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Click OK when you have finished your selections.

Global variable criterion

If you click Add and select Global variable criterion, you need to specify a global variable from the Global Variable drop-down list as well as the Verification logic by checking one of the five bullets:

For an explanation of the Optional and Invert check boxes, in the Attributes section, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

For information on advanced global variable programming, refer to the HATS Programmer's Guide.

Color criterion

You can define your screen recognition criteria by color by clicking the down arrow beside the Add button and selecting Color Criterion. This will open a panel in which you can select the row and column position as well as the foreground and background color.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Compare region to value criterion

The Compare region to value criterion allows the comparison of text from a selected region of the host screen and to a hard coded value.

Start by drawing a box around the region of the terminal or type in the coordinates for the recognition in the Define Region section. The Current value on the terminal will also be shown in the text box.

Next, you can specify what the region will be compared to and how it will be compared. In the Define Comparison section, select how your region will be compared by selecting from the drop-down list next to Region, and enter what it will be compared to in the Value text box.

Comparison Type will either be Numeric or Text (with the a Case sensitive check box option).

Attributes can also be defined. For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Click OK when you have finished your selections.

Compare region to region criterion

The Compare region to region criterion allows the comparison of one region on the host screen to another region of the same host screen.

First select the First Region tab and start by drawing a box around the region of the terminal or type in the coordinates for the recognition in the Define Region section. The Current value on the terminal will also be shown in the text box.

Next, you can specify how these regions will be compared in the Define Comparison section by selecting from the drop-down menu between Region 1 and Region 2.

Comparison Type will either be Numeric or Text (with the a Case sensitive check box option).

Attributes can also be defined. For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Repeat the same steps for the Second Region tab then click OK when you have finished.

 

Actions

The Actions tab of the screen customization editor displays the actions for the screen customization. These actions are applied in the order that they are listed. If you want to change the order of the actions, select one and click Up or Down to move that action higher or lower in the list.

Any action you want performed before an end user sees a screen should be done before the Apply transformation action. Also, a Play macro and a Send key action must always run last when considering the order of your action list.

You can add, edit, or remove actions on this tab. These are the possible actions:

All the action types you have defined for the screen customization and their descriptions are shown in the table on the Actions tab. If you highlight a row of the table and click Edit, the Edit Action dialog appears.

If you click Add, the Select an Action wizard appears. The first panel shows a list of all the actions available. You can select the action you want to occur by clicking the radio button of that action and click Next. Depending on the action you choose, the rest of the panel displays information that you can specify for that action.

You cannot change the action type in the Edit Action dialog. You can change only the information that applies to the action.

 

Apply transformation action

If you decide to apply a transformation as an action of this screen customization, you can select the transformation you want to apply from the drop-down list of transformations defined in the project.

The Template field has "(default template)" selected by default. Unless you select a different template to be applied with this particular transformation, the template that surrounds the transformation in the browser window is the template you specified as the default template for the project. The drop-down list contains all the templates defined in the project.

Click Immediate host keys if you want host keys that the end user presses to be sent to the host immediately instead of waiting until all actions have been performed. Select the check boxes of the keys that should be sent to the host immediately. If you did this, no other actions would occur. The immediate sending of these keys applies only to the current transformation, and not to all transformations in the project.

You can turn on global rule processing as well by checking the Apply global rules check box.

 

Execute business logic action

If you decide to execute some business logic as the action of this screen customization, specify in the fields provided the fully qualified Java class name and the Java method for the business logic you want to perform. You can click Browse next to the Class name field to select a class in which the business logic method is defined. You can select any class defined under the Source folder in the HATS Project View tab of the HATS Studio. If you have not created the Java code for this business logic, right-click in the HATS Project View tab of the HATS Studio, and click New HATS > Business Logic to invoke the Create Business Logic wizard.

For more information on business logic, see the HATS Programmer's Guide

 

Extract global variable action

You can extract information from the screen and define it as a global variable. When you extract a global variable, you can specify a name or select an existing global variable name from the drop-down list for the Name field. For the region of the host screen, you define the starting and ending rows and columns for the area of the screen you want to assign as a global variable.

To specify how text extracted from multiple rows of the host screen is defined in a global variable, click Advanced. You must select one of the radio buttons to specify if the extraction should be treated as one string or as a list of strings (indexed). If you selected an existing global variable in the Name field before you clicked Advanced, click one of the following radio buttons specifying how HATS should handle the extracted data:

For the two options that use a specified index, enter the number of the index in the Index field.

The following example illustrates how the variable value is modified based on the option you choose. Start with an existing indexed variable named "sample". The values of "sample" are "a b c d". The "a" in the value has an index of 0, so the value of "sample[0]" is "a", and the "b" in the value has an index of 1, so the value of "sample[1]" is "b", and so on. Assume that you extract a new set of values "e f g".

Checking the Shared check box will take the global variable from the shared list.

For more information about global variables, see Interacting with global variables.

 

Insert data action

You can insert information onto the host screen. Specify the row and column of the screen where the data should be inserted. If you want to see where the input fields are defined on the screen, select the Highlight input fields check box. If you want to see what fields are protected, select the Highlight protected fields check box. Click Next then select whether the data is a string or a global variable by clicking the appropriate radio button. To insert a string, type the text in the entry field provided. To insert a global variable, select the name of an existing global variable from the drop-down list or type in the name of the global variable. If you want to use a shared global variable from a different application, you will need to type the name in the field.

If the value of the global variable is indexed (contains a list of strings), click Advanced. You must click one of the radio buttons to specify whether all of the strings are inserted at the specified position one after the other or if the strings are inserted as separate lines into a rectangular region of the screen.

Checking the Shared check box will take the global variable from the shared list.

Inserting information onto a host screen must occur before any transformation occurs for the global variable to appear in the Web page. See Actions for information on modifying the order of the actions.

For more information about global variables, see Interacting with global variables.

 

Set global variable action

Set global variables to be used by other objects within your project and also by other projects in the .ear. When you set a global variable, you can specify a name or select an existing global variable name from the drop-down list for the Name field. If you select an existing indexed global variable, click Advanced to specify how to handle the setting of the value. The following options are available:

For the two options that use a specified index, enter the number of the index in the Index field.

For an example of how a variable value is set based on the option you choose, see Extract global variable action.

If you are setting the global variable to a fixed value, type the value in the entry field.

If you are setting the global variable to a calculated value, you specify the operands to be used and the operation of the calculation. The operands can be either fixed values that you enter into the field, or you can use the values of existing global variables for the calculation. If you use an existing indexed global value, and you want to specify an index of the variable to use as the operand, click Advanced. Enter the number of the index in the Index field. Checking the Shared check box will take the global variable from the shared list.

For more information about global variables, see Interacting with global variables.

 

Show URL action

If you want to show a Web page as the action of this screen customization, specify the URL (uniform resource locator) address of the Web page in the URL field. With Internet Explorer Version 5.5 or later and Netscape Version 6.2 or later, the Web page is shown surrounded by the default template, similar to the way a transformation is shown. Once the Web page loads, you can go back to your HATS application by pressing the Continue Application button at the bottom of the Web page. For a list of supported Web browsers and limitations, refer to HATS Getting Started.

 

Forward to URL action

The forward to URL action enables you to pass control from a transformation-oriented HATS project to a JSP that invokes one or more chained Integration Objects. This enables you to use Integration Objects that you have already created. The Integration Objects can use the existing connection or a background connection. To add a forward action to an event, specify the following parameters:

The forward to URL allows multiple ways to manage the connection that will be used by the JSP/Integration Object logic. For example:

  1. The HATS project has already established a default connection and you want the JSP/Integration Object logic to use this connection. In this case, the JSP that gains control should drive an Integration Object that is not first-in-chain. The integration object that is driven will locate the connection to use by looking up the connection in the HTTP session object using the start state label that was associated with the integration object when it was created. This label should match the label that was specified as part of the forward to URL definition. In this case, note that when control is returned to the transformation-oriented project, a check will be made to see if the host screen has been updated. If it has, all remaining actions in the action list associated with the current event will be ignored. If the host screen has not been modified, the remaining actions will be honored.

  2. The HATS project has already established a default connection, but you want the JSP/Integration Object logic to use a new background connection. In this case, the JSP that gains control should drive an Integration Object that is either first-in-chain or not chained at all. The integration object will cause a new background connection to be established and perform its designated task against that connection. Note that the startStateLabel does not need to be specified in the forward to URL definition in this situation.

  3. A default connection has not been started. This will be the case if you add the forward to URL action to the Start event or to the Connect event (before the obtain action is executed). In this scenario, many possibilities exist. For example, the JSP that gains control can drive an Integration Object that gets its own background connection, performs a designated task, and is programmed to return control to the HATS entry servlet. At that point, the HATS entry servlet can continue with the event processing and establish a default connection. Another possibility would be that the JSP drives an integration object that is first-in-chain. The integration object establishes a connection, performs a task, and then passes the connection to the HATS entry servlet to be used as the default connection.

When you use the forward action, control does not return automatically to the HATS entry servlet after the Integration Objects have been run. The JSP must explicitly pass control back to the HATS entry servlet. If the default connection was not made before the forward action, and the Integration Objects used the default connection, pass the connection to the HATS entry servlet to be used as the default connection. In this case set a request parameter on the HttpServletRequest before forwarding the request to the HATS entry servlet. The parameter is CommonConstants.HATS_EXISTING_CONN. You can obtain the value needed for this parameter by calling the getHPubEndChainName method on the last Integration Object in the chain.

For example:

<FORM NAME="exampleLink" METHOD="GET" 
ACTION='<%= response.encodeURL(request.getContextPath()+"/entry")%>'>
<INPUT TYPE="HIDDEN" NAME="<%= CommonConstants.HATS_EXISTING_CONN %>" 
VALUE="<%= ExampleIO.getHPubEndChainName()%>" />
<INPUT TYPE="submit" VALUE="Return to HATS Entry Servlet" />
</FORM>

You can also use the HATS Tools menu to Insert Forward to HATS Servlet. This option will automatically insert the code with one exception. It will not include the following line:

<INPUT TYPE="HIDDEN" NAME="<%= CommonConstants.HATS_EXISTING_CONN %>"
       VALUE="<%= IntegrationObjectName.getHPubEndChainName() %>" />

If you wish to pass the connection to the HATS entry servlet, then edit the JSP and add the line of code right after the "FORM NAME=" line of code.

In all other cases (when the default connection was opened before the forward action was invoked, or when the Integration Objects do not use the default connection), you do not have to return the connection. You can omit the first INPUT statement from the example in those cases.

It is possible for the JSP/Integration Object logic to be the first entry into your HATS application. In that case, you can use the code that is identified to drive your HATS entry servlet and pass the connection established by the JSP/Integration Object logic to the HATS entry servlet to be used as the default connection (if the connection was created from the default connection definition).

 

Play macro

If you recorded a macro, you can select it from the drop down box to play it. The macro will begin playback whenever this event is selected. It should be noted that the Play macro action runs a macro on the current connection. The Perform macro transaction, however creates a new connection to run the macro on.

To play a macro, select the Play macro bullet from the Add Action list, then select the name of the macro to play from the drop-down list. If you define a macro to be played as an action of this screen customization, it is the last action applied. Be sure to use very specific criteria for recognizing that screen, so that the macro will not be played on other screens. For example, if you are using a string criterion, specify that it must be found at the exact location, rather than anywhere on the screen. Make sure that the screen on which the macro ends does not satisfy the criteria for starting the macro. When you record a macro, be sure that the final screen is not the screen that is recognized by the screen customization. If the recognized screen is the final screen of the macro, a loop will be created.

Ordinarily you will not apply a transformation and play a macro as actions on the same screen. If both actions are specified, the transformation will be applied, and the macro will be executed only after the user interacts with the transformed screen. The playing of a macro is always the last action to be taken. If you want a macro to be played automatically when a screen is recognized, do not apply a transformation to that screen. When you create the screen customization for that screen, clear the Apply a transformation check box on the Actions page of the wizard. You can create another screen customization for the last host screen to which your macro will navigate, and apply a transformation to govern the appearance of the Web page derived from that final screen.

You can insert a macro button into a transformation to enable the end user to run a macro from the transformed screen. In this case, the end user can either interact with the transformed screen or click the macro button to cause a macro to begin running at the current host screen.

You can record macros in the HATS Studio using the host terminal. For more information on importing macros, see Incorporating macros.

 

Perform macro transaction

Selecting this action enables you to play a recorded macro on a new instance of a designated connection. After clicking the Perform macro transaction button, select which macro you want to play in the Play a macro drop-down list and what connection to use in the Perform on connection drop-down list.

 

Send key

This action sends a specified key to the host screen. Once you have selected the location on the screen to apply your action, choose which key to send to your host screen.

Select either PF and PA keys or Other host keys from the bulleted list. Then click the drop-down menu of the bullet you selected and select the key.

Keep in mind that the key you select must change the host screen in some way or an infinite loop of the action results.

The Send key action must always run last when considering the order of your action list.

 

Text Replacement

The Text Replacement tab displays a table in which you can specify protected host screen text you want to replace, the text, HTML or image with which you want to replace the original protected text, and whether the texts are case sensitive. If the Case sensitive check box is used, it will search for the exact text that you entered in the Replace: text box.

To replace with text, simply type in the text you want replaced in the window to the right of With:. If you enter HTML code, HATS will highlight it in red so that the you will know whether or not your code is valid.

You can also replace text with images by clicking the Image radio button and selecting one from the drop-down list, or clicking the Import Image button.

You can add, modify, or remove any text replacement specifications by using the buttons to the right of the table of values. The text can be replaced at the screen customization level or at the project level.

Care should be taken when using text replacement. Text replacement with a disparate number of characters in the strings can cause changes in the HTML representation of the screen. Depending on the widget used for presenting a region of a screen, text on a line of the screen could be contracted, expanded, or forced to a new line.

 

Source

The Source tab displays the tags and values in the sc-name.evnt file for all the information supplied for the screen customization, where sc-name is the name you gave to the screen customization when you created it. As you make changes on other tabs in the screen customization editor, the tags and values displayed under the Source tab change to match.

You can also make changes to the tags and values in the source file, and they are reflected on the appropriate tabs of the screen customization editor.

 

Screen customization priority

You can modify the order of the screen customizations using the Events tab of the project editor. See Events for more information.

When a HATS application is running and a new host screen is encountered. HATS checks the first enabled screen customization in the event priority list is checked to determine if the screen recognition criteria match the host screen. If so, no more screen customizations are checked for matches, and the actions for the first screen customization are performed. If not, the next screen customization in the list is checked to determine whether the screen recognition criteria match the host screen. This continues until the last screen customization in the list is checked.

If there are no screen recognition criteria in the screen customizations that match the current host screen, HATS processes the unmatched screen event. The HATS unmatched screen event is a special screen customization that occurs only when no defined screen customizations match the host screen. The default action of this event is to display the host screen (default transformation) that applies the default template.

You can modify the actions to be taken if a host screen does not match any of your screen customizations. For example, you could create a Web page that tells the end user that the page was not found and gathers information on how the user reached that screen. You could use the Show URL action to present the Web page.

If you want to modify the action of the unmatched screen event, go to the Events tab and click Unmatched screen under the Application Events section to open its editor. Click the Actions tab at the bottom of the editor to display the actions. Click Add, Edit, or Remove to customize the unmatchedScreen.evnt file.

If you want your HATS application to recognize inhibited screens, modify each HATS screen customization that could be used to recognize inhibited screens.

An inhibited screen, also called an input-inhibited or keyboard-locked screen, is a screen containing a message notification or partial output, on which the keyboard is not enabled. Usually the user must press a certain key, such as the Escape key, to move to the next screen. By default HATS applications do not recognize inhibited screens. If you want your HATS application to recognize inhibited screens, modify each HATS screen customization that could be used to recognize inhibited screens.

Follow these steps to modify the screen customization:

  1. In the HATS Project View, expand your project and the list of screen customizations.

  2. Click on a screen customization to start the screen customization editor.

  3. At the bottom of the editor, click the Source tab.

  4. Find the line that contains the string status="NOTINHIBITED". Change "NOTINHIBITED" to "DONTCARE".

  5. Save the change by clicking File > Save or pressing Ctrl-S.

Repeat this process for each screen customization that you want to recognize inhibited screens.

 

Application Events

The rules-based approach used by HATS enables you to customize screens by applying certain actions upon a screen recognition event. You can also associate actions with other HATS events, known as application events. Application events include project occurrences such as connecting and disconnecting from the host server, starting or stopping your HATS application on a Web browser, or when your application encounters an error or an unrecognized host screen. You can configure these application events to perform certain actions when they occur.

To access the application events, go to the HATS Project View and double click the Project Settings of your HATS project and select the Events tab.

Each application event has six available associated actions: executing business logic, setting a global variable, showing a URL, forwarding to an URL, playing a macro or performing a macro transaction.

The unmatched screen event additionally allows you to apply a transformation, extract a global variable, insert data, forward to an URL, perform a macro transaction and send key information.

The following list provides descriptions of the HATS application events and when they might occur.

Start Event

A start event occurs when starting your HATS application on a Web browser. There is no default action for the start event.

Connect Event

A connect event occurs when your HATS application connects to the host server. For example, upon connecting you might want to configure your project to run a macro to bypass certain screens to display a logon screen. The default action for the connect event is to obtain a connection. This event always happens after the start event.

Unmatched Screen Event

An unmatched screen event occurs when HATS receives a screen from the host application that does not match any screen customizations in the HATS application. If you have configured your HATS application to use the default rendering for some screens, then this is a normal occurrence. If you have tried to recognize all possible host screens in screen customizations, you could configure the unmatched screen event to show a URL that tells the user he has reached an unexpected screen, asks how he got to it, and offers paths back into the proper screens. The default action for the unmatched screen event is to show the default transformation.

Error Event

An error event occurs when HATS encounters an application or host error. You might want to add an action that displays an error JSP when an error event occurs. The default action for the error event is to show a URL. The URL which is displayed is error.jsp.

Disconnect Event

A disconnect event occurs when your HATS application disconnects from the host server. The default action for the disconnect event is to release the transformation connection.

Stop Event

A stop event occurs after stopping your HATS application on a Web browser. The default action for the stop event is to show a URL. The URL which is displayed is stop.jsp

 

Home