creating a web service using ibm rational hats for ibm ... · transformation services perspective,...

Creating a Web Service using IBM Rational HATS

For IBM System i (5250)

Creating a Web Service using HATS 1

Lab instructions

This lab teaches you how to use IBM Rational HATS to create a Web service that exposes logic contained in a System i 5250 application. You will learn how to create a HATS project, record a macro to navigate through the screens of the transaction, generate a Java bean wrapper for the macro, and to create a Web service using the tooling provided in the Rational Software Development Platform. Once the Web service is built, you will learn how to use the Web Services Explorer to test the service.

Please report any issues or problems with this lab to Will Smythe ([email protected]).

Learning objectives

♦ Use the HATS Toolkit to create a Web project capable of containing a Web service

♦ Use the HATS Host Terminal to record a macro

♦ Use the Visual Macro Editor to enhance a macro

♦ Create an Integration Object Java class that drives the macro

♦ Create a Web service that calls the Integration Object

♦ Test the Web service in the Web Services Explorer

Total time: 90 minutes

Skill level

Introductory

Audience

Programmer

Requirements

♦ IBM Rational Application Developer 7.0.0.5 (or above)

♦ IBM Rational Host Access Transformation Services (HATS) 7.1 with the Visual Macro Editor technology preview component

♦ Internet connection

Prerequisites

♦ Basic IDE skills

♦ Basic understanding of terminal applications

Conventions used in this lab

♦ Bold font for user interface controls ♦ Mono-spaced font for user input and code blocks ♦ Italic font for variable names and glossary terms


Glossary

macro - automates interactions with the host. Macros can send commands to the host, enter data into entry fields, extract data from the host, and be used to navigate screens on behalf of the user. Macros are created in either the HATS Host Terminal or the Visual Macro Editor.

Integration Object - a Java bean that encapsulates an interaction with a host screen or a series of host screens. Integration Objects are constructed from macros and can be included in Web services or HATS EJB projects.

Web service – an operation that can be published, located, and invoked programmatically over the Web. A HATS Web service drives a HATS Integration Object, which invokes a HATS macro.

Creating a HATS project and macro

This module will teach you how to create a HATS project and macro. From within the Host Access Transformation Services perspective, you can launch the wizard to create a new project. You will use the Host Terminal to record the initial “main path” macro. In the next module, you will use the Visual Macro Editor to enhance the macro.

Starting HATS

1. From your desktop click Start > Programs > IBM Software Development Platform > IBM Rational HATS 7.1 > HATS Toolkit 7.1.

A dialog appears asking you for the workspace location. The workspace contains your projects and files. You can accept the default or use different workspace for this tutorial (such as c:\myhatslab). You can always start with a new workspace later, if you don’t want to mix this tutorial with your real work.

2. Click OK.

After a few moments of loading, the workbench opens, and the HATS welcome page appears.


Creating the project

1. Click the New HATS Project link on the HATS Projects view to launch the new project wizard.

2. In the Name field, type the name HATS5250SOA. 3. Select the Web deployment radio button since HATS Web services are hosted in a web project.


4. Select WebSphere Application Server v6.1 from the Target server drop-down.

Note: if WebSphere Application Server v6.1 is not listed, you may select any other WebSphere server type.

5. In the Enterprise application project field, type the name HATS5250SOA_ear. This will ensure there are no conflicts when you deploy your application to the server later.

Your panel will look like this:

6. Click Next to display the Connection Settings panel.

The Connection Settings panel enables you to setup the connection to your 3270 or 5250 system. Your Web service will use this connection to communicate with the host application.

Note: Before proceeding, please check with your lab instructor (if applicable) for updated connection settings.

7. In the Host name field, type iseriesd.demos.ibm.com 8. Select 5250 from the Type field. 9. Accept the default values for the Port, Code page, and Screen size.



10. Click Next.

The Project Theme panel is not important when building Web services. In a standard HATS transformation project, a theme controls the basic appearance and behavior characteristics for the application. For example, you can select the Classic terminal emulator theme to enable emulator-like features, such as automatic field advance, in your application by default.

