timunderwood.net€¦ · iv using ibm websphere host access transformation services v5 chapter 2....

ibm.com/redbooks

Using IBM WebSphere Host Access Transformation Transformation Services V5

Byron BraswellMing can Jing

Alejandro Saavedra

Integrate Host Access Transformation Services (HATS) with business applications

Use enhanced customization with default transformation

Benefit from support for Web services

Front cover

http://www.redbooks.ibm.com/


Using IBM WebSphere Host Access Transformation Services V5

May 2004

International Technical Support Organization

SG24-6099-00

© Copyright International Business Machines Corporation 2004. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

First Edition (May 2004)

This edition applies to Version 5 of IBM WebSphere Host Access Transformation Services.

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThe team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. New components and widgets . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.1 Server hardware and software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.2 HATS development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.1 Creating the database and adding data . . . . . . . . . . . . . . . . . . . . . . . 51.2.2 Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Creating a HATS application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.1 Building a basic application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 Testing the HATS application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.5 Generating a template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1.5.1 Creating a corporate template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.6 Screen captures and drop-down lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.6.1 Capturing screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.7 Using tabbed folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.7.1 Adding a tabbed folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.7.2 Customizing the tabbed folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.8 Generating global rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301.9 Using pop-up lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.10 Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

1.10.1 Capturing the screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431.10.2 Capturing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.11 Using the text replacement option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521.12 Using graphics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551.13 Changing the cascading style sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

1.13.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571.13.2 Creating an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591.13.3 Finding the tag that is used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

1.14 Running the HATS project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631.15 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

© Copyright IBM Corp. 2004. All rights reserved. iii

Chapter 2. Integrating HATS with business applications . . . . . . . . . . . . . 712.1 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

2.1.1 Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732.1.2 HATS development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 742.1.3 Enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

2.2 Integrating HATS with a database application . . . . . . . . . . . . . . . . . . . . . 752.2.1 Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752.2.2 Creating an AS/400 database access application. . . . . . . . . . . . . . . 772.2.3 Using macros in an OS/400 environment . . . . . . . . . . . . . . . . . . . . 1012.2.4 Combining HATS with the database application . . . . . . . . . . . . . . . 1162.2.5 Testing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

2.3 Using HATS with a 3270 application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392.3.1 Generating a macro with 3270 application . . . . . . . . . . . . . . . . . . . 1392.3.2 Generating an Integration Object with a 3270 application . . . . . . . 1422.3.3 Generating a Model 1 application with a 3270 application . . . . . . . 1462.3.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

2.4 Using HATS with VT applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552.4.1 Creating a new connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552.4.2 Using a User List in a VT transformation . . . . . . . . . . . . . . . . . . . . 1582.4.3 VT macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592.4.4 Generating an Integration Object with VT application. . . . . . . . . . . 1642.4.5 Generating Model 1 application Web pages with VT application . . 1662.4.6 Testing the VT application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

2.5 Exposing Integration Objects as a Web application using Struts . . . . . . 1692.5.1 Creating Struts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702.5.2 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

2.6 Exposing Integration Objects as a Web application using Web services 1772.6.1 Creating a Web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782.6.2 Testing the Web services application . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 3. Integrating HATS with WebSphere Portal Server. . . . . . . . . . 1893.1 HATS portal support overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

3.1.1 HATS portal integration architecture . . . . . . . . . . . . . . . . . . . . . . . . 1903.1.2 HATS portal support requirements and limitations . . . . . . . . . . . . . 192

3.2 Scenario topology and preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1933.2.1 Scenario topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1933.2.2 Preparing the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

3.3 Creating, deploying, testing a basic HATS portlet . . . . . . . . . . . . . . . . . . 1983.3.1 Creating a basic HATS portlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983.3.2 Converting the HATS application to portlet . . . . . . . . . . . . . . . . . . . 2033.3.3 Deploying the HATS portlet on WebSphere Portal Server . . . . . . . 2053.3.4 Testing the HATS portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

3.4 Using portal credential support in HATS . . . . . . . . . . . . . . . . . . . . . . . . . 221

iv Using IBM WebSphere Host Access Transformation Services V5

3.4.1 HATS test scenario with portal credential vault. . . . . . . . . . . . . . . . 2223.4.2 Building the Credential Vault Populate portlet. . . . . . . . . . . . . . . . . 2223.4.3 Deploying and testing the Credential Vault Populate portlet . . . . . . 2303.4.4 Creating the HATS credential integration portlet. . . . . . . . . . . . . . . 2383.4.5 Creating a screen customization for the logon screen . . . . . . . . . . 2413.4.6 Creating the credential vault business logic Java method . . . . . . . 2493.4.7 Recording the signon macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2533.4.8 Enhancing the signon macro with multi-process path support . . . . 2613.4.9 Completing the signon screen customization . . . . . . . . . . . . . . . . . 2783.4.10 Deploying and testing the credential-enabled HATS portlet . . . . . 280

3.5 Administration for a HATS portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2813.5.1 HATS administration support included in the HATS portlet . . . . . . 2823.5.2 Stand-alone HATS administration portlet . . . . . . . . . . . . . . . . . . . . 283

3.6 HATS portal support advanced topics. . . . . . . . . . . . . . . . . . . . . . . . . . . 2843.6.1 Converting a JSP file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2843.6.2 Extending the HATS portlet function . . . . . . . . . . . . . . . . . . . . . . . . 2853.6.3 More portal integration support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Chapter 4. Using Web Express Logon with HATS portlets . . . . . . . . . . . 2894.1 Web Express Logon overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2904.2 Getting started with Web Express Logon . . . . . . . . . . . . . . . . . . . . . . . . 290

4.2.1 Web Express Logon background . . . . . . . . . . . . . . . . . . . . . . . . . . 2904.2.2 Network security layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2914.2.3 Application environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2914.2.4 HATS Web Express Logon process . . . . . . . . . . . . . . . . . . . . . . . . 2924.2.5 Web Express Logon example scenario. . . . . . . . . . . . . . . . . . . . . . 2934.2.6 Web Express Logon configuration process. . . . . . . . . . . . . . . . . . . 295

4.3 Using Web Express Logon portal scenario . . . . . . . . . . . . . . . . . . . . . . . 2954.3.1 Scenario overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2964.3.2 Creating a HATS portlet project to use Web Express Logon . . . . . 2974.3.3 Configuring Web Express Logon in a HATS project . . . . . . . . . . . . 2974.3.4 Recording a logon macro with Web Express Logon support . . . . . 3014.3.5 Configuring a HATS project to use the logon macro. . . . . . . . . . . . 3114.3.6 Deploying the Web Express Logon enabled portlet . . . . . . . . . . . . 3114.3.7 Preparing the portal Credential Vault Populate Portlet for Web Express

Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3124.3.8 Testing the HATS_WEL portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

4.4 Web Express Logon advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . 3254.4.1 Credential mapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3264.4.2 Network security provider plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . 3264.4.3 Credential mapper plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Chapter 5. Deploying applications in WebSphere Application Server V5329

Contents v

5.1 Introduction to HATS Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3305.2 Deploying a HATS application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3305.3 Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

vi Using IBM WebSphere Host Access Transformation Services V5

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

© Copyright IBM Corp. 2004. All rights reserved. vii

TrademarksThe following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

Eserver®ibm.com®iSeries™z/OS®AIX®AS/400e™AS/400®

CICS®DB2 Universal Database™DB2®IBM®OS/390®OS/400®Redbooks (logo) ™

Redbooks™RACF®RS/6000®Tivoli®WebSphere®

The following terms are trademarks of other companies:

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC.

Other company, product, and service names may be trademarks or service marks of others.

viii Using IBM WebSphere Host Access Transformation Services V5

Preface

IBM® WebSphere® Host Access Transformation Services (HATS) provides tools to quickly and easily extend your legacy green-screen applications to the Web. HATS makes your 3270 and 5250 applications available as Hypertext Markup Language (HTML) through Web browsers. It also converts your host screens to a Web look and feel. Using HATS, you can improve the workflow and navigation of your host applications without any access or modification to source code.

HATS has a development component called HATS Studio, which runs in WebSphere Studio. There is no specialized HATS runtime server. All of the necessary runtime information is deployed into an Enterprise Archive (EAR) file and runs in WebSphere Application Server.

This IBM Redbook helps you to tailor and configure the new features that are included with HATS V5. Examples and usage scenarios demonstrate how to implement many of the new features and functions, along with those that were present in previous releases of HATS.

The team that wrote this redbookThis redbook was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Raleigh Center.

Byron Braswell is a networking professional at the ITSO, Raleigh Center. He received a Bachelor of Science degree in physics and a Master of Science degree in computer sciences from Texas A&M University. He writes extensively in the areas of networking and host integration software. Before joining the ITSO four years ago, Byron worked in IBM Learning Services Development in networking education development

Ming can Jing is an Advisory IT Specialist at IBM China. He has nearly five years experience in software pre-sales and post-sales support. He is an IBM-certified WebSphere Application Server Specialist, System Expert, AIX® specialist, MQ Series specialist, and WebSphere Studio Application Developer specialist. He is also a SUN certified Java™ Programmer and Microsoft® certified System Engineer. He received his Bachelor of Science and Master of Science degrees in computer sciences from XIDIAN University, People’s Republic of China in Xi'an. He currently provides pre-sales technical support in the advanced technical support team in IBM China.

© Copyright IBM Corp. 2004. All rights reserved. ix

Alejandro Saavedra is an Accredited IT Specialist in IBM Argentina. He has nearly six years experience in software pre-sales support. He is an IBM-certified WebSphere Application Server Specialist, System Expert, and a Host Integration and WebSphere Portal Server solution specialist. He received his System Engineer degree in computer sciences from Universidad Abierta Interamericana, Argentina. He currently provides pre-sales technical support in Spanish South America.

The authors from left to right: Alejandro Saavedra, Byron Braswell, Ming can Jing

Thanks to the following people for their contributions to this project:

Tamkia BarrowLinda RobinsonBirgit RoehmMargaret TicknorInternational Technical Support Organization, Raleigh Center

Sherrie AbshireSusy ChinratanaGabriel CohenRon CraigKyle CroutwaterBill HaltermanThom HaynesAshish JainChristin LaiPatrick LyerlySue MitchellBrian Safron

x Using IBM WebSphere Host Access Transformation Services V5

Timothy SipplesIBM Research Triangle Park, North Carolina

Juan Manuel MartinezIBM Spain

Become a published authorJoin us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability.

Find out more about the residency program, browse the residency index, and apply online at:

ibm.com/redbooks/residencies.html

Comments welcomeYour comments are important to us!

We want our Redbooks™ to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways:

� Use the online Contact us review redbook form found at:

ibm.com/redbooks

� Send your comments in an Internet note to:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HZ8 Building 662P.O. Box 12195Research Triangle Park, NC 27709-2195

Preface xi

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html


http://www.ibm.com/redbooks/


http://www.redbooks.ibm.com/contacts.html

xii Using IBM WebSphere Host Access Transformation Services V5

Chapter 1. New components and widgets

Today many companies are studying ways to migrate from their legacy applications or to modernize the old fashioned presentation style of their legacy applications. In a normal business environment, we see many situations where it is not necessary to modify traditional applications (5250, 3270, and VT) using software reprogramming. On the contrary, what is necessary is a robust solution that can permit a transparent, faster, and dynamic transformation to new e-business Web applications without changing anything in the legacy mainframe systems. Figure 1-1 shows an overview of the big picture.

This chapter reviews some of the new features in IBM WebSphere Host Access Transformation Services (HATS) V5. It describes how to transform legacy applications into a new Web interface. It also discusses the possibility to integrate your legacy applications into a new or existing e-business environment. The most important consideration here is to define a robust set of rules to transform, in a dynamic way, the information that passes through WebSphere HATS to new e-business applications and the end user.

1

© Copyright IBM Corp. 2004. All rights reserved. 1

Figure 1-1 Understanding the big picture

This chapter covers the following features that are either new in HATS V5 or have been enhanced in this release:

� Templates (see 1.5, “Generating a template” on page 17)� Drop-down lists (see 1.6, “Screen captures and drop-down lists” on page 21)� Tabbed folders (see 1.7, “Using tabbed folders” on page 25)� Global rules (see 1.8, “Generating global rules” on page 30)� PopUp list (see 1.9, “Using pop-up lists” on page 36)� Calendar (see 1.10, “Calendar” on page 43)� Text replacement (see 1.11, “Using the text replacement option” on page 52)� Graphics (see 1.12, “Using graphics” on page 55)� Cascading style sheet (CSS) (see 1.13, “Changing the cascading style sheet”

on page 57)

1.1 Environment This section reviews the hardware and software environment used to develop and test the HATS scenarios in the following sections. Figure 1-2 displays the network environment used to develop our tests.

WebSphereWebSphere

WebWeb3270327052505250VTVT

Transformation Rules

New channel"Web environment"

Traditional applications"Legacy applications"

2 Using IBM WebSphere Host Access Transformation Services V5

Figure 1-2 General environment

1.1.1 Server hardware and softwareWe use an IBM AS/400e™ server, as opposed to a newer IBM Eserver iSeries™ server, to show the process to create and use basic rules and features. This section describes the AS/400e hardware that is used for our transforms.

In this environment, we use the AS/400e 9406 Model 500 running OS/400® V4R5, with the resources listed in Table 1-1.

IBM AS/400 or IBM Eserver iSeries

OS/400 V4R5PetStore DBAgenda DB

IBM Eserver pSeries

AIX V5.3

IBM Eserver zSeries

CICSApplication

Intranet

IBM Eserver xSeries

WebSpherePortal Server

V5.02 IBM Eserver

xSeries

WebSphereApplication

ServerV5.02

IBM Eserver

xSeries

WebSphereStudio

ApplicationDeveloper V5.1

Host AccessTransformation

Services V5

Portal plug-in

Note: In this scenario, we use an AS/400e model that, as a matter of fact, is no longer supported. As you see when going through the scenario, HATS demonstrates its ability to work just as well with older mainframe systems.

With this in mind, you are not required to upgrade or change your host systems to start the process of integrating your legacy applications into the new e-business environment. However, an upgrade may be required if you want to run HATS on an AS/400e or iSeries™ machine. Consult the IBM Eserver Workload Estimator on the Web at:

http://www-912.ibm.com/wle/EstimatorServlet

Chapter 1. New components and widgets 3


Table 1-1 Display processor resources

1.1.2 HATS development environmentThe HATS development environment consists of the following hardware, operating system, and software:

� Hardware

– Pentium® 4 CPU 1.80 GHz– 40 GB hard drive

� Operating system

– Windows® 2000 Professional– Service Pack 4

� Software

– WebSphere Studio Application Developer V5.1– Host Access Transformation Services V5– Portal Toolkit V5.02

1.2 ApplicationsFor our test scenario environment, we created one database using DB2® Query Manager provided by the AS/400® system. The name of the database is PET40AE (part of the PETSTORE example).

Resource Type-model Status Information

CEC01 9406-500 Operational Main Card Enclosure

PN01 2468-001 System control Operational Panel

MP01 2142-000 Operational system Processor Card

SP01 9162-001 Service processor Operational Card

BCC01 Operational Bus Extender


MS01 3187-0E1 Operational 256 MB Main Storage Card





1.2.1 Creating the database and adding dataPETSTORE is the example application that is supplied with the current version of WebSphere Application Server (and in the previous two versions). If you want to create this database on an iSeries system and you have installed WebSphere Application Server, you can obtain the script to automatically generate the database, tables, and data on your iSeries server. The script typically is found in /QIBM/ProdData/WebAS51/Base/samples/bin/installsamples.

Alternatively, you can go to the following Web site and download the script and instructions:

http://publib.boulder.ibm.com/was400/51/english/info/rzaiz/51/admin/qshinstsamp.htm

You need to add one table (AGENDA) in the PET40AE database. To do this, use the Query Manager facilities to manually create the table using the definitions TABLE NAME = AGENDA as shown in Table 1-2.

Table 1-2 Table definitions

After you create the AGENDA table, add some sample data, for example:

� Name = CHUCHI� Birthday = 10/10/2003

The PET40AE database has many tables. We use only the CATEGORY table.

1.2.2 ReviewWe created one database named PET40AE with two tables: AGENDA and CATEGORY. We do not need anything else because we use the normal administration environment that comes with the OS/400.

1.3 Creating a HATS applicationWe work with some of the features of HATS V4 (Tabbed folder, CSS, and others), and then show how these features are enhanced in HATS V5. In addition, we discuss some of the new features (global rules, calendars, and importing templates).

Column Type Length

NAME VARCHAR 80

BIRTHDAY DATE


http://publib.boulder.ibm.com/was400/51/english/info/rzaiz/51/admin/qshinstsamp.htm

1.3.1 Building a basic applicationThe following section describes in detail the steps needed to build a basic application to transform the AS/400e environment.

Project settingsTo initiate the HATS Studio environment, follow these steps:

1. Click Start →Programs →IBM WebSphere HATS →HATS Studio.

2. If you see the message shown in Figure 1-3, you have the option to select where you want to create your HATS project in the file system. If you saw the message previously and selected Use this workspace as the default and do not show this dialog box again, you don’t see this message again.

Click OK.

Figure 1-3 Storing your work in the workspace directory


Depending on your workstation’s hardware configuration, wait a few seconds and then you see the HATS V5 Studio Welcome page.

Figure 1-4 HATS Studio Welcome page


Creating a projectTo create a new project, follow these steps:

1. Click File →New →Other →HATS →HATS Project. As an alternative, you can click the Create HATS Project button on the toolbar or, on the Welcome to HATS page, click the launch the Create HATS Project wizard link.

2. If you choose the first method (from the File menu), the New – Select window (Figure 1-5) opens. Confirm that HATS and HATS Project are highlighted as shown in Figure 1-5. Click Next.

Figure 1-5 Selecting a project


3. In the Create a Project panel (Figure 1-6), set the project name with your particular information. For our test example, we entered the following information:

– Name (project): OX– Enterprise Application project name (default): OX.EAR

Leave the other check boxes at their defaults and click Next.

Figure 1-6 Creating a project


4. In the Connection Settings panel (Figure 1-7), enter the appropriate host connection information. For our example, we entered:

– Host name: 9.42.102.158 (or system name)– Port: 23 (default)– Type: 5250 (OS/400)

Click Next.

Figure 1-7 Connection settings


5. In the Select Default Template panel (Figure 1-8), you have the option to select one of the 15 templates provided by HATS in the base installation. You can also create your own corporate template using different techniques. We cover this option later. In our example, we select Simple1.jsp and click Finish.

Figure 1-8 Selecting the default template


You see the window shown in Figure 1-9 when you successfully complete the principal configuration.

Figure 1-9 Overview

The next step is to test the application.

1.4 Testing the HATS applicationThe application we created using the HATS Studio plug-in is a Java 2 Platform, Enterprise Edition (J2EE) application. HATS Java applications require


WebSphere Application Server to run. Therefore, we must deploy our HATS J2EE application to an application server to test it.

A WebSphere Application Server V5 Test Environment comes with WebSphere Studio Application Developer V51. You need only to configure one test environment and assign the project to it.

If you have not yet created a test environment, run the HATS project that you created and accept the default values presented by WebSphere Studio Application Developer.

1. Using HATS as shown in Figure 1-10, right-click the project name and select Run on Server.

Figure 1-10 Selecting to ‘Run on Server’


2. In the Server selection panel (Figure 1-11), click Finish to run the project.

Figure 1-11 Server selection


3. Figure 1-12 shows the HATS application running using the default template that we selected in Figure 1-8 on page 11. If you prefer, copy the Uniform Resource Locator (URL) that is displayed and paste into a stand-alone browser window running on your PC. Replace localhost in the Web address with the numeric IP address associated with your development PC. If you have another PC or Macintosh that can connect over the network to your development workstation, you can test your HATS Web pages there too.

You see the same sequence of application windows. However, using a browser interface allows you to immediately evaluate the user experience. Double-clicking the Web Browser tab makes the browser fill the entire WebSphere Studio Application Developer window.

Navigate through some pages to see the default transformation. Double-click Project Settings for your project

Figure 1-12 Running the default transformation


4. The project editor (Figure 1-13) opens. You see the settings used for the entire project.

Figure 1-13 Project editor overview

Use the project editor tabs to modify any of the settings used in the project:

– Overview: General information (see Figure 1-13)

– Connections: Legacy host information

– Template: Defines the default template (stylesheets and structure into which the transformation is placed) for the project (can be overriden for particular host screens)

– Rendering: Default changes or settings for your components

– Events: Allows you to prioritize any screen customization events that are associated with a recognized screen


– Other: More features

– Source: Extensible Markup Language (XML) source code view of the application.hap file that contains all settings for a project

See IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575, for additional information.

1.5 Generating a templateHATS V4 included support to create custom templates. However, it required at least general knowledge of Web page creation, formatting, style sheets, and so on. In HATS V5, you can import a predefined company template using the wizard provided with HATS.

1.5.1 Creating a corporate templateA template is simply a JavaServer Pages (JSP) file that includes information about how you want to display Web pages and transformations for this site. Think of this as a master template where all the Hypertext Markup Language (HTML) pages receive the same background information. HATS V5 includes more facilities to customize your own template.

You can modify one of the samples provided with HATS V5, or create one using another template. We discuss both options in the following sections.

Modifying an existing HATS templateIn the following example, we modify one of the templates supplied with HATS:

1. As shown in Figure 1-14, open project name →Web Content →Templates. Double-click a supplied template. In our example, we click Simple1.jsp. Recall that Simple1.jsp is the default template we used previously.

2. Modify the links, colors, names, and other items to create a customized template.

Important: All HATS product installations install the same default templates. If you modify one of them, change all the graphics, colors, and fonts to avoid possible duplication with the HATS transformations created by other HATS product users.


Figure 1-14 Modifying a template

Importing an existing templateUsing a currently existing company Web template may be the best and easiest way to integrate a HATS e-business solution into a company’s Web presence. Importing an existing template into a HATS project is easier in Version 5.

Let’s begin customizing our template:

1. Right-click the project name and select New HATS →Template.

2. In the Create a Template – Select name and destination of template window (Figure 1-5), type a name for the template (OX in our example) and select the Templates folder. Click Next.


Figure 1-15 Creating a template

3. On the next screen, select from the following options:

– Create a new template– Preload the template with information from an existing HATS template– Preload the template from an existing Web Page (File or URL)

For our example, select Prefill the template from an existing Web Page (File or URL). We set the URL as http://www.ibm.com/ (or your company URL) and click Finish.

4. You can make changes to the template as shown in Figure 1-14.

It is important to first remove any unnecessary information such as links, images, text, tables, and so on, that will not be required on any of our HATS transformations. We recommend that you leave only the principal banners where your company displays basic information along with any company-wide news or information display.


5. Assign the customized template to our HATS project as shown in Figure 1-16:

a. From the HATS Project View, select the project name (ox in our example) and double-click Project Settings.

b. Select the Template tab.

c. In the Template pane, from the Template list, select your own template (in this case, ox.jsp).

d. Press Ctrl+S to save and close the window.

Figure 1-16 Selecting your customized template


1.6 Screen captures and drop-down listsTo demonstrate the use of some host screens, new features in HATS, we need to capture some screens. We capture the following screens from our host session:

� Logon screen� Work with Active Jobs (WRKACTJOB) output� User tasks

1.6.1 Capturing screensTo capture screens, follow these steps:

1. Right-click the project name and select Open Terminal →main.

2. The logon screen (Figure 1-17) of our application opens. We want to capture the logon screen. Click the Create Screen Capture button (circled in Figure 1-17) at the top of the Host Terminal screen. Keep the screen name that is proposed by HATS and click Finish.

Type your user name and password in the logon screen. Press Enter to proceed to the Main Menu.

Figure 1-17 Screen capture logon

Attention: Before you continue to the next section, close all tabs in the editor pane, but not the HATS tab. We test all the customizations together at the end of this chapter.


3. We also want to capture the Work with System Status (WRKSYSSTS) command output. WRKSYSSTS is a typical OS/400 command to query the system status. You type it on an OS/400 command line. Using the process described previously, capture the WRKSYSSTS output with the name mygraphic. Return to the AS/400 Main Menu.

4. On the Main Menu display, type 1 and press Enter.

5. You proceed to the User Tasks screen. Click the Create Screen Capture button as described previously to capture the User Tasks screen. Press PF12.

6. You return to the Main Menu as shown in Figure 1-18. In the left corner of this display, click the New Screen Customization icon.

Figure 1-18 Host terminal Main Menu

7. Leave the next two screens without changes and click Finish.


8. The Insert Component Tag – Screen Region window (Figure 1-19) opens. Here you have the option to select a region of the screen to be transformed. We transform the Main Menu options into a drop-down list.

Using the mouse, select the entire options list in the Main Menu as shown in Figure 1-19. Click Next.

Figure 1-19 Insert Component Tag window showing the Main Menu


9. In the Insert Component Tag – Rendering Options window (Figure 1-20), you can select from a list of Widgets that apply with the selection we highlighted previously. Under Components, we selected Selection List. Under Widgets, we selected Drop-down (selection). Click Finish.

Figure 1-20 Insert Component Tag selection list

10.Press Ctrl+S to save and close the window.


1.7 Using tabbed foldersUse this feature when you need to organize information in different views. Tabbed folders are helpful when the screens have much information. They allow you to separate the information into different views.

1.7.1 Adding a tabbed folderTo add a tabbed folder, follow these steps:

1. In the HATS Project View pane, select project name →Web Content →Transformation. Click As_400MainMenu.jsp. On the right, you see the JSP ready to add more definitions.

Attention: Before you continue to the next section, close all tabs in the editor pane, but do not close HATS. We test all the customizations together at the end of the chapter.


2. Place the cursor anywhere on the As_400MainMenu.jsp Design view (Figure 1-21). Right-click and select HATS Tools →Insert Tabbed Folder.

Figure 1-21 Inserting a component into As_400MainMenu.jsp

1.7.2 Customizing the tabbed folderIn the Insert Tabbed Folder window (Figure 1-22), add the following information to customize the environment for one screen, in this case, the Main Menu.

