Using Integration Objects

This chapter introduces Integration Objects, which are Java™ beans that encapsulate interactions with a host application. Integration Objects are supported only by ZIETrans Web applications

You may need to use Integration Objects if any of these statements are true:

When you have created an Integration Object, you can use it in many ways:

Refer to the ZIETrans Web Application Programmer's Guide for information about other advanced tasks that can be performed with Integration Objects. Some of the tasks discussed are:

Creating an Integration Object

An Integration Object is created from a macro. Follow the steps described in Macros and host terminal to record a macro.

Right click on the macro in the ZIETrans Projects view and select Create Integration Object. The Integration Object will have the same name as the macro. You can also set a preference in ZIETrans to automatically generate an Integration Object when a macro is recorded. Click Window > Preferences, expand ZIETrans in the tree on the left, and click Integration Object. Select the box labeled Automatically generate Integration Object when saving macro, then click Apply.

When naming a macro used to create an Integration Object, ensure that you follow these requirements:

Notes:
  1. Automatically generated Integration Objects are always non-chained.
  2. For information about creating Integration Objects when using DBCS support see Creating an Integration Object.

Integration Objects cannot get created from chained macros. Integration Object chaining is quite different from macro chaining, in that each Integration Object in a chain is run to completion before the next Integration Object in the chain takes control. Macro chaining, using the ZIETrans play macro action, terminates the current macro (the one in which the play macro action occurs) and begins to process the specified macro screen of the target macro. If you import a Host On-Demand macro that contains the <playmacro name="chainedMacroName"/> tag, you can only use this macro in the ZIETrans play macro and perform macro transaction actions. See ZIETrans Advanced Macro Guide for more information about macro chaining.

If a macro is changed using the macro editor, after an Integration Object has been created from that particular macro, the Integration Object has to be regenerated to accurately reflect the change. If the Automatically generate Integration Object when saving macro preference is selected, the Integration Object will be updated automatically.

To see a list of Integration Objects which you have created, click the ZIETrans Projects view tab of the ZIETrans Toolkit and expand the project name, then go to Source > IntegrationObject and double click the folder to view the contents.

Note:
The IntegrationObject folder under Source is only visible after creating your first Integration Object.

Integration Object chaining

Integration Object chaining enables you to create multiple Integration Objects which can be grouped together into a single major task within your Z and I Emulator for Transformation application. Each Integration Object performs one subtask, and the major task is performed by an Integration Object chain. When the application is run, the Integration Objects run in sequence, each using the same connection.

When you right click on the macro to create the Integration Object, select Create Chained Integration Object. Then specify whether the Integration Object is the first, middle, or last in the chain. There can be more than one middle Integration Object in a chain. Enter the labels that identify the start and stop states for this Integration Object. There is no start state label for an Integration Object that is first in its chain, and no stop state label for an Integration Object that is last in its chain. State labels are required to ensure that the Integration Objects in a chain are processed in the correct order, with the correct data passed each time.

This section describes Integration Object chaining in detail and shows you how to use it in your ZIETrans applications.

Deciding when to use Integration Object chaining

To determine how many Integration Objects are needed in the chain, begin by listing all of the subtasks that need to be performed. For example, imagine a host application called fileview that, when invoked, displays a list of files. From the list of files, a user can select any file by typing 1 next to its name, pressing Enter, then viewing its contents. There are two tasks to perform:

  1. Obtain the list of files to present to the user.
  2. Retrieve file details for a selected file.

Two macros are required because the user must make a decision before the second macro can run. The second macro must wait for user input. Defining where user input is required is the first step in separating your tasks into individual Integration Objects.

If the user has multiple choices and each choice causes different host actions, then each choice must be a separate Integration Object. You can then piece together the Integration Objects dynamically, depending on the selections of the user. An example of this is a menu of five items. If the user is allowed to select any of the five choices, each selection must be created as an independent Integration Object.

After you understand the number of distinct tasks in your application, you can decide how chaining will affect your application. If you have more than two tasks, chaining might help improve your application's response time or decrease the amount of macro recording you must do, thus reducing the overall complexity of your Integration Objects.