11. Click Next.

The Default Template panel is also not important when building Web services. In a standard HATS transformation project, a template controls the basic layout and style (such as color and font) of the application.

12. Click Finish to create the project.

After a few minutes, the new project will appear in the HATS Projects view and the Project Settings editor for the project will open.

Caution: There is a known issue that sometimes causes WebSphere Application Server 6.1 not to start. Because you will use this server later in the tutorial to test your Web service, please take the opportunity now to fix this problem on your system by following the steps below.

13. Open the Servers view tab at the bottom of the workbench window, select WebSphere Application Server v6.1, right-click and select Open.

14. In the Server section, select the SOAP (Designed to be more firewall compatible) radio button. Click File > Save to save the server configuration.


15. Close the server configuration editor window.

If you were building a standard HATS transformation application, you could, at this point, right-click on the project (in the HATS Projects view) and select Debug on Server to run your application on the server. Since the purpose of this tutorial is to show how to create a Web service, you can skip this step. Here is what you would have seen:

If you want to sign on to server iseriesd use user ATDEMO password DEMO4YOU

Lesson checkpoint

In this section, you learned how to:

♦ Start the HATS toolkit

♦ Create a new HATS project

Creating the macro


A macro is a script that defines a flow through screens in your application. Typically a macro is responsible for performing a very specific task. For example, you might record a macro that collects information about a customer based on a supplied customer identification number (this happens to be the scenario described in later steps of this tutorial). Macros can be input only, output only, input and output, or purely navigational. The input and output you define in a macro will be the input and output of your eventual Web service.

For this tutorial, you will create a macro that signs in, navigates to a customer information application, and retrieves important information about a customer.

This tutorial describes using the HATS Host Terminal to record the macro. Macros can also be created using the HATS Visual Macro Editor, or VME, but the Host Terminal allows you to more quickly create the main flow of your macro. Later in this tutorial you will use the VME to add error handling to your macro.

Caution: This tutorial assumes the Display Program Messages screen appears after the Sign On screen and before the Main Menu screen. In order to make sure this happens you must start a separate telnet session using the same user name and password. Follow the instructions below to do this:

1. From your desktop, click the Start button and select Run. 2. In the Open field, type telnet iseriesd.demos.ibm.com

3. Click OK.

You will see a telnet window:

Note: If the userid/password below don’t work, please ask your lab instructor (if applicable) for the user name and password to use or get the current user name and password for the System i demo system from: http://websphere.dfw.ibm.com/atdemo/atdemo_help.html

4. Type ATDEMO and press the TAB key. 5. Type DEMO4YOU and press the ENTER key.


You should now be at the Main Menu or a Display Program Messages screen. If you are at a Display Program Messages Screen, press the ENTER key.

6. Minimize this window and switch back to your workbench window. 7. In the HATS Projects view, right-click on your project’s folder and select Open Host Terminal then

select the Main host connection. This will open an emulator session to your system.

You will see the sign on screen:

8. To start recording the macro, click the Record Macro button on the toolbar.


9. In the Name field, type getCustomerInformation. Macro names should reflect the operation being performed.

10. Check the Create screen captures automatically while recording checkbox. When this option is enabled, HATS takes a capture of each of screen while recording the macro and saves it in your project. This makes it easy to tweak screen recognition criteria or add new screen actions when using the Visual Macro Editor.


11. Click Finish.

For the first screen in a macro, HATS asks you to define its screen recognition. You should see this panel:


12. In the Screen name field, type SignOn. This will make it easier to understand the flow of your macro later when you edit it in the Visual Macro Editor.

13. Accept the default selections on this panel and click Finish.

The Host Terminal is now in record mode. This means that every keystroke you make (in the terminal area) is recorded in the macro.

14. In the User field, type ATDEMO (your cursor should already be positioned in this field). 15. Press the TAB key to advance to the next field. 16. In the Password field, type DEMO4YOU. 17. Press the ENTER key.

Notice HATS has recorded your keystrokes and shows the structure of your macro at the left side of the terminal window:


You will see the Display Program Messages. If you do not see this screen, see the first few steps of this section.