Configure the Number of tabs as 2. Complete Tab 1 and Tab 2 using options that are explained later. For Tab1, we add a command line host component, and for Tab 2, we add the system name.


Figure 1-22 Defining tabbed folder options.

Configuration for Tab 1To configure Tab 1, follow these steps:

1. On the Tab 1 page (Figure 1-22), specify the following values:

– For Label text, enter Command Line.– For Selected background color, select Light gray.

2. On the same page, for Insert host component, click the Insert Host Component button.


3. The Insert Component Tag – Screen Region window (Figure 1-23) opens. Select the command line and click Next.

Figure 1-23 Tabbed folder for command line component

4. The Rendering options panel opens. Under Components, select Input field. Under Widgets, select Text input. Click Finish.


Configuration for Tab 2To configure Tab 2, follow these steps:

1. On the Tab 2 page, specify the following values:

– For Label text, enter System Name.– For Selected background color, select Cyan.

2. On the same page, click the Insert Host Component button.

3. The Insert Component Tag – Screen Region window (Figure 1-24) opens. Select the system name and click Next.

Figure 1-24 Tabbed folder for system name


4. The Rendering options panel opens. Under Components, select Text. Under Widgets, select Label. If you want, you can test the tabbed folder using the Full page preview button. Click Finish.

5. Click OK.

6. Press Ctrl+S to save the transformation.

1.8 Generating global rulesGlobal rules can be one of the most useful features in HATS V5. In the previous version, you had only the ability to generate individual rules. If you had good skills for developing Java applications, you could develop global rules without any extra support within HATS. In version 5, you can define global rules using HATS wizards.

Typically, there are requests to change host green screens to provide a new user interface. Or there are requests to include host green-screen data in a migration of the entire legacy application to a new environment using J2EE development.

Two different approaches are available.

� The first approach is to reuse all the existing legacy applications. In this case, HATS is used with all the major features including individual transformations and others to expose your entire solution using Web services, Struts, etc.

� The second is to migrate all the legacy applications. This is a long-term process. It involves research and selection of the technologies that meet the requirements best for the new Web environment. During the migration process, HATS can help to show a solution up and running in a few weeks. HATS can also be used as a migration path from the legacy solution to a new middleware application solution. HATS also supports the ability to mix legacy applications and data with J2EE applications.

The following steps take you through a scenario using HATS global rules:

1. Select project name →Project Settings and double-click.


Important: The recommendation for both situations is to use global rules because it requires less development time and maintenance.


2. In the right panel (Figure 1-25), select the Rendering tab. In the Rendering pane, select Global Rules and click the Add button.

Figure 1-25 Default rendering of Global Rules


3. As shown in the Create a Global Rule – Global Rule window (Figure 1-26), enter the following information:

– Name: oxGV– Create transformation fragment: oxGV.jsp

Click Next.

Figure 1-26 Creating a Global Rule: Adding a name

4. In the Global Rules settings display, select SignOn. We captured this display in 1.6, “Screen captures and drop-down lists” on page 21.


5. To mark the part of the screen where we want to work, we must use the Search for and Located options under Pattern Settings (see Figure 1-27). In this example, work with the Current library field. Complete with the following information:

– Search for: Current lib*– Located: To the left

Click Next.

Figure 1-27 Creating Global Rules: Current library


6. The Rendering options panel opens (Figure 1-28). Under Components, select Input field. Under Widgets, select Drop-down list (data entry).

7. A drop-down list needs the values that it uses to show the options. To do this, click the Widget Settings button as shown in Figure 1-28.

Figure 1-28 Default rendering: Drop-down

Widget Settings


8. The Widget Settings window (Figure 1-29) opens. Deselect the Use project defaults check box. Select String. For List Items, specify Administrator=QSYS;Customers=QGPL. Click OK.

Figure 1-29 Default rendering list items

9. Click Finish.

10.You have more options to select from if you choose. Table 1-3 lists the library select list for OS/400.

Table 1-3 Library selection list

Library Type

QSYS SYS

QHLPSYS SYS

QUSRSYS SYS

QTEMP USR

QGDDM USR

QGPL USR


1.9 Using pop-up listsIn the previous release of HATS, a developer could only specify that an Input Field should be rendered as a Text Input Widget. In this release, a developer can render the Input Field as a field followed by a button. When pressed, it results in a pop-up list of possible values. This is similar to the usage of a drop-down list, just with a different look. A valid value pop-up list is used if the developer wants to limit the values that a user can enter into this input field.

To use this pop-up list feature, follow these steps:

1. Select project name. Right-click and select New HATS →Transformation.

2. In the window that opens, for the Transformation name, type UserTasks and click Next.



3. In the Create a Transformation – Select Screen window (Figure 1-30), select User Tasks. We captured this screen in 1.6, “Screen captures and drop-down lists” on page 21. Click Next.

Figure 1-30 Pop-up selection list


4. Complete the Rendering Options panel as shown in Figure 1-31 with the following information:

– Initial Layout: Blank – Leave other options at their default values

Click Next. And then click Finish.

Figure 1-31 Pop-up rendering options

5. HATS opens the New Screen Customization panel. Click Next twice and then click Finish.


6. Press Ctrl+S to save the UserTask.jsp file.

7. Be sure that you are on the Design view of UserTask.jsp as shown in Figure 1-32. Right-click and select HATS Tools →Insert Host Component.

Figure 1-32 Pop-up Insert Host Component


8. In the Insert Component Tag – Screen Region window (Figure 1-33), select the command line using your mouse pointer.

Figure 1-33 Pop-up selection on a screen

9. The Rendering options panel opens. Under Components, select Input field. Under Widgets, select Popup. Click Next.


10.We need to pass the values that the Popup widget uses. As shown in Figure 1-34, click the Widget Settings button.

Figure 1-34 Selecting the Popup widget

Widget Settings


11.In the Settings - Popup window (Figure 1-35), you can customize the widget for this transformation. Deselect the Use project defaults check box. Select String. For List Items, type System Status=wrksyssts;Jobs Running=wrkactjob.

Click OK.

Figure 1-35 Popup list items

12.Click Finish.

13.Press Ctrl+S to save the transformation and close the windows.

Note: This feature is very appropriate in situations where the end user is required to complete repetitive information, for example a Country (region) field.


1.10 CalendarIn the previous release of HATS, the developer could only specify that an Input Field should be rendered as a Text Input Widget. In this release, the developer can choose to render the input field as either text inputs, drop-down lists, radio buttons, check boxes, or calendars.

The developer can also specify that input fields should be used to render a date. HATS renders these host input fields as input fields on the browser followed by a button to launch a pop-up calendar that the end user may use to select a date. The developer must specify the date pattern to enter into the host input fields when the end user selects a date from the pop-up calendar. There is a graphical user interface (GUI) to help the developer build these patterns (for example mm/dd/yy).

1.10.1 Capturing the screenTo capture the screen, follow these steps:

1. Select your project name, right-click, and select Open Terminal →main.

2. In the command line, type STRQM and press Enter.

3. On the next screen, type option 3 and press Enter.



4. In the DB2 Query Manager for AS/400 screen (Figure 1-36), in the Library field, type PET40AE and press Enter.

Figure 1-36 Specifying a collection or library


5. On the Work with Query Manager Tables screen (Figure 1-37), in the AGENDA table option, type 5. Press Enter.

Figure 1-37 Calendar work with Query Manager tables

Important: In this chapter, we do not use macros. For this reason, we must pass through all screens every time. In Chapter 2, “Integrating HATS with business applications” on page 71, we use macros. After reviewing that chapter, you can return to this part and generate a macro to navigate through all of these screens automatically.


6. Figure 1-38 shows your host terminal. We make an individual transformation for this page. Click the Create HATS Transformation button (circled at the top of the window).

Figure 1-38 Calendar Query

7. The next screen asks you about the name of the transformation. Do not change anything. Click Next twice.


8. In the Create a Transformation – Rendering Options window (Figure 1-39), under Initial Layout, select Blank. Click Finish. At this moment, we have captured only the page.

Figure 1-39 Calendar transformation options

9. Now we need to define the Recognition Criteria. In the window that follows, leave the name proposed for the tool and click Next.

10.In the next window, leave the default recognition criteria and click Next.

11.Click Finish. When you finish the screen capture and recognition criteria, your window should appear like the example in Figure 1-40.


1.10.2 Capturing componentsUsing the Screen Transformation capabilities, we capture two different components from the FindDataInQueryManage_1 screen. The first one is the value and the second one is the column and test.

Capturing valueTo capture the value, follow these steps:

1. Be sure that you are on the Design view of FindDataInQueryManage_1.jsp. Right-click and select HATS Tools →Insert Host Component as shown in Figure 1-40.

Figure 1-40 Calendar Insert Host Component


2. In the Insert Component Tag – Screen Region window (Figure 1-41), for Select a screen, select FindDataInQueryMange_1. The screen changes to Find Data in Query Manager Table. Use the mouse pointer to select the Value Input Field. Click Next.

Figure 1-41 Calendar Screen region


3. The Rendering options panel opens. Under Components, select Input field. Under Widgets, select Calendar. Click Finish.

You return to the initial Design view for FindDataInQueryManage_1.jsp.

Figure 1-42 Calendar special configuration

Capturing column and testUsing the previous steps used to capture Value, we capture two more fields.

Important: We do not use all of the functions that are available for each feature. There are extended possibilities that you have with the Calendar Widget. The Calendar Widget’s Settings window provides a way to manually type a pattern and to obtain help for building a pattern. The Settings window also shows the developer an example of the pattern that was built. The window shown in Figure 1-42 is used to make calendar modifications.


1. Be sure that you are on the Design view of FindDataInQueryManage_1.jsp. Right-click and select HATS Tools →Insert Host Component as shown in Figure 1-40 on page 48.

2. On Insert Component Tag – Screen Region window (Figure 1-43), select the Test and Value columns. Click Next.

Figure 1-43 More Calendar screen regions


3. The Rendering options panel opens. Under Components, select Input Field. Under Widgets, select Text Input.

4. Now you see a panel similar to the one shown in Figure 1-44. Click Finish.

Figure 1-44 Calendar Final

5. Press Ctrl+S to save the transformation and close the windows.

1.11 Using the text replacement optionYou can replace text with HTML or with images using the text replacement options at the Project Settings level and a new option at the Screen Customization level. This feature is quite useful in the following situations:

� When your core system was developed in external language and you need to translate some parts of it

� When you can’t show internal information outside the company

� When you need to change the normal text per marketing requirements

We performed the following steps for our text replacement scenario:

1. Select project name →Project Settings and double-click.



2. As shown in Figure 1-45, in the right panel, click the Rendering button. In the Rendering pane, click Text Replacement and then click the Add button.

Figure 1-45 Text replacement Adding rule

3. Add a rule to replace SYSTEM NAME (in our case ELCRTP06) with an image. In our example, we use an image showing a Chinese translation for MYCOMPANY. You can generate your own image for your company.


4. In the Add Text Replacement window (Figure 1-46), for Replace, enter your system name. In this example, we type ELCRTP06. For With, select Image and specify your image file. Click OK.

When you import an image, you add that file in the projectname/Web Content/common/images/ directory.

Figure 1-46 Text replacement: Defining rules


5. To see or add more image files in your project, change to the Navigator view (Figure 1-47). Then in the Navigator pane, select project name →Web Content →common →images.

Figure 1-47 Text replacement Navigator view

6. Click OK.

7. Press Ctrl+S to save the transformation and close the window.

1.12 Using graphicsThe ability to render some information as a graphic is useful in situations where it’s necessary to show reports about marketing trends or system status in a graphical view. Using this feature, you can add the extra graphical representation that you need to show a complete e-business application.



1. Select project name →New HATS →Screen Customization.

2. In the Create Screen Customization panel, for Name, type mygraphic and click Next.

3. In the Insert Component Tag – Screen Region window (Figure 1-48), for Select a screen, select mygraphic. We captured this screen in 1.6, “Screen captures and drop-down lists” on page 21. Click Next and then click Finish.

4. Using your mouse pointer select Pool Size (Figure 1-48). Click Next.

Figure 1-48 Graphic Pool size


5. The Rendering options panel opens. Under Components, select Visual Table. Under Widgets, select Visual bar graph. Click Finish.

6. Press Ctrl+S to save transformation and close the window.

You also have the option to use Widget Settings to change the axis, name, color, images, and other details of the graphical display.

1.13 Changing the cascading style sheetUsing this feature with global rules, you can define and run in a few days a complete e-business solution customized totally for your company.

1.13.1 ScopeIn the HATS environment, the <HATS:Component> tag represents the transformation of a section of the host screen into HTML. The CSS class definitions can be overwritten globally in the CSS file or with more granularity in the Template JSP or the Transformation JSP. You can also substitute the CSS class name with one of your own.

Consider, for example, the HTML text shown in Figure 1-49, followed by an input field, followed by a button. Assume that the plain text uses the HATSLABEL class name, the input field uses HATSFIELD, and the button uses HATSBUTTON.

Figure 1-49 CSS normal

An inline style of "FONT-STYLE: normal; FONT-WEIGHT: bold; COLOR: red;" changes all of the text into bold, red text as shown in Figure 1-50.

Figure 1-50 CSS input field

A substitution of NEWLABEL for the HATSLABEL class name only changes the HTML elements, which use the HATSLABEL class, and allows for more control over the style changes. At Runtime, any use of the old CSS class name is



substituted with the new CSS class name. The developer can determine which CSS class to overwrite by running the JSP, right-clicking it, and selecting the View Source option. The developer looks through the HTML source to find the CSS class to redefine and does so to create the output shown in Figure 1-51.

Figure 1-51 CSS text

You can use an input field in the Widget Settings Text input window (Figure 1-52), which is launched from the Insert Host Component wizard. This field allows the developer to specify the HATS CSS class names to substitute and the new CSS class name with which it should be substituted. This is a Widget setting that can be done at the Project level, by changing the Widget's default settings, or at an instance level in the <HATS:Component> tag in the Transformation JSP.

Figure 1-52 CSS: Changing your style

The Insert Host Component Wizard allows the developer to specify an inline style (Example 1-1) for the current component or widget being inserted into the JSP. This is stored in a new attribute of the <HATS:Component> tag.


Example 1-1 Specifying an inline CSS

<HATS:Component type="…" widget="…"row="…" col="…" erow="…" ecol="…"label="…" componentSettings="…"widgetSettings="CSS_HATSLABEL=NEWLABEL"inlineCSS=" FONT-STYLE: normal; FONT-WEIGHT: bold; COLOR: red;" />

We change the general definition.

1.13.2 Creating an exampleFollow these steps:

1. As shown in Figure 1-53, change the perspective to Navigator. In the Navigator pane, select project name →Web Content →stylesheets.

2. Double-click monochrometheme.css.

The Monochrometheme.css style is used to convert all the text that comes from the host application. In this case, we change the color and font.

Figure 1-53 CSS: Changing the view


3. Now you see the window shown in Figure 1-54. If you are not familiar with WebSphere Studio Application Developer, you may need some help understanding Figure 1-54.

When you open a CSS file, by default, the GUI selects the Styles view. In the right panel, you see the actual definition of the CSS file. On the left, you see an example of that definition. If you change something on the right, you see the visual change on the left.

The tag used to present the default transformation is HGREEN. To make a change, double-click Type Selected = HGREEN.

Figure 1-54 CSS: Changing the default transformation

Sample

Actual value

Type selected

View in use


4. The Set Style Properties window (Figure 1-55) opens. Select Fonts and make the following changes:

a. Select MS Gothic and click Add.b. Select monospace and click Remove.c. For Color, specify Blue.d. For Size, type 14.

Figure 1-55 CSS fonts


5. Under Fonts, click Fonts styles.

6. The Properties window changes as shown in Figure 1-56. Set Weight to Bold. Click OK.

Figure 1-56 CSS fonts styles

7. Press Ctrl+S to save the CSS and close the window.

1.13.3 Finding the tag that is usedAs you shown in Figure 1-54 on page 60, many tags are available for use. In normal situations, you need to see the application programming interface (API) to understand where each one is used. Since this is not WebSphere Studio Application Developer training, we use a simpler method to see which tag HATS is using to present HTML.

When you run your HATS application, use the View Source provided by your browser and find, for example, a word on the page that you want to change. See Figure 1-57.


Figure 1-57 CSS: Finding tag

1.14 Running the HATS projectIn this section, we view all the changes that we made running at the same time. If you performed a different kind of customization, skip this part. This is a good overview of one possible solution.

1. Now that we have completed our HATS modifications for this chapter, you need only to run the entire project to see the customized Web application for your company. Follow the instructions provided in 1.4, “Testing the HATS application” on page 12.



2. On the first page (Figure 1-58), you see the following HATS features in use:

– Import Template– Global Rules– Text Replacement

Type the user name and password. Then press Enter.

Figure 1-58 Login

Text Replacement

Drop-down list using global rules

Changing CSS


3. The next display shows an example of using:

– Tabbed Folder (Figure 1-59)– Text Replacement (Figure 1-60)– Drop-down List (Figure 1-61)

Figure 1-59 Tabbed folder

Figure 1-60 Text replacement

Using the drop-down list, select 1. User tasks

Figure 1-61 Drop-down list

System Name

System Name


4. The display shown in Figure 1-62 uses the pop-up feature. Using the pop-up options, select System Status and press Enter to see a graphic rendering.

Figure 1-62 Using pop-up options

5. You now see a graphic rendering (Figure 1-63). Press PF3.

Figure 1-63 Running the WRKSYSTS output

6. Type STRQM and press Enter.

7. On the following screen, type 3 and press Enter.


8. On the next screen, in the Library input field, type PET40AE and press Enter.

9. You now see all the tables inside the PET40AE database (Figure 1-64). For the AGENDA table, select the Display table option using the drop-down options.

Figure 1-64 Run select table


10.In the next display (Figure 1-65), you can make a select request to that table using valid values in your database or table, for example:

– For Value, specify 10/10/2003.– For Column, type BIRTHDAY.– For Test, type EQ (equal).

Figure 1-65 Run Calendar

11.You can also transform the default OS/400 output using Screen Customization or change the normal display using global rules. Figure 1-66 shows the normal result.

Figure 1-66 Run Calendar request


1.15 SummaryIn this chapter, we prepared a basic transformation using many common and useful features designed for a fast start without Java skills or in-depth Web knowledge. This can help your business transformation by reducing costs and minimizing the complexity associated with exploiting Internet technologies. The information is then delivered to the Web browser through standard HTML. Easy-to-use GUIs and wizards allow Web designers to create and manage new composite applications. These applications combine multiple back-end data sources to form a Web page.

Using these features, the HATS tool helps you in the creation of new e-business applications, allowing you to reuse your investment in legacy applications and functions.


Chapter 2. Integrating HATS with business applications

This chapter introduces Integration Objects (IO). Integration Objects are JavaBeans that encapsulate interactions with legacy data sources. These legacy data sources include terminal-oriented applications that use 3270, 5250, and VT data. These objects are then embedded within Web pages, which allow people to use a Web browser to interact with the data.

IOs are generated using the IBM WebSphere Host Access Transformation Services (HATS) application programming interface (API) or macros. Using IOs, you obtain information from different hosts and present the data on one Web page. The following sections use IOs to generate a Web application.

We use macros to generate an IO. A macro is an Extensible Markup Language (XML) script that defines a set of screens. Each screen includes a description of the screen, the actions to perform for that screen, and the screen or screens that can be presented after the actions are performed. A macro can be specified as one of the actions to take when a host screen matches the screen recognition criteria of a screen customization.

After you create an Integration Object, you can generate:

� Model 1 application Web pages� Struts Web Pages (Model 2)� Web services

2


We cover the following features that are either new in HATS V5 or that have been enhanced in this release:

� Generating a database application (see 2.2, “Integrating HATS with a database application” on page 75)

� Macro (see 2.3, “Using HATS with a 3270 application” on page 139)

� Integrated object (see 2.3, “Using HATS with a 3270 application” on page 139)

� VT applications (see 2.4, “Using HATS with VT applications” on page 155)

� Generating Struts (see 2.5, “Exposing Integration Objects as a Web application using Struts” on page 169)

� Generating Web services (see 2.6, “Exposing Integration Objects as a Web application using Web services” on page 177)

2.1 EnvironmentThis section presents the details of the environment, including the servers and HATS development environment, and the enterprise application. Figure 2-1 shows the global environment to prepare the scenarios discussed in this chapter.




IBM Eserver pSeries

AIX V5.2

IBM Eserver zSeries

CICSApplication

Intranet

IBM Eserver xSeries


V5.02 IBM Eserver

xSeries


ServerV5.02

IBM Eserver

xSeries

WebSphereStudio



Services V5

Portal plug-in


In this chapter we use different systems to test Macros, Integration Objects, and other features. Following is the server information in detail.

2.1.1 ServersThe servers that make up this environment include:

� AS/400e 9406 Model 500 using OS/400 V4R5, with the resources listed in Table 2-1

Table 2-1 Display processor resources

� pSeries running the operating system AIX V5.2

� zSeries running OS/390 R10 and applications running with CICS® Transaction Server V1.3

Note: In this scenario, we use an older AS/400e model that is no longer supported. As you see when going through the scenario, HATS demonstrates its ability to work just as well with older mainframe systems.

With this in mind, you are not required to upgrade or change your host systems to start the process of integrating your legacy applications into the new e-business environment. However, an upgrade may be required if you want to run HATS on an AS/400e or iSeries machine. Consult the IBM Eserver Workload Estimator on the Web at:


Resource Type-model Status Information

CEC01 9406-500 Operational Main Card Enclosure

PN01 2468-001 System Control Operational Panel

MP01 2142-000 Operational System Processor Card

SP01 9162-001 Service Processor Operational Card







Chapter 2. Integrating HATS with business applications 73


2.1.2 HATS development environmentThe HATS development environment consists of the following hardware, operating system, and software:

� Hardware:

– Pentium 4 CPU 1.80 GHz– 40 GB hard drive

� Operating system:

– Windows 2000 Professional– Service Pack 4

� Software:

– WebSphere Studio Application Developer V5.1– Host Access Transformation Services V5– Portal Toolkit V5.02

2.1.3 Enterprise applicationBecause HATS V5 is based on the Java 2 Platform, Enterprise Edition (J2EE) standard, it uses a single Enterprise Archive (EAR) file to assemble an entire project. It also uses a Web Archive (WAR) file to group different Web applications inside the same EAR file (for example: 5250.war, VT.war, 5250_1.war, and others). The assembled EAR file is installed on WebSphere Application Server.

For a better understanding of the enterprise application organization, refer to Figure 2-2. It shows the components needed to run a normal HATS project.

Figure 2-2 Enterprise application schema

Connection ManagementMacros processing, Sessions Management, IO processing

52505250WARWAR

32703270WARWAR

VTVTWARWAR

Access BeanAccess Bean

WebSphere Application ServerWebSphere Application Server

Rules engine and runtime information

Rules engine and runtime information


Note the following points based on Figure 2-2:

� WebSphere Application Server V5 is the driving force. As you can see, WebSphere Application Server is the base of HATS applications.

� The Access Bean is the management component of a HATS application. The management configuration and information are located there.

� Rules engine and runtime information contain customer definitions, screen customization rules, and other basic customization above the HATS core.

� The WAR file is the entire package for your Web application. You can create many WAR files inside the same EAR project.

2.2 Integrating HATS with a database applicationIn this example, we perform one entire integration process between HATS and an external database application.

2.2.1 ApplicationTo understand what we do in the following sections, you must see the functional environment of the application (see Figure 2-3). As shown in Figure 2-3, there are four steps to perform before we run the database application:

1. We plan to develop a macro to automatically navigate through various screens to present the Display Result screen. Therefore, we must capture the AS/400 Main Menu screen to include the macro inside it.

2. Using the normal AS/400 navigation, we navigate to the AS/400 Data Management Query tool. Then, using normal navigation options, we run a SELECT request against the database PET40AE/PRODUCT. The result of the request is the Display Result screen. We create a macro to develop a user friendly application. We use the macro to record all the screens from the AS/400 Main Menu to the Display Result screen. In addition, we use the macro for the input to the SELECT request.

3. After running the macro, we see the Display Result screen. Since we need to work with data displayed in the Display Result screen, we must capture that screen. After capturing the Display Result screen and using advanced customization options, we add some actions:

– Extract Global Variable (GV): We pass the value of one screen (Display Result) as an input for the database application. The value we use is the CATEGORY column of the Display Result screen.

– Run Business Logic (BL): We must develop a Java application to receive the global variable. This is required because we share values from HATS


with an external application. Within the HATS environment, you do not need to add extra code to get or set a global variable. We must share the global variable on the session (in the same Web container). After that, we can call that global variable from any Java application. We add more code inside database application inputform.

– Show URL: We integrate the database application inside HATS. This means that we get a Form (database application) inside another Form (HATS). This feature adds a button to execute some action requirement, such as a Send Key value. You do this in following sections.

– Send Key: After running the database application, you may want to return to the initial page (in our example, the AS/400 Main Menu screen). There are two different options to do this:

• Develop another macro and record the steps necessary to return to AS/400 Main Menu screen.

• Use Send Key to pass the keys necessary to return to AS/400 Main Menu screen. In our example, we use the Send Key because we already created a macro.

4. The current database application is a normal application where you first need to add some value in an inputform page. Then you click the Submit button to retrieve a value from the database.

In the step prior to running the business logic, the value of the global variable is shared in the session. You only need to add one sentence and one import action inside your business logic application to get the value.


Figure 2-3 Functional environment

2.2.2 Creating an AS/400 database access applicationIn this step, we create an AS/400 database access application using WebSphere Studio Application Developer.

Creating a new projectWe need a new environment to show the Business Logic application clearly. If you have previous experience using HATS, you can use the same project used in Chapter 1, “New components and widgets” on page 1. As an alternative, you can generate a new one. See the information in “Creating a project” on page 8 for help in generating a new project.

Creating a database applicationIn this section, we create a database application using the wizards provided by WebSphere Studio Application Developer:

1. Select File →New →other.

AS/400Main Menu Display ResultMACRO

PET40AE

DatabaseApplication

Send Key [pf3] [pf3] [pf3]

Show URLdpInputForm.jsp

Extract GVRun BL

Show URLSend Key

<%=session.getAttribute("mydb")

%>

Busines Logic (BL)import java.util.Hashtable;

IGlobalVariable pepe =blInfo.getGlobalVariable("categoryGV",true);

String myVariable = pepe.getString();

blInfo.getRequest().getSession().setAttribute("mydb",myVariable);

Logon

1122

33

44


2. In the New Select window (Figure 2-4), in the left pane, select Web and in the right pane, select Database Web Pages. Click Next.

Figure 2-4 Creating Web pages from an SQL query


3. In the Create Database Web Pages panel (Figure 2-5), complete the following fields as explained here:

a. For Destination folder, specify /project name/Web Content.b. For Java package, type itso.db.c. For SQL Statement Type, choose Select Statement.d. For Model, select IBM Database Access Java Beans - Master Details

Pattern.e. Click Next.

Figure 2-5 Create Database Web Pages panel


4. In the Choose SQL Method panel (Figure 2-6), select Be guided through creating an SQL statement and Connect to a database and import a new database model. Leave the others at their default settings. Click Next.

Figure 2-6 Choose SQL Method

5. Define the connection to the database. In the Connection Page panel (Figure 2-7), complete the following fields as indicated:

a. For Connection name, type CON1.b. For Database, select PET40AE.c. For User ID, select HPTEST.d. For Password, type your password.e. For Database vendor type, select DB2 Universal Database™ (UDB) for

iSeries, V5R1.f. For JDBC Driver, choose AS/400 Toolbox for Java JDBC Driver.g. For Host, specify your IP address or host name.h. For Class location, specify x:\your_path\jt400.jar.i. Click the Filters button to define a connection filter.

When developing Java applications in an AS/400 environment, there are two options to connect to the database:

– Using the DB2 JDBC driver– Using IBM Toolbox for Java (previously called AS/400 Toolbox for Java)

Important: After you complete the fields, do not click the Connect to Database button.


For more information about when to use which option, see Java and WebSphere Performance on IBM Eserver iSeries Servers, SG24-6256.

For this application, we use IBM Toolbox for Java.

Figure 2-7 Specifying the settings to connect to the database

Note: Using the AS/400 Toolbox for Java JDBC Driver to access data, we need to configure the jt400.jar file as a Java Database Connectivity (JDBC) class connection. You can obtain this file from your AS/400 machine and make a local copy. The regular path where you can find this file is \QIBM\ProdData\HTTP\Public\jt400\lib.

Do not click


6. In the Connection Filters window (Figure 2-8), click the Add Filter button.

Figure 2-8 Connection filters

7. In the Add Filter window (Figure 2-9), complete the fields as indicated:

a. For Select, choose SCHEMA.b. For where name, select LIKE.c. In the field on the far right, type PET40AE.d. Click OK.

Figure 2-9 Customizing the filter

8. Click OK again to return to the Connection Page panel (Figure 2-7).

9. Click the Connect to Database button.


10.Before you run the filter, the Confirm Filters window (Figure 2-10) asks you to confirm the filter definition. Click Continue.

Figure 2-10 Confirming the filters

Attention: It’s important that you understand this message. In OS/400, you should access all file systems as a database. For that reason, the filter is a must in this wizard. If you do not use the filter or skip a step, you must reset the WebSphere Studio Application Developer or wait more than seven minutes until the wizard presents results. Depending of your hardware configuration, you may need to wait more than seven minutes.


11.Depending on your hardware and network configuration, you see all the PET40AE tables as shown in Figure 2-11. On the Tables page, in the right pane, select PET40AE →Tables →PET40.CATEGORY. Click the > button to add PET40AE.CATEGORY as the table to use. Now you see PET40AE.CATEGORY in the right pane of the window.

Do not click Next.

12.Select the Columns tab.

Figure 2-11 Constructing SQL tables


13.On the Columns page (Figure 2-12), under Available Columns, select PET40AE.CATEGORY. Click the >> button to select all the columns. You now see the columns under Selected Columns on the right side of the page.

Do not click Next.

14.Select the Conditions tab.

Figure 2-12 Constructing the SQL columns


15.On the Conditions page (Figure 2-13), define the following conditions:

a. For Column, select CATEGORY.CATID.b. For Operator, select =.c. For Value, type :category. This value can be whatever you choose, but do

not forget to type a colon (:) before the value.d. Click Next.

Figure 2-13 Setting the conditions


16.On the SQL Statement Page (Figure 2-14), click the Execute button.

Figure 2-14 SQL Statement Page

17.On the SQL Query page (not shown), again, click the Execute button.

18.In the Host Variable Values panel (Figure 2-15), test the SELECT. In this case, Value is set to 'DOGS'. Click Finish.

Figure 2-15 Host variable values


19.You see the Query Results as shown in Figure 2-16. Click Close.

Figure 2-16 Execute SQL

20.Click Next.

21.In the Runtime Connection Page panel (Figure 2-17), you have the option to select the type of connection that you will use to connect to the database. In this case, we select Use driver manager connection. Accept the default values and click Next.

Figure 2-17 Runtime Connection Page


22.In the Controller Page panel (Figure 2-18), you can select the cascading style sheet (CSS) for this application. To change the CSS, follow these steps:

a. Click Add.

Figure 2-18 Controller Page


b. In the Style Sheet window (Figure 2-19), click Web Content → common →stylesheets and then select monochrometheme.css.

We use the monochrometheme style because our project style is based on this style. You have the chance to select another one (see Figure 2-19).

Click OK.

Figure 2-19 Choosing a CSS file

c. Back on the Controller Page, accept the default values and click Next.


23.In the Database Web Pages – Design the Input Form window (Figure 2-20), you have the option to change the default generation. Since this is a basic example and we only need to see the integration between database application and HATS, we do not change anything here. Click Next.

Figure 2-20 Changing basic generation

24.Click Next on each of the two windows that follow.


25.In the Database Web Pages window (Figure 2-21), change the default prefix name to a short name. In this example, we specify db. Click Finish.

Figure 2-21 Selecting a prefix

26.After you complete the database application, you see HATS Project View (Figure 2-22).

Figure 2-22 Wizard results


The wizard generates different files:

� One Hypertext Markup Language (HTML) file for the input page� Two JavaServer Page (JSP) files as controller and view� Two JavaBeans to connect to database

Configuring database runtime environmentTo run a database application, it is necessary to add some configuration parameters on top of the application server. As you know, each Java application needs an individual configuration. In our example, since we used the bean database generation, we must add the JDBC driver used in the process generation into the application server environment.

1. From the menu bar, select Windows →Open Perspective →Server as shown in Figure 2-23.

Figure 2-23 Opening a server perspective

2. Now in the Server perspective, to run the database application, complete these steps:

a. Add this new project to the same server environment used in Chapter 1, “New components and widgets” on page 1.

Important: You must understand that we are using this wizard because we do not have any Java application. For that reason, we need to develop a new Java application easily to show the integration with HATS. However, if you have your own database application (or any Java application), focus your attention on the methodology used to mix both applications.


i. Go the Server Configuration. Select WebSphere V5.0 Test Environment Server. right-click and select Add and remove projects as shown in Figure 2-24.

Figure 2-24 Server Configuration


ii. In the Add and Remove Projects window (Figure 2-25), you see the projects that the server has in your base. Include the new project in this server. In the left pane, select the project name and click Add. You now see the project name in the right pane. Click Finish.

We have now added the new project inside the same server environment that we used in the previous chapter. If you prefer, you can create a new server model or simply add this project to your existing server model.

Figure 2-25 Adding project


b. Now add the JDBC driver used for the database application.

i. In the Server perspective, go to the Navigator pane (see Figure 2-26).

ii. Click Servers and double-click defaultServer.wsi.

You have different tab options where you can set the environment necessary for any application. Since this is not WebSphere Studio Application Developer training, we so not explain them in detail. We only add the JDBC driver necessary to run the application. To learn more about the configuration options, see WebSphere Studio Application Developer Programming Guide, SG24-6585.

iii. Begin adding the JDBC. Click the Data Source tab.

iv. Click the Add button to add another driver to the JDBC provider list

Figure 2-26 Default server configuration


v. In the Create a JDBC Provider window (Figure 2-27), for Database type, select IBM DB2. For JDBC provider type, select DB2 UDB for iSeries (Toolbox). Click Next.

Figure 2-27 Selecting the JDBC provider


vi. In the next Create a JDBC Provider window (Figure 2-28), for Name, type any name that you want. We type myJDBC.

For Classpath, highlight the default and click Remove. Click Add External JARs to add your current jt400.jar file in the Classpath.

Click Finish.

Figure 2-28 Selecting a driver

3. Press Ctrl+S to save and close all the windows.

At this point, we finished creating the database application and the environment necessary to run. The final step is to test the application.

Testing the database applicationTo test the application, return back to the HATS perspective.

1. Select Window →Open perspective →HATS.


2. Select project name →Web Content →dbInputForm.HTML. Right-click the file and select Run on Server as shown in Figure 2-29.

Figure 2-29 Database run on server

3. In the next window, click Finish.


4. Wait a few seconds to see the dbInputForm.html file in the browser (Figure 2-30). After you see the Open for e-business message in the Console environment, you can test the application.

Figure 2-30 Database running

5. In the server selection, click Finish.


6. Complete the Input Form (Figure 2-31). The test the application has different values such as DOGS and FISH. Click Submit.

Figure 2-31 Test input form

You now see the Master Table View with the results as shown in Figure 2-32.

Figure 2-32 Master Table View result

If you want, click Details or try another request. Our purpose here is to make sure that our application is working properly. For that reason, we do not continue with more tests.

2.2.3 Using macros in an OS/400 environmentAs described in the beginning of the chapter, a macro brings the possibility to record an entire process as an execution unit. Macros are a powerful feature to facilitate screen navigation, avoid repetitive jobs, improve speed, integrate with external applications, and more.

For more information about macro structure, see IBM WebSphere Host Access Transformation Services (HATS) V5 Advanced Macro Guide, SC31-6590.


Introduction to a macro environmentTo start using a macro, open the Host Terminal window.

MacroWhen creating a macro, you see three different parts where you can add information:

Screen1 = Screen number.STRQM = values (commands and keys) for Screen 1.Next Screen = in the normal environment Current Screen + 1.

If you experience a problem with a value or in knowing what the next screen is, simply stop the macro, delete any incorrect values, and start the macro again. When you start a macro within another macro, you are asked if you want to begin a new macro or continue with the current macro. See Figure 2-33.

Figure 2-33 Macro action

Using a macro, you can define or limit which values the user can enter in an input field when using a browser. Or we can define which values to extract from a host screen using different techniques, such as global variables.

Global variablesA single HATS application can have only one transformation connection. To allow the sharing of data among more than one HATS transformation connection, HATS allows a user's single browser process to work with more than one HATS application.

Global variables allow the sharing of variables among many cooperating HATS applications. This way, a user can, for example:

1. Follow a link in application 1 to application 22. Gather data from one or more connections in application 23. Follow a link back to application 14. Have transformation screens in application 1 pre-filled with data gathered

from application 2.


For more information, see IBM WebSphere Host Access Transformation Services (HATS) V5 Programmer’s Guide, SC31-6576.

Creating a macroTo create a macro, follow these steps:

1. From the HATS Project view (Figure 2-34), select the project name, right click, and select Open Terminal → main.

Figure 2-34 Open Host terminal

2. On the Host Terminal logon display, enter these valid values and press Enter:

– User = HPTEST– Password = *****

3. In the Host Terminal window (Figure 2-35), click the Record Macro button.

Figure 2-35 Starting a macro recording


4. In the Record Macro window (Figure 2-36), type a name for the macro. Leave the default values and click Finish.

Figure 2-36 Macro name

5. In the next window, define the recognition criteria for the current page. Leave the default values and click Next and then click Finish.


6. Start to record the macro. See the Figure 2-37. Type the STRQM command in the command line and press Enter.

Figure 2-37 Macro recording

Attention: Recording a macro also records all the keys that you enter in the keyboard. Use care. When you type a command on the host terminal, you see in the left panel that the macro is recording everything.


7. In the DB2 Query Manager for AS/400 display (Figure 2-38), select option 3 and press Enter.

Figure 2-38 Macro for Query Manager


8. In the Specify Collection or Library sub-window (Figure 2-39), type PET40AE and press Enter.

Figure 2-39 Macro library


9. In the Work with Query Manager Tables display (Figure 2-40), press PageDown until you see the Product table. Tab down to the Product table. In the Opt column for PRODUCT, type 5 and press Enter.

Figure 2-40 Macro tables


10.We want to query the data by product ID. In the next window (Figure 2-41), follow these steps:

a. Under COLUMN, type PRODUCTID. b. Press the Tab key to advance to the TEST field. c. Under Test, type EQ. d. Press the Tab key again. e. Since we insert VALUE data using an Input field on the Web page, click

the Add Prompt Action icon at the top of the window.

Figure 2-41 Macro product

We insert this value asan input form in the Web


11.Set the prompt action for VALUE:

a. To use Add prompt action, it is necessary to recognize the screen. For that reason, the Screen Recognition Criteria Does not Match message window (Figure 2-42) opens. It informs you about the requirement to recognize this page. If you previously captured or customized the Find Data in Query Manager Table screen, you do not see this message window. Click Yes.

Figure 2-42 Recognition criteria does not match


b. In the Define Screen Recognition Criteria window (Figure 2-43), using your mouse pointer, select the Find Data in Query Manager Table text and click Next.

Figure 2-43 Defining a screen

c. On the following panel, click Next again and then click Finish.


d. In the Add Prompt Action window (Figure 2-44), notice the Handle Macro Prompt option. You have three different options:

• Show handler allows you to specify which JSP file to render the default transformation. A default macro handler is shipped with HATS, and it is named default.jsp.

• Set prompt to string is used when you know what value should be returned from a prompt. You can enter that string in the String field.

• Set prompt to global variable is used when you want the value of the prompt to be provided by a global variable. Enter a name for the global variable in the name field or select an existing variable using the drop-down menu.

• If you have a User List in your project, use Set prompt to property from User List to set the user and password. Using this feature, the values for User and Password are completed by HATS and you need only to press Enter to continue with your application. We use a combination of a macro and a User List in 2.4.2, “Using a User List in a VT transformation” on page 158.

Complete with the name of the variable. In this example, for Name, type productid. Leave the default values and click OK.


Figure 2-44 Macro prompt action

12.In the Prompt window (Figure 2-45), enter a real value. In this case, we type FI-SW-01. Then click OK.

Figure 2-45 Macro value pop-up

13.Press Enter.


14.On the Display Report screen (Figure 2-46), you see the result of the SELECT request. We have completed the macro. Click the Stop Macro button.

Figure 2-46 Macro display report


15.Save the macro. Click the Save Macro button as shown in Figure 2-47.

Figure 2-47 Macro saving

Testing the macroAfter you finish recording the macro, you can test the entire macro using the Play macro button. Remember that we started with the record on the AS/400 Main Menu screen.

1. Return to AS/400 Main Menu screen. Depending on what screen you are on, press PF12 or PF3.

2. When you reach the AS/400 Main Menu screen, click the Play Macro button as shown in Figure 2-48.

Figure 2-48 Macro play

3. The Supply Prompt Values window (Figure 2-49) asks you to enter the productid value that the macro will use in the Add Prompt Action created in the previous section.

Type a valid value for your database (in this case FI-SW-01) and click OK.

Figure 2-49 Macro input

If the macro completes successfully, you see the results page as shown in Figure 2-46.


2.2.4 Combining HATS with the database applicationTo combine a regular J2EE application with HATS, we use Global Variables and Business Logic as an integration technology. Both features can help in the integration of sending and receiving HATS data to or from J2EE applications.

Adding a macro in the Main MenuTo complete this task, you must capture the AS/400 Main Menu, add the macro, and then capture the Display Report screen.

Capturing the AS/400 Main MenuWe use this capture to insert the macro script:

1. Open a Host Terminal.

2. Go to the AS/400 Main Menu.

3. Click the Create Screen Capture button. Leave the default value and click Finish.

4. Click the Create HATS Transformation button. Leave the default values and click Next twice.

5. In the Rendering Options panel, select Prepopulated with host components and click Finish.

6. In the New Screen Customization window, click Next twice and click Finish.

7. Press Ctrl+S to save. Do not close the window.

For help with the capture screen sequence, see 1.10.1, “Capturing the screen” on page 43.


Adding the macroAfter you capture the AS/400 Main Menu, you see Main Menu as shown in Figure 2-50.

Figure 2-50 Capturing the main menu


1. Using the mouse pointer, click in the bottom line of the page, right-click, and select HATS Tools →Insert Macro Key as shown in Figure 2-51.

Figure 2-51 Choosing Insert Macro Key

2. In the Insert Macro window (Figure 2-52), you are asked which macro to add. Complete the following steps:

a. For the Macro name, specify your macro name or AS_400MainMenu as we did in this example.

b. Under Style options, select Individual button.

c. Click OK.


Figure 2-52 Insert Macro

3. Press Ctrl+S to save and close the windows.

Capturing the Display Report screenWe use this screen to render the database application inside HATS:

1. Open a Host Terminal.

2. Go to the Display Report page.

3. Click the Create Screen Capture button. Leave the default value and click Finish.

4. Click the Create HATS Transformation button. Leave the default values and click Next twice.

5. In the Rendering Options panel, select Blank and click Finish.

6. In the New Screen Customization window, click Next twice and click Finish.

7. Press Ctrl+S to save and close the window.

For help with the screen capture sequence, see 1.10.1, “Capturing the screen” on page 43.


Extracting global variables from Display ReportFinally, you present the SELECT request in the Display Report screen. Using global variables, we extract one value from the Display Report screen to use as the dbInputform value from the database application.

Using global variablesFollow these steps:

1. Open the DisplayReport.evnt file to extract a global variable. Select project name →Screen Customizations. Double-click the DisplayReport.evnt file.

2. Click the Actions tab. The Actions tab of the screen customization editor displays the actions for screen customization.

3. In the DisplayReport.evnt pane, click Add.

Figure 2-53 DisplayReport actions


4. In the Select an Action window (Figure 2-54), select Extract global variable and click Next.

Figure 2-54 Selecting an action for global variable

Tip: To send a list of values from HATS to an external application, you can use the same method that is explained in this section. However, instead of extracting one value as a string, you can extract a list of values and then send those values, for example, to a drop-down list.


5. In the Add Extract Global Variable Action – Select Screen Region window (Figure 2-55), select the value to extract. Using your mouse pointer, select the result under Category and click Next.

Figure 2-55 Selecting a value to extract

6. Define the global variable name. In the Add Extract Global Variable Action – Define Action Properties window (Figure 2-56), select the name categoryGV. Click Finish.

Figure 2-56 Global variable name



Developing business logic to share global variablesTo develop business logic to share global variables, you must first create the business logic and then add it in the database application.

Creating business logicHATS comes with a wizard to create a Business Logic skeleton. Follow these steps:

1. Select project name. Right-click and select New HATS →Business Logic. See Figure 2-57.

Figure 2-57 Selecting Business Logic


2. In the Create Business Logic – Create a Java class window (Figure 2-58), complete these steps as indicated:

a. For Project, select project_name.b. For Class name, type expose.c. For Package, choose itso.com.d. Under Which method stubs would you like to create?, select Get global

variable. e. Click Finish.

Figure 2-58 Creating a Java class

3. The wizard generates the basic skeleton. In a few seconds, you see the expose.java file in the right panel of the window. Add the following code:

a. Import a new package. Enter:

import java.util.Hashtable;


b. Add the source shown in Example 2-1 after //add code here to perform your business logic.

Example 2-1 Adding extra Java code

// Getting the variable.IGlobalVariable pepe = blInfo.getGlobalVariable("categoryGV",true);// Setting as a String.String myVariable = pepe.getString();// Sharing the String in the session.blInfo.getRequest().getSession().setAttribute("mydb",myVariable);

After making the changes, you see a window like the example in Figure 2-59.

Figure 2-59 Java skeleton


4. Press Ctrl+S to save and close the windows.

Adding business logic in the database applicationWe have finished the database application and business logic necessary to expose the global variable in the session. The last part of this application is to change and add extra code in the dbInputForm file.

Default application dbInputForm.htmlExample 2-2 shows the source for the dbInputForm.html file to validate your code.

Example 2-2 dbInputForm.html file

!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><HTML><HEAD><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><META name="GENERATOR" content="IBM WebSphere Studio">

<TITLE>Input Form</TITLE>

<STYLE TYPE="text/css"></STYLE>

<LINK href="common/stylesheets/monochrometheme.css"

rel="stylesheet" type="text/css"></HEAD>

<body><SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript"><!--function submitForm(nav){ document.myForm.elements["command"].value = nav document.myForm.submit()}

//--></SCRIPT>

<H1>Input Form</H1>

<FORM name="myForm" method="POST" action="dbMasterView"><A

href="javascript:submitForm('dbMasterView')">Submit</A> <BR><BR>

 <INPUT TYPE="hidden" NAME="command"VALUE="dbMasterView"> <INPUT TYPE="hidden" NAME="new_input"VALUE="true"> 

<TABLE border="0"><TBODY>

<TR><TH>CATID:</TH><TD><INPUT NAME="CATID" TYPE="text" VALUE=""></TD>

</TR></TBODY>

</TABLE>

</FORM></body></HTML>

Renamed dbInputForm.jspTo change the dbInputFom.html file into dbInputForm.jsp, follow these steps:

1. Change to the Navigator window.

2. Select project name →Web Content →dbInputForm.html (see Figure 2-60).

3. Press PF2 and change the name to dbInputForm.jsp.

4. In the next window (fixing links), click Accept. The conversion process from HTML to JSP completes.

Attention: We must convert the HTML file into a JSP file to add the logic necessary to retrieve the String value from the session.

Figure 2-60 Changing to JSP

5. Select the dbInputForm.jsp file and double-click to open it.

6. After the conversion process from an HTML file to a JSP file, import some Java packages and add some additional code.

a. In the beginning of the source, add the code shown in Example 2-3.

Example 2-3 JSP definition and imports

<%@ page contentType="text/html; charset=utf-8"%><%@ page language="java" %><%@ page import="com.ibm.hats.common.*, com.ibm.hats.util.*" %>

<%@ taglib uri="hats.tld" prefix="HATS" %>

b. Find the INPUT type as shown here:

<TD><INPUT NAME="CATID" TYPE="text" VALUE=""></TD>

c. Replace the word VALUE in the INPUT type with the following text:

value = "<%= session.getAttribute("mydb") %>"

7. The dbInputForm.jsp file should appear as shown in Example 2-4.


Example 2-4 dbInputForm.jsp file

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><%@ page contentType="text/html; charset=utf-8"%> <--------<%@ page language="java" %> <--------<%@ page import="com.ibm.hats.common.*, com.ibm.hats.util.*" %> <--------

<%@ taglib uri="hats.tld" prefix="HATS" %> <--------

<META name="GENERATOR" content="IBM WebSphere Studio"><TITLE>Input Form</TITLE><STYLE TYPE="text/css"></STYLE><LINK href="dbInputForm.jsp"

rel="stylesheet" type="text/css"></HEAD>

<body><SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript"></SCRIPT>

<H1>Input Form</H1>

<FORM name="myForm" method="POST" action="dbMasterView"><A

href="javascript:submitForm('dbMasterView')">Submit</A> <BR><BR>

 <INPUT TYPE="hidden" NAME="command"VALUE="dbMasterView"> <INPUT TYPE="hidden" NAME="new_input"VALUE="true"> 

<TABLE border="0">

<TBODY><TR>

<TH>CATID:</TH><TD><INPUT type="text" name="CATID" size="20" value = "<%= <-----

session.getAttribute("mydb") %>"></TD> <-----

</TR></TBODY>

</TABLE>

</FORM></body></HTML>

8. Press Ctrl+S and close the windows.

Adding a Show URL in Display ReportIn this example, we add the database application inside the HATS environment:

1. Open the DisplayReport.evnt file to add the Show URL widget. Select project name →Screen Customizations. Double-click the DisplayReport.evnt file.

If you have any problems with this step, see “Using global variables” on page 120.

2. Click the Actions tab.

3. In the Actions pane, click the Add button.

4. In the Select an Action window, select Show URL and click Next.

5. In the Add Show URL Action – Define Action Properties window (Figure 2-61), for URL, type dbInputForm.jsp. Click Finish.

Figure 2-61 Defining an action

6. Press Ctrl+S to save. Do not close the window.


Adding business logic in Display Report After you define a global variable and develop business logic, add it to those files in the Display Report window:

1. Click the Actions tab. In the Actions pane, click the Add button.

2. In the Select an Action window, select Execute Business Logic and click Next.

3. In the Add Execute Business Logic Action – Define Action Properties window (Figure 2-62), enter the business logic name that we developed in previous sections (see Figure 2-58 on page 124). Click the Browse button and select itso.com.expose. Click OK and then click Finish.

Figure 2-62 Adding business logic

4. Press Ctrl+S to save. Do not close the windows.


Adding the Send Key actionThe last action allows the application to return to the initial screen, in this case the AS/400 Main Menu:

1. Click the Actions tab.

2. In the Actions pane, click the Add button.

3. In the Select an Action window, select Send Key. Click Next.

4. Click Next again.

5. In the Add Send Key Action – Define Action Properties window (Figure 2-63), select Other host keys and type [pf3][pf3][pf3] in the field. Click Finish.

Figure 2-63 Send Key

6. Press Ctrl+S to save. Do not close the windows.

2.2.5 Testing the applicationTo test the application, it is necessary to define the execution order to ensure the proper sequence of execution.

1. Click the Action tab.

2. In the Actions pane (Figure 2-64), select the action type Apply a transformation and click Remove. Then, click the Up and Down buttons to reorganize the actions into the following order:

– Extract a global variable.– Run a Java method.– Show a URL.– Send key to host screen.


Figure 2-64 Realigning actions


Changing module visibilityThe relationship among the class loaders implies that it is not usually possible to access the classes of one Web application from another Web application. The application server settings include a property for specifying module visibility. Module visibility determines the level of isolation among the classpaths for various application components and related class loaders.

How a class loader worksBy default, Web module class loaders load the contents of the WEB-INF/classes and WEB-INF/lib directories. The application class loader is the parent of the Web module class loader. You can change the default behavior by changing the application's WAR Classloader Policy.

This application class loader can load each application's Web modules if that WAR module's Classloader Policy is also set to APPLICATION. If the WAR module's Classloader Policy is set to APPLICATION, then the application's loader loads the WAR module's classes. If the WAR Classloader Policy is set to MODULE, then each WAR module receives its own class loader.

Since we need to share information in the session, we must set the class loader to APPLICATION so that the Web module contents are also loaded by the application class loader.

For more information about module visibility, go to:

http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp



Setting visibilityTo change the default module visibility from MODULE to APPLICATION, perform the following steps.

1. Change the perspective. Select Window →Open perspective and select Server.

2. In the Server Configuration pane, double-click WebSphere V5.0 Test Environment. In the lower right side of the window, click the Application tab.

3. In the Application Options pane (Figure 2-65), select the project name (in this case ox_db). For the WAR Classloader Policy, select APPLICATION.

Figure 2-65 Defining classloader



We have now set up the environment necessary to run the application. The next step is testing.

Testing the applicationWe use the browser windows that come with WebSphere Studio Application Developer to test the application. Otherwise, you can open an external browser and test the application there.

1. Select your project name, right-click, and select Run on Server.

2. In the server selection, click Finish. If you accepted this request in previous steps, you are not asked again.

3. To maximize the window, double-click the top of the Window browser and you see the default Logon transformation as shown in Figure 2-66.

Figure 2-66 Default logon transformation


4. Type the User and Password as follows and press Enter:

– User = HPTEST– Password = *****

5. As shown in Figure 2-67, click the AS_400MainMenu button.

Figure 2-67 Main Menu with macro

6. Recall in the creation of the macro that we set an extract action to pass the value of the SELECT request (see Figure 2-45 on page 113). Now, we are challenged to provide a productid value. Type FI-SW-01 and click OK as shown in Figure 2-68.

Figure 2-68 Extract action


7. If everything works as planned, you see the category ID completed in your input form. Using Business Logic and Global Variables, we typed that value. To test, on the Input Form (Figure 2-69), click the Submit link.

Figure 2-69 Input Form

Completed using GV+BL


8. Remember that we are using a Show URL action and that action places one Form (database application) inside another Form (HATS). For that reason, after you click the Submit link, you don’t change the HATS page. See Figure 2-70. Select the Details, Back, and Refresh buttons...

9. To continue with the application, return to the AS/400 Main Menu page. Click the Continue Application button as shown in Figure 2-70 and you return to the AS/400 Main Menu.

Figure 2-70 Result Master Table View

If you see Figure 2-67 on page 136, you successfully completed the application.


2.3 Using HATS with a 3270 applicationUp to this point, we have used the AS/400 environment to demonstrate some of the most important features of HATS V5.

In this section, we use a 3270 application to generate a macro. Then, using the macro generated in the previous section, we generate an Integration Object, which is the base to gain access to such new technologies as Web services and Struts. In the following example and scenario, we use an IO to generate a Model 1 application. We then generate Web services and Struts in the sections that follow.

Here is a list of features that we use with 3270:

� Generating a macro (see 2.3.1, “Generating a macro with 3270 application” on page 139)

� Generating IOs (see 2.3.2, “Generating an Integration Object with a 3270 application” on page 142)

� Generating Model 1 application (see 2.3.3, “Generating a Model 1 application with a 3270 application” on page 146)

2.3.1 Generating a macro with 3270 applicationWe generate a macro using a 3270 application. If you have previous experience using HATS, you can use the same project used in Chapter 1, “New components and widgets” on page 1. Otherwise, you should generate a new project. If you do not remember how to generate a new project, see “Creating a project” on page 8.

In this environment, we use the host configuration as shown in Figure 2-71. The project name is ox_io.

Important: You must understand the entire process. In this example, we shared one string value using a global variable. Using business logic, we shared that string value in the entire HATS session. Using this methodology, you can pass a list of values (using a global variable) to an external Java application. In addition, using business logic, you can gather information from an external application inside the HATS application.

Attention: You can use all features described in Chapter 1, “New components and widgets” on page 1, with 3270 applications.


Figure 2-71 z/OS® host connection

1. In the HATS Project View (Figure 2-72), select project name (ox_io), right-click, and select Open Terminal →main.

Figure 2-72 Opening Host Terminal


2. The sample CICS application we use for this example is not generally available. Therefore, we do not cover details of the application processing. Instead we explain the steps to create the macro for our 3270 environment.

a. For z/OS host application name, specify RA03C.b. For the CICS transaction name, type TCHM.c. For the macro name, type TCHM2.d. The macro is recorded as shown here and in Figure 2-73:

RA03C [Enter][Clear] TCHM [Enter] - Application name1 [Ctrl]Add Prompt Action = account [Enter] - Insert dataAdd Extract Action = myresult [Enter] - Extract data

Figure 2-73 Macro recorded


3. In the macro, we add two actions:

– An Add Prompt Action to request the account number needed for the customer information request. The variable name is account. See Figure 2-74.

– An Extract Prompt Action. The variable name is myresult. We use this extract action to show the results of the request. See Figure 2-74.

Figure 2-74 Credit account demonstration

2.3.2 Generating an Integration Object with a 3270 applicationIn the beginning of this chapter, we explain that you can generate Integration Objects using APIs or macros. In this case, we use the macro to generate the IO.

account variable

myresult variable


1. As shown in Figure 2-75, select project name →Macros →macro name (TCHM2). Right-click and select Create Integration Object.

Figure 2-75 Starting Create Integration Object


2. After a few seconds, HATS generates a Java application with the same name of the macro. You can see the IO generated when you select project name →Source →IntegrationObject →TCHM2 as shown in Figure 2-76.

Figure 2-76 IO generated

3. Example 2-5 shows the IO code that you can use to validate your IO.

Example 2-5 IO example

package IntegrationObject;import com.ibm.HostPublisher.IntegrationObject.*;import com.ibm.HostPublisher.Server.Ras;

public class TCHM2 extends HPubHODCommon{ public static float getIOTemplateVersion() { return 5.0F; } // Template version - HATS 5.0 public static String getIOTemplateType() { return "-DEFAULT"; } // Template type - Host Default public static String getIOVersionInfo() { return "(IBM)"; } // Version info - IBM supplied public static String getIOTemplateRevision() { return ":1.1"; } // Template revision per version - internal value public String hPubIOVersion= getIOBaseVersion()+";"+getHPubBeanType()+ getIOTemplateType()+getIOTemplateVersion()+ getIOTemplateRevision()+getIOVersionInfo(); public String getIOVersion() { return hPubIOVersion; }

// Generated Objects


HAOVariable account = new HAOVariable("account","null","account",true,"",0,0,5,0,HAO_VARIABLE_SIMPLE); HAOVariable myresult = new HAOVariable("","myresult","myresult",false,"",0,0,12,5,HAO_VARIABLE_SIMPLE);

// Constructor public TCHM2() { // Generated vector population vHAOVariables.addElement(account); vHAOVariables.addElement(myresult);

hPubStartPoolName = new String("main"); hPubStartChainName = null; hPubStartType = BEAN_START_FROM_POOL;

hPubEndChainName = null; hPubEndType = BEAN_END_TO_POOL;

stringHODMacroFilename = "TCHM2.hma"; stringBeanName = new String("TCHM2"); hPubBeanName = new String("TCHM2");

}// *********************************************************************** /* Generated Setters */public void setAccount( String stringToBe) { hPubErrorOccurred = 0; allowTracing(); // call made in case started from IDE and was not able to // start tracing on the constructor if (HPubTracingOn) { Ras.traceEntry( className, "setAccount(String)", stringToBe); }

account.stringValue = stringToBe; }

/* Generated Getters */ public String getAccount() { hPubErrorOccurred = 0; if (HPubTracingOn) { Ras.trace( className, "getAccount simple: ", account.stringValue); } return (account.stringValue); } public String getMyresult() { hPubErrorOccurred = 0; if (HPubTracingOn) { Ras.trace( className, "getMyresult simple: ", myresult.stringValue); }


return (myresult.stringValue); }

public void DoTheWork() { if (HPubTracingOn) { Ras.traceEntry( className, "DoTheWork()", "Start doing the work"); } DoTheWork(this); }}

2.3.3 Generating a Model 1 application with a 3270 applicationThis option allows users to create Web pages using the Model 1 methods (used in Host Publisher). It is a simple way to create input and output JSP pages.

A Model 1 architecture consists of a Web browser directly accessing Web-tier JSP pages. The JSP pages access Web-tier JavaBeans that represent the application model. The next view to display (JSP, servlet, HTML page, etc.) is determined either by hyperlinks selected in the source document or by request parameters. A Model 1 application control is decentralized, because the current page being displayed determines the next page to display. In addition, each JSP or servlet processes its own inputs (parameters from GET or POST).

In this model, a single JSP page contains:

� The information to be presented to the user� Formatting tags that specify how the information is displayed� Control logic that controls which page is called next


1. As shown in Figure 2-77, select project name →Source →Integration Object →TCHM2 bean. Right-click and select Create Model 1 Web Pages.

Figure 2-77 Selecting Create Model 1 Web Pages


2. The Create Model 1 Web Pages – Basic information window (Figure 2-78) opens. Do not change anything. Click Next.

Figure 2-78 Creating model 1 Web pages


3. In the Create Model 1 Web Pages – Define inputs window (Figure 2-79), you can change the input control values. To see the scope of this feature, we make some changes. Under Input name, select account and click Edit.

Figure 2-79 Defining inputs


4. In the Define input property window (Figure 2-80), you can change the default definition of the input form and the label that the user sees in the browser. Do not change the default Input Form. Change only the Leading Text field by adding, for example, Enter Account number:. Click OK.

Figure 2-80 Changing default input property

5. In the Create Model 1 Web Pages – Define inputs window (Figure 2-79), click Next.


6. In the Create Model 1 Web Pages – Define outputs window (Figure 2-81), you can change the output control values. To see the scope of this feature, we make some changes. Under Output name, click myresult and click Edit.

Figure 2-81 Defining outputs

7. In the Define output property window (Figure 2-82), you can change the default definition of the output control and the label that the user sees in the browser. Do not change the default output control. Change only the Leading Text field by adding, for example, Customer Information:. Click OK.

Figure 2-82 Changing the default output control

8. In the Create Model 1 Web Pages – Define outputs window, click Finish.


9. To see the files generated by the wizard, as shown in Figure 2-83, select project name →Web Content →Model 1 Pages.

Figure 2-83 Model 1 generation

The next step is to test the application.

2.3.4 TestingIn the previous step, we created a Model 1 application. Now we run and test the Model 1 Application that we generated using a 3270 CICS host application.

1. Add your project name into the same WebSphere V5.0 Test Environment Server that we used in the previous chapters. For more information, see “Configuring database runtime environment” on page 93.

2. Select project name →Web Content →Model 1 Pages →TCHM2Input. Right-click and select Run on Server.

3. In the server selection, click Finish. If you accepted this request in previous steps, you aren’t asked again.


4. As you can see in Figure 2-84, after the server starts (open for e-business), the next line executed was the TCHM2Input.jsp file. This input page gathers the data required by the Integration Object.

Complete the input form shown in Figure 2-84. For Enter Account number, type 12000 and click Submit.

Figure 2-84 Testing model 1 application input


As you can see in Figure 2-85, after the application applies the template in use (Simple1.jsp), the next line executed is the TCHM2Output.jsp file. This output page presents the results after the Integration Object is executed. Compare the output displayed here with the 3270 screen displayed in Figure 2-74 on page 142.

Figure 2-85 Testing model 1 application output

This completes the test of this model. This model is not used often because there is no clear separation between the layers.


2.4 Using HATS with VT applicationsIn the previous release of HATS, only one connection configuration was allowed. It was created when the developer used the New Project wizard. HATS V5 allows you to define multiple connections in a single HATS project. HATS has the ability to use one or more Integration Objects. Each of these IOs can use a different host connection. HATS has the ability to specify several different connections to various backend hosts.

This section works with the following topics:

� Creating a new connection (see 2.4.1, “Creating a new connection” on page 155)

� User lists (see 2.4.2, “Using a User List in a VT transformation” on page 158)� VT macros (see 2.4.3, “VT macro” on page 159)� Testing VT applications (see 2.4.6, “Testing the VT application” on page 166)

Using a User List and a macro together, it is possible to improve the user experience. A User List basically is a list of users that HATS records. Then using, for example, a macro, it is possible to use the user values recorded inside the macro to avoid typing the user and password. Then the user only needs to press Enter or click the Submit button.

2.4.1 Creating a new connectionFirst, you must create a new connection for an existing project. Remember that when using VT emulation, you cannot generate a default transformation. You only can create and run Integration Object applications. In HATS V5, you can add different connections to the same project. Using this feature, you can access a VT application.

We use the project created in 2.3.1, “Generating a macro with 3270 application” on page 139 with the name ox_io.

Restriction: VT hosts (VT52, VT100/102, VT320, and VT420) are limited to background connections. If the VT Connection is used as one of the project’s background connections, it may be used to record macros and run IOs.


1. Select project name and double-click Project Settings (see Figure 2-86).

2. In the right pane of the window shown in Figure 2-86, you see different tabs to configure the project. In this case, click the Connections tab. In the Connections pane, click the Add button to add a new connection.

Figure 2-86 Creating a new connection


3. In the Create a Connection – New Connection window (Figure 2-87), add a name and basic configuration for the connection. Type the connection name (vt in this example) and leave the other values as the default. Click Next.

Figure 2-87 New Connection panel


4. In the Create a Connection – Connection Settings window (Figure 2-88), specify the settings for your own information. We specify the following values:

– Host name: 9.24.105.60– Port: 23– Type: VT100– Code page: 1100 DEC Multinational Replacement Character Set– Screen size: 24x80

Click Finish.

Figure 2-88 Connections Settings panel

5. You now see the connection overview. Press Ctrl+S to save the window, but do not close it.

The next step is to create and customize the basic navigation window.

2.4.2 Using a User List in a VT transformationIn this section, we create a User List within a VT environment to show some facilities for VT applications.


1. As shown in Figure 2-89, select the User List tab. In the User List pane, click the Add button.

2. In the Add User Profile window (Figure 2-89), provide the valid values for your system and click OK. In this VT example, we define an AIX system using he following values:

– User ID: root– Description: usuario1– Password: ********– Confirm Password: ********

Figure 2-89 User List


2.4.3 VT macroIn this section, we create a new macro for the VT application. Since the creation of the macro is the same in any type of emulation, we add a basic example to join with the User List feature. For more information about how to use macros, see 2.2.3, “Using macros in an OS/400 environment” on page 101.


1. To create the macro, open a host terminal. Select project name →Connections →vt. Right-click vt and select Open Terminal →vt. See Figure 2-90.

Figure 2-90 Opening the terminal for VT

2. The AIX welcome window (Figure 2-91) opens. This indicates that the VT connection is working.

Figure 2-91 AIX welcome window

3. On the Host Terminal (Figure 2-92), click the Record Macro button.

Figure 2-92 Starting the macro

4. In the window that opens, you are asked for a macro name. Complete the name request with some value and leave the other fields as default. We use macro_list as the macro name. Click Finish.

5. Define the recognition criteria for the current page. Leave the default values and click Next.

6. Click Finish.


We now begin to record the macro:

1. Click the Add Prompt Action icon.

2. In the Add Prompt Action window (Figure 2-93), define an action. In this case, we use User List:

a. In the Handle Macro Prompt box, select the Set prompt to property from User List option. From the User Profile list, select the name of your user (in this example, root). For User List property, select _userid.

b. The macro requests a User List to complete the correct value for _userid. Click OK.

c. Press Enter.

Figure 2-93 User list property _userid


3. Pass the User List password value using User List options. Click the Add Prompt Action icon.

4. In the Add Prompt Action window (Figure 2-94), define an action. Again we use User List.

a. In the Handle Macro Prompt section, select the Set prompt to property from User List option.

b. From the User Profile list, select the name of your user (in this example root).

c. From the User List property list, select _password.

d. The macro requests a User List to complete the correct value for password. Click OK.

e. Press Enter.

Figure 2-94 User list property _password


5. Select a result that shows in a result page. Using your mouse pointer, select the area that you want to use as a result.

6. Click the Add Extract Action icon. For this example, we use the welcome window (Figure 2-95) presented by AIX after the user completed the user name and password.

7. Define the recognition criteria for the current page. Leave the default values and click Next.

Figure 2-95 Result page

8. Click Finish.


9. Complete the Add Extract Action window (Figure 2-96). For Name, specify a value and leave the others as default. For this example, we set Name to welcome. Click Finish.

Figure 2-96 Add Extract Action window

10.Click the Stop macro button and then click the Save macro button for the example macro_list.

Using the macro_list file, we generate the IO. Since we covered generating an IO earlier, we cover only the major steps here. For more information, see 2.3.2, “Generating an Integration Object with a 3270 application” on page 142.

2.4.4 Generating an Integration Object with VT applicationAs explained in the following steps, we now generate an Integration Object with a VT application.


1. Select project name →Macros and right-click the macro name (macro_list in this example) →Create Integration Object as shown in Figure 2-97.

Figure 2-97 Creating an Integration Object

2. After a few seconds, HATS generates a Java application with the same name as the macro. To see the generated IO, select project name →Source →IntegrationObject.


2.4.5 Generating Model 1 application Web pages with VT applicationUsing the IO, we generate the Model 1 Web pages to test the application.

1. Select project name →Source →Integration Object. Right-click Macro_list bean and select Create Model 1 Web Pages. See Figure 2-98.

Figure 2-98 Selecting the model 1 Web pages

2. In a few seconds, additional information is requested. Accept the defaults and click Finish.

2.4.6 Testing the VT applicationAfter you create the input and output pages, the last step before testing the application is to change the password input type in the input HTML page.

Changing the input formYou change the input form as explained in the following steps:

1. Select project name →Web Content →Model 1 Pages and double-click the Macro_listInput.jsp file.


2. As shown in Figure 2-99, in the right pane, you see the opened Macro_listInput.jsp file. Click the Design tab.

3. Select the _password input form. Right-click and select Attributes.

4. In the Attributes pane, change the Input type of _password from Text to Password.

Figure 2-99 Changing the _password attributes



Testing Now you test the application as explained here:

1. Add your project name into the same WebSphere V5.0 Test Environment Server that we used in the previous chapters. For more information, see “Configuring database runtime environment” on page 93.

2. Select project name →Web Content →Model 1 Pages →Macro_listInput. Right-click and select Run on Server.


4. If everything works as expected, you see the user and password completed by HATS as shown in Figure 2-100. Click Submit.

Figure 2-100 Testing VT login

5. You see the result that we captured using the Add Extract action in the macro creation. See Figure 2-101.

Figure 2-101 Testing VT result


Remember that this example is a basic one. It is important that you understand the entire process. You can use a List of values from a Result table as a result page.

2.5 Exposing Integration Objects as a Web application using Struts

A major feature of WebSphere Studio V5 is the integrated support for Struts. The Struts tag libraries, supporting Struts classes, and a graphical Struts editor are available within WebSphere Studio. Struts is a popular Model-View-Controller (MVC) framework, which HATS V5 uses for Model 2-based Web pages.

Struts, a framework that can help to develop Web applications, is an open source project sponsored by the Apache Software Foundation. It is written entirely in Java and uses the standard J2EE APIs. For more information about Struts, see:

http://jakarta.apache.org/struts

Model 2 architecture introduces a controller servlet between the browser and the JSP pages or servlet content being delivered. The controller centralizes the logic for dispatching requests to the next view based on the request URL, input parameters, and application state. The controller also handles view selection, which decouples JSP pages and servlets from one another. Model 2 applications are easier to maintain and extend, because views do not refer to each other directly. The Model 2 controller servlet provides a single point of control for security and logging, and often encapsulates incoming data into a form usable by the back-end MVC model. For these reasons, we recommend the Model 2 architecture for most interactive applications.

The users can build Web pages conforming to the Struts model that execute Integration Objects.



2.5.1 Creating StrutsIn this section, we use an existing IO to generate a Struts-based application. The IO that we use is the TCHM2 IO generated in 2.3, “Using HATS with a 3270 application” on page 139.

1. Select project name (ox_io) →Source →Integration Object →TCHM2. Right-click and select Create Struts Web Pages as shown in Figure 2-102.

Figure 2-102 Creating struts


2. In the Create Struts Web Pages – Basic Information window (Figure 2-103), you can change the basic parameters of the Struts application such as name of the Input and Output page and destination. For this example, leave the parameters as the default and click Next.

Figure 2-103 Basic information panel


3. In the Create Struts Web Pages – Define Inputs window (Figure 2-104), you can change the input form definition or the name of the label used in the Web environment as the name of the input form. In our example, simply click Next.

Figure 2-104 Define inputs panel


4. In the Create Struts Web Pages – Define Outputs window (Figure 2-105), you can change the output result definition or the name of the label that is used in the Web environment as the name of the output result. To finish the creation of the Struts application, click Finish.

Figure 2-105 Defining outputs


5. After the pages are built, users can right-click the Struts graphic interface (*.gph file in Figure 2-106) and add more nodes, links, and logic to the Web application.

Figure 2-106 Graphical designer

The input and results pages look like the example in 2.4.6, “Testing the VT application” on page 166. However, the underlying mechanism to execute the Integration Object is not inline Java code. Instead it is the custom Struts tags that invoke the supporting Struts classes and subsequently the Integration Object.

2.5.2 TestingTo test the Struts application in WebSphere Application Server, no additional runtime support is necessary to enable Struts. All necessary supporting files for Struts is in the packaged EAR project when it is exported for production.


1. Add your project name into the same WebSphere V5.0 Test Environment Server that we used in previous chapters. For more information, see “Configuring database runtime environment” on page 93.

2. Select project name →Web Content →Struts Pages →TCHM2Input. Right-click and select Run on Server.


4. As you see in Figure 2-107, there is no difference with the Model 1 application output. The final user does not know when they are using Model 1 or Model 2 applications. The look of the page is not important here. However, it is important that you receive the same results when using MVC applications.

Complete the Account input form with a valid value. In this example, type 12000 and then click the Submit button.

Figure 2-107 Testing the input page


5. If things work as planned, on the result page (Figure 2-108), you see the account information.

Figure 2-108 Testing output page

All necessary supporting files for Struts are in the packaged EAR project when it is exported for the production environment including:

� Struts class� ActionForm class� Web Diagram� Others

To see more information about these files, see IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575.


2.6 Exposing Integration Objects as a Web application using Web services

HATS Web services support helps you to create a Web service from an Integration Object or an Enterprise JavaBean (EJB) Access Bean. The ability to deploy an IO as a Web service extends IO function beyond browser-based interaction to software looking to connect to other software. It builds upon Web Services Description Language (WSDL), Simple Object Access Protocol (SOAP), and Universal Description, Discovery, and Integration (UDDI).

HATS users can:

� Describe an IO service (WSDL)� Publish an IO service (UDDI and WSDL)� Locate an IO service (UDDI)� Invoke an IO service (SOAP)

You can achieve this based on open standards, independent of programming language, transport layer, and platform.

Web services provides an industry-accepted method for applications to connect to and interact on the Web, enabling you to publish interfaces to your business processes. This method allows you to streamline interaction with your organizational value net and gives multiple divisions, trading partners, contractors, customers, and suppliers the ability to connect business processes and create cross-enterprise transactions.

Using HATS, you can quickly and easily extend your legacy applications as new Web services. HATS has been enhanced to provide a selectable option so that your existing skills and implementations can be leveraged in creating new Web services. In addition, it now generates new Java technology-based methods specific to Web services that are developed to help optimize network performance and response time when deploying legacy services across a wide area network (WAN).

HATS is used in conjunction with WebSphere Studio to create Web services and build the corresponding WSDL. You can also register Web services within the UDDI registry and deploy Web services on WebSphere Application Server.

A key strength of the Web services industry standard is that existing back-end implementations do not require modification. Your well-tested and operational core information technology structure can be reused without the scheduling impact and risk involved in rework. For more information, go to:

http://www.w3.org/2002/ws/



2.6.1 Creating a Web serviceTo create a Web service environment, you must create an Integration Object. We use the IO generated in 2.3.2, “Generating an Integration Object with a 3270 application” on page 142, with the name TCHM2.

1. Select project name →Source →IntegrationObject →TCMH2. Right-click and select Create Web Service Support Files as shown in Figure 2-109.

Figure 2-109 Creating Web service support files


2. The Create Web service support files – Choose HATS project and Web service class name window (Figure 2-110) opens. Since we use WebSphere Application Server Version 5.0.2 runtime to test the WSDL, you must follow these naming conventions when creating Web services:

– Method names must begin with a lowercase letter.– Class names must begin with an uppercase letter.– If a method or class name contains an underscore followed by a letter, the

letter must be an uppercase letter.– If a method or class name contains a number followed by a letter, the letter

must be an uppercase letter.

In this panel, specify the following values:

– Project name: ox_io– Class name: ProxyTCHM2

Click Next.

Figure 2-110 Project name


3. In the Create Web service support files – Chose HATS Integration Object and HATS EJB Access window (Figure 2-111), select the IO name that you will use to generate the WSDL. In our example, we select TCHM2. Click Finish.

Figure 2-111 Choosing HATS IOs

4. After you finish creating the Web service support files, you see three new files as shown in Figure 2-112.

Figure 2-112 Web services support files


These files are used in the Web services creation process:

– The ProxyTCHM2 class contains an io_nameProcessWS() method for each Integration Object that you included in the ProxyTCHM2 class. When you create the Web service using WebSphere Studio Wizards, you create a Web service that contains all of the io_nameProcessWS() methods contained in the ProxyTCHM2 class.

