Integrating a host application with an IBM Business Process Manager business process

This article shows you how to integrate a simple, customized IBM® Host On-Demand Java™ applet that shows a basic 3270 video session, with an IBM Business Process Manager V7.5 or WebSphere Lombardi Edition V7.2 process. This content is part of the IBM Business Process Management Journal.

Gianpaolo Gabutti (, Senior IT Specialist, IBM China

Gianpaolo GabuttiGianpaolo Gabutti is a Senior IT Specialist in Italy, where he works as a business process management consultant in IBM Software Services for WebSphere. He has been working in the IT industry since 1988, and has experience in diverse technologies, such as object-oriented programming, Enterprise Application Integration, J2EE and Eclipse. He holds a degree in Economics from the Catholic University of Milan.

15 February 2012


This article describes how to design and implement a simple, customized Host On-Demand Java applet that provides users with a basic 3270 video session. The applet is capable of running a Host On-Demand macro, received as an input parameter. You'll then learn how to integrate the applet into a process developed with IBM Websphere Lombardi Edition V7.2 or IBM Business Process Manager V7.5, to make it easy and straightforward for users to complete a human task on a 3270 application, using the applet embedded in a Coach, which, in business process management terminology, is a screen or page hosted in an internet browser.

This solution may be useful whenever a human task can be completed only by means of a traditional 3270 application that does not expose web services or in other ways communicate with external systems (these applications are sometimes called "siloed applications"). It may also be useful when you need to keep both a 3270 application and a new solution based on a BPM process operational together for some time. In such scenarios, the process could be used to orchestrate the operations to be performed on the legacy system, and a macro could be used to effectively facilitate the 3270 operations. The use of macros also enables integration at the data level between the process and the 3270 application.

The intended audience for this article includes architects, developers and designers who need a simple way to include in a process a human task that can completed only by using a 3270 video session. It is assumed that the reader has a basic knowledge of Java and of BPM development and terminology.

Overview of the sample

The package provided for download with this article contains an applet developed with Rational® Application Developer V7.5, an example process application (developed with WebSphere Lombardi Edition V7.2, but also usable with IBM Business Process Manager V7.5), and other supporting material that will be explained later in this article.

Although the applet is a simple, custom Host On-Demand applet, it can optionally receive as an input parameter a macro, which is executed once the 3270 video session has been opened. In order to show the usage of Host On-Demand macros, a simple macro is provided to connect to the 3270 application of your choice. Note that the macro provided is only an example and works only within the IBM EMEA intranet. You will need to make some adjustments if you want to use the example macro in your environment, as we'll explain later.

The sample process hosts the custom Host On-Demand applet inside a Coach; more precisely, the unique human activity of the sample process is composed of two server scripts, which prepare the parameters and the macro for the applet, and by a Coach with a custom HTML component to render the applet. The idea is that when the users complete the operations on the legacy system (using the 3270 session hosted in the Coach), they can complete the associated human task in the context of the process.

Pre-requisites to run the sample

The solution in this article was tested on Microsoft® Windows® XP Professional and Windows Server 2008 R2. In both environments, we tested it with Internet Explorer® 8 and Firefox® 8, running the same Java plugin (at 6.0 level).

In order to view the Java applet code, unzip the BpmHodIntegration.jar file and look at the included Java files. If you want to modify or run the Java applet code, you should use a Java IDE (like Rational Application Developer or Eclipse). If you want to run or test the sample applet locally, you should also have the IBM Host On-Demand JAR files, available with the product.

If you plan to use a similar solution in a production environment, you will need a licensed version of IBM Host On-Demand. We used IBM Host On-Demand Version 11 for our demonstration purposes, but older versions should be compatible as well.

To view and run the sample process application, you need Lombardi Edition V7.2 or IBM Business Process Manager V7.5 or beyond.

A IBM Host On-Demand server, although not necessary for the purposes of this article, is useful if you plan to develop new macros or if you need to edit existing macros with the macro editor or the code editor.

A brief introduction to Host On-Demand

A brief introduction to IBM Host On-Demand will help you understand this article.

Note: Some of the material in this section comes from the IBM Host On-Demand Information Center.

Host On-Demand supports emulation for common terminal types, communications protocols, communications gateways, and printers, including the following:

  • TN3270 and TN3270E terminals
  • TN5250 terminals
  • VT52, VT100, VT220, VT320, and VT420 terminals
  • The Secure Shell (SSH)
  • File Transfer Protocol (FTP)
  • Customer Information and Control System (CICS) Transaction Gateway
  • TN3270E and TN5250 printers

Figure 1 shows how a Host On-Demand system works. Host On-Demand is a client/server system. The Host On-Demand clients are Java applets that are downloaded from the web server to a web browser on a remote computer.

Figure 1. How Host On-Demand works
How Host On-Demand works
  1. The user opens a browser and clicks a hyperlink.
  2. IBM Host On-Demand applet downloads to the client workstation.
  3. When the applet is downloaded, IBM Host On-Demand connects directly to any telnet server to access host applications.

Session information is configured in the HTML file or Host On-Demand configuration server.

Host On-Demand client applets can be run as download clients, Web Start Clients, or cached clients. Download clients are downloaded from the web server every time they are used. Cached client and Web Start Clients are downloaded from the web server and stored on the client computer. After the initial download, the cached client is loaded from the local machine. The cached client checks the Host On-Demand server for new versions of the client and automatically downloads the updated version.

Host On-Demand includes the following administrative components:

  • The Deployment Wizard, a tool for creating emulator client HTML files. The Deployment Wizard enables administrators to quickly and easily build Host On-Demand HTML files that are customized for an organization's needs.
  • Administration clients that can be used by system administrators to define common sessions, create users and groups, and perform other administrative tasks on the Host On-Demand server.

You can use the Java component-based Host Access Toolkit to create customized business applications. The toolkit contains a set of Java libraries and application programming interfaces: Host Access Class Library (HACL), Host Access Beans for Java, and Java 2 Enterprise Edition (J2EE) connectors.

The example applet used in this article was developed with the Host Access Toolkit. Obviously the applet needs some configuration settings. Usually these settings are configured in the Host On-Demand configuration server, but for this example we pass the applet as a sole configuration parameter, from the server script, the telnet 3270 server's IP address, which is enough for our purposes. Other parameters are instead hardcoded in the Java code (available in the attached zip file). We also pass the applet a simple executable macro, because this feature may be add value to the solution.

Host On-Demand macros

The macro feature of Host On-Demand enables you to build scripts (or macros) consisting of command sequences that perform actions on the host. If you regularly do the same task when you work with a host system, you can record your keystrokes and the host's responses, save them, and then play the macro whenever you need to perform the same task. This is an ideal way to store frequently used actions for repeated use. Every authorized user can access the macro toolbar (a toolbar to manage macros, optionally available on the 3270 emulation window), record his or her macros using the macro recorder, and save them to the local file system.

Macros are defined in a XML script and usually get stored in the video session configuration files. A macro can be exported in a file with extension .MAC (using the export option of the macro editor); it can also be passed as an input parameter of type String to our example custom applet, as we'll show in this article.

The macro statements are editable through the Code Editor or the Macro Editor of Host On-Demand. In our example, the macro is executed as soon as the session with the host has started.

The Macro Manager

The Macro Manager toolbar contains all the necessary functionality to operate on macros. You can access it as follows:

  1. Start an enabled Host On-Demand client.
  2. Launch a 3270 display session.
  3. Select View => Macro Manager.

The Macro Editor and Code Editor

Both the Macro Editor and the Code Editor are tools that enable updating of existing macros. The Macro Editor has a graphical user interface you can use to edit the different macro parts, while you can use the Code Editor to edit the XML macro file. To access the Macro Editor, click Select a Macro icon from the Macro Manager toolbar. If more than one macro is available, the dialog shown in Figure 2 appears.

Figure 2. Available macros dialog

When Current Session is selected, the dialog shows all the macros defined for the current session. If you select the CLOSE macro and click OK, the CLOSE macro becomes the currently selected macro. Then you can the select the Edit current macro properties button to open the Macro Editor containing the CLOSE macro data, as shown in Figure 3.

Figure 3. Macro Editor UI

The meanings of the different available options in this article is beyond the scope of this article. These are described in the Macro Programming Guide in the Resources section. We only add here that the Screen tab contains the criteria the macro will use to recognize a screen (for example, the presence of a string of characters at a given position), as well as the capability to define prompts (or requests to the user to enter characters that will be used by the macro) and the command (or commands) to be executed when a screen is recognized. Moreover, in the Links tab, you can link together screens in a sequence.

Also, note the Export function shown in Figure 3, which generates a file of type .MAC, and the Import function, which imports a macro stored in a .MAC file into the current client.

The Code Editor provides access to the XML document of the macro, so that you can edit it directly. You can access the Code Editor from the highlighted Code Editor button in Figure 3. Figure 4 shows the Code Editor window.

Figure 4. The Code Editor UI
The Code Editor UI

With these three tools, the Macro Recorder, Macro Editor, and Code Editor, you can define new macros and update existing ones. For further details on all these functions, refer to the Resources section.

Using the example applet to achieve the integration

The example applet was developed using Rational Application Developer V7.5 as the IDE. It is composed of the following Java classes, all contained in the package bpm.hod.integration:

  • Launcher: A utility class to launch the applet as a standard Java application (see the main() method).
  • HodJApplet: This class represents the applet; it can be launched within the Rational Application Developer applet viewer. To do so, you should first set the initial parameter (host and macro) in the launch configuration, as appropriate. Note that the macro parameter is optional and can be set to null if it is not required.
  • HodJFrame: This class is the applet's UI component. Note that in method getDefaultProperties() sets the configuration parameters used by the applet to configure the 3270 display session. Among the other parameters you may set here is the expected screen size layout (the number of rows and columns).
  • MacroExecutorThread: This class is responsible for executing the macro and managing the callback invocations by the implementation of MacroEvent listeners. The class has its own implementation of MacroRuntimeListener, so that when the macro sends a MacroPromptEvent, a message box with a text field to collect the user's input is shown.

These classes are contained in the BpmHodIntegration.jar file and must be set on the Lombardi or Business Process Manager runtime process server as server file, as you'll see. You will probably want to add further functionality to the applet, or create additional macros, which might require a different implementation of the MacroEventListener. Some ideas on how the applet can be improved are listed at the end of the article.

It's important to consider the availability of the JAR files needed by the applet. These files are those containing the classes and resources of the HACL toolkit (Host Access Class Library), specifically:

  • hacp.jar
  • hacp1a.jar
  • hoddbg2.jar
  • ha_en.jar
  • hodimg.jar
  • hadbcs2.jar (double-byte character set)
  • hafntap.jar
  • hafntib.jar (IBM 3270 font)

If you have access to a Host On-Demand server, you'll find these JAR files in the HOD server directory (the <hod_home>/HOD directory). In theory, these JAR files could stay on the server and be downloaded on the client when the applet is invoked; however, due to the huge size of the files, it's better to pre-install them on the client workstation or use a "sticky cache" mechanism, as described below:

  1. To pre-install, copy all the JAR files needed by the Host On-Demand applet (except BpmHodIntegration.jar) onto the client workstation, in the <JAVA_HOME>/lib/ext directory, where <JAVA_HOME> is the Java home directory of the Java Virtual Machine (JVM) used by the Java2 plugin, that is, the Java runtime environment used by your internet browser. To check which Java plugin you are using, refer to the Java control panel.
  2. Use the sticky cache mechanism provided by the Java2 plugin. This mechanism, based on the concept of JAR file versioning, requires the use of the <OBJECT> tag, instead of the <APPLET> tag, and keeps the JAR files in an internal cache (which is not the volatile one of the browser), which is downloaded only if you change the versioning identifier on the HTML page (on the server side). Thus, these JAR files are downloaded on the client only at the first access and are subsequently kept in the cache until the versioning change. The same mechanism can be applied to the JAR file containing the custom applet. Note that we did not use this mechanism in our example.

You should also check that the plugin installed on the client is supported by IBM Host On-Demand; the list of supported plug-ins is available here.

Applets running in a Java2 clients are contained in the sandbox, and therefore require specific permissions to access the local file system, and the custom applet is no exception. This means one of the following is necessary:

  • The file containing the applet's Java code (BpmHodIntegration.jar) must be signed using the signing mechanism available in the Java Development Kit (JDK) environment.
  • All the necessary permissions must be granted to the applet by appropriately setting the java.policy file, which is contained in the lib/security folder in the Java home directory of the client workstation. You can edit this file directly or, preferably, using the Java policy tool (policytool.exe) provided by the plugin's JDK.

The second solution is much quicker and is the one used in this project. In a real production environment the JAR signing mechanism is the preferred one.

For our development tests, we have updated the java.policy file by adding the following entries:

grant codeBase "file:C:/$user/Projects/BPMHodIntegration/-" {

grant codeBase "http://localhost:19086/teamworks/webasset/-" {

The first statement grants the permission called to the Java classes contained in JAR files below the directory C:/$user/Projects/BPMHodIntegration. The exact meaning of a codeBase value depends on the characters at the end. A codeBase with a trailing "/" matches all class files (not JAR files) in the specified directory. A codeBase with a trailing "/*" matches all files (both class and JAR files) contained in that directory. A codeBase with a trailing "/-" matches all files (both class and JAR files) in the directory and recursively all files in subdirectories contained in that directory. This first statement is necessary for testing the applet from an HTML file available on the local file system (in our case at location C:/$user/Projects/BPMHodIntegration).

The second statement grants the permission named to the Java classes downloaded from the URL: http://localhost:19086/teamworks/webasset/-, and recursively to all files in subdirectories contained in that directory. This statement is necessary to test the applet when you deploy it to your local host. Be sure to match the port number in the address to the http port number used by your application server (in Business Process Manager the default value is 9080).

The example macro

As described earlier, the applet receives as input a string of characters representing a macro. The macro has been obtained with the Macro Recorder and subsequently saved on the local file system as Simple Macro.mac.

The macro performs the following operations:

  1. It waits for the session to start and for the first screen to display. The first screen is recognizable by the string “E M E A V A M P” starting at row 1, column 27. This screen (available only on the IBM EMEA intranet) is actually a list of available 3270 applications.
  2. After the first screen has been recognized, it prompts the user for an application name by displaying a simple dialog.
  3. It writes the application name on the EMEAVAMP screen.
  4. It presses the Enter key.
  5. It terminates.

The following shows the XML body of the macro.

<HAScript name="Simple Macro" description="Simple macro"
 timeout="60000" pausetime="300" promptall="true"
 blockinput="false" author="IT023599" 
creationdate="16-Sep-2011 11:11:51" supressclearevents="false" 
usevars="false" ignorepauseforenhancedtn="false" 
delayifnotenhancedtn="0" ignorepausetimeforenhancedtn="true">

    <screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">
        <description >
            <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
            <string value="E M E A V A M P" row="1" col="27" 
                     erow="-1" ecol="-1" casesense="true" 
                     wrap="false" optional="false" invertmatch="false" />

            <prompt name="Choose Application" description="Choose application"
              row="24" col="5" len="20" default="" clearfield="false" encrypted="false"
              movecursor="true" xlatehostkeys="true" assigntovar="" 
              varupdateonly="false" required="true" title="Choose Application"    />
            <input value="[enterreset]" row="0" col="0" movecursor="true"
                             xlatehostkeys="true" encrypted="false" />
        <nextscreens timeout="0" >

Let's take a look of some of the most interesting macro statements:

  • <string>: The <string> tag within the <description> tag, sets a condition for the subsequent actions; it says that the macro can perform the actions as long as the screen has the string E M E A V A M P at row 1 and column 27 (a 3270 video session's screen is organized in rows and columns, like a matrix, and a point on the screen is identified by specifying its row and column numbers).
  • <prompt>: The <prompt> tag within the <actions> tag, says that the macro, once started and before any another activity, will ask the user to enter a value, which will then be transposed to the position on the screen identified by row 24, column 5. Behind the covers, this tag creates a callback event (MacroPromptEvent) that is captured by the MacroEventListener implementation, which is included in the class MacroRuntimeThread.
  • <input> tag: The <input> tag within the <actions> tag indicates an input operation, in other words, the data the macro writes to the screen after the prompt action has been executed (or the prompt actions, as you can have more than one); in this case the enter key is sent to the screen.

For other tags and attributes, refer to the Resources section.

Now you have all the elements to proceed with the integration with Lombardi or Business Process Manager.

Testing the applet locally

The example contains a simple HTML file, BPMHodIntegration.html, that you can use to test the applet locally before sending it to the Lombardi or Business Process Manager server. You may want to do this if, for example, you have updated the applet code or if you want to test your own macro.

In order for the applet to run into your local environment, you must have edited the java.policy file of the browser's JVM, as described earlier, and you must have copied the Host On-Demand's JAR files to the <JAVA-HOME>/lib/ext directory.

Note that in the example HTML file we have "linearized" the macro and replaced the double quote characters with single quote characters. The example also uses the OBJECT tag. We have noticed that this tag does not seem to work correctly when used in Lombardi or Business Process Manager; therefore, at integration time, we used the APPLET tag instead.

To launch the example, double-click on the file. The default browser should start and the Host On-Demand applet should appear in the middle. You should see the applet connecting to the TN3270 server (identified by the host parameter) and the macro being executed. Notice that the applet is expecting a screen organized in 24 rows by 80 columns; this parameter is hardcoded in the Java code).

Don’t forget to update the macro XML because using the example, you will not receive the EMEAVAMP screen if you are not logged into the IBM EMEA network. You'll probably need to change the String tag in the macro (the statement waiting for "E M E A V A M P" to appear at row 1 and column 27, as shown here:

<string value='E M E A V A M P' row='1' col='27' erow='-1' ecol='-1' 
casesense='true' wrap='false' optional='false' invertmatch='false' />

Running the application

Now that you've tested the applet locally, you can proceed with integrating the applet by completing the following steps:

  1. Open the Process Designer in Business Process Manager (or the authoring environment, if you are working using Lombardi) and import the process application included in the package (the HOD BPM Integration sample, HODBIS), >In order to do so, you should import the file HOD_BPM_Integration_Sample - Final_v.1.0.twx into the Process Center.
  2. You will notice that the process application already contains the original BPMHodIntegration.jar file in the server file section (with the applet's Java code). Don't forget to replace this file with the one containing your own applet, if you want to use your own applet.

    The HODBIS application contains a human service called HoD BPM Integration, shown in Figure 5. As the figure shows, the service is composed of an initial server script, Set Parameters, which defines and sets some variables, a second script in which the macro gets prepared, and a coach containing the Host On-Demand applet.

    Figure 5. HoD BPM Integration service
  3. If you have your own macro to test, you should change the Set Macro Parameter component. Note that since the service is executed inside a process, it has access to all the data in the process, giving you the capability to control and personalize the macro's content. If you pass a null value to the applet as the macro parameter, the applet will not try to execute it and the applet will only show the 3270 display session's first screen.

    Note that in the example, the Coach contains only a custom HTML component with the <applet> tag.

  4. Once you have completed your customization, you are ready to test your artifact by simply testing the service in isolation (or the process containing the service). To do this click the Run Service icon. You should see something like the Figure 6.
    Figure 6. Running the applet
    Running the applet


You now seen how it is easy to integrate a Host On-Demand 3270 video session in a task that is part of a WebSphere Lombardi Edition V7.2 process or an IBM Business Process Manager V7.5 process. This type of integration can be useful when there is no other way to integrate an existing legacy application, for example, because it is a "siloed application," or as an interim solution when a more complex integration is technically possible, but there is no time or resources to develop it. This integration can also be useful when you need to demonstrate in a short time the benefits of the BPM technology, for example, in a proof of concept situation.

Following are some suggested improvements that can make the integration more effective:

  • Develop an applet with a printer session in a separate tab.
  • Set, as an input parameter, the display session LUNAME. In our example the LUNAMEis obtained automatically from a pool of sessions by the TN3270 server.
  • Add an additional input parameter, representing a second macro that can be executed when the applet is unloaded; for example, when the applet's destroy() method is invoked.
  • Because the macro is only an XML file, you may want to programmatically create it using data available on the server (perhaps using an XSL transformation).

The solution described in this article is an example of a client-side integration. Other solutions, requiring a more complex infrastructure, are also possible, and you might want to consider using another IBM product, such as Rational Host Access Transformation Services (HATS). With HATS the 3270 sessions are actually hosted on a server and the client receives the data from 3270 applications as if they were a web application. Using HATS could make even tighter the integration at data level between your process and the legacy system.


Sample applicationSourceCode.zip479KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Integrating a host application with an IBM Business Process Manager business process