Forward to URL action (Web-only)

The forward to URL action enables you to pass control from a transformation-oriented ZIETrans Web application to a JSP that invokes one or more chained Integration Objects. This enables you to use Integration Objects that you have already created. The Integration Objects can use the existing connection or a background connection.

This action is supported in ZIETrans Web projects

To add a forward action to an event, you must specify the following parameters:

The JSP to which control is passed. In addition to invoking the Integration Objects, this JSP can interact with the user if information is needed.
The startStateLabel of the first Integration Object to be run. This value is used by the ZIETrans application to store the default connection to ensure that it will be available to the Integration Objects.
Note: This parameter is only required if the default connection needs to be passed to the JSP/Integration Object logic.

Note: If you plan on running a large JSP, set the JVM system property com.sun.tools.javac.main.largebranch=true and then restart the server. You can set JVM properties by using the administrative console, by setting up arguments for the JVM, or by creating a Custom Property.

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

The ZIETrans application has already established a default connection and you want the JSP/Integration Object logic to use this connection. In this case, the JSP that gains control should drive an Integration Object that is not first-in-chain. The Integration Object that is driven will locate the connection to use by looking up the connection in the HTTP session object using the start state label that was associated with the Integration Object when it was created. This label should match the label that was specified as part of the forward to URL definition. In this case, note that when control is returned to the transformation-oriented project, a check will be made to see if the host screen has been updated. If it has, all remaining actions in the action list associated with the current event will be ignored. If the host screen has not been modified, the remaining actions will be honored.
The ZIETrans application has already established a default connection, but you want the JSP/Integration Object logic to use a new background connection. In this case, the JSP that gains control should drive an Integration Object that is either first-in-chain or not chained at all. The Integration Object will cause a new background connection to be established and perform its designated task against that connection. Note that the startStateLabel does not need to be specified in the forward to URL definition in this situation.
A default connection has not been started. This will be the case if you add the forward to URL action to the Start event or to the Connect event (before the obtain action is performed). In this scenario, many possibilities exist. For example, the JSP that gains control can drive an Integration Object that gets its own background connection, performs a designated task, and is programmed to return control to the ZIETrans application. At that point, the ZIETrans application can continue with the event processing and establish a default connection. Another possibility would be that the JSP drives an Integration Object that is first-in-chain. The Integration Object establishes a connection, performs a task, and then passes the connection to the ZIETrans application to be used as the default connection.
When the connection is established by the first in chain Integration Object, it is saved using a link created by the first in chain Integration Object.
In this scenario, subsequent Integration Objects must reuse the same link. The link can be retrieved from the first Integration Object calling the getHPubLinkKey() method. If necessary, the link can be passed to subsequent JSPs as a parameter on the request object. This can be accomplished by adding a hidden input parameter to a form, as shown below:
```
<INPUT NAME="<%= CommonConstants.HPUB_LINK_KEY %>"
       VALUE="<%= ExampleIO.getHPubLinkKey() %> "TYPE="hidden">
```
The subsequent JSP would use the following statement to retrieve the key and set it on the IO, before calling the processRequest() method:
```
ExampleIO_2.setHPubLinkKey
 ((String)request.getParameter(CommonConstants.HPUB_LINK_KEY));
```

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

For example, in a Web project, the FORM might look like this:

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

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

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

If you want to pass the connection to the ZIETrans application, you must then edit the JSP and add the line of code right after the "FORM NAME=" line of code.

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

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