18. On the Display Program Messages screen, click the Define Screen Recognition Criteria button on the toolbar to name the screen and defines its recognition criteria.

19. In the Screen name field, type DisplayProgramMessages.

Using your mouse, rope off (i.e. select) the “Display Program Messages” text at the top of the screen. The default screen recognition region includes text that will change on subsequent logins – you do not want this text to be included in the recognition criteria for this macro screen.

20. Click Finish. 21. Press the ENTER key to navigate the host terminal to the Main Menu screen.

You should now be at the i5/OS Main Menu screen.

22. Click the Define Screen Recognition Criteria button to supply a new name for the screen. 23. In the Screen Name field, type MainMenu and click Finish. 24. In the Command field at the bottom of the screen, type GO CELDIAL and press the ENTER key.

You should now be at the CelDial Communications main menu screen:


25. Click the Define Screen Recognition Criteria button to supply a new name for the screen. 26. In the Screen Name field, type CelDialCommunications and click Finish.

Because the purpose of this macro is to gather customer information based on a supplied customer number, you will use the Customer inquiry application.

27. In the command field, type 1 and press ENTER.

Note that HATS is still recording every keystroke you make and is showing a representation of your macro on the left side of the terminal window.

You should now be at the CelDial – Custom Inquiry screen.

28. Click the Define Screen Recognition Criteria button to supply a new name for the screen. 29. In the Screen Name field, type CustomerInquiry and click Finish.

A prompt action is responsible for populating a field from a value supplied by a user (or by a caller of the macro). Think of a prompt as an input variable into a macro. For this macro, the prompt value will be supplied via an input parameter to the Web service.

30. Click the Add Prompt Action button on the toolbar.


31. In the Name field, type customerNumber since this prompt value will reflect some customer number supplied by the user.

Your panel should look like this:

32. Most of the other settings on this panel do not apply when building a macro for a Web service. Click OK to add the prompt. The prompt action will appear in the Macro Navigator tree on the left side of the terminal window:

In order for HATS to continue recording the macro after adding a prompt, HATS will prompt you for a value for the prompt action and fill the value you supply into the field.

33. In the Enter a value field, type the value 0010200 (this is a valid customer number) and click OK.

You will notice this value is inserted into the Custom inquiry field.

34. Press the ENTER key to submit the customer number to the application.


You should now be at the CelDial – Customer Detail screen.

35. Click the Define Screen Recognition Criteria button to supply a new name for the screen. 36. In the Screen Name field, type CustomerDetail and click Finish.

Extract actions are responsible for pulling data from fields on the screen and exposing the data as outputs on the Web service. Although we could add extract actions for each of the important fields on this screen using the Host Terminal, we will only add one extract action now and add the rest using the Visual Macro Editor later.

Use your mouse to rope off the Customer Name field:

37. Click the Add Extract Action button on the Host Terminal toolbar to open the Add Extract dialog.

38. In the Name field, type customerName.

39. The values in the position group should match the values shown in the screen shot above. Make any necessary changes and click Finish.


You now have an extract action that will, when the macro is played, pull the contents of the customer name field into a variable.

You will now exit out of the application, sign off, and return to the sign on screen. In general, it is recommended to name each screen in your macro. In order to save time, however, you will not be instructed to do this.

40. Press the F12 key on the Customer Detail screen. 41. Press the F3 key on the Customer Inquiry screen. 42. Press the F12 key on the CelDial Communications main menu screen. 43. In the Command field, type 90 and press the ENTER key to sign off.

You should now be back at the Sign On screen.

44. Click the Stop Macro button on the Host Terminal to stop recording. If prompted to define exit screen criteria for the macro, accept the defaults and click Finish.

45. Click the Save Macro button on the Host Terminal to save the macro.

You have created a macro that signs on, navigates to a customer information application, populates the customer number field with a supplied prompt value, navigates to the customer detail screen and extracts the contents of the name field into a variable, and then navigates back to the sign on screen.

Lesson checkpoint


♦ Use the HATS Host Terminal to record a macro

♦ Define the screen recognition and name for a screen in the macro