Using Integration Object chaining

An Integration Object in a chain leaves the connection in a state (at a particular screen). After the Integration Object finishes running, another Integration Object that begins in that state (that is, at that screen) can run.

You can use chaining to break up a complex application into multiple tasks, each task represented by an Integration Object. You must ensure that the order of the Integration Objects is correct.

For example, if you have three Integration Objects in a chain (A, B, and C), then you must use A first, then B, then C. If Integration Object C is invoked before Integration Object B, then when C requests its connection, the connection is not available in the correct state, and the Integration Object fails.

Figure 55. Connection lifetime with chaining
connection lifetime with chaining

Figure 55 depicts the lifetime of a connection throughout the execution of three Integration Objects. Integration Object A is configured as first, Integration Object B as middle, and Integration Object C as last. Connection state data represents the connection and the state label of the last Integration Object run.

  1. When Integration Object A begins to run, it retrieves the connection specified in the macro. If checkin screen enabled and a connection is available, the connection is already logged on and ready. If checkin screen is enabled, but a connection is not available, the connection is created and the connect macro (if specified) is run. If checkin screen is disabled, a connection is created and the connect macro (if specified) is run.
  2. Integration Object A runs the associated macro, then saves the connection and its current state for the next invocation. (You would have defined this state as the stop state label during Integration Object chaining).
  3. When Integration Object B begins to run, it retrieves a connection and its state from the connection state data because it is the middle Integration Object. You must have defined Integration Object B's start state label as Integration Object A's stop state label, which allows these Integration Objects to be chained.
  4. When execution completes for Integration Object B, the connection and its state are saved in the connection state data.
  5. Integration Object C also retrieves the connection from the connection state data. When Integration Object C begins to run, it retrieves a connection and its state from the connection state data because it is the last Integration Object. You must have defined Integration Object C's start state label as Integration Object B's stop state label, which allows these Integration Objects to be chained. Last-in-chain Integration Objects have no end labels because the connection is always returned.
  6. When checkin screen is enabled, the connection returns to the pool; otherwise, the disconnect macro (if specified) is run and the connection ends.
Note:
Settings for the checkin screen are made by going to the Macro tab of your connection settings. You must enable pooling in order for the checkin screen setting to be available. For more information, see Connection editor.

To build an application using Integration Object chaining with ZIETrans, you must first build the Integration Objects and then create your Web pages from the Integration Objects.

Follow these steps to create your application:

  1. Record macros.
  2. Create chained Integrations Objects from each macro.
  3. Create Web pages for each Integration Object.
Record a Macro

You can record macros in ZIETrans Toolkit using the ZIETrans host terminal. On the ZIETrans host terminal screen, click the Record Macro icon. For information about recording macros, see Macro related icons.

Repeat these steps for each Integration Object you want to create.

Create Integrations Objects from each macro
Once all of your macros are created, you can go to the ZIETrans Project View tab of the ZIETrans Toolkit and expanding the project name, and open the Macros folder.

Right-click on each individual macro and select Create Chained Integration Object. You will have the option of selecting the position in the object chain to either First, Middle or Last. If you select First, the state will be the stop state during Integration Object chaining configuration. If you select Middle, the state can either be the start state, or the stop state. The Last position of the object chain uses the start state.

This needs to be done for all the Integration Objects which are part of the chain.

Create Web pages from each Integration Object.
Once you have created your Integration Objects, you can then create your Web pages. For information about creating Web pages from Integration Objects, see Building Web pages from an Integration Object.

Debugging applications that use Integration Object chaining

While Integration Object chaining is a powerful tool for modeling the most complex host applications, take care when assembling your applications. There is a risk of creating a Java EE application with Integration Objects that are invoked out of order; therefore, you should be aware of the errors you get on the server when this happens.

If you chain the Integration Objects incorrectly, you will experience problems when you run your Integration Object. Here are the error messages you might see on the server and how to debug them.