– Input properties classes (io_name_Input_Properties) for each Integration Object that you included in the ProxyTCHM2 class. The input properties class is used to set all the necessary inputs for the Integration Object.

– Output properties classes (io_name_Output_Properties) for each Integration Object that you included in the ProxyTCHM2 class. All of the Integration Object output properties can be retrieved from the output properties class.

For more information about these files, see IBM WebSphere Host Access Transformation Services (HATS) V5 Programmer’s Guide, SC31-6576.

5. Create the WSDL file. Change the perspective and stop the WebSphere Application Server Test Environment. Select Window →Open Perspective →Server. Right-click your server and select stop.

6. Change the perspective again. Select Window →Open Perspective →Web.

7. Inside the Web perspective (Figure 2-113), select project name →Java Source →hatsWebServiceClasses. Right-click the ProxyTCHM2.java file. Select Web Services →Deploy as Web service.

Figure 2-113 Selecting to deploy as a Web service


8. In the Deploy as Web Service – Service Deployment Configuration window (Figure 2-114), do not change anything. Click Next.

Figure 2-114 Service Deployment Configuration panel


9. In the Web Service Java Bean Selection window (Figure 2-115), leave the default values and click Next.

Figure 2-115 Web Service Java Bean Selection panel


10.In the Web Service Java Bean Identity window (Figure 2-116), leave the default values. To finalize the Web services creation process, click Finish.

Figure 2-116 Web Service Java Bean Identity panel

In a few seconds, you see many new files and WSDL definitions. HATS creates a set of classes to use in creating the Web service process.

11.To see the configuration, select project name →Web Content →wsdl →hatsWebServiceClasses. Double-click the ProxyTCHM2.wsdl file.


12.The configuration is displayed as shown in Figure 2-116. Review the general configuration and then close the file.

Figure 2-117 WSDL definition

2.6.2 Testing the Web services applicationTo test the Web service that we generated, we use the Web Services Explorer facility. This tool generates the environment and files necessary to test your WSDL definition. See Figure 2-118.

For more information about how WebSphere Studio Application Developer generates the environment to test a Web service, see:

http://www.ibm.com/software/awdtools/studioappdev/library



Figure 2-118 Web services relationships

To test the application, follow these steps:

1. Select project name →Web Content →wsdl →hatsWebServiceClasses and right-click ProxyTCHM2.wsdl. Select Web Services →Test with Web Services Explorer as shown in Figure 2-119.

Figure 2-119 Testing WSDL

-----------------------------------------------------

--------------------------------------------------------------

UDDI

WSIL

RequestorProvider

WSDL

ClientWebService

SOAPHTTP

PublishDiscover

Discover

References to service descriptors

Pointers to WSDL documents

Orginates from


2. After a few seconds, you see the Web Services Explorer. To test your application, select WSDL Main →x:\your Studio document root\* →ProxyTCHM2Service →ProxyTCHM2SoapBinding and select tCHM2ProcessWS. In the right pane shown in Figure 2-120, you see all possible actions for this WSDL. For this example, complete the account string by typing 12000 for user account and click Go.

Figure 2-120 Testing the WSDL input definition


3. If everything was configured properly, you see the result in the Status section, as shown in Figure 2-121. You should see the account information.

Figure 2-121 Testing WSDL result definition

4. After testing using Explorer, you can generate the client. We do not need to create the client to test the WSDL, so we do not explain the process here. However, if you want to generate the client, select WSDL definition →Web Services →Generate Client as shown in Figure 2-122. For more information about how to create the client, see:

http://www.ibm.com/software/awdtools/studioappdev/library/

Figure 2-122 Generating a client




Chapter 3. Integrating HATS with WebSphere Portal Server

This chapter discusses IBM WebSphere Host Access Transformation Services (HATS) V5 support for WebSphere Portal Server. It discusses the following topics:

� An overview of HATS portal support

� A simple testing scenario which creates, deploys, and tests a basic HATS portlet

� Using the Portal security credential vault with a HATS portlet (We work through an end-to-end HATS portlet and portal server integration scenario.)

� HATS Portal support advanced topics

This chapter uses the following HATS programming capabilities:

� Screen customization� Using global variables� Business logic� Advance macro creation� HATS Studio graphical user interface (GUI) support for portlet development

3


3.1 HATS portal support overviewIBM WebSphere Portal Server provides enterprise knowledge employees an integrated Web work space. This enables them to access diverse content and enterprise applications or services in a highly dynamic customized and personalized manner.

Together with WebSphere Host Access Transformation Services, backend legacy host applications, business logic (BL) and data can be integrated more easily in a modern manner. Also, the data can flow freely between HATS applications, WebSphere Portal, and other portal applications that enable the enterprise application to cope with new customer requirements more responsively.

With HATS V5 portal support, many relevant features of WebSphere Portal Server are available for exploitation within HATS by built-in tooling or straightforward Java development. The majority of HATS functionality is preserved when running HATS in the WebSphere Portal Server environment.

3.1.1 HATS portal integration architectureTo integrate HATS with a portal environment, we need to enable the HATS application portal. In general, a portal-enabled application means that we have a portlet version of this application. However, HATS V4 and V5 have different approaches to portal enabling a HATS application.

HATS V4 portal support architectureWith HATS V4, HATS users have a single option of using the HATS portlet for integration with WebSphere Portal. They use a separate HATS portlet to access a HATS application. The HATS portlet acts as a transcoding proxy, accessing a HATS application that is running in another WebSphere Application Server environment. The HATS portlet presents the back-end HATS application’s output within the WebSphere Portal page.

Beyond its presentation in the portal page, there are no hooks for communication between a HATS application, WebSphere Portal, or other portal applications. Because of this, we are unable to provide solutions to customers who want to exploit interaction between WebSphere Portal and HATS.

Figure 3-1 illustrates a sample scenario environment where a HATS V4 portlet and a HATS V4 application are used to connect a legacy mainframe.

Note: For an introduction to WebSphere Portal and portlets, see Chapter 1 and Chapter 2 in IBM WebSphere Portal V4 Developer’s Handbook, SG24-6897.


Figure 3-1 A simple scenario using HATS V4 portlet

True portal-enabled architecture requirementTo function as a real portlet instead of as a transcoding proxy, HATS needs to integrate into WebSphere Portal Server in such a fashion that satisfies the following set of requirements:

� Data can flow freely between HATS application, WebSphere Portal Server, and third-party portal applications.

� Relevant features of WebSphere Portal Server are available for exploitation within HATS built-in tooling or straightforward Java coding.

� As much HATS functionality as possible is preserved when running HATS in the WebSphere Portal Server environment.

� Prior HATS development effort and experience is leveraged when migrating to the WebSphere Portal environment.

HATS V5 portal support architectureTo support real portal enabled architecture, a significant amount of work was done on HATS runtime and HATS Studio. This is the portal integration re-architecture in HATS V5. From HATS V5, a HATS portlet application can be installed directly into and run on top of WebSphere Portal.

Figure 3-2 illustrates a sample scenario environment where a HATS V5 portlet application is used to connect to a legacy mainframe. We can see that HATS executes directly in the WebSphere Portal runtime, allowing WebSphere Portal and HATS to interact directly.

Correspondingly, HATS Business Logic classes can use the WebSphere Portal application programming interfaces (APIs), and HATS JavaServer Pages (JSPs) can include WebSphere Portal tag markup. In this way, HATS can exploit the


WebSphereApplication Server Legacy HostBrowser Client

HATS V4Application

Other J2EE

Application

HATS V4Portlet

Other Portlet

Chapter 3. Integrating HATS with WebSphere Portal Server 191

entire breadth of WebSphere Portal Server capabilities. For example, HATS Business Logic classes can access the Portal credential vault to retrieve authentication data, and HATS transformations can include Click-2-Action markup, facilitating the interchange of data between portlets. See 3.4, “Using portal credential support in HATS” on page 221, for an end-to-end example to using portal internal capabilities in a HATS portlet.

Figure 3-2 A simple scenario using HATS V5 portlet application

3.1.2 HATS portal support requirements and limitationsThis section highlights HATS portal support requirement and limitations.

HATS portlet development environmentThe HATS portlet development environment has the following requirements:

� WebSphere Studio Application Developer V5.1: WebSphere Studio V5.1 is the base requirement of HATS V5.

� WebSphere Portal Toolkit V5.0.2: This allows you to set up a portlet development environment by plugging into WebSphere Studio. It helps you to develop portlet applications for WebSphere Portal 5.0.2 and WebSphere Portal 4.2.1. For the latest downloads, see the WebSphere Portal Toolkit Web site at:

http://www.ibm.com/websphere/portal/toolkit

� WebSphere Host Access Transformation Services V5

� WebSphere Application Server V5: For the base production application server runtime support, check the HATS Web site for the latest list:

http://www.ibm.com/software/webservers/hats

WebSphere Portal

HATS V5 with Portal Server

HATS V5 Portlet

BusinessLogic

JSPs

WebSphere Application Server

WebSphere Portal

Legacy HostBrowser Client

Other Portlets



http://www.ibm.com/software/webservers/hats

LimitationsSee Chapter 14 in IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575, for more details about HATS portal support limitations.

3.2 Scenario topology and preparationThis chapter provides two different end-to-end scenarios using HATS together with portal. Both scenarios use the same software and hardware environment. This section describes the topology of our testing environment and the preparation procedure for the software environment.

3.2.1 Scenario topologyAs shown in Figure 3-3, we have a development workstation with HATS development tools installed. We also have a server machine with WebSphere Portal Server V5 installed to run our HATS portlet application. We have a back-end legacy AS/400 system for use as a host system to be integrated into the portal environment.

Figure 3-3 HATS portal integration scenario topology

Important: All HATS portlet development features are available or accessible only when both HATS V5 and the WebSphere Portal Toolkit are installed.

ITSO EthernetHostName:RS600010

IP: 9.24.105.60

HostName:ka0knhb

IP: 9.24.104.125

uid: jing

2216

Network9.37.232.xx

9.24.104.yy9.24.105.yy

9.24.104.1

uid: root

P170

HostName:M23VNX85

IP:9.24.105.124

uid: administrator

8658

WAS 5.01WPS 5.0

Win2K svr

WSAD 5.1HATS 5

WPS Toolkit 5.02Win2K

iseriesd.dfw.ibm.com

uid: user4boat

WAS 5.01WPS 5.0DB2 8.1AIX 5.2

Router

AS/400


The machine details are shown in Table 3-1.

Table 3-1 Machine details in scenario

3.2.2 Preparing the environmentThis section shows you how to prepare the software environment for the following two testing scenarios.

Installing WebSphere Studio Application Developer V5.1 and HATS V5.0For installation instructions, see IBM WebSphere Host Access Transformation Services (HATS) V5 Getting Started, SC31-6574.

Installing WebSphere Portal Toolkit V5.0.2There are three different installation approaches to install the WebSphere Portal Toolkit on WebSphere Studio Application Developer:

� Local debug configuration with portal server� Remote debug configuration� Local toolkit configuration without portal server

The first two approaches result in a debuggable WebSphere Portal environment.

For HATS portlet development, the main focus is development with HATS features and components. In our scenario, we are not concerned with portlet debugging. To simplify the installation process, we try the third approach. We

Machine information

Installed software Roles

ka0knhbIP:9.24.104.125

1. Windows 2000 Professional2. WebSphere Studio Application Developer V5.13. HATS V5.04. WebSphere Portal Toolkit V5.0.2

HATS application development workstation

iseriesd.dfw.ibm.com®

1. OS/400 V5.22. Some AS/400 green-screen applications

Back-end TN5250 host.This machine is publicly available from the Internet.

M23VNX85IP: 9.24.105.124

1. Windows 2000 Server2. WebSphere Portal Server V5.03. WebSphere Application Server V5.0.1

Running HATS application

RS600010IP: 9.24.105.60

1. AIX V5.22. WebSphere Portal Server V5.03. WebSphere Application Server V5.0.14. DB2 v8.1

AIX portal environment


install WebSphere Portal Toolkit plug-in without debug and portal server support. This is sufficient to generate our HATS portlet application. After we complete the HATS portlet application, we export it to the portal server for testing.

To install the portal debug configuration, you can reference the WebSphere Portal Toolkit installation guide found on the Web at:


We install WebSphere Portal Toolkit V5.0.2 on the machine ka0knhb, which is our development workstation.

1. Stop WebSphere Studio if it is started.

2. If you download WebSphere Portal Toolkit from the Web, the WebSphere Portal Toolkit is a self-extracting archive. Place it into a temporary directory and run the executable file PortalToolkit502MP.exe.

3. The first window prompts you to select a temp directory to extract the toolkit. Click Next.

4. The second window shows the language selection option, leave it as the default and click OK. Click Next.

5. In the License Agreement window, read and accept this license. Click Yes and then click Next to continue the installation.

6. In the component selection panel (Figure 3-4), select Portal Toolkit V5.0.2 and click Next.

Figure 3-4 Selecting the component for Portal Toolkit



7. The WebSphere Portal Toolkit installation shield can find your WebSphere Studio Application Developer installation directory, and prompt you with a window to verify it. Click Next.

8. A window opens and shows a process bar to display your installation process completion status. After completing the installation, click Finish to exit the installation shield window.

9. Click Start →Programs →IBM WebSphere HATS →HATS Studio to start the HATS Studio.

10.The WebSphere Studio window (Figure 3-5) prompts you to select your workspace directories. Select a directory. Then select Use this workspace as the default and do not display this dialog box again.

Figure 3-5 Select HATS workspace directory


11.The Configuration Changes – Pending Configuration Changes window (Figure 3-6) opens. Expand the changes list. We do not want to reject any changes, so we click Finish to accept all.

Figure 3-6 Studio configuration changes window

12.After HATS Studio commits all of the changes, a window prompts you to restart the workbench and make the changes effective. Click Yes to accept the message.

HATS Studio restarts. When the Studio window opens again, it is ready to develop the HATS portlet.

Installing WebSphere Portal Server V5.0We don’t provide detailed instructions about installing WebSphere Portal V5.0 on Windows and AIX systems. You can find an introduction in Chapters 4 and 6 in IBM WebSphere Portal for Multiplatforms V5 Handbook, SG24-6098.


3.3 Creating, deploying, testing a basic HATS portletThis section describes a simple HATS portlet end-to-end development and testing scenario. First we create a HATS project with default transformation settings. Then we generate a portlet from the HATS project. Finally we deploy it to the portal server and test it.

3.3.1 Creating a basic HATS portletWe create our first HATS portlet project. In HATS V5, there are two methods to create a HATS portlet project:

� Create a new project using the HATS Create a Project wizard and designate that the project should be created as a portlet.

� Convert an existing HATS application to a portlet. This ensures that all of our efforts on existing HATS applications are not wasted when moving them to WebSphere Portal.

In this section, we use the second method. We create a normal HATS project, and then convert it to a HATS portlet project. We use the first method in 3.4.4, “Creating the HATS credential integration portlet” on page 238.

Creating the base HATS applicationTo create the base HATS application, follow these steps:

1. Start HATS Studio. Click Start →Programs →IBM WebSphere HATS →HATS Studio.

2. In the white space area of the HATS Project View, right-click and select New HATS →Project.

Note: If you have an existing HATS V4 application, you must migrate it to HATS V5 before you convert to your new portlet. For migration instructions, see Chapter 2 in IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575.


3. The Create a Project wizard (Figure 3-7) opens. In the Create a Project panel, type the name for the new HATS project and a description for the project. For our example, we enter mydfw. You may want to change the name of the Enterprise Application project name. The default is HATS.ear. The name that you enter is also shown in the WebSphere Application Server when the application is deployed on WebSphere. Click Next.

Figure 3-7 HATS Create a Project wizard


4. In the Create a Project – Connections Settings window (Figure 3-8), specify the connection properties for the HATS application. For Host name, we specify iseriesd.dfw.ibm.com and for Type, we select 5250. For the other settings, leave the default values. Click Next.

Figure 3-8 Connection Setting panel

Note: After you create the HATS project, you can edit the connection properties and configure the advanced connection properties in the project setting view.


5. On the Create a Project – Select Default Template window (Figure 3-9), select the template you want to use. We select Swirl.jsp. Click Finish.

Figure 3-9 Select Default Template panel


The HATS Project Wizard completes the creation of the HATS project. You see the new HATS project in the HATS Project View of HATS Studio (Figure 3-10).

Figure 3-10 HATS project view with new HATS project (mydfw)


3.3.2 Converting the HATS application to portletYou convert the HATS application to the portlet as explained in the following steps:

1. In the HATS Project View (Figure 3-11), select the mydfw project, right-click, and select Generate Portlet.

Figure 3-11 Selecting Generate Portlet

2. The Portlet Generation Options window (Figure 3-12) opens. It shows some options for the conversion process, such as new project name, whether to update all the templates, transformations, and macro handles, etc. We leave all of the settings as default and click OK.

Figure 3-12 Portlet Generation Options window


3. After the convert process is invoked, a Progress Information window (Figure 3-13) opens. It shows a progress bar and the changes undergone to create the new Portlet project. You can see what tasks were taken to convert from the status text line.

Figure 3-13 Progress bar

4. A new project appears in the Project View (Figure 3-14) after the convert process has completed. The project name is the old project name + Portlet, which in this example is mydfwPortlet.

Figure 3-14 Converted project view

Attention: After generating a portlet, the HATS project from which the portlet was generated is independent from the portlet project. Changes in one project are not reflected in the other. You can always generate a new HATS portlet from a HATS project to reflect changes made in the latter.

You cannot convert a HATS portlet project back into a regular HATS project.


3.3.3 Deploying the HATS portlet on WebSphere Portal ServerWe need to export the portlet as a Web Archive (WAR) file and then deploy it on a portal server. In our scenario, the portal server is already up and running on system M23VNX85 (IP 9.24.105.124).

1. In HATS Studio, select File →Export...

2. The Export – Select window (Figure 3-15) opens. Select WAR file and click Next.

Figure 3-15 Export HATS portlet


3. The Export Resources to a WAR File – WAR Export window (Figure 3-16) opens. From the Web Project list, select the portlet project name, which is mydfwPortlet in this example. Specify an archive name for the destination. Click Finish (not shown) to complete the export.

Figure 3-16 Export settings

4. Open an Internet Explorer window. Enter the Uniform Resource Locator (URL) of the portal server to display the first page of the WebSphere Portal Server. For our example, we type http://9.24.105.124/wps/portal.

5. In the upper right corner of the portal first page that opens, click Log in.

6. The log in page (Figure 3-17) of the portal server opens. Enter the user ID and password of the portal administrator. Click Log in.


Figure 3-17 Logging into the portal server

7. Enter the portal server administration page. In the menu bar at the top of the portal Web page, click Administration as shown in Figure 3-18.

Figure 3-18 Accessing the portal server administration page


8. On the administration page, click Portlets →Install.

9. The Install Portlets panel (Figure 3-19) opens. Click Browse to select the location of the portlet archive file. For our example, we specify C:\temp\mydfwPortlet.war. Then click Next.

Figure 3-19 Selecting the portlet archive file


10.The portlet is transferred to the portal server for further installation. It may take several minutes to upload the entire archive file depending on your network bandwidth. After the transfer is complete, a new page (Figure 3-20) opens. Click Install to continue the installation process.

Figure 3-20 Installing the portlet

As shown in Figure 3-21, a new page displays a message informing you that the portlet was installed successfully.

Figure 3-21 Installing the basic HATS portlet is successful


3.3.4 Testing the HATS portletWe successfully deploy the HATS portlet in the previous section. In this section, we create a new portal top page named HATS Portlet Testing and add a sub-page named HATS Basic Portlet to this top page. Then we add the portlet installed in the previous section on the HATS Basic Portlet sub-page.

Creating new portal pagesIn the following steps, we create portal pages named HATS Portlet Testing and HATS Basic Portlet.

1. Log on to the portal server using the portal administrator user ID. Then change the portal page to the administration page. See step 4 on page 206 through step 7 on page 207.

2. In the right side of the Manage Pages panel (Figure 3-22), click Portal User Interface →Manage Pages. Click the New page button.

Figure 3-22 Adding a new page


3. In the Properties panel (Figure 3-23), enter a page title. For our example, we name it HATS Portlet Testing. Click OK to continue.

Figure 3-23 Setting the properties of the new portal page

4. A message is displayed as shown in Figure 3-24. It informs you that the new portal page is created. Click OK to clear this message page.

Figure 3-24 New portal page created successfully message


5. Return to the Manage Pages view. Scroll down the page until you see HATS Portlet Testing as shown in Figure 3-25. Click the HATS Portlet Testing link.

Figure 3-25 Clicking the HATS Portlet Testing link

6. You see a Manage Page for this page (Figure 3-26). Click New page to create a dedicated page for the HATS basic portlet placement.

Figure 3-26 Clicking New page


7. In the Properties panel (Figure 3-27), for Title of the new page, we specify HATS Basic Portlet. This new page is the sub-page of the HATS Portlet Testing page group. Expand Advanced options for this page setting. Because the HATS transformation pages are rather large, we specify that the pages only have one column container to hold the portlet as shown in Figure 3-27.

Figure 3-27 Setting the Advanced options

8. A message is displayed as shown in Figure 3-28. It informs you that the new portal page is now created. Click OK to clear this page.

Figure 3-28 New portal page created successfully message


Adding our portlet to the portal pageWe now add the portlet (deployed to the portal server in 3.3.3, “Deploying the HATS portlet on WebSphere Portal Server” on page 205) to the portlet page named HATS Basic portlet.

1. As shown in Figure 3-29, for HATS Basic Portlet, click the Edit page layout button.

Figure 3-29 Selecting to edit the page layout


2. In the Edit Layout panel (Figure 3-30), click the Add portlets button.

Figure 3-30 Clicking the Add portlets button


3. In the next panel (Figure 3-31), in the Search for text box, enter mydfw. Click Search.

Figure 3-31 Searching for mydfw


4. Figure 3-32 shows the search result. Select the mydfwPortlet Portlet check box. Click OK to continue.

Figure 3-32 Search results

Remember that mydfwPortlet is the name that was automatically created for the HATS portlet (see 3.3.2, “Converting the HATS application to portlet” on page 203). The steps to deploy and install mydfwPortlet on the portal server are detailed in 3.3.3, “Deploying the HATS portlet on WebSphere Portal Server” on page 205.


5. A message is displayed stating that the portlet is now added. Figure 3-33 shows that mydfwPortlet was added to the container in this layout page.

Click the Done button (not shown) to complete the portlet layout.

Figure 3-33 mydfwPortlet added to the container


Showing the HATS portletWe now view the HATS portlet on the portal server.

1. Click the right arrow as shown in Figure 3-34.

Figure 3-34 Accessing the HATS Portlet Testing portal page

2. The HATS Portlet Testing portal page comes into focus as shown in Figure 3-35. Click HATS Basic Portlet.

Figure 3-35 Selecting HATS Basic Portlet


3. The basic HATS portlet shows up with the default transformation of the AS/400 signon display as shown in Figure 3-36. For User, type user4boats. For Password, type password. Then press the Enter key to sign on to the AS/400 system.

Figure 3-36 Basic HATS portlet signon screen


You now see the OS/400 Main Menu displayed in our portal pages. It works!

Figure 3-37 OS/400 Main Menu

3.4 Using portal credential support in HATSWe demonstrated that with HATS V5, HATS applications can execute directly in the WebSphere Portal runtime as a portlet, allowing WebSphere Portal and HATS to interact directly. In this way, HATS can exploit the entire breadth of WebSphere Portal capabilities.

In this section, we create an end-to-end scenario in which a HATS portlet exploits the WebSphere Portal security credential vault and then uses it to automatically log on to the AS/400 system. Also in this scenario, we cover some advanced HATS development skills such as screen customization, business logic, global variables, and macros.


3.4.1 HATS test scenario with portal credential vaultThe objective of this scenario is to create a HATS portlet which can use portal security features to perform a single signon to an AS/400 system. The application process occurs as explained here:

1. A user written portlet sets a user name and password pair to a portal credential vault slot.

2. A HATS portlet runs and connects to an AS/400 system.

3. A HATS screen customization is defined for the initial AS/400 log on screen.

4. The screen customization creates two HATS Global Variables.

5. The screen customization runs some HATS Business Logic which accesses the portal credential vault to access the user name and password, which were set by the user written portlet in step 1.

6. The business logic sets the user name and password to the global variables were created in step 4.

7. A logon macro runs. It uses the global variables (set by step 6) to log on to the AS/400 system.

8. The AS/400 system main menu is displayed.

The hardware and software environment are the same as for 3.2, “Scenario topology and preparation” on page 193.

3.4.2 Building the Credential Vault Populate portletIn this section, we build a simple portlet using WebSphere Portal Toolkit. We use use this portlet to set a user name and password pair for an AS/400 administrator slot in the credential vault.

1. Select Start →Programs →IBM WebSphere HATS →HATS Studio.

2. Select File →New →Project.


3. A wizard window opens that guides us to create a project. In the New Project – Select window (Figure 3-38), in the left pane, select Portlet Development. In the right pane, select Portlet Application Project. Click Next.

Figure 3-38 Creating a new portlet application project


4. In the Create a Portlet Project – Define the Portlet Project window (Figure 3-39), for Project name, enter HATSCredential. For Select a portlet type, select Create basic portlet. Select the Configure advanced options check box. Click Next.

Figure 3-39 Defining the portlet project


5. In the J2EE Settings Page panel (Figure 3-40), accept all default option values. For portlet development, the Enterprise Archive (EAR) file is not required. We need only the WAR file. Click Next to continue.

Figure 3-40 J2EE Settings Page panel


6. In the Portlet Settings panel (Figure 3-41), you can set the portlet application name and portlet name, and other settings. We leave the default values for all options. Click Next to continue.

Figure 3-41 Portlet Settings panel


7. In the Event Handling panel (Figure 3-42), deselect the Add action listener option. Click Next to continue.

Figure 3-42 Event Handling panel


8. In the Single Sign-On panel (Figure 3-43), select to add credential vault handling and use the administrative credential vault slot. In this example, for Slot name, we specify the credential slot name myHATSVault iseriesd.dfw.ibm.com HATSPortlet. Select the Show password option. Click Next to continue.

Figure 3-43 Single Sign-On panel

Note: For more information about credential vault slot and slot type, see IBM WebSphere Portal V4 Developer’s Handbook, SG24-6897.


9. In the Miscellaneous panel (Figure 3-44), accept all default values. Click Finish to complete the portlet creation process.

Figure 3-44 Miscellaneous panel

10.The Confirm Perspective Switch message box opens. Click Yes to confirm that you want to switch to the portlet perspective.

Figure 3-45 Switch perspective box


HATS Studio switches to the portlet perspective. The portlet code was generated automatically. The function of this portlet is to set the value of a username-password-credential slot. The slot type (SLOT_TYPE) is an administrative slot.

3.4.3 Deploying and testing the Credential Vault Populate portletThe deployment process of the HATSCredential portlet is the same as the steps described in 3.3.3, “Deploying the HATS portlet on WebSphere Portal Server” on page 205.

Adding the HATSCredential portlet to our test pageTo test the HATSCredential portlet, we add it to the HATS Portlet Testing page.

1. Log on to the portal server using the portal administrator user ID. Change the portal page to the administration page. See step 4 on page 206 through step 7 on page 207.

2. As shown in Figure 3-46, click Portal User Interface →Manage Pages. In the Search for field, enter HATS Portlet Testing, and click Search.

Figure 3-46 Searching for the HATS Portlet Testing page


3. Find the HATS Portlet Testing page and click the Edit icon button as shown in Figure 3-47.

Figure 3-47 Editing the HATS Portlet Testing page

4. On the left side of the Edit Layout page (Figure 3-48), click Add portlets.

Figure 3-48 Clicking the Add portlets button


5. In the Search for field, type HATSCredential and click Search as shown in Figure 3-49.

Figure 3-49 Searching for HATSCredential

6. On the search result page (Figure 3-50), select HATSCredential portlet and click OK.

Figure 3-50 Search results page showing HATSCredential portlet


7. As shown in Figure 3-51, click Done to complete the addition of our vault credential portlet (HATSCredential) to our test page (HATS Portlet Testing).

Figure 3-51 Completing the addition of the vault credential portlet to the test page


Adding a vault slot for our back-end applicationWe must now create a portlet credential vault slot using the portal admin page. This vault slot is used to contain the logon user ID for the AS/400 back end.

1. On the portlet administration page, click Access →Credential Vault.

2. The Credential Vault management page opens as shown in Figure 3-52. Select the Add a vault slot option by clicking the arrow symbol to the left.

Figure 3-52 Selecting to add a vault slot


3. In the next panel under Create a vault slot (Figure 3-53), in the Name field, enter myHATSVault iseriesd.dfw.ibm.com HATSPortlet. Click OK to add this slot. The credential vault slot name specified here must be the same name defined in our Populate Credential Portlet. See step 8 on page 228.

Figure 3-53 Adding a slot

Important: HATS V5 supports the background connection function. For the credential vault to work correctly with Web Express Logon, you must define a different vault resource to associate with the credential vault slot for each host connection.


4. On next page (Figure 3-54), click Done.

Figure 3-54 Completing the vault entry creation

Testing the HATSCredential portletWe now test our HATSCredential portlet by adding the user ID and password for our back-end AS/400 server into the credential vault slot we created previously.

1. Switch the portal page by clicking My Portal and HATS Portlet Testing.

2. You see the page in Figure 3-55. Since we have not yet set values in this credential slot, it prompts us with the message There are no user ids and passwords in the vault for this portlet. Use the edit mode to store them. Click the Edit icon to enter edit mode for this portlet.


Figure 3-55 Clicking the edit icon to store the user IDs and passwords

3. In edit mode as shown in Figure 3-56, specify the user ID and password. For the Enter user id field, we type user4boats. For Enter password, we type password. Click Save.

Figure 3-56 Specifying the user ID and password to store with the credential vault


The portlet displays the credential and values as shown in Figure 3-57. In this scenario, this credential vault slot is used to automate the logon process for our sample HATS portlet.

Figure 3-57 Portlet displaying the credential and values

3.4.4 Creating the HATS credential integration portletIn this section, we create a HATS portlet for portlet credential integration testing. Instead of converting from an existing HATS portlet, we create a HATS portlet directly.

1. Start HATS Studio. Click Start →Programs →IBM WebSphere HATS →HATS Studio.

2. In the white space area of HATS Project View, right-click and select New HATS →Project.


3. The Create a Project wizard opens as shown in Figure 3-58. In the Create a Project panel, for Name, we type HATSPortlet. Select Create as Portlet to designate it as a portlet project directly. Click Next to continue.

Figure 3-58 Create a Project wizard to create HATSPortlet


4. In the Connect Settings panel (Figure 3-59), for Host name, type iseriesd.dfw.ibm.com. For Type, select 5250. Click Next to continue.

Figure 3-59 Connection Settings panel


5. In the Select Default Template panel (Figure 3-60), select PortletBlank.jsp and click Finish to finish creating the project.

Figure 3-60 Select Default Template panel

3.4.5 Creating a screen customization for the logon screenWe create a screen customization, which recognizes the logon screen for the back-end AS/400. It then takes actions to set and initialize two global variables: user and password.

Note: PortletBlank.jsp is a new template that provides less content for transformed pages because WebSphere Portal produces its own header and banner. The related stylesheet emulates the existing WebSphere Portal themes.


1. In the HATS Project View, right-click your project and select Open Terminal →main. The HATS terminal opens and automatically connects to the AS/400 host set during the initial project creation.

Figure 3-61 Opening the Host Terminal

2. In the open Host Terminal window (Figure 3-62), click the icon to create a HATS screen customization.

Figure 3-62 Creating a HATS screen customization


3. The Create a Screen Customization – New Screen Customization window (Figure 3-63) opens. Enter a name for this screen customization. We accepted the default values. Click Next to continue.

Figure 3-63 New Screen Customization panel


4. In the Select Screen Recognition Criteria panel (Figure 3-64), in the terminal window, select an area by clicking and dragging your mouse. We deselected the Use default criteria option and selected the Within a rectangular region option. Click Next to continue.

Figure 3-64 Select Screen Recognition Criteria


5. In the Select Actions panel (Figure 3-65), deselect the Apply a transformation option and select Add advanced actions. This allows us to add advanced options such as global variables and macros to this transformation. Click Next to continue.

Figure 3-65 Select Actions panel


6. In the Advanced Actions panel (Figure 3-66), click Add to add advanced actions for screen customization. For our scenario, we set values for two global variables.

Figure 3-66 Advanced Actions panel

7. In the Select an Action panel (Figure 3-67), select Set global variable. Click Next.

Figure 3-67 Select an Action panel


8. In the Define Action Properties panel (Figure 3-68), for Name, type user. Select the Set to a fixed value option and specify user in the field. Click Finish to complete this setting.

Figure 3-68 Define Action Properties panel

9. Repeat step 6 on page 246 through step 8 to add another global variable with the name of password and value of password.


10.Now you see the Advanced Actions panel as shown in Figure 3-69. Click Finish to complete the screen customization.

Figure 3-69 Advanced Actions panel showing actions

Figure 3-70 shows the final project view.

Figure 3-70 Final project view


3.4.6 Creating the credential vault business logic Java methodWe create HATS Business Logic. It accesses the credentials from the portal credential vault and then uses the credential values to set the global variables user and password.

1. Open the Business Logic wizard. In the HATS Project view (Figure 3-71), right-click your project and select New HATS →Business logic.

Figure 3-71 Opening the Business Logic wizard


2. In the Create a Java class panel (Figure 3-72), enter the class name and package name for the business logic. The name should follow the Java programming naming convention. For Class name in this example, we type blCredential. For Package, we type com.itso.hats. Select the options Get global variable, Set global variable, and Credential Vault samples. Click Finish to complete creating the business logic.

Figure 3-72 Create a Java class panel


3. The Java edit window (Figure 3-73) opens for our business logic. We can add Java code in this Java class.

Figure 3-73 Create HATS Business Logic - 3

Since we tell the wizard to Create Credential Vault samples (see Figure 3-72), we received the set and getUserCredential methods in our business logic class. In our business logic, we call the getUserCredential method to get the user credentials from the portal credential vault. We copy getUserCredential as shown in Example 3-1. Notice that the credential vault slot name is constructed to be slotID + space + host name + space + application.

Example 3-1 getUserCredential method

/** * Example method that retrieves a UserPasswordPassiveCredential from the Credential Vault so * the authentication information can be used in a macro to log into a host system * The slotName is constructed to be slotID (space) host (space) application. * @param blInfo - BusinessLogicInfo from current session * @param slotID - the vault slot ID to store the credential * @param host - the host name used to resolve this credential, or null for none * @param application - the application name used resolve this credential, or null for none * @return a string array with the credential : {userID, password}, or null if it could not be found


*/public static String[] getUserCredential(BusinessLogicInfo blInfo, String slotID, String host, String

application) {PortletContext context = (PortletContext) blInfo.getServletContext();PortletRequest portletRequest = (PortletRequest) blInfo.getRequest();

CredentialVaultService cvs = null;

try {cvs = (CredentialVaultService) context.getService(CredentialVaultService.class);

} catch (PortletServiceUnavailableException e) {e.printStackTrace();return null;

} catch (PortletServiceNotFoundException e) {e.printStackTrace();return null;

}

slotID = slotID.replace(' ', '_');if (host != null)

host = host.replace(' ', '_');if (application != null)

application = application.replace(' ', '_');String uniqueSlotID = slotID + " " + (host != null ? host : "") + " " + (application != null ?

application : "");

UserPasswordPassiveCredential cred = null;try {

cred = (UserPasswordPassiveCredential) cvs.getCredential(uniqueSlotID, "UserPasswordPassive", new Hashtable(), portletRequest);

} catch (Exception e) {e.printStackTrace();return null;

}if(cred!=null) {

return new String[] {cred.getUserId(), new String(cred.getPassword())};}return null;

}


4. We add the code shown in Example 3-2 to the business logic execute method and save the Java file. Our business logic is now complete.

Example 3-2 Sample business logic code

public static void execute(BusinessLogicInfo blInfo) { String [] cred = null; //add code here to perform your business logic

System.out.println("Verify value: global variable init value is "+ blInfo.getGlobalVariable("user") + blInfo.getGlobalVariable("password"));

cred = getUserCredential(blInfo,"myHATSVault","iseriesd.dfw.ibm.com","HATSPortlet");if (cred != null ) {setGlobalVariable(blInfo,"user",cred[0]);setGlobalVariable(blInfo,"password",cred[1]);}System.out.println("Verify value: user credential is "+ cred[0]+cred[1]);System.out.println("Verify vaule: global variable is "+ blInfo.getGlobalVariable("user") +

blInfo.getGlobalVariable("password"));

}

5. Press Ctrl+S to save the changes in WebSphere Studio.

3.4.7 Recording the signon macroIn this section, we record a HATS macro to automatically sign us to the back-end AS/400 system.

1. Follow the first two steps 3.4.5, “Creating a screen customization for the logon screen” on page 241, to open the HATS terminal window.

2. In the Host Terminal window (Figure 3-74), click the Record Macro button to begin recording.

Figure 3-74 Clicking the Record Macro button on Host Terminal


3. In the Record Macro – Record Macro window (Figure 3-75), for Name, type the macro name. We keep the default value of SignOn and click Finish.

Figure 3-75 Record Macro window


4. In the Define Screen Recognition Criteria – Define the starting screen of the macro window (Figure 3-76), complete these steps:

a. Change Screen Name to Sign On Screen. b. Click and drag to draw a rectangular region in the screen. c. Under String position, select At a specific position as recognition criteria.d. Click Finish to complete defining the sign-on screen.

Figure 3-76 Define the starting screen of the macro panel


5. In the Host Terminal window (Figure 3-77), click Add Prompt Action button in the toolbar. Make sure that your cursor is in the same location as shown in the figure (User field).

Figure 3-77 Clicking the Add Prompt Action button


6. In the Add Prompt Action window (Figure 3-78), complete these steps:

a. For Name, type setUID.b. For Default value, type user4boats. c. Under Handle Macro Prompt, select Set prompt to global variable. d. For Global variable, select user. e. Click OK to add this action.

Figure 3-78 Add Prompt Action window

7. Add another prompt action. This time, place your cursor at the beginning of the password field shown in Figure 3-77 on page 256. Click the Add Prompt Action button.


8. Now you see the Add Prompt Action window as shown in Figure 3-79. Complete these steps:

a. For Name, type setPWDb. For Default value, type password. c. Under Handle Macro Prompt, select Set prompt to global variable.d. For Global variable, select password. e. Click OK to add this action.

Figure 3-79 Adding another prompt action

9. On the return to the HATS terminal screen, press Enter to log on to the AS/400.


10.The OS/400 Main Menu screen is displayed in the HATS Terminal (Figure 3-80). Click the Define Screen Recognition Criteria button in the toolbar.

Figure 3-80 HATS Terminal showing the OS/400 Main Menu


11.On the Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 3-81), complete these steps:

a. For Screen Name, type Main Menu Screen. b. Click and drag to draw a rectangular region. c. Under String position, select At a specified position. d. Click Finish to complete the screen definition.

Figure 3-81 Select Screen Recognition Criteria


12.In the Host Terminal window (Figure 3-82), click the Stop Macro button to end the macro recording.

Figure 3-82 Clicking the Stop Macro button

13.As shown in Figure 3-83, click the Save Macro icon to save the macro. Then close the terminal window. We have finished recording a signon macro.

Figure 3-83 Saving the macro

3.4.8 Enhancing the signon macro with multi-process path supportYou may think that the signon macro is completed. If you run this macro in a real environment, it may fail in different scenarios.

Problems in a simple signon macroThe macro we created in the previous section work only for a basic signon scenario. For example, consider that another session already signed on to the AS/400 system with the same user name. We run our signon macro. After we log on to the AS/400 system, the second screen shows an error message.

The macro we created fails on this scenario because the macro stops and waits for the main menu screen, but that screen is not displayed.

Let’s do a test to see what the problem is:

1. Sign on the AS/400 system with user4boats as the user name using any terminal emulator such as AS/400 Client Access or IBM Personal Communications.


2. Open HATS Studio.

3. As shown in Figure 3-84, select HATSPortlet →Macros. Double-click the SignOn macro. In the Overview pane, click Open Host Terminal to open the host terminal for the SignOn macro.

Figure 3-84 Opening Host Terminal for the SignOn macro


4. In the HATS terminal window, click the Play button to play the SignOn macro.

Figure 3-85 Playing the SignOn macro

5. In the Supply Prompt Values window (Figure 3-86), for setUID, type user4boats. For setPWD, type password. Click OK to continue the macro.

Figure 3-86 Specifying setUID and setPWD


6. The macro does not stop automatically. If you look at the Macro Navigator frame on the left pane in Figure 3-87, you can see that the macro stopped before the Main Menu screen (circled in the figure). It hangs after the Sign On Screen and before Main Menu Screen. In the right pane, you see a message screen displayed by the AS/400. This is not the Main Menu screen as expected by the SignOn macro.

Figure 3-87 Problem with SignOn macro not stopping automatically

Summary of the problemThere are some problems in the simple signon macro. If the runtime execution path was not the same as we designed, the macro hangs and never reaches the macro exit (the Main Menu Screen).

To solve this problem, we must create a macro with multiple execution paths to handle different runtime scenarios.

Creating an enabled signon macroFigure 3-88 shows a chart to explain the final macro we plan to create.


Figure 3-88 Multi-path for sign-on macro

Now we enhance the signon macro with multiple execution path support. Continue from Figure 3-87 after clicking the Stop Macro button.

1. Close the HATS terminal window if it is opened.

2. Open the HATS terminal window for SignOn macro as shown in Figure 3-84 on page 262. In the left pane of terminal window, select SignOn. Click the Record Macro button as shown in Figure 3-89.

Figure 3-89 Enhance sign-on macro - 1

3. The Record New Macro or Append window (Figure 3-90) opens. You can create a new macro or append a macro to an existing one. We click Append.

Figure 3-90 Selecting to record a new macro or to append one

Message Screen

Main Menu

No sign on info

Wrong User ID

EndEndMacroMacro

Entry Screen

NextScreen

Exit Screen

Exit Screen

Exit Screen

NextScreen

Sign on ScreenTransient Screen


4. In the Host Terminal window (Figure 3-91), for User, type WRONGUSER. For Password, type a password. Press Enter to sign on. A wrong user message is displayed at the bottom of the screen.

Figure 3-91 WRONGUSER does not exist message

5. As shown in Figure 3-92, click the Define Screen Recognition Criteria button.

Figure 3-92 Clicking the Define Screen Recognition Criteria button


6. The Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 3-93) opens. Follow these steps:

a. For Screen Name, type Wrong User Screen. b. Click and drag a box on the screen area. c. Under String position, select Anywhere on the screen. d. Click Finish to complete this wizard.

Figure 3-93 Select Screen Recognition Criteria panel


7. The macro view should look like the example in Figure 3-94. Return to the right pane of the HATS terminal and delete the wrong user name. Press Enter to sign on without any user information.

Figure 3-94 Enhance sign-on macro - 6

8. You see the screen in Figure 3-95. Set the screen recognition criteria for this screen using the same instructions in step 5 on page 266.

Figure 3-95 Signon screen


9. When you reach the Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 3-96), follow these steps:

a. For Screen Name, type No Sign-on info Screen. b. Click and drag a box. c. Under String position, select Anywhere on the screen. d. Click Finish to complete this wizard.

Figure 3-96 Setting the screen recognition criteria


10.Now the macro view should look like the example shown in Figure 3-97. Return to the right pane of HATS Terminal. Enter the correct user name and password. Then press Enter to sign on.

Figure 3-97 Enhanced signon macro


11.Now you see the screen shown in Figure 3-98. Set the screen recognition criteria for this screen using the same instructions as step 5 on page 266.

Figure 3-98 Signed on


12.When you reach the Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 3-99), complete these steps:

a. For Screen Name, type Program Messages Screen. b. Click and drag a box. c. Under String position, select Anywhere on the screen. d. Click Finish.

Figure 3-99 Selecting the screen recognition criteria

13.In the HATS Terminal window, press Enter to proceed to the next screen.


14.In the Host Terminal window, click the Stop Macro button to end macro recording. Click the Save Macro button to save the macro. Don’t forget to type 90 in the terminal screen to sign off the AS/400 system.

Now the HATS Terminal window looks like the example shown in Figure 3-100.

Figure 3-100 OS/400 Main Menu in the Host Terminal window


15.In the Macro Navigator view, select and delete all of the useless actions recorded during previous steps (see image on the left in Figure 3-101). Press and hold the Ctrl key and click all of the useless actions in the navigator view. Press the Delete key to delete these selections.

Make sure your screen looks the example in shown on the right. If some items are not deleted, repeat this step to delete them.

Figure 3-101 Deleting useless actions in the Macro Navigator view

16.Edit the macro path. In the Macro Navigator, select Sign on Screen →Next Screens. Right-click and select Edit.

Before

After


17.The Edit Next Screens for Sign on Screen window (Figure 3-102) opens. Click the >> and << buttons to move the screens between the Available Screens and Next Screens panes until you see the results shown in the example. Click OK to close this window.

Figure 3-102 Edit Next Screens for Sign on Screen window

18.In the Macro Navigator, select Program Message Screen →Next Screens. Right-click and select Edit.

19.In the Edit Next Screens for Program Messages Screen window (Figure 3-103), click the >> and << buttons to move the screens between the Available Screens and Next Screens panes until you see the results shown in the example. Click OK to close this window.

Figure 3-103 Edit Next Screens for Program Messages Screen window

20.Click the Save Macro button to save the changes and close the terminal window.


21.We use an advanced editor to further edit the macro and make it suitable for our scenario. In the HATS Studio, double-click the SignOn macro to open the view page. To launch the advanced editor, in the Overview pane, click the Advanced Editor... button as shown in Figure 3-104.

Figure 3-104 Using Advanced Editor

22.Using Figure 3-88 on page 265, we construct Table 3-2. We make changes to the macro using the editor as shown in Figure 3-105. Click Save to save the changes.

Table 3-2 Screen properties table

Screen name Entry screen Exit screen Transient screen

Sign On Screen True False False

Main Menu Screen False True False

Wrong User Screen False True False

No Sign-on info Screen False True False

Program Message Screen False False True


Figure 3-105 Advanced macro editor

We have now finished the sign-on macro supporting different execution paths. You may test the new macro using the HATS terminal following the steps in “Problems in a simple signon macro” on page 261.

Actually, the new macro still does not handle all of the logon execution paths. For example, if you enter the correct user name but wrong password to log on to the AS/400, you receive the Wrong User Profile screen. We leave it as an exercise for you.

Hint: You may add an extra screen recognition criteria to include this scenario.


3.4.9 Completing the signon screen customizationNow, we complete the whole screen customization. We add the business logic created in 3.4.6, “Creating the credential vault business logic Java method” on page 249, and the macro created in the previous section to the SignOn screen customization’s action list.

1. In the HATS Project View (Figure 3-106), select Screen Customizations. Double-click SignOn. In the right pane, click the Add button to add actions.

Figure 3-106 Adding actions for SignOn


2. On the Add Action – Select an Action window (Figure 3-107), select Execute business logic and click Next to continue.

Figure 3-107 Selecting an action for SignOn

3. In the Add Execute Business Logic Action – Define Action Properties window (Figure 3-108), for Class name, specify com.itso.hats.blCredential. Click Finish to close the window.

Figure 3-108 Defining the action properties


4. Repeat step 1 on page 278 through step 3 to add the SignOn macro to the action list. Make sure that the final action list is in the same order as shown in Figure 3-109. Save the changes.

Figure 3-109 Action list for SignOn

3.4.10 Deploying and testing the credential-enabled HATS portletIn this section, we export and deploy the HATSPortlet application to the portal server. The we create and add a portal page named HATSPortlet to the portal page HATS Portlet Testing.

Follow the steps in 3.3.3, “Deploying the HATS portlet on WebSphere Portal Server” on page 205, to export and deploy the HATSPortlet application on the portal server.

Then follow steps 5 on page 212 through 8 on page 213, and steps 1 on page 214 through 4 on page 217 to create and add a new page named HATSPortlet to the HATS Portlet Testing page. Finally, add the HATSPortlet portlet to this new page.


When we click the HATSPortlet page, our HATSPortlet application runs smoothly as shown in Figure 3-110. You do not need to enter your user name and password in the AS/400 logon menu any more. Our HATSPortlet handles all logon details for you. The HATS portlet proceeds to the main menu screen automatically.

Figure 3-110 HATSPortlet final page

3.5 Administration for a HATS portletWhen creating a HATS portlet project, we can specify if the portlet project includes HATS administration support, or we can create a separate portlet for HATS administration.


3.5.1 HATS administration support included in the HATS portletAfter we add administration support to the HATS project, we can install the HATS portlet project in either of the following ways:

� On a portal server via the normal portlet installation process

In this case, the portal server automatically creates the Web context root for HATS administration. We must examine either the WebSphere Administration Server Administrative Console or the file system to discover the context root of the HATS project EAR file. We then append the context root to assemble the HATS admin URL.

� As a separate J2EE EAR file on WebSphere Application Server on which the portal server is running

For our scenario, we looked in the portal server installation directory and found the application.xml file for our portlet application. The directory location and file name are C:\WebSphere\PortalServer\installedApps\HATSPortlet_PA_1_0_M0.ear\META-INF\application.xml. Example 3-3 lists the contents of the application.xml file.

Example 3-3 HATSPortlet application.xml file

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd">

<application id="Application_ID"> <display-name>HATSPortlet_war</display-name> <module id="WebModule_1067658320531"> <web> <web-uri>HATSPortlet.war</web-uri> <context-root>/wps/PA_1_0_M0</context-root> </web> </module> </application>

We know that the HATS admin URL assembling rule is:

http://host:port/appname/hatsadmin/admin

Note the following explanation:

� host is your host name

� port is the port number of the HTTP transport of the application server on which the HATS application is running


� appname is the name of a HATS application that includes administration support

We assembled an admin URL for our example HATS portlet as:

http://9.24.105.124/wps/PA_1_0_M0/hatsadmin/admin

We opened an Internet Explorer window to access this URL. We received the result shown in Figure 3-111, which is the HATS Administrative Console.

Figure 3-111 HATS portlet administration page

3.5.2 Stand-alone HATS administration portletCreate a stand-alone HATS administration project in HATS Studio:

1. Select File →New →Project →Host Access Transformation Services →HATS Administration Project. The HATS Administration project appears only in HATS Studio on the Navigator panel.

Note: Port is not needed if URL requests are directed to a Web server configured for WebSphere.


2. Deploy the .EAR file that you created to the WebSphere Application Server console for the portal server http://portalhostname:9091/admin. Make sure it is installed to the portal server. Perform the Web server plug-in regeneration.

3. On the portal server administrative console, select Server →Portal Server. Look for BOOTSTRAP_ADDRESS End Point for the portal server. The default is 9810.

4. Open the HATS administration console:

http://portalhostname/adminprojectname/hatsadmin/admin

5. In the left pane, select Manage Scope. Add new node Portalhostname 9810.

3.6 HATS portal support advanced topicsThe following topics are of interest to experienced portal users.

3.6.1 Converting a JSP fileHATS Studio adds a new function to support conversion of a normal JSP file to a portletized version. This function helps a user to copy a JSP file from a non-portlet project into the HATS portlet project.

The new menu item, Convert JSP for Portal, was added to the HATS Project View context menu, which is available only for JSP files. It invokes the conversion logic that is used when converting a HATS project for portlet usage. There is no window for this action since it only requires one step. You can apply it to multiple JSP files at one time if multiple items are selected in the tree view.

Figure 3-112 shows the menu Convert JSP for Portal menu option.