♦ Add a prompt action in order to fill in a host input field

♦ Add an extract action in order to extract the contents of a field


Testing the macro

To confirm the macro works as expected, you will play it back using the Host Terminal. You should already be at the Sign On screen of the system.

1. Click the Play Macro button on the Host Terminal toolbar.

HATS will display a dialog asking you to supply values for all prompt actions defined in the macro. Since you only added on prompt action (for the customer number), you will only be asked to supply one value:

2. In the Value column, type 0010900 (this is also a valid customer number) and click OK. Later in the tutorial you will learn how to handle the scenario where an invalid customer number is supplied.

HATS will navigate the screens using the key strokes you previously recorded and will populate the customer number field with the value you supplied. On the customer detail screen, the extract action you created previously will extract the data from the customer name field. HATS will show the extracted data and continue playing the macro.


The Extract Results window will show “Village Telephone” (since this is the name of the customer with the number 0010900). The terminal, which is beneath the Extract Results window, should be on the sign on screen.

3. Close the Extract Results window by clicking the X in the upper right corner. 4. Click the Disconnect button on the Host Terminal to disconnect the session.

5. Click the X at the upper right corner of the window to close the terminal window.

Enhancing the macro using the Visual Macro Editor

The HATS Visual Macro Editor, or VME, is a graphical tool for creating new macros from scratch or enhancing macros recorded with the HATS Host Terminal. With the VME, you can add new screens, flows, and actions to your macros. For this tutorial you will record an alternate flow for the scenario where an invalid, or non-existent, customer number is supplied. You will also use the VME to easily add multiple extract actions for fields on the customer details screen.

1. From the HATS Projects view, expand the Macros folder, select the getCustomerInformation macro and right-click and select Open With > Visual Macro Editor Technology Preview.


The VME will open and you will see a visual representation of your macro.

Currently the macro only works if the Display Program Messages screen appears after the Sign On screen. This poses a problem since this screen does not always appear. Using the Visual Macro Editor, you will learn how to draw a next screen connection line between the Sign On and Main Menu screens. This will allow the macro to work regardless of whether the Display Program Messages screen appears or not.

2. From the Palette view, click the Next Screen Connection tool.


3. Move your mouse back to the design area (notice the cursor has changed) and click the SignOn screen.

4. Move your mouse (notice a line is drawn between the SignOn screen and your mouse pointer) and click the MainMenu screen.

You will now see a new line drawn between the SignOn screen and the MainMenu screen.

This indicates that either the Display Program Messages or Main Menu screen can follow the Sign On screen.

In order to handle the scenario where an invalid number is supplied, you need to navigate to the customer inquiry screen, supply an invalid value, and then add the resulting screen into the flow of your macro.

5. Click the Connect button near the bottom of the editor (just above the Design tab) to show and to connect the integrated terminal.


Unless your monitor is set to a high screen resolution, you may want to double-click the getCustomerInformation.hma editor tab at the top of the workbench window to maximize the editor. Your display will look like this:

6. Click the Play button on the integrated terminal toolbar to play the macro. 7. Just like in the Host Terminal, HATS will prompt you to supply a value for the customerNumber

prompt. Supply an invalid value, such as 200 and click OK.

HATS will play the macro and supply the customer number into the appropriate field, but the macro will stall because it’s waiting for the Customer Detail screen to appear after the Customer Inquiry screen. Notice the error message at the bottom of the screen. You will add this screen into the flow of the macro in order to handle this error scenario.


Note: if you wait for 60 seconds, HATS will show a Macro Play Error messages because the Customer Detail screen never appeared (and your macro expects this screen to follow the Customer Inquiry screen).

8. If the macro is still playing (well, waiting), click the Stop button on the toolbar to stop the playback.

You will now update the macro to handle the case where this error screen appears on the Customer Inquiry screen. This screen only appears if an invalid number is supplied.

9. While on the screen with the error message, click the Add Screen button on the integrated terminal toolbar to open the Add Screen wizard.

10. In the Name field, type InvalidCustomerNumber. 11. Check the Exit screen checkbox. This tells HATS that the macro should stop (and the connection

should be terminated) in the event that this screen is encountered.

