Programmatically invoking WebFacing applications from other Web applications

WebFacing applications can be invoked programmatically from other Web applications. This provides a way to integrate WebFacing generated user interfaces with existing Web applications.

WebFacing applications are launched from URLs. Typically, a URL is represented as a link that a user clicks to start the application. During WebFacing conversion, URLs are written to an index.jsp file and after the application is deployed, these are the links users click to start the application. However, WebFacing URLs can also be constructed dynamically by other programs such as controller servlets. These URLs could be sent back to users as links to click on a Web page. But, more importantly, they can be used in the forward() and sendRedirect() methods in other Web applications. Using dynamically determined WebFacing URLs with forward() and sendRedirect() methods means that a program like a controller servlet can perform actions such as determining the host to use, the WebFacing program to launch, what CL command to use for the WebFacing program, or other actions. After these actions are completed, the servlet can provide the appropriate WebFacing application, with its parameters already set, directly to a user.

With control of how WebFacing is invoked, it is also possible to use alternative methods of authentication. All user authentication can now be performed in a custom servlet before WebFacing is called. The authentication mechanism used must be able to provide the WebFacing application with i5/OS® user credentials so that it can access i5/OS resources.

Here is a simple example for a determining the CL command to use to launch a program:

URL constructed by a controller servlet:
WFInvocation.do?clcmd=call%20ordentr
In this example, ordentr is the name of a program to launch. The value ordentr could be determined by a servlet and assigned to a variable such as orderProgram . Your servlet could construct the URL string using the value determined for orderProgram and assign it to a variable newURL using a line like:
newURL = "WFInvocation.do?clcmd=call " + orderProgram;
newURL could then be used as the forward or redirect URL for your forward() or sendRedirect() methods.
In this example, the complete URL used by the browser, if sent as a redirect, would look like:
http://<hostname>:<port>/<application>/WFInvocation.do?clcmd=call%20ordentr

The example shows the full URL beginning with http://<hostname>:<port>/<application>/ . The value for newURL is the string after this. That is, the string: WFInvocation.do?clcmd=call%20ordentr . In an example like this, the first part of the URL: http://<hostname>:<port>/<application>/ , represents the host, port, and context root for the application. If your controller servlet is in the same context root, it is not always required for the servlet to determine the entire URL. If necessary, though, you could code the servlet to construct a string for the fully qualified URL.

Note: The characters %20 in the URL represent a space character as encoded when sent to a browser. Space characters generally cannot be used explicitly in URLs. In the example where the URL string is being constructed and assigned to newURL , the space is present in the part of the string just after clcmd=call . The reason for the space in the string is that the example represents a CL command call ordentr . In the URL string that is being constructed , it is not necessary to add %20 directly. The server will add this encoding if necessary.

URL parameters that can be determined dynamically

clcmd
CL command to launch the program.
host
Host name where the original 5250 application is located.
userid
userid is used to log onto the application. Note: If a forward() method is used in your controller servlet, URL parameters are only sent within the application server tier (middle tier). Using sendRedirect() instead exposes URL parameters to the browser. In this way, sendRedirect() is less secure because information such as user IDs and passwords can be revealed in a browser's location field, or if a user views the properties for the page they are using.
password
Password used to log onto the application. Note: If a forward() method is used in your controller servlet, URL parameters are only sent within the application server tier (middle tier). Using sendRedirect() instead exposes URL parameters to the browser. In this way, sendRedirect() is less secure because information such as user IDs and passwords can be revealed in a browser's location field, or if a user views the properties for the page they are using.
inv
The invocation name for the WebFacing CL command used to launch the application. If values such as host, user ID and password are defined for a CL command, these values will override the general values specified for a project. To view the invocation name for a CL command, open the WebFacing perspective in the workbench, click the WebFacing Projects tab, expand your WebFacing project, expand the CL Commands folder and click the label for the command. The value for the invocation name can be viewed in the Properties pane. (If the Properties pane is not displayed in the WebFacing perspective, to open it, click Window > Show View > Properties.) To edit the invocation name, right-click the CL command in the WebFacing Projects view, and select Properties.