HPS5075 Received STATE_PLAY_ERROR while playing macro in file zzz.macro
This error occurs when the macro fails to play because it cannot match the current screen. This might happen if an Integration Object in a chain is invoked in the correct order (a connection in a specific chain was found for it to use), but the macro itself failed to play. It can be a problem if your start and stop state labels are all the same, or at least are the same for two Integration Objects, and you invoke the Integration Objects out of logical order.
HPS5035 There is no data source object {0} in HttpSession. A possible cause is the use of multiple browsers from a single machine to a chained application. See documentation for more information.
This error occurs when an Integration Object with a start state label of last Integration Object state fails to retrieve the connection and its state because its start state label does not match the stop state label of the preceding Integration Object.

When this happens, determine why this Integration Object is being invoked out of order.

Building Web pages from an Integration Object

You can create a JSP from any Integration Object There are three approaches to building these pages; they are called Model 1, JSF, and Struts. The following sections describe these three approaches and how to create pages using them.

Create Model 1 Web pages

The traditional ZIETrans approach to building a JSP is called Model 1.

In this model, a single JSP contains:

In the ZIETrans Projects view, right click on the name of an Integration Object and select Create Model 1 Web Pages. Specify the input and output page names along with the destination, or accept the default names created from the Integration Object name. You can also specify Page generation options by selecting Append to existing files or Overwrite existing files. Click Next after completing your selections.

When you create Model 1 Web pages, you define two pages: an input page, which gathers the data required by the Integration Object, and an output page, which presents the results after the Integration Object is run.

On the Define outputs page, you select the output properties of the Integration Object that you want to display. To change a control, select an output property and click Edit. You have the option to render output properties using either HTML controls, or normal text. You can mix HTML controls on the same Model 1 Web page. You can add the leading text for the control. The output JSP contains code to initialize the Integration Object, to set the Integration Object properties from global variables, to run the Integration Object, and to display the Integration Object output.

The pages you create go in the Web Content/Model 1 Pages folder in the ZIETrans Projects view. To edit a Web page and invoke the Rich Page Editor, double-click on the name of the page. To test your pages, right-click on the input page (or output page if there are no inputs) and select either Debug on Server or Run on Server.

Create Struts Web pages

ZIETrans enables you to use Struts 2 to build Web pages based on Integration Objects.

In the ZIETrans Projects view, right click on the name of an Integration Object and select Create Struts Web Pages. Specify names for input and output pages, or accept the default names created from the Integration Object name. Click Finish.

When you create Struts Web pages, ZIETrans generates following new files:

Struts Action class
This class is the main class. It instantiates the Integration Object, sets the Integration Objects properties using values in the ActionForm class, sets the Integration Object's poolname, and runs the Integration Object. It then forwards to the output JSP, or if there is an error, then it returns to the ZIETrans runtime and allows the ZIETrans runtime to handle the error. The developer should not modify this class. This file is located in the Source/Struts/Actions folder in your project.
ActionForm class
This class contains setters and getters for each input in the input JSP. The input JSP submits to the Struts Servlet, which instantiates the ActionForm class and sets all of its properties based off the submitted input JSP form. This class is used by the Action class to set all of the Integration Objects properties. If you add or remove input properties from the input JSP, you must add or remove the matching setters and getters from this file. This file is located in the Source/Struts/ActionForms folder in your project.
input JSP
The input JSP contains a Struts HTML form that sends the request to the Struts Controller, which creates an ActionForm and forwards the request to appropriate Action class. If the Integration Object does not need any input, or where the inputs come from different sources, such as global variables, an empty input JSP is created containing only the HTML form. The input page is created in the Web Content/Struts Pages folder. To test your pages, run the link http://<hostname>:<port>/<contextRoot>/<StrutsActionClassName>.action in the browser.
output JSP
The output JSP displays the Integration Object's output properties. This page is similar to the Model 1 output JSP. This file is located in the Web Content/Struts Pages folder in your project.

ZIETrans also adds or updates an action to the struts.xml file to associate the Action class with the input/output/error pages.

Note:
When you create Struts pages, if Struts is not already installed in your project, ZIETrans installs it and creates struts.xml file under source folder of your project.