Note: In general, it is recommended to sign off a session before disconnecting. The best approach for doing this is to wire this screen into the existing flow that signs off. For the purpose of saving time, these steps are not described in this lab.

12. From the Preceding screen drop-down, select the CustomerInquiry screen. This tells the HATS to wire this new screen as a possible option after ENTER is sent on the Customer Inquiry screen. Because the Exit screen checkbox is checked, HATS will not allow you to select a next screen (since the macro will terminate after encountering this screen).



13. Click Next.

The Screen Recognition criteria panel enables you to configure the criteria HATS will use to identify the screen. For this screen, you will just use text on the screen to identify the screen.

14. Uncheck the checkboxes for Total number of fields, Number of input fields, and Cursor position.

15. Click the Add button to add new String (text) recognition criteria. 16. Rope off (i.e. select) the “not found” text at the top of the screen. 17. Select the radio button Anywhere on the screen. This tells HATS to match whenever the text “not

found” is found anywhere on the screen.


18. Click OK.

Your panel should look like this:

19. Click Next to show the Actions panel.

The actions panel enables you to control what HATS does when this screen is encountered. When recording the macro in the Host Terminal, HATS created Input actions for all sequences of keystrokes.


You also manually added Prompt and Extract actions. For this screen you will extract the error message and make it available as an output variable on the Web service.

20. Click the Add button. 21. Select the Extract action option.

22. Click Next. 23. In the Name field, type errorMessage. 24. Rope off the error message on row 24.

25. Click Finish to add the action.


You should see this panel:

This indicates that a single extract action will be performed when this screen is encountered.

26. Click Finish to add the screen.

Notice how the VME has wired the new screen, InvalidCustomerNumber, as a possible path after the CustomerInquiry screen. Also notice the red exit indicator on the title area of the new screen. This indicates the macro will stop after the actions in this screen have been performed (the last screen of your original macro has the same indicator).

27. In the design area, click the CustomerInquiry screen.

Notice a “1” and “2” appear above the lines connecting the two possible next screens after the CustomerInquiry screen. These numbers indicate the order in which HATS will evaluate the recognition criteria defined in these screens when playing the macro. Since the CustomerDetail screen has a higher priority number (1 vs. 2), HATS will first look to see if this screen appears after ENTER is pressed on the Customer Inquiry screen. If it doesn’t appear, HATS will look to see if InvalidCustomerNumber (i.e. a screen with “not found” on it) appears. In this case, the ordering of the next screens isn’t terribly important because both possible next screens are unique and quite different from each other. But, in other situations, the ordering of the next screens can be very important.


28. Save the macro by clicking File > Save. 29. Press the left arrow key on your keyboard to unlock the display. 30. Press the F3 key to return to the Customer Inquiry screen. 31. Press the F3 key to return to the Main Menu screen. 32. In the Command field, type 90 and press ENTER to sign off.

You should now be back on the sign on screen.

33. Press the Play button again to test the new flow.

You will be prompted to supply a customer number.

34. In the Value column, type 300 (or any invalid customer number).

35. Click OK.

Notice the Extract Results window shows the extracted error message. Also notice the path of the macro is highlighted in the design area of the VME. This shows you the path the macro took as it played. Also notice that the macro correctly stopped (i.e. the Stop button on the integrated terminal toolbar is not enabled).


In order to demonstrate another feature of the VME, you will learn how to add additional actions to a screen.

36. Find the CustomerDetail screen in the design area and select it, right-click, and select Properties.

You will see the properties dialog for the screen. This dialog enables you to change the basic properties of the screen, including its associated screen capture, screen recognition criteria, and actions.

37. Click the Actions section on the left side of the window to show the screen’s actions.

At this point you should see two actions – an extract action (to extract the customer’s name) and an input action to send the F12 command.


You will now add additional extract actions for each of the other important fields on the Customer Detail screen. Instead of manually adding each individual action, you will use the Extract all action type to add multiple actions at the same time.

38. Click the Add button. 39. Select the Extract all action type and click Next.