Filtering programmatic invocation commands

You can specify the CL command prefixes that will be allowed for programmatic invocation using the clcmd parameter. Programmatic invocations that use the clcmd parameter and specify a value that does not start with a prefix that you allow will be blocked from running. The default is to not allow any programmatic invocations that override the CL command to be run.

For migration of projects from WebFacing plugin version 5.1.2.2 and earlier to V6, a special value of *ALL will be included to allow all CL commands to be run.

<context-param>
	<param-name>WFCLCMDAllowed0</param-name>
	<param-value>*ALL</param-value>
</context-param>

If the clcmd parameter is not used or if the clcmd values that are used are known, you should remove the *ALL value and provide values as indicated below.

To specify which command prefixes are allowed, edit the source of the web.xml file for your WebFacing application. Add parameter names consisting of WFCLCMDAllowed, followed by additional text to make each parameter distinct. Then add a parameter value for each to specify the command that is being allowed. The following example allows all commands that start with CALL MYCMD and GO MYMENU.

<context-param>
	<param-name>WFCLCMDAllowed0</param-name>
	<param-value>GO MYMENU</param-value>
	<param-name>WFCLCMDAllowed1</param-name>
	<param-value>CALL MYCMD</param-value>
</context-param>

Provide additional context parameters with values as required.

This will allow clcmd values such as CALL MYCMDisOK or CALL MYCMD PARAM(ONE), but disallow values such as CALL MY or CALL OTHERCMD. Similarly for GO MYMENU, allowed commands must start with the specified string. Case is ignored for the comparison.

Note: This only affects programmatic invocation using the clcmd parameter. WebFacing invocations using the inv parameter are unaffected.

Example URLs

WFInvocation.do?clcmd=call%20ordentr
CL command call ordentr is passed by the URL. Host, user ID, and password in the deployment descriptor file web.xml will be used. Prompt user to logon only when user ID or password are missing or prompt is specified. Print error message if user ID or password are incorrect.
WFInvocation.do?inv=INV1
Host, user ID, password, and CL command will be retrieved from the deployment descriptor file web.xml. CL command invocation name is INV1. Prompt only when user ID or password is missing or prompt is specified. Print error message if user ID or password are incorrect.
WFInvocation.do?inv=INV1&host=SYSTEM1&userid=WEBFACING&password=WEBFACING
CL command invocation name is INV1. Host, user ID, and password are passed by the URL. Multiple parameters are separated by &.
WFInvocation.do?clcmd=call%20ordentr&host=SYSTEM1&userid=WEBFACING&password=WEBFACING
CL command call ordentr is passed by the URL. Host, user ID, and password are passed by the URL. Multiple parameters are separated by &.
Fully qualified example

http://<hostname>:<port>/<application>/WFInvocation.do?clcmd=call%20ordentr&host=SYSTEM1&userid=WEBFACING&password=WEBFACING

Note: in this example the strings <hostname> and <port> refer to the hostname and port for the application server where the WebFacing application is deployed. <application> is the context root for the deployed application. The example shows the following values being passed by the URL: CL command is call ordentr. Host where the 5250 application is located is SYSTEM. The user ID is WEBFACING. The password is WEBFACING. Multiple parameters are separated by &.

Servlet methods for calling a WebFacing application programatically

There are two servlet methods for calling a WebFacing application programatically. They are:
  • forward() -- The forward() method is in the javax.servlet.RequestDispatcher class.
  • sendRedirect() -- The sendRedirect() method is in the javax.servlet.http.HttpServletResponse class.
The most important differences between these two methods are listed below:
javax.servlet.RequestDispatcher's forward() method javax.servlet.http.HttpServletResponse's sendRedirect() method
A Server-side call. This method calls the other resource, retrieves its output, and returns it to the client. Sends the HTTP 302 status code to the browser. The browser will automatically re-connect to the URL of the resource. In this case, the browser knows that the output came from the other resource.

Feedback