Create JSF Web pages

JavaServer Faces (JSF) is a framework for developing user interfaces (UI) for Web applications which run on a Java server. You can quickly build web applications by assembling reusable UI components in a page. Once you have created JSF Web pages, you can use tools such as the Rich Page Editor and the palette for modifications and editing.

In the ZIETrans Projects view, right click on the name of an Integration Object and select Create JSF Web Pages. Specify names for input and output pages as well as the destination, or accept the default names created from the Integration Object name. You can also Overwrite existing files by selecting the check box. Click Next after completing your selections.

When you create JSF Web pages, you define two pages: an input page, which gathers the data required by the Integration Object, and an output page, which presents the results after the Integration Object is run.

For the input page, you can define an input control for each input property. To change a control, select an input property and click Edit. You can add the leading text for the control and, where necessary, configure the selected control. Click Next.

For the output page, you select the output properties of the Integration Object that you want to display. To change a control, select an output property and click Edit. You can add the leading text for the control. Click Finish.

The pages you create go in the Web Content/JSF Pages folder in the ZIETrans Projects view. To edit a Web page and invoke the Rich Page Editor, double-click on the name of the page. To test your pages, right-click on the input page (or output page if there are no inputs) and select either Debug on Server or Run on Server.

Note:

BasicIOErrorPage.jsp and AdvancedIOErrorPage.jsp

The BasicIOErrorPage is the default error page used by JSPs that drive Integration Objects. If an error occurs, it will return basic information to the browser about the nature of the error. The backend connection is automatically discarded in this processing.

The AdvancedIOErrorPage.jsp allows the connection to be passed to the ZIETrans entry servlet for a default transformation if the connection was created from the default connection definition. This processing allows you to interact with the backend connection and possibly determine why the error happened. The default transformation also gives you the ability to disconnect the connection. Basically, the AdvancedIOErrorPage.jsp gives you more control over the processing when an Integration Object encounters an error.

You can find these error pages in the Navigator view, in the Web Content folder of your project.

Working with Integration Objects on JSPs

These ZIETrans tools functions are applicable to working with Integration Objects on JSPs. You can select the items listed below using the ZIETrans Tools menu on ZIETrans Toolkit menu bar.

Insert Integration Object Properties

You can add Integration Object input and output to your transformation JSP.

Input

Select Insert Integration Object Properties > Input when you want to add Integration Object input to a JSP. On the Select Integration Object class page, enter the class name of the Integration Object you want to use and the destination page that displays when the user submits the input form. Click Next. On the Define inputs page, to change a control, select an input property and click Edit. Here you can define the leading text, select an appropriate input control and configure it if necessary, and store the value as a global variable.

Output

Select Insert Integration Object Properties > Output when you want to add Integration Object output to a JSP. On the Select Integration Object class page, enter the class name of the Integration Object you want to use and click the check box Insert Integration Object transaction methods to include the transaction methods that run Integration Objects. Click Next. On the Define outputs page, to change a control, select an output property and click Edit. Here you can define the leading text and select an appropriate output control.

A ZIETrans global variable contains a value that can be used to pass information from one ZIETrans object to another. If you want to pass Integration Object output data to another ZIETrans object, you must add code to the output JSP used to drive the Integration Object. You should add the code after successfully running the Integration Object, for example:

<%
IOGV.setGlobalVariableString(session, "exampleGV", 
exampleIO.getOutputData());
%>

In this example, the shared global variable named exampleGV is assigned the value of the OutputData property of the exampleIO Integration Object.

The global variable used in an Integration Object environment must be defined as a shared global variable. The code in the example creates the shared global variable if it does not already exist.

Insert Forward to ZIETrans Application

Select Insert Forward to ZIETrans Application to add a button to your transformation that forwards JSP control information back to the ZIETrans application (Web application), that your user started. For example, you might want to return control to the ZIETrans application after a JSP drives an Integration Object and performs a designated task. You can edit the attributes of this button in the Design view by highlighting the button, right-clicking, and selecting Attributes.