You will see a panel like this:

Notice each field on the screen is represented in the table. Default names have been generated for each extract action. Also notice the value of the field is shown in the table.

40. Check the Exclude empty protected fields and Exclude input fields checkboxes (this will limit the number of fields in the table and make it easier to find the important fields).

41. Click the Deselect all button (this will allow you to just select the fields you want to include).

You will see a panel like this:


You will notice that 21 fields are shown (as indicated by the label at the bottom right of the table).

42. Since you already extracted the customer name field, double-click the text in the address field (e.g. “Maple View Plaza, 256 New St.”) to fully select the field.

Notice the corresponding row in the table is also highlighted. Selecting the field in the table also highlights it in the screen preview area.

43. In the Name column, replace in_664_40 (which is a default name generated by HATS for this field), with customerAddress. To change the value, click once on the current text – the cell will become editable.

44. Check the box at the beginning of this row. This will cause HATS to create an extract action for this field when Finish is clicked later.

45. Repeat this process (steps 42 – 44) for one or more other fields (such as the field containing the city, country, or postal code).

46. Click the Finish button.

HATS will ask you to confirm that you want to add X number of extract actions.


47. Click Yes.

Notice the new actions are listed in the actions table for the screen:

48. With the two actions still highlighted (selected), click the Up button to move the actions above the Input action (you want the extraction to take place before the F12 key is pressed).

49. Click OK.

Notice the two actions are now shown in the design area:

50. Save the macro by clicking File > Save.

Optionally, you can navigate back to the sign on screen in the integrated terminal and play the macro. You will be prompted for a customer number, but, once the macro is finished, the Extract Results window will show data for each of the fields you extracted in the previous few steps. You will also have the opportunity to see the extracted data later when you test the macro in the Web Services Explorer tool.

Lesson checkpoint


♦ Use the Next Screen Connection tool on the palette to draw a flow between two macro screens

♦ Use the integrated terminal to play a macro

♦ Handle an alternate flow / error condition

♦ Quickly extract data for multiple fields on the screen

Creating the Integration Object and Web service

A HATS Integration Object is a Java class that encapsulates a programmed interaction with a host application. Integration Objects can be used in multiple ways to integrate interaction with a host


application into new Java or Web based programs. One use of an Integration Object is to provide the interaction with a host application for a Web service.

The Web service you are building in this tutorial is intended to gather customer information from the host system based on a customer number submitted by the Web service caller. You have just finished creating the macro that collects this information. Now all you need to do is tell HATS to create an Integration Object from your macro and then create a Web service from the Integration Object.

Creating the Integration Object

1. From the HATS Projects view expand the Macros folder, right-click on your macro, getCustomerInfromation, and select Create Integration Object.

HATS will generate the Integration Object Java class and some support files and place them in the IntegrationObject package under your Source folder.

2. Expand the Source and IntegrationObjects folders in the HATS Projects view. Look for your Integration Object now. Notice it has the same name as the macro used to create it (except the first letter has been converted to uppercase in order to maintain Java naming conventions).


Creating the Web service support files

3. Before you create the actual Web service, you must first create HATS Web service support files. To do this, from the HATS Projects view, right-click on your Integration Object and select Create Web Service Support Files.

4. In the Project field, select HATS5250SOA. 5. In the Name field, type CustomerServices. Because a Web service can contain multiple

operations, the name of the service should reflect the collection of services it might contain.

Your wizard panel will look like this:


6. Click Next. 7. Ensure your Integration Object, GetCustomerInformation, is checked and click Finish. If your

project contained other Integration Objects, you could include them in the same Web service. Each would be exposed as a different operation on the service.

HATS will generate the support files necessary for creating a Web service using the IBM Rational Software Development Platform tools. Notice the new Java classes, including CustomerServices, in the webserviceclasses folder under your Source folder:

Lesson checkpoint

In the previous sections, you learned how to:

♦ Create an Integration Object from a HATS macro

♦ Create Web service support Java files, which are needed to create the actual Web service

Creating the Web service

You are now ready to create the actual Web service, including the WSDL (Web Services Description Language). A WSDL describes a Web service and its operations, including its inputs and outputs. The caller of the Web service will consume this WSDL file in order to know what operations are available and inputs required for each (if applicable).

8. Select the CustomerServices file, right-click and select Web Services > Create Web service.


The Web Service wizard will appear. This wizard enables you to generate the actual WSDL and to select whether or not to deploy and start the service on the server. The wizard also enables you to create a sample client. For this tutorial, you will not generate a sample client since you have the ability to test the service using the Web Services Explorer.

9. Ensure the Web service type field says Bottom up Java bean Web Service. This means the Web service will be constructed from an existing Java class. Also ensure the Service implementation field says webserviceclasses.CustomerServices.

10. Ensure the first section says Start service. If not, use the slider on the left side to select Start. This section controls whether the service is just built, built and installed, or built, installed, and started.

11. Ensure the second section indicates No client since you do not need to build an actual client at this time (you will use the Web Services Explorer later to test the service).


12. Click Next. 13. Click Next again to bypass the Service Endpoint Interface Selection panel and to show the

Web Service Java Bean Identity panel.

The Web Service Java Bean Identity panel is important because it shows the name of the WSDL being created and the operations available on the Web service. You should see getCustomerInformationWS in the list of methods.

14. Click Next to show the Start Server panel.

Note: if you previously started the server and it is still running, you will not see the Start Server panel. Skip to step 16.

15. Click Start server to publish the Web service on the local server and to start it.

The server will take a few minutes to start.

16. Click Finish once the server starts.

Your Web service has been created and is installed on your local WebSphere Application Server. The next step is to test the service to confirm it works properly.

Testing the Web service using the Web Services Explorer

The IBM Rational Software Development Platform provides the Web Services Explorer tool to test Web services. In this section you will learn test your Web service using this tool.


17. To launch the Web Services Explorer, expand the Web Content > /WEB-INF/Web Service Definitions folder, select CustomerServices, right-click and select Web Services > Test with Web Services Explorer.

After a few moments, the Web Services Explorer browser window will open. You should see your getCustomerInformationProcessWS method listed.


18. Click the getCustomerInformationProcessWS link. This will show all input parameters on the Web service.

Note: all input parameters that start with HPub are used internally by HATS.

19. Scroll down and find the customerNumber parameter. Recall this is the name of the prompt action you added to the macro earlier.

20. In the customerNumber field, supply a valid value such as 0010200 and click the Go button.

When the operation is called, HATS will initiate a new connection to the host system and play the macro. Prompt actions will be filled from values supplied by the caller and extract actions will collect data. Results are then displayed in the Status area.

21. In the Web Services Explorer Status panel scroll down the Form view and notice the outputs. Remember these are the macro extracts you created in your macro. For example, notice customerName shows the name of the customer with the supplied customer number.

Now scroll up and switch to the Source view.

22. In the Source view notice the SOAP Request Envelope and SOAP Response Envelope. This is the actual XML that was sent and received during the operation.


You will now test the Web service operation with an invalid customer number. Recall how you created an alternate flow for this scenario in your macro using the Visual Macro Editor.

23. Switch back to the Actions area, find the customerNumber field, type an invalid value such as 00200, and click Go.

24. Switch back to the Status area, click the Form link near the top to switch to the Form view, and scroll down and find the errorMessage output parameter. Notice it shows the extracted error message.

The caller of the Web service can use this information to determine what step to take next. For example, the caller might display the message to a user.

Lesson checkpoint

In the previous sections, you learned how to:

♦ Create a Web service and deploy it to the server

♦ Test a Web service using the Web Services Explorer

Conclusion

This concludes the tutorial on creating a Web service using IBM Rational Host Access Transformation Services (HATS). This tutorial has shown the tools available to a HATS developer to create Web services that provide access to proven, critical green screen application processes and data. These services can be hosted on the proven WebSphere Application Server and safely exposed and accessed by external partners or internal organizations.

Please report any errors in this tutorial to Will Smythe ([email protected]).


creating a web service using ibm rational hats for ibm ... · transformation services perspective,...

Documents