Note: This item appears only if the WebSphere Portal Toolkit is installed in the WebSphere Studio. It does not affect files that are converted already.

Figure 3-112 Convert JSP for Portal menu option


3.6.2 Extending the HATS portlet functionWe can add functions to the HATS portlet by extending the EntryPortlet. For details, see Chapter 9 in IBM WebSphere Host Access Transformation Services (HATS) V5 Programmer’s Guide, SC31-6576.

3.6.3 More portal integration supportYou can use more portal functions for HATS portlet development such as portlet messaging and cooperative portlets. You can create sample portal integration code inside HATS Business Logic using the GUI support shown in Figure 3-113. For more details, see Chapter 9 in IBM WebSphere Host Access Transformation Services (HATS) V5 Programmer’s Guide, SC31-6576.

Figure 3-113 Portlet integration sample


The sample method interface and functions are:

� setUserCredential method

setUserCredential(BusinessLogicInfo blInfo, String slotID, String userID, String password, String host, String application)

Function: Stores a user ID and password in the credential vault in a userPasswordPassiveCredential so it can be persisted and retrieved later in Business Logic or in the Credential Vault Web Express Logon (WEL) plug-in.

� getUserCredential method

String[] getUserCredential(BusinessLogicInfo blInfo, String slotID, String host, String application)

Function: Retrieves a UserPasswordPassiveCredential from the credential vault so authentication information can be used in a macro to log into a host system.

� broadcastPortletMessage method

broadcastPortletMessage(BusinessLogicInfo blInfo, String contents)

Function: Sends a string out as a portlet message to all portlets sharing the portal page.

� sendPortletMessage method

sendPortletMessage(BusinessLogicInfo blInfo, String target, String contents)

Function: Sends a string out as a portlet message to another portlet on the portal page.

� registerProducedProperties method

registerProducedProperties(BusinessLogicInfo blInfo, String[ ] names)

Function: Registers the application so that it can publish the named list of global variables as property broker properties.

Note: If the business logic includes this method, add an execute business logic action to the prepresentation block.

Note: If the business logic includes this method, add an execute business logic action to the prepresentation block.


� registerConsumedProperties method

registerConsumedProperties(BusinessLogicInfo blInfo, String[] names)

Function: Registers the application so that it can listen for changes to the property broker properties corresponding to the named list of global variables.

� registerProperties method

registerProperties(BusinessLogicInfo blInfo, String[] names, int direction)

Function: Registers this application's set of properties and whether they are produced or consumed.

� publishPortletProperty method

publishPortletProperty(BusinessLogicInfo blInfo, String name, boolean shared) {

Function: Publishes a HATS Global Variable to the Portlet PropertyBroker service.

Prepresentation blocks and block actionsWe know that, if an application runs in portal environment, it may involve some application cooperative or application integration situation. WebSphere Portal supports these requirements by providing portlet messaging and cooperative portlet support. That is one portlet may invoke or trigger another portlet behavior.

If we configure actions for HATS events in which a HATS portlet may interact with other portlet applications, we must use more care when defining HATS actions. Some actions may affect HATS portlet rendering. In HATS V5, we may need to split actions into prepresentation and presentation blocks to avoid affecting the rendering process. Figure 3-114 shows the GUI support in HATS Studio.

Important: For the publishPortletProperty, sendPortletMessage, broadcastPortletMessage methods, you must invoke them from a prepresentation block. If the business logic includes these methods, add an execute business logic action to the prepresentation block.


Figure 3-114 Block action

When the portal page is posted back to the server, and if the next action is a block action, the portlet continues executing in the actionPerformed phase. If the portlet doesn’t see the block action, the portlet immediately terminates and the HATS action list continues from the doView phase.

In Example 3-4, HATS runtime attempts to execute MyLogic in the prepresentation processor in the entry portlet if it arrives at the event while still in that state. After the transform is submitted, it executes MyLogic2 in the prepresentation method. The successor to this action can begin with prepresentation code.

Example 3-4 Block action list example

<actions> <block enabled="true"/> <execute class="MyLogic" enabled="true" method="execute" package=""/> <block enabled="true"/> <apply enabled="true" immediateKeyset="" template="" transformation="OfficeTasks.jsp"/> <block enabled="true"/> <execute class="MyLogic2" enabled="true" method="execute" package=""/> <block enabled="true"/> </actions>


Chapter 4. Using Web Express Logon with HATS portlets

This chapter discusses a new feature called Web Express Logon (WEL) in IBM WebSphere Host Access Transformation Services (HATS) V5. WEL provides a new mechanism to simplify the host application logon process. It also provides credentials to the host application automatically.

4


4.1 Web Express Logon overviewIn a typical IT environment, many applications run in an enterprise environment. Simplifying the signon processes to different applications is a basic requirement for IT. Many different products or applications are available to address the issue at the network security layer. There does not seem to be a single solution that works in all circumstances.

Web Express Logon is the approach from HATS to enable end-user access to host applications and systems without providing security credentials explicitly. HATS Web Express Logon works in conjunction with your company’s network security application to maintain company security. At the same time, it allows users to log on to host systems without re-entering user IDs and passwords.

4.2 Getting started with Web Express LogonThis section provides the information you need to understand the HATS Web Express Logon function, its application process flow, and configuration steps. Then, we describe a hands-on scenario in 4.3, “Using Web Express Logon portal scenario” on page 295. In addition, we provide an advanced discussion in 4.4, “Web Express Logon advanced topics” on page 325.

4.2.1 Web Express Logon backgroundAs the typical corporation has evolved their proprietary, dedicated computing environment to a standards-based, distributed model, the issue of security and security management has become a top priority. Many systems can solve the security issue. But as long as there are two environments of different technologies in the workplace, there is not one all-inclusive solution.

Because of this division of technologies, there are duplications of the authentication and authorization process. This duplication causes a problem for many enterprises. Their users are forced to provide credentials multiple times during the work day. They are looking for a solution that can relieve their users of the repetitive task of identifying themselves multiple times.

An example scenario for the problem is as follows:

1. A user turns on a computer and logs into the operating system.

2. The user connects to a corporate or team home page.

3. The user connects to a Web-based accounting application and performs necessary work.


4. The user now needs to perform a Human Resources (HR) task. The HR application is host-based and may have been deployed to the company’s intranet via a HATS application.

5. The user loads the HATS application to connect to the host system and performs the desired tasks.

In each of these steps, it is possible that the user is required to provide credentials (user ID and password, or a certificate of some type). Some products and practices can provide a single signon (SSO) solution for steps 1, 2 and 3, but a portion of step 4 and all of step 5 are out of their target domain.

The term single signon is used frequently by marketing literature and product documentation. It has many definitions, each depending on the context of its application.

HATS Web Express Logon provides user access to host resources by automated retrieval of the required security credentials. In this specific use, it’s a HATS feature to avoid confusion with broader SSO solutions in the marketplace. The specific ability to access host systems and host applications without providing additional security credentials is the key feature for HATS Web Express Logon.

4.2.2 Network security layerMany companies with many different products are addressing the issue of network security. We have yet to find a single solution that handles all circumstances.

Because of this, the responsibility for obtaining authenticated user credentials falls outside of the control of HATS Web Express Logon. A flexible approach, HATS Web Express Logon can work with the customer’s chosen network security package. It does not try to duplicate the function of the network security layer.

Prior to Web Express Logon establishing user access to the host, an assumption is made that the users’ credentials are already acquired via the network security layer, and HATS is simply passing the mapped host credential to the host.

Network security applications typically provide the ability to manage users and policies. Users are created and assigned to groups that are governed by the policies assigned to them. These policies map what network resources are available to the users and how the user is to be identified (credential acquisition).

4.2.3 Application environmentAs an objective, Web Express Logon should ask the user only one time for their credentials. Since Web Express Logon requires several steps, it is important to

Chapter 4. Using Web Express Logon with HATS portlets 291

note that many of the required steps fall outside of the control of HATS. For HATS applications, HATS Web Express Logon acts as the glue that pulls together all of the participants and unifies the process. Table 4-1 lists the possible applications involved in a typical Web Express Logon procedure.

Table 4-1 Application environment

Any of the products identified in Table 4-1 can be replaced in the equation by another comparable product. Therefore, in place of Tivoli Access Manager, a customer may use the Netegrity SiteMinder product.

4.2.4 HATS Web Express Logon processHATS Web Express Logon follows this process:

1. The network security layer performs authentication.

In an environment where a system-wide network security management application is in place, authentication by the network security application happens first. This may take place when the user logs on to their workstation, or when they initially access some network resource. The actual mechanisms used for credential acquisition vary by network security application vendor. For Web Express Logon, the credentials acquired at this time are referred to by the term WebID. This is not an industry-standard term for user credentials, but rather a way to distinguish between types of credentials.

2. Access the HATS application.

After the WebID is acquired, the user is granted access to a number of network resources. One of these resources, it is understood, is a Web page that contains a link to a HATS application.

Application Typical product

Browser Internet Explorer

Web server IBM HTTP Server

Web application server WebSphere Application Server

Host CICS, TSO, etc....

Host security RACF®

Network security Tivoli® Access Manager

Database server DB2


3. Start a host connection.

When the HATS application is selected by the user, either as a transformation connection or an Integration Object (IO) driven request, a back-end host connection can be started that requires a logon process.

4. Begin a credential mapper.

To automate the login, HATS must provide the host with the user’s credentials, without prompting the user to provide the information. The only user-specific information available at the time the automated login process is started is the WebID. As described earlier, WebID is the credentials provided by the user through the network security layer when initially connected to the network. Using the WebID as a key, HATS must perform a lookup to acquire the user’s host credentials. We call this process the credential mapper or Host Credentials Bind. The actual mechanics of what occurs during this procedure vary greatly depending on the customer’s infrastructure.

We break down the Host Credentials Bind process into two areas of responsibility:

– The interface to communicate with the network security application

This interface provides Web Express Logon the ability to acquire the WebID when needed. You access this interface through the network security plug-in component.

– The mechanism that takes the WebID and retrieves the host credentials

You access this interface by the credential mapper plug-in component. The implementation of a credential mapper varies by host and host type. There may be one or more credential mappers in use by a customer depending on the nature of where they store host credentials.

5. Automate the host logon process.

Here the user is normally prompted by the host to provide a user ID and password. This information is referred to by Web Express Logon as the HostID. Through the credential mapper, HATS allows for user-specific host credentials to be used for logon automatically.

4.2.5 Web Express Logon example scenarioThis section provides an example of Web Express Logon for a z/OS application. Figure 4-1 shows the process flow as explained here:

1. The HATS user, in a browser window, makes a Secured Hypertext Transfer Protocol (HTTPS) GET request of the Entry Servlet to start a HATS application. HTTPS is not strictly required at this step, but the credential mapper plug-ins in most cases retrieve information from the request object, which is only stored when using HTTPS.


2. The network security layer validates the user the first time through. It attaches header information to the HTTPS request, which identifies the validated user.

3. The HATS entry servlet requests a connection in the appropriate pool from the pool or connection manager.

4. The connection manager discovers that this is a Web Express Logon connection. In the process of running the logon macro, it processes a custom macro event (using the <custom> macro tag), which sets the application ID, and a prompt event looking for host credentials. The connection manager calls the credential mapper with a request for those credentials. All requests made of the credential mapper include the parameters: host application ID, host destination, and authentication type.

5. The credential mapper servlet acquires the WebID (user credentials) of the requestor through a call to the configured Network Security Application Plug-in. The WebID is contained in a CMResponse object returned by the plug-in. The parameters supplied on the request are combined with a CMResponse (WebID) object to construct a second CMRequest object.

Figure 4-1 Web Express Logon: Servlet, DCAS, z/OS

HATS Entry Servlet

ConnectionManagerAPP

Config

CredentialMapper

Network Security Plugin

Credential Mapping Plugin

HATS Application .EAR Runtime

WebSphere Application Server

Web Server

Network Security Layer

z/OS

HostAPP

RACF

DCAS

ClientBrowser

HATS StudioToolkit

TNServer

1

2 3

4

5

6

8

7

9


6. Based on the criteria contained in the CMRequest object, the credential mapper determine the most suitable credential mapper plug-in to handle the request. After the proper credential mapper (plug-in) is chosen, it is given the request via the credential mapper interface API. The plug-in is then responsible for mapping the WebID to the Host ID and passticket.

7. The credential mapper plug-in processes the request and returns the results in another CMResponse object (this one returns the HostID information). In this example, the host credentials are retrieved from Digital Certificate Access Server (DCAS).

8. Credential mapper takes the results stored in the CMResponse object and returns the host credentials to the HATS connection manager.

9. HATS connection manager, processing the logon macro, answers the prompt event with the retrieved host credentials and proceeds with the logon sequence to the TN server.

4.2.6 Web Express Logon configuration processAfter you obtain the information to set up Web Express Logon, you must complete these steps:

1. Configure the connections in your HATS project for Web Express Logon.

2. Configure Web Express Logon:

a. Identify the network security plug-in to be used, and specify any initialization parameters.

b. Identify the credential mapper plug-ins to be used, the criteria for selecting each one, and the initialization parameters for each one. Order them optimally based on their selection criteria.

3. Configure any required key-ring database files needed to connect to back-end credential sources such as DCAS.

4. Record macros that include prompts for user ID and password to trigger Web Express Logon processing.

5. Trigger the macros at appropriate times in the HATS project (for example, the connection’s connect macro).

4.3 Using Web Express Logon portal scenarioIn this section, we create an end-to-end scenario to show the HATS Web Express Logon feature in action. We create a Web Express Logon-enabled HATS portlet. This portlet uses WebSphere Portal credential vault service as the


Web Express Logon host credential storage. In addition, it uses the Web Express Logon portal credential mapper to access the host credential.

4.3.1 Scenario overviewThe scenario hardware topology is the same as the HATS portal integration scenario shown in Figure 3-3 on page 193. The software environment is shown in Table 3-1 on page 194.

The objective of this scenario is to make a HATS portlet that can automatically log on to an AS/400 using the HATS V5 Web Express Logon feature.

Application processThe application follows this process:

1. A user-written portlet sets a user name and password pair to a portal credential vault slot.

2. A HATS portlet is running and connects to an AS/400 system. This portlet is configured with Web Express Logon support.

3. The HATS Web Express Logon component—portal credential mapper plug-in—parses the portal credential vault slot to access the host user name and password.

4. The logon macro logs on to the AS/400 host system using the Web Express Logon user name and password.

5. The AS/400 system Main Menu is displayed.

Configuration processFor the configuration, follow these steps:

1. Create a HATS portlet project named HATS_WEL.

2. Enable and configure the Web Express Logon for the HATS_WEL project.

3. Record a logon macro and configure the Web Express Logon for it.

4. Configure the connection in the HATS_WEL project to use the logon macro.

5. Export the portlet and deploy it to the portal server.

6. Prepare a user created portlet to populate the credential vault, which is used by the HATS_WEL portlet.

7. Test the HATS_WEL portlet.


4.3.2 Creating a HATS portlet project to use Web Express LogonTo create a HATS portlet project, follow the instructions and steps in 3.4.4, “Creating the HATS credential integration portlet” on page 238. We name the project HATS_WEL. After we create the project, we see the HATS Studio project view as shown in Figure 4-2.

Figure 4-2 HATS project view

4.3.3 Configuring Web Express Logon in a HATS projectIn this section, we enable and configure Web Express Logon for our HATS_WEL project. This differs from the normal Web Express Logon process, when using WEL together with portal server credential service. We need to configure only the credential mapper plug-in for Web Express Logon. We do not need to configure a network security provider plug-in.


1. Continuing from the previous section, in the HATS Project View, select HATS_WEL →Connections. Double-click main (default). In the right pane, click the Security tab. In the Security pane, select the Use Web Express Logon option as shown in Figure 4-3. Then click the Configure button.

Figure 4-3 Enable Web Express Logon for HATS project


2. The edit view (Figure 4-4) for Web Express Logon opens. Click Credential Mapper Plugins to switch to the Credential Mapper Plugins view.

Figure 4-4 Web Express Logon editor

3. In the Credential Mapper Plugins view (Figure 4-5), click Add to add credential mapper configurations.

Figure 4-5 Credential Mapper Plugins view


4. In the Add Credential Mapper Plugin window (Figure 4-6), select Add built-in Credential Mapper plugin. From the list, select WebSphere Portal Credential Vault Credential Mapper. Click OK.

Figure 4-6 Add Credential Mapper Plugin window

5. In the Credential Mapper Selection editor view (Figure 4-7), set Authentication type as AuthType_5250HOST, and Host mask as *.

Figure 4-7 Setting authorization type and host mask

6. Under Details (Figure 4-8), set the SLOT_ID and SLOT_TYPE initialization parameters. Credential mapper uses these values and other parameters to assemble the credential slot name in the portal server. For our scenario, for SLOT-ID, we specify the value myHATSVault. For SLOT_TYPE, we leave a default value of 2.


Figure 4-8 Setting the initialize parameter

7. Press Ctrl+S to save the changes and close the editor window.

4.3.4 Recording a logon macro with Web Express Logon supportIn this section, we record a logon macro enabled for Web Express Logon.

1. Follow steps 1 and 2 on page 242 in 3.4.5, “Creating a screen customization for the logon screen” on page 241, to open the HATS terminal window.

Before you record a logon macro, open another AS/400 logon session using a traditional terminal emulator such as IBM Personal Communications. We log on to the AS/400 system where we record the macro by using the terminal emulator.

Note: The SLOT_TYPE parameter indicates the type of portal credential slot you want to access. Valid values are:

0 - Private slot1 - Shared slot2 - Administrative Slot (default value)3 - System slot

For descriptions of the different types of slots, see IBM WebSphere Portal V4 Developer’s Handbook, SG24-6897.


2. In the Host Terminal window (Figure 4-9), click the Record Macro button to begin recording.

Figure 4-9 Clicking the Record Macro button

3. In the Record Macro wizard (Figure 4-10), enter the macro name as any name you want. We keep the default value and click Finish.

Figure 4-10 Naming the macro

Note: Here, make sure that the logon macro includes a transient screen, which displays a program message.


4. The Define Screen Recognition Criteria – Define the starting screen of the macro window (Figure 4-11) opens. Complete these steps:

a. Change the Screen Name to Sign On Screen. b. Click and drag to draw a rectangular region. c. Under String position, select At a specific position. d. Click Finish to complete the definition of the starting screen.

Figure 4-11 Defining a starting screen of the macro


5. In the Host Terminal window (Figure 4-12), make sure that the cursor is at the same location as shown in the Sign On display. Then click the Add Prompt Action button in the toolbar.

Figure 4-12 Clicking the Add Prompt Action button


6. In the Add Prompt Action window (Figure 4-13), complete these steps:

a. For Name, type setUID. b. For Default value, type uid. c. Under Handle Macro Prompt, select Use Web Express Logon. d. For Prompt type, select User ID. e. Click OK to add this action.

Figure 4-13 Add Prompt Action for User ID

7. Return to the HATS terminal screen. Enter user4boats. The cursor moves to the Password input field in the terminal window.


8. Add another prompt action. Repeat step 5 on page 304. This time, set the cursor in the Password field shown in Figure 4-12 on page 304. In the Add Prompt Action window (Figure 4-14), complete these tasks:

a. For Name, type setPWD.b. For Default value, type pwd. c. Under Handle Macro Prompt, select Use Web Express Logon.d. For Prompt type, select Password. e. Click OK to add this action.

Figure 4-14 Add Prompt Action for password

9. You return to the HATS terminal screen. Now enter password. Press the Tab key. The cursor moves to the Program/procedure input field in terminal window. Press Enter to log on.


10.You see an AS/400 program message screen (Figure 4-15) in the HATS terminal since with the same user name is already logged on another session. Verify the contents in the Macro Navigator pane with yours.

Figure 4-15 Enter program message screen

11.Click the Define Screen Recognition Criteria button in the toolbar as shown in Figure 4-16.



12.The Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 4-17) opens. Follow these steps:

a. For Screen Name, type Message Screen. b. Click and drag to draw a rectangular region. c. Select This is a transient screen. d. Under String position, select At a specified position. e. Click Finish to complete the screen definition.

Figure 4-17 Define program message screen criteria

13.In the HATS terminal window, press Enter to continue the macro to the next screen.


14.You arrive at the AS/400 Main Menu screen. Click the Define Screen Recognition Criteria icon in the toolbar as shown in Figure 4-18.


15.In the Define Screen Recognition Criteria – Select Screen Recognition Criteria window (Figure 4-19), follow these steps:

a. For Screen Name, type Main Menu. b. Click and drag to draw a rectangular region. c. Under String position, select At a specified position. d. Click Finish to complete the screen definition.

Figure 4-19 Defining the criteria for the Main Menu screen


16.In the Host Terminal window (Figure 4-20), click the Stop Macro button to end the macro recording.

Figure 4-20 Clicking the Stop Macro button

17.In the HATS terminal window Macro Navigator view, select some useless actions captured during recording as shown in the example on the left. Press the Delete key to remove these items. Then the macro should appear as shown in the example on the right.

Figure 4-21 Removing useless actions in the macro

18.In Host Terminal, click the Save Macro button to save the macro and close the window. We are finished recording the logon macro.

Figure 4-22 Save macro

It’s a good practice to test the macro after you create it. You need to verify if it works as we expected. For our scenario, the macro we created is simple.

Before

After


However you may need to add some error handling paths to this macro. See 3.4.8, “Enhancing the signon macro with multi-process path support” on page 261, for detailed testing and enhancing instructions.

4.3.5 Configuring a HATS project to use the logon macroAfter you create the logon macro, configure it to be used in the Web Express Logon project.

In the HATS Studio Project View (Figure 4-23), select HAT_WEL →Connections. Double-click main (default). On the right side, click the Macros tab. In the Macros pane, for Connect macro, select SignOn. Press Ctrl+S to save your changes.

Figure 4-23 Configuring the connect macro

4.3.6 Deploying the Web Express Logon enabled portletIn this section, we export and deploy the HATS_WEL application on the portal server. Then we create and add a portal page named Web Express Logon to a portal page HATS Portlet Testing.


Follow the steps in 3.3.3, “Deploying the HATS portlet on WebSphere Portal Server” on page 205, to export and deploy the HATS_WEL application on the portal server. Then follow steps 5 on page 212 through 8 on page 213 in 3.3.4, “Testing the HATS portlet” on page 210, to create and add a new page named Web Express Logon to the HATS Portlet Testing page. Then, add the portlet HATS_WEL to the Web Express Logon page.

4.3.7 Preparing the portal Credential Vault Populate Portlet for Web Express Logon

In this section, we create a portlet to populate the portal credential vault used by the HATS_WEL application. Since we created a portal credential portlet in 3.4.2, “Building the Credential Vault Populate portlet” on page 222, we clone a copy of it and then modify it for Web Express Logon.

1. Log on to the portal using the Portal administrator user ID. Change the portal page to the administration page.

2. Click Portlets →Manage Portlets. In the right side of the Manage Portlets pane (Figure 4-24), in the Search for portlets field, type HATS and click Go.

Figure 4-24 Searching for the HATS_WEL portlet


3. Select the HATSCredential portlet and click Copy as shown in Figure 4-25.

Figure 4-25 Copying the HATSCredential portlet

4. We see a cloned copy of the HATSCredential portlet (Figure 4-26). By default, this copy is inactive and contains the same configuration parameters as the parent copy. Select the cloned portlet. Click Modify parameters.

Figure 4-26 Modifying the parameters for the cloned portlet


5. Change VaultSlotName to myHATSVault iseriesd.dfw.ibm.com .

See step 3 on page 251 in 3.4.6, “Creating the credential vault business logic Java method” on page 249, for the slot name assembling rule. For our scenario, the application name is null.

Figure 4-27 Changing the slot name

Note: There is a space after iseriesd.dfw.ibm.com. Be sure to include the space.


6. Click Save to save your changes to the parameters.

Figure 4-28 Saving the changes


7. Select English as the locale title.

Figure 4-29 Selecting the English as the title locale

8. Click the Set title for selected locale button to set the title for the cloned portlet as shown in Figure 4-30.

Figure 4-30 Setting the title for the portlet


9. Change the portlet title to any name you want. The objective is to set a different title for the cloned portlet to distinguish it from its parents. For our scenario, we change the English field to HATSCredential portlet for WEL.

Figure 4-31 Changing the portlet title

10.Click Save button to save the changes. Then click Cancel to return to Manage Portlets page.

Figure 4-32 Saving the changes


11.Select the cloned portlet. Now it is named HATSCredential portlet for WEL. Click the Activate/Deactive button to activate it.

Figure 4-33 Making the cloned portlet active

12.Switch to Manage Pages. Click Portal User Interface →Manage Pages. Then click My Portal →HATS Portlet Testing as shown in Figure 4-34. Click the Edit button to edit the page layout for HATS Portlet Testing.

Figure 4-34 Editing the page layout for the portlet testing page


13.In the right pane of the Edit Layout page, click Add portlets.

Figure 4-35 Adding a portlet to the page


14.In the Search for field, type HATS to search for the credential portlet. In the search result list, select the cloned version HATSCredential portlet for WEL. Click OK to confirm the selection.

Figure 4-36 Selecting the portlet


15.We see the portal page displayed (Figure 4-37). Click Done to confirm.

Figure 4-37 Completing the add portlet task

16.Select Access →Credential Vault. Click Add a vault slot to add a credential vault slot (Figure 4-38).

Figure 4-38 Selecting the Add a vault slot option


17.In the Create a vault slot page, for Name, type myHATSVault iseriesd.dfw.ibm.com .

Leave the other default values and click OK to create a slot.

Figure 4-39 Creating a vault slot

Note: There is a space after iseriesd.dfw.ibm.com. Be sure to include the space.

Important: HATS V5 supports the background connection function. For the credential vault to work correctly with Web Express Logon, you must define a different vault resource to be associated with the vault slot for each host connection.


18.Switch to HATS Portlet Testing page. Click the Edit button on the HATSCredential portlet for WEL portlet.

19.The Edit panel (Figure 4-40) is displayed. Set the values for user ID and password. Click Save.

Figure 4-40 HATS Portlet Testing page


You return to the normal portal page (Figure 4-41).

Figure 4-41 Final populate portlet page


4.3.8 Testing the HATS_WEL portletSwitch to the Web Express Logon page. Our HATS_WEL application runs smoothly as shown in Figure 4-42. You do not need to enter your user name and password. HATS Web Express Logon does it for you automatically.

Figure 4-42 HATS_WEL final page

4.4 Web Express Logon advanced topicsIn this section, we discuss the credential mapper—the core component of Web Express Logon. We also discuss its two sub-components: network security provider plug-in and credential mapper plug-in.


4.4.1 Credential mapperThe core of the Web Express Logon is the credential mapper. It determines the caller’s WebID, matches the request to the best credential mapper plug-in, and returns the needed HostID.

For each running instance of the credential mapper, one-to-many credential mapper plug-ins may be made available, but only one network security plug-in is allowed.

See Figure 4-43 for the credential mapper workflow as explained here:

1. The credential mapper requests the network security plug-in to provide user credentials.

2. The network security plug-in retrieves the WebID from security provider context and provides it to the credential mapper.

3. The credential mapper finds a suitable credential mapper plug-in to which to send a request.

4. The request arrives at the credential mapper plug-in to do the mapping.

5. The credential mapper plug-in gets the HostID or passticket and returns it to credential mapper.

Figure 4-43 Credential mapper workflow

4.4.2 Network security provider plug-inWe show an example in Figure 4-44. Suppose we use Tivoli Access Manager as the network security provider application. Tivoli Access Manager provides a policy-based access control solution for e-business and enterprise applications.

Credential Mapper

NetworkSecurityPlugin

51

CredentialMapperPlugin

2

CMRequest WebID

Select4

3

CMRequestHostID /Passticket


HATS provides a plug-in for Tivoli Access Manager. This plug-in can access the user ID from a special HTTP Header, which is set by Tivoli Access Manager.

Figure 4-44 Network security plug-in for Tivoli Access Manager

For more information about network security plug-ins, see Chapter 15 in IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575.

4.4.3 Credential mapper plug-inThe credential mapper plug-in accesses a back-end repository that maps users’ network IDs to their host IDs. The repository can be a Java Database Connection (JDBC) database such as IBM DB2 Universal Database. The Digital Certificate Access Server and Vault plug-ins provided with Web Express Logon are designed to work with such a database. Another possibility for a repository is an Lightweight Directory Access Protocol (LDAP) directory.

Credential Mapper

Network Security Plugin

CMRequest WebID

WebID get from Tivoli Access Manager


We give a JDBC plug-in example as shown in Figure 4-45.

Figure 4-45 JDBC credential mapper plug-in

This credential mapper plug-in is designed to potentially be a repository of all host-based credentials for all users of the system. For each WebID, a set of host credentials exists for each host to be used in the Web Express Logon environment. The method to be used for storage is a JDBC-accessible database.

This work is to be done using JDBC and a customer specified database. The use of a network accessible database for this function should provide customers a flexible and secure means of associating a user’s WebID to the desired HostID. It is possible for the customer to configure access to an existing database or point to a newly created one. Security of the database depends on the database package and its safeguards. Some parameters are needed to support this item. For details about the configuration parameters, see chapter 15, IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575.

Based on the information provided by the parameters, an SQL query can be made of the database to get the host id. The query will use the WebID, Host Address and Host Application as keys for the query. The result will be a HostID and passticket or password.

Credential Mapper

JDBC PluginSelect

CMRequest

HostID /Passticket

(containsWebID)

Map WebID to HostIDand passticket

Return results

Customer provideddatabase

WebID

HostID /Passticket


Chapter 5. Deploying applications in WebSphere Application Server V5

This chapter discusses the process of deploying a IBM WebSphere Host Access Transformation Services (HATS) V5 application to WebSphere Application Server V5. We discuss the following topics:

� Introduction to HATS administration� Deploying an application� Testing

5


5.1 Introduction to HATS AdministrationThere are many new functions in HATS V5 Administration as a result of integration with WebSphere Host Publisher.

When you create a HATS application, you can select the creation of an administration environment by selecting Add administration support. This administration support is acceptable if you require only one or a few HATS projects. If you require many HATS projects, you do not need to create one administration environment per project. Therefore, you should deselect Add administration support. In this situation, the best approach is to generate the administration environment as a separate HATS project. Using the centralized administration console, you can administer any enterprise application deployed on any application server in the same cell.

The HATS Administration project environment allows administration personnel to perform different actions on multiple HATS projects from one browser console. For example, administrators can:

� Select the management scope� Manage licenses� Monitor connections� Monitor connection pools� Monitor pool definitions� Monitor user lists and user list members� Perform problem determination

This chapter describes one entire deployment process from the developer environment to the production server. It does not explain the details of all the administration features. For more information, see IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575.

5.2 Deploying a HATS applicationIn this scenario, we use three machines. The first one is the developer environment, the second is the server environment, and the third machine is the AS/400e server that contains the host data used to extract information. For more information about the server and software configuration, refer to 2.1, “Environment” on page 72.

Figure 5-1 shows an overview of this environment.



We use the HATS application that we developed for the AS/400 system in 2.2, “Integrating HATS with a database application” on page 75. The name of the application is ox_db (project name).



IBM Eserver pSeries

AIX V5.3

IBM Eserver zSeries

CICSApplication

Intranet

IBM Eserver xSeries


V5.02 IBM Eserver

xSeries


ServerV5.02

IBM Eserver

xSeries

WebSphereStudio



Services V5

Portal plug-in

Chapter 5. Deploying applications in WebSphere Application Server V5 331

1. Go to the HATS developer environment. In the HATS Project View (Figure 5-2), select ox_db, right-click, and select Assemble HATS Project.

Figure 5-2 Creating an EAR file


2. In the Export – EAR Export window (Figure 5-3), define where to create the assembled EAR file. For this example, we share the server hard drive as x:. The destination folder is x:\WebSphere\AppServer\InstallableApps\. Click Finish.

Figure 5-3 EAR destination


3. Add the JT400.jar file used in the creation of the database application. Before you install the EAR file in WebSphere Application Server, add the JT400.jar file to the WAR Classpath.

a. Go to your server environment and open a command line editor.

b. Change to the directory c:\WebSphere\AppServer\bin and type assembly to open the Application Assembly Tool (AAT).

The AAT is used when you need to work with Web Archive (WAR), client, and Enterprise Archive (EAR) files, add a new classpath, change the welcome file, add more resources, and so on. For more information about the AAT, see:

http://www.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/06060005.html

c. In a few seconds, you see the AAT environment. In the first window presented by AAT, you have the option to open an existing EAR file.

i. In the Welcome to Application Assembly Tool window, click the Existing tab.

ii. On the Existing page (Figure 5-4), click the Browser button. Select the ox_db.ear file. Click OK.

Figure 5-4 Application Assembly Tool



d. After the AAT presents the EAR information, select ox_db → Web Modules. In the right pane, you see all the properties and configuration options for the Web Modules scope.

e. Click the General tab. In the Classpath option, add the c:\jt400.jar (your classpath) file at the end of the Classpath definition. Click Apply and then save the modification.

Figure 5-5 Adding jar files using AAT

f. Close the AAT. The EAR file is now ready to deploy in a production environment.


4. If you have not started the WebSphere Application Server, go to your server environment and open a command line editor. Change to the directory c:\WebSphere\AppServer\bin and type startserver server1 (use your instance name). See Figure 5-6.

5. Wait to see the server1 open for e-business message, meaning that the application server started.

Figure 5-6 Starting the application server

6. Start the administration interface:

a. Open a browser and type:

http://server IP address:9090/admin

server IP address is in the form of 9.x.x.x or your server’s host name.

b. In a few seconds, you see the administration environment. For User ID, type admin and click OK. In our example, we do not have the security feature running. We can use any value for user ID and just press Enter or click OK without completing the User ID value.

Figure 5-7 Administration login


7. The administration interface is displayed (Figure 5-8). Click Applications →Enterprise Applications to view all the applications in your instance. In the right panel, click Install.

Figure 5-8 Administration welcome


8. You are asked for the EAR path. Remember that in this example, we use the default c:\WebSphere\AppServer\InstallableApps\ directory, but you do not need to use the same directory.

Select Local path and click the Browse button. Select the ox_db.ear application. Click Next. See Figure 5-9.

Figure 5-9 Installing path

9. In the next panel (Figure 5-10), you must define general settings. Select Generate Default Bindings and leave the other values as default. Click Next.

Figure 5-10 General settings


10.In the Step 1: Provide options to perform the installation panel (Figure 5-11), do not change anything. Click Next.

Figure 5-11 Deployment options


11.In the Step 2: Map virtual hosts for Web modules panel (Figure 5-12), do not change anything. Since we use a default installation, the default virtual host is default_host. Click Next.

Figure 5-12 Virtual hosts for Web modules


12.In the Step 3: Map modules to application servers panel (Figure 5-13), you can define the scope of the application. WebSphere Application Server V5 allows you to run the same application on different servers at the same time. If you defined a cell, you can select the scope in this window.

For this example, do not change anything. Click Next. The scope for this application is the node and the instance is server1.

Figure 5-13 Mapping modules to application servers


13.In the Step 4: Map security roles for users/groups panel (Figure 5-14), you can define the groups or users who will act as an administrator, operator, and monitor for the HATS administration. For our example, click Next.

Figure 5-14 Security mapping


14.At this point, we finish deploying the application. The next window (Figure 5-15) shows Step 5: Summary of the installation options. Click Finish.

Figure 5-15 Summary


15.To finish the installation, click the Save to Master Configuration link (Figure 5-16). This commits the writing of the master configuration.

Figure 5-16 Installing EAR


16.In the Save to Master Configuration window (Figure 5-17), click Save. This completes the installation process.

Figure 5-17 Save view

After you finish the installation process, you must change the scope of the WAR Classloader Policy as we did in “Changing module visibility” on page 133.

In the creation of the application, we changed the module visibility in the WebSphere V5.0 Test Environment. Now we must set the same in the external WebSphere Application Server.


1. Select Applications →Enterprise Applications. In the right panel, select ox_db.ear as shown in Figure 5-18. Open the application.

Figure 5-18 EAR installed

2. You now see the configuration environment (Figure 5-19). You need only to change the module visibility. For WAR Classloader Policy, select Application. Click OK.

Figure 5-19 Classloader policy


3. Before you commit the change, the application server confirms the setting modification as shown in Figure 5-20. Click the Save link.

Figure 5-20 Save changes

4. In the Save to Master Configuration window (Figure 5-21), click Save. This completes the modification process.

Figure 5-21 Save view


We have now installed and configured the application. The last part is to start the application.

1. As shown in Figure 5-22, select Applications →Enterprise Applications. Select ox_db.ear and click the Start button.

Figure 5-22 Starting application

2. In a few seconds, you see the Status button in green. That means the application is up and running.

Figure 5-23 Application started

WebSphere Application Server V5 has embedded an internal Web server to be used in a development environment. You can use that environment if you do not have an external Web server to test the application. The default port is 9080.

Using an internal or external Web server, we must update the Web server with the new application because you are working in a WebSphere environment, not in a Web server definition.


1. To communicate with the Web server, select Environment →Update Web Server Plugin. In the right panel (Figure 5-24), click OK.

Figure 5-24 Updating the plugin

At the top of the same window (Figure 5-25), you see the Update Web server plugin configuration message.

Figure 5-25 Plug-in message

2. Restart your Web server.

This completes the installation process.

5.3 TestingAfter you complete the installation and configuration steps, you must test the application in a real environment using a browser.


1. Open a browser and type the URL:

http://server IP address/ox_db

Press Enter.

2. In the Sign on display (Figure 5-26), enter a valid user and password for your system and press Enter.

Figure 5-26 Application login


3. You now see the AS/400 Main Menu (Figure 5-27) where we developed a macro to navigate through the Main Menu to the Display Report window.

Click the AS_400MainMenu button to start the macro.

Figure 5-27 AS/400 Main Menu and starting the macro


4. During execution, the macro requires a value to pass to the database as a SELECT request. Type a valid productid value, in this case FI-SW-01, and click OK to continue. See Figure 5-28.

Figure 5-28 Macro input request


5. If the application is installed correctly, you see the Input Form of the database application with the CATID form completed by the business logic (BL) we developed previously. Remember that the business logic combines global variables and code inside the database input form to access the information from the session. See Figure 5-29. Click Submit to continue.

Figure 5-29 Database application

For more information, see Chapter 2, “Integrating HATS with business applications” on page 71.


6. Remember that we set the JT400.jar file using the Application Assembly Tool. Assuming that setting is correct, you see the result of the request as shown in Figure 5-30.

To complete the test, click Continue Application as shown in Figure 5-30. You should return to the AS/400 Main Menu screen as shown in Figure 5-27.

Figure 5-30 Database application view


acronyms

AAT Application Assembly Tool

API application programming interface

BL business logic

CICS Customer Information Control System

CM credential mapper

CPU central processing unit

CSS cascading style sheet

DCAS Digital Certificate Access Server

EAR enterprise archive

EJB Enterprise JavaBean

GUI graphical user interface

GV global variable

HATS Host Access Transformation Services

HR human resources

HTML hypertext markup language

HTTP Hypertext Transport Protocol

HTTPS Secure Hypertext Transport Protocol

IBM International Business Machines

IO Integration Object

IP Internet Protocol

IT information technology

ITSO International Technical Support Organization

JDBC Java Database Connector

JSP JavaServer Pages

LDAP Lightweight Directory Access Protocol

MQ Message Queueing

MVC Model-View-Control

QM query management

SOAP Simple Object Access Protocol

SQL Structured Query Language

SSO single signon

Abbreviations and

© Copyright IBM Corp. 2004. All rights reserved.

UDB Universal Database

UDDI Universal Description, Discover, and Integration

URL Universal Resource Locator

VT Virtual Terminal

WAR Web Archive

WAS WebSphere Application Server

WEL Web Express Logon

WSAD WebSphere Studio Application Developer

WSDL Web Services Description Language

XML Extensible Markup Language

355

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

IBM RedbooksFor information about ordering these publications, see “How to get IBM Redbooks” on page 359. Note that some of the documents referenced here may be available in softcopy only.

� Creating and Modifying HATS Projects, REDP-3698

� Host Access Transformation Server Concepts and Architecture, REDP-3706

� IBM WebSphere Portal for Multiplatforms V5 Handbook, SG24-6098

� Java and WebSphere Performance on IBM Eserver iSeries Servers, SG24-6256

� WebSphere Studio Application Developer Programming Guide, SG24-6585

� IBM WebSphere Portal V4 Developer’s Handbook, SG24-6897

� iSeries Access for Web and HATS Limited Edition: V5R2 Hot Topics for IBM Eserver iSeries Browser Users, SG24-7005

Other publicationsThese publications are also relevant as further information sources:

� IBM WebSphere Host Access Transformation Services (HATS) V5 Getting Started, SC31-6574

� IBM WebSphere Host Access Transformation Services (HATS) V5 User’s and Administrator’s Guide, SC31-6575

� IBM WebSphere Host Access Transformation Services (HATS) V5 Programmer’s Guide, SC31-6576

� IBM WebSphere Host Access Transformation Services (HATS) V5 Advanced Macro Guide, SC31-6590


Online resourcesThese Web sites are also relevant as further information sources:

� WebSphere Host Access Transformation Services Web site

http://www.ibm.com/software/webservers/hats/

� HATS Information Center

http://www.ibm.com/software/webservers/hats/library/version5/infocenter

� Sample WebSphere Application Server applications

http://www7b.software.ibm.com/wsdd/library/samples/Express/plantsby_express.html

� WebSphere Application Server V5 Information Center


� Apache Software Foundation Struts information


� W3C Web Services Activity


� WebSphere Application Developer


� WebSphere Portal Toolkit information


� WebSphere Application Assembly Tool


� IBM Eserver Workload Estimator



http://www.ibm.com/software/webservers/hats/

http://www.ibm.com/software/webservers/hats/library/version5/infocenter

http://www7b.software.ibm.com/wsdd/library/samples/Express/plantsby_express.html








How to get IBM RedbooksYou can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site:

ibm.com/redbooks

Help from IBMIBM Support and downloads

ibm.com/support

IBM Global Services

ibm.com/services

Related publications 359




http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/

Index

Numerics3270 application 139

AAAT

See Application AssemblyToolAccess Bean 177

defined 75actionPerformed 288Add Prompt Action 109–110, 112, 142, 161–162, 256–257, 304–305administration support 281–284, 330

included in HATS portlet 282stand-alone portlet 283

administrative slot 228, 230, 301Application Assembly Tool 334application testing 132, 135, 152, 168AS/400 Client Access 261AS/400 database access application 77Assemble HATS Project 332

Bbackground connection 155, 235, 322BOOTSTRAP_ADDRESS 284broadcastPortletMessage method 286–287Business Logic 116, 123–131, 221–222

adding 126, 131, 249–250credential vault 249–253portal support 191

Ccalendar modifications 50calendars 43–52cascading style sheet 57–63, 89changing module visibility 133class loader 133Classloader Policy 133–134, 345–346CM

See credential mapperCMRequest 294–295CMResponse 294–295connection manager 294–295

© Copyright IBM Corp. 2004. All rights reserved.

convert JSP to portlet 284cooperative portlets 285, 287creating a Credential Vault Populate portlet 222–230creating a HATS credential integration portlet 238–241creating a HATS portlet 198–204creating a new project 8–12credential mapper 293, 295, 300, 326

advanced topics 325CMRequest 294–295CMResponse 294–295defined 293, 326editor 300host credentials bind 293portal 296process 294workflow 326

credential mapper plug-in 293, 295, 297, 299, 326advance topics 325defined 327–328identifying 295portal 296selection 299

credential slot name 228, 300credential vault 189, 192, 221–222, 234–235, 249–251, 295–296, 312, 322

portlet 222–230samples 250–251slot 222, 228, 235–236, 238, 296, 321

creating 234–235slot name 251

CSSSee cascading style sheet

Ddatabase application

adding busines logic 126combining with HATS 116

dbInputForm.html 126dbInputForm.jsp 127DCAS

See Digital Certificate Access Server

361

deploying a Credential Vault Populate portlet 230–238deploying a HATS application 330–349deploying a HATS portlet 205–209Digital Certificate Access Server 295, 327Display Report 120

adding a Show URL 130adding business logic 131

drop-down lists 21–24, 34

EEAR

See Enterprise Archivee-business 1, 18, 55, 57, 69EJB

See Enterprise JavaBeanenterprise application organization 74Enterprise Archive 75

Application Assembly Tool 334defined 74HATS administration support 282, 284portlet development 225Struts 174, 176

Enterprise JavaBean 177EntryPortlet 285Extract Global Variable 75, 121, 132

GgetUserCredential method 251, 286global rules 30–35, 57, 68

adding 31recommendation 30

Global Variables 75, 116, 120–122, 221–222, 247defined 102name 122sharing 123

graphics 55–57

HHATS

combining with database application 116Component tag 57–58portal integration 190–192portal requirements 192portlet development environment 192using with a 3270 application 139V4 portal support 190

V5 portal support 191VT application 155

HATS administration support 281–284, 330included in HATS portlet 282stand-alone portlet 283

HATS portlet 198–221add HATS portlet to portal page 214–218create new portal pages 210–213creating 198–204

convert HATS application to portlet 203create base HATS application 198

deploying 205–209testing 210–221warnings 204

host credentials bind 293credential mapper 293process 293

HostID 293, 295, 326, 328defined 293

HTML, converting to JSP 127–130

IIBM eServer Workload Estimator 3, 73IBM Personal Communications 261IBM Toolbox for Java 80importing a template 18–20Integration Objects 71, 139, 155, 177, 181

3270 142–144defined 71exposing as a Web application using Struts 169VT 164Web services 178

IOSee Integration Objects

JJ2EE

See Java 2 Enterprise EditionJava 2 Enterprise Edition 12, 30, 74, 116, 169Java Database Connector 81, 93, 96, 98, 327–328JDBC

See Java Database ConnectorJSP file converting to portlet 284

LLDAP

See Lightweight Directory Access Protocol


legacyapplications 1, 3, 69, 73

migrate 30portal 190reuse 30Web services 177

connection data 16data sources 71mainframe 1, 190–191

Lightweight Directory Access Protocol 327

Mmacro 101, 139

creating 3270 139–142creating 5250 101–115creating signon 253–261creating VT 159–164defined 71enhancing signon 261–277testing 115

macrosproblems 261problems summary 264

Model 1 application 71, 139, 175defined 146generating 3270 146–152generating VT 166testing 3270 152–154testing VT 166–169

Model 2 169, 175architecture 169controller servlet 169Web pages 169

modifying a template 17module visibility

changing 133–134described 133

NNetegrity SiteMinder 292network security layer 291–293network security plug-in 293–295, 326–327

advanced topics 326network security provider 326

Ppassticket 295, 326

pop-up list 36–42portal top page 210Portalhostname 284portlet application name 226portlet development environment 192portlet messaging 285, 287portlet name 226prepresentation block 287private slot 301Project Settings 6, 15, 20, 30, 52, 156publishPortletProperty method 287

QQuery Manager 4–5, 106, 108, 110–111

RRedbooks Web site 359

Contact us xiregisterConsumedProperties method 287registerProducedProperties method 286registerProperties method 287rules engine 75Run Business Logic 75Run on Server 13, 99, 135, 152, 168, 175

Sscreen customization 241–248Send Key 76, 132

adding 132sendPortletMessage 287Set global variable 246Set prompt to global variable 112Set prompt to property from User List 112Set prompt to string 112setPWD 258, 263, 306setUID 257, 263, 305setUserCredential method 251, 286shared slot 301Show handler 112Show URL 76, 130signon macro

creating 253–261enhancing 261–277problems 261problems summary 264

Simple Object Access Protocol 177single signon (SSO) 222, 228, 291

Index 363

slot name 228, 300SLOT_ID 300SLOT_TYPE 230, 300–301

administrative slot 228, 230, 301private slot 301shared slot 301system slot 301

SLOT-ID 300SOAP

See Simple Object Access ProtocolSSO

See single signonStruts 71, 139, 169–176

creating 170–174defined 169testing 174–176

system slot 301

Ttabbed folders 25–30

customizing 26template 17–20

HATS samples 11importing 18–20modifying 17

text replace 52–55Tivoli Access Manager 292, 326–327top page, portal 210transcoding proxy 190–191transformation

avoiding duplicates 17cascading style sheet 60create new 46default 15, 112, 220

no VT support 155portlet 198

VT 158with pop-up list 36

UUDDI

See Universal Description, Discovery, and Inte-gration

Universal Description, Discovery, and Integration 177User List 158–159

defined 155

Vvault slot 222, 228, 234–236, 238, 296, 322

creating 234–235, 322name 251

VT application 155, 164, 166–169limitation 155

VT connection, creating 155–158VT emulation 155VT macro 159VT transformation 158

WWAR

See Web Archive 74, 205Web Archive 74, 225

Application Assembly Tool 334Classloader Policy 133–134, 345–346defined 75export 205–206

Web Express Logon 235, 289–328background 290configuration process 295credential mapper 293, 295, 300, 326

advanced topics 325CMRequest 294–295CMResponse 294–295defined 293, 326portal 296process 294workflow 326

credential mapper editor 300credential mapper plug-in 293, 295, 297, 299, 326

advanced topics 325defined 327–328identifying 295portal 296selection 299

credential vault 295–296, 312, 322slot 296, 321

host credentials bind 293process 293

network security plug-in 293–295, 326–327advanced topics 326

overview 290process 292SLOT_ID 300SLOT_TYPE 300–301


WebID 292–295, 326, 328defined 292

Web services 71, 139, 177creating 178–185described 177relationships 186testing 185

Web Services Description Language 177, 180creating the file 181naming conventions 179

WebID 292–295, 326, 328defined 292

WebSphere Application Server V5 192WebSphere Portal Server 190–192

credential vault 189, 192, 221–222, 234–235, 249–251, 295–296, 312, 322

slot 222, 228, 235–236, 238, 321creating 234–235

credential vault slot name 251described 190HATS V4 support 190HATS V5 support 191SLOT_ID 300SLOT_TYPE 300–301

WebSphere Portal Toolkit V5.0.2 192installation 194–197

WebSphere Studio Application Developer V5.1 192installation 194

WebSphere V5.0 Test Environment 13, 94, 134, 152, 168, 175, 345WEL

See Web Express LogonWidget Settings 34–35, 41, 57–58Widgets

calendar modifications 50calendars 43–52drop-down lists 21–24, 34graphics 55–57pop-up list 36–42Show URL 130

WSDLSee Web Services Description Language

Index 365

(0.5” spine)0.475”<->

0.875”250 <->

459 pages

Using IBM W

ebSphere Host Access Transformation Services V5

®

SG24-6099-00 ISBN 0738497622

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICALINFORMATION BASED ONPRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:ibm.com/redbooks

Using IBM WebSphere Host Access Transformation Services V5

Integrate Host Access Transformation Services (HATS) with business applications

Use enhanced customization with default transformation

Benefit from support for Web services

IBM WebSphere Host Access Transformation Services (HATS) provides tools to quickly and easily extend your legacy green-screen applications to the Web. HATS makes your 3270 and 5250 applications available as Hypertext Markup Language (HTML) through Web browsers. It also converts your host screens to a Web look and feel. Using HATS, you can improve the workflow and navigation of your host applications without any access or modification to source code.

HATS has a development component called HATS Studio, which runs in WebSphere Studio. There is no specialized HATS runtime server. All of the necessary runtime information is deployed into an Enterprise Archive (EAR) file and runs in WebSphere Application Server.

This IBM Redbook helps you to tailor and configure the new features that are included with HATS V5. Examples and usage scenarios demonstrate how to implement many of the new features and functions, along with those that were present in previous releases of HATS.

Back cover




timunderwood.net€¦ · iv using ibm websphere host access transformation services v5 chapter 2....

Documents