iProcess Connecting to Action Processor through Proxy and JMS – Part 2

Following the first part, I explained the problem scenario and outlined the solution, in this post I present the implementation.

We need to create the following components:

1) Local Proxy – which will be the target for the Workspace Browser instead of the Action Processor which is sitting inside the ‘fence’ and therefore not accessible over HTTP.

2) Proxy for JMS – Proxy which puts the http request in a JMS message and gets the response back to the Local Proxy which returns it to the Workspace Browser.

3) JMS Queues – Queues to act like channels through the ‘fence’.

4) Service for JMS – Service to handle the requests sent over JMS inside the ‘fence’ and to send the response back over JMS.


I will group the above into three ‘work-packages’:

1) JMS Queues – TIBCO EMS based queues.

2) Proxy and Service for JMS – implemented using BusinessWorks.

3) Local Proxy – implemented using JSP.


Creating the TIBCO EMS Queues

Using the EMS administrator create two queues:

1) iPRequestQueue – to put requests from Workspace Browser.

2) iPResponseQueue – to return response from Action Processor.

Command: create queue <queue name>


Proxy and Service for JMS

For both the Proxy and Service to work we will need to store the session information and refer to it when making HTTP requests to the Action Processor. To carry through the session information we use the JMS Header field: JMSCorrelationID.

Otherwise we will get a ‘There is no node context associated with this session, a Login is required.’ error. We use a Shared-Variable resource to store the session information.

Proxy for JMS:

The logic for the proxy is simple.

1) HTTP Receiver process starter listens to requests from the Workspace Browser.

2) Upon receiving a request it sends the request content to a JMS Queue sender which inserts the request in a JMS message and puts it on the iPRequestQueue.

3) Then we wait for the JMS Message on iPResponseQueue which contains the response.

4) The response data is picked up from the JMS Message and sent as response to the Workspace Browser.

5) If the returned response is a complaint about ‘a Login is required’ then remove any currently held session information in the shared variable (so that we can get a fresh session next time).

In the HTTP Receiver we will need to add two parameters ‘action’ and ‘cachecircumvention’ with ‘action’ as a required parameter. The ‘action’ parameter value will then be sent in the body of the JMS Message through the ‘fence’.

In the HTTP Response we will put the response JMS Message’s body as ascii and binary content (convert text to base64), Session information in JMSCorrelationID to Set-Cookie HTTP Header in response, Content-Type Header in response will be “application/xml;charset=utf-8”, Date can be set to the current date and Content-Length to length of the ascii content length (using string-length function).


Service for JMS:

The logic for the Service sitting inside the fence waiting for requests from the Proxy, over JMS, is as follows:

1) JMS Queue Receiver process starter is waiting for requests on iPRequestQueue.

2) On receiving a message it sends the request from the JMS Message body to the Action Processor using Send HTTP Request activity.

3) A Get Variable activity gets us the session information to use in the request to the Action Processor.

4) The response is then sent to a JMS Queue Sender activity which sends the response out as a JMS Message on iPResponseQueue.

5) If the session information shared variable is blank then we set the session information received in the response.

The Send HTTP Request will also have two parameters: ‘action’ and ‘cachecircumvention’ (optional). We will populate the ‘action’ parameter with the contents from the received JMS Message’s body. The session information will be fetched from the shared variable and put in the Cookie header field of the request. We will also put the contents of the JMS Message’s body in PostData field of RequestActivityInput. Make sure also to populate the Host, Port and Request URI to point to the ActionProcessor.

An example, if you Action Processor is located at: http://CoreWebServer1:8080/TIBCOActProc/ActionProcessor.servlet  [using the servlet version] then the Host = CoreWebServer1, Port=8080 and RequestURI=/TIBCOActProc/ActionProcessor.servlet. If you expect these values to change, make them into global variables.


Local Proxy

This wass the most important, difficult and frustrating component to create. The reason I am using a local proxy based on JSP and not implementing the functionality in the BW Proxy was given in the first part, but to repeat it here in one line: using a Local Proxy allows us to separate the ‘behavior’ of the Action Processor from the task of sending the message through the ‘fence’.

The source jsp file can be found here.

The logic for the proxy is as follows:

1) Receive the incoming request from the Workspace Browser.

2) Forward the request received from the Workspace Browser, as it is, to the BusinessWork Proxy.

3) Receive the response from the BusinessWork Proxy also get any session information from the response.

4) Process the response:

a) Trim the request and remove any newline-carriage returns.

b) Check the type of response and take appropriate action – if response has HTML then set content type in header to “text/html”, if response is an http address then redirect             response and if normal xml then set content type to “application/xml”.

c) Set session information in the header.

5) Pass on the response received from the BusinessWorks Proxy, back to the Workspace Browser.


Once everything is in place we need to change the Action Processor location in the Workspace Browser config.xml file. This file is located in <iProcess Workspace Browser Root>/JSXAPPS/ipc/ folder. Open up the XML file and locate the <ActionProcessor> tag. Change the ‘baseUrl’ attribute to point it to the Local Proxy. Start the BW Proxy and Service, iProcess Process Sentinels, Web-Server for the ActionProcessor and the Workspace Browser. Also test whether the Local Proxy is accessible by type out the location in a browser window.

The screenshots given below show the proxy setup in action. The Local Proxy is at: http://glyph:8080/IPR/iprocess.jsp (we would put this location in the ‘baseUrl’). We track the requests in Firefox using Firebug.

In the picture above we can see normal operation of the Workspace Browser. Above we see requests going direct to the ActionProcessor without any proxy.


Above we see the same login screen but this time the Workspace Browser is using a proxy. All requests are being sent to the Local Proxy.


Above we can the Workspace Browser showing the Work Queues and Work Items (I have blacked out the queue names and work item information on purpose). Tracking it in FireBug we see requests being sent to the Local Proxy (iprocess.jsp).


That’s all folks!




iProcess Connecting to Action Processor through Proxy and JMS – Part 1

The iProcess Workspace Browser is a web-based front-end for iProcess. The Workspace Browser is nothing but a web-application which is available in both asp and servlet versions. It does not connect directly to the iProcess engine though. It sends all requests to the iProcess Action Processor which is also a web-application (again available in a servlet and asp version). The Action Processor forwards the request (via TCP/IP) to the iProcess Objects Server which works with the iProcess Engine and processes the request. This arrangement is shown below (with both the Workspace Browser and Action Processor deployed in the same web-server).

Now this setup is fine in an ideal scenario but in most organizations web-servers are isolated (‘fenced’) from the core infrastructure (such as databases and enterprise servers). Usually the access to the core infrastructure is through a single channel (e.g. through a messaging queue server) with direct TCP/IP connections and port 80 requests from outside blocked. In that case you will need to deploy the Action Processor inside the ‘fence’ with the core infrastructure and setup a proxy system to communicate with the Workspace Browser (which will be sitting outside the ‘fence’). The proxy system will transport the HTTP request over the allowed channel (JMS in this example) and return the response. An example is shown below using JMS.

 To implement the above we need to create the following components:

1) Local Proxy – which will be the target for the Workspace Browser instead of the Action Processor which is sitting inside the ‘fence’ and therefore not accessible over HTTP.

2) Proxy for JMS – Proxy which puts the http request in a JMS message and gets the response back to the Local Proxy which returns it to the Workspace Browser.

3) JMS Queues – Queues to act like channels through the ‘fence’.

4) Service for JMS – Service to handle the requests sent over JMS inside the ‘fence’ and to send the response back over JMS.

You might ask why do we need a local proxy and why not call the BW Proxy directly. The reason is very simple. The BW Proxy and Service should be as uncluttered as possible, ideally their only task is to carry the request through the ‘fence’ and bring out the response. Any processing of the request and response should be done somewhere else (and as we shall see in the example there is a lot of processing required).

As we don’t want to fiddle with the internals of the iProcess Workspace Browser, we simply add a Local Proxy which does the processing of the request and response. Then we set the Workspace Browser to send all Action Processor requests to the Local Proxy. This means that the Local Proxy will ‘behave’ exactly like the Action Processor as far as the Workspace Browser is concerned.

To put it in one line: using a Local Proxy allows us to separate the ‘behavior’ of the Action Processor from the task of sending the message through the ‘fence’.


In the example to follow, we have:

1) JSP based Local Proxy (easy to code – no compiling required!).

2) BusinessWorks based Proxy for JMS

3) TIBCO EMS Server based queues.

4) BusinessWorks based Service for JMS


In the next part, the example!


Deploying to a Business Work Service Container

There are three ‘locations’ or ‘containers’ that a Business Work EAR can be deployed to. These are:

1) Business Work Standalone Service Engine

2) Business Work Service Engine Implementation Type (BWSE-IT) within an ActiveMatrix Node

3) Business Work Service Container (BW-SC)

The first two scenarios do not require any special effort during deployment and usually can be done through the admin interfaces (bw-admin for standalone and amx-admin for BWSE-IT). But if one wishes to deploy an EAR to a Service Container then we need to setup the container and make a change in the Process Archive. This tutorial is for a Windows-based system.

Before we get into all that let us figure out what a BW Service Container (BW-SC) and why one would want to use it.

A BW-SC is a virtual machine which can host multiple processes and services within individual process engines. Each EAR deployed to a BW-SC gets its own process engine. The number of such process engines that can be hosted by a container depends on the running processes and the deployment configurations. To give an analogy, the load that an electric supply (service container) can take depends on not just the number of devices (i.e. process engines) on it but also how electricity each device requires (processes running within each engine).

Keeping in mind the above, when using BW-SC, it becomes even more important to have proper grouping of processes and services within an EAR.

The standard scenario when you would use a BW-SC is for fault-tolerance and load-balancing. In other words, to deploy the same service (fault-tolerance) and required backend processes (load balancing) on multiple containers.  Also Service Containers can be used to group related services together to create a fire-break for a failure-cascade.

The first step to deploying to a BW-SC is to enable the hosting of process engines in a container. The change has to be made in the bwengine.xml file found in the bw/<version>/bin directory. Locate the following entry (or add it if you cannot find it):

<name>BW Service Container</name>
<description>Enables BW engine to be hosted within a container</description>

The second step  is to start a service container to which we can deploy our EARs. Go to the command line and drill down to the  bw/<version>/bin directory. There run the following command:

bwcontainer –deploy <Container Name>

Here the <Container Name> value, supplied by you, will uniquely identify the container when deploying EARs. Make sure  that the container name is recorded properly. In the image below you can see an example of starting a container called Tibco_C1.

Starting Container


The third step is to deploy our application to the container (Tibco_C1). Log in to the BusinessWork Administrator and upload the application EAR. In the image below the test application EAR has been uploaded and awaits deployment.

EAR Uploaded

The fourth step is to point the process archive towards the container we want to deploy to. Click on the Process Archive.par and select the ‘Advanced’ tab. Go down the variable list and locate the bw.container.service variable which should be blank if you are already not deploying to a container.

Property Set

Type the container name EXACTLY as it was defined during startup. TIBCO will NOT validate the container name so if you set the wrong name you will NOT get a warning, you will just be left scratching your head as to why it didn’t work. In our example we enter ‘Tibco_C1’ in the box (see below).

  Property Defined

 Save the variable value and click on Deploy. Once the application has been deployed, start the service instance. That is it.

To verify that your application is running on the container, once the service instances enter the ‘Running’ state, go back to the command line and the bin directory containing bwcontainer.exe. There execute the following:

bwcontainer –list

This command will list the process engines running in any active containers on the local machine. The output from our example can be seen below.

Command Line Listing

We can see the process archive we just deployed, running in the Tibco_C1 container.

If you have any other containers they will also show up in the output.

Remember one important point: If a service container goes down, all the deployed applications also go down. These applications have to be re-started manually through the Administrator, after the container has been re-started.


Changing TIBCO Messaging Encoding from ISO8859-1 to UTF-8

If your project has messaging encoding set to UTF-8 but your TIBCO Administrator is set to ISO8859-1 then you will not be able to deploy your project.
The TIBCO recommended encoding to use is UTF-8. But in case you made the mistake of not using UTF-8 (either in your project or in TIBCO Administrator) then you will need to change the encoding.

To change project encoding:
– Click on the root project folder.
– In the configuration panel you will see three tabs [Configuration, Project Settings and Design Time Libraries].
– Click on Project Settings where you will find a drop down titled ‘TIBCO Messagin Encoding’ with two values: ISO8859-1 and UTF-8.
– Select UTF-8 and click Apply and then save your project.

To change it for the TIBCO Administrator:
– Locate the tibcoadmin_.tra file. It should be in: \administrator\domain\\bin
– Open this file in a text-editor and locate the entry ‘tibcoadmin.client.encoding’ and ‘repo.encoding’.
– Change them both to UTF-8 if they are not UTF-8.
– Save the file.
– Restart both the Hawk Agent and the TIBCO Administrator service on the machine.

If the Administrator fails to deploy a UTF-8 encoded project after making the changes above and in the log you see a ‘com.tibco.infra.repository.OperationFailedException: Can not change encoding from ISO8859-1 to UTF-8 because of other existing connection with different encoding’ exception try and restart your Hawk Agent and any other TIBCO related service.

Developing SOAP over JMS Web-Services using TIBCO BusinessWorks and Designer

Version of Designer:

Version of TIBCO EMS: 4.4.3

Some time ago I did a post about developing web-services using TIBCO BusinessWorks. In this post I would like to discuss how to develop a web-service which uses JMS as the SOAP transport instead of HTTP. The problem with developing a web-service bound to a JMS Queue instead of an HTTP transport, is that it can be used only in a homogeneous TIBCO environment.  In other words we need to have TIBCO at both (client and server) ends if we are using a web-service bound to a JMS Queue.

This is so because the WSDL representation of the binding is proprietary to TIBCO (more on this later) as there is no agreed standard for binding SOAP to JMS. Although when I was digging around I did find a ‘working draft’ at W3.org for SOAP over JMS  (http://www.w3.org/TR/soapjms/) so something is being done to plug this gap!

Why all this hassle for SOAP over JMS you ask? Why not stick with good old SOAP over HTTP? Well simply because JMS transport is whole lot more robust and can be scaled up easily without affecting QoS etc.

Introducing the Example

The web-service we are going to create in this example is a relatively simple one. It will take in two integers and return their sum. A fairly simple example but this post is about using SOAP over JMS so that is what we will concentrate on.

The schema for the request and response messages is given below:

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	<xs:element name="add">                   <!-- Request - two integers a and b to be added -->
				<xs:element name="a" type="xs:int"/>
				<xs:element name="b" type="xs:int"/>
	<xs:element name="result" type="xs:int"/>  <!-- Response - the sum of a and b -->
Now the next thing we need to do is to setup the Service Resource. I won't go into the details of how it is done as I have already covered most of the steps in a different post

The reason I don’t need to go into details is because web-services are designed to decouple the operation from the ways of accessing that operation (i.e. the binding). Obviously as binding = message format + transport AND each operation can have different bindings, the only thing that will be different when setting up the Service Resource will be the Binding Section. Furthermore as we are still using SOAP as the message format the only difference that you will see in the Service Resource, as compared to SOAP over HTTP configuration, will be in the Transport sub-tab (see image below).


Service Resource SOAP over JMS

In the Transport sub-tab, if instead of selecting a HTTP connection, a JMS connection is selected in the Transport box (see image above), then you will get options to setup the JMS transport.

Setting up the JMS Transport

Setting up the Transport in case of JMS is bit more involved than HTTP. For the sake of clarity we will use Queues for our web-service instead of Topics. There are four main things to setup once you have selected a JMS connection in the Transport box. These settings are similar to those in the JMS activities such as JMS Queue Sender.

1) JMS Destination – the queue or topic which will contain the JMS message carrying the SOAP as payload.

2) JMS Destination Type – Queue or Topic (depending on what kind of interaction is required).

3) JMS Message Type – Text or Bytes message – we go for Text in the example so that we can examine the SOAP message being sent over the EMS.

4) Acknowledgement Mode – Auto for the example otherwise all the standard and TIBCO EMS specific options are available for selection.

If you select ‘Topic’ as the JMS Destination Type then you can also decide which of the Operations have a ‘durable subscription’.

That is the only difference in changing from SOAP over HTTP to SOAP over JMS as far as the Service Resource is concerned.

Looking at the WSDL

Once everything is setup navigate to the WSDL Source tab in the Service Resource configuration to look at the WSDL which has been generated for the web-service.

<?xml version="1.0" encoding="UTF-8"?>
<!--Created by TIBCO WSDL-->
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.example.com/1301947961037" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:jms="http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS" xmlns:jndi="http://www.tibco.com/namespaces/ws/2004/soap/apis/jndi" xmlns:ns0="http://www.tibco.com/schemas/WebServiceTest/Schema/Schema.xsd" name="Untitled" targetNamespace="http://xmlns.example.com/1301947961037">
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.tibco.com/schemas/WebServiceTest/Schema/Schema.xsd" targetNamespace="http://www.tibco.com/schemas/WebServiceTest/Schema/Schema.xsd" elementFormDefault="qualified" attributeFormDefault="unqualified">
            <xs:element name="add">
                        <xs:element name="a" type="xs:int"/>
                        <xs:element name="b" type="xs:int"/>
            <xs:element name="result" type="xs:int"/>
    <wsdl:service name="JMSAddService">
        <wsdl:port name="AddPortEndpoint1" binding="tns:AddPortEndpoint1Binding">
            <soap:address location=""/>
                <jndi:property name="java.naming.provider.url" type="java.lang.String">tibjmsnaming://localhost:7222</jndi:property>
                <jndi:property name="java.naming.factory.initial" type="java.lang.String">com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi:property>
            <jms:targetAddress destination="queue">inQueue</jms:targetAddress>
    <wsdl:portType name="AddPort">
        <wsdl:operation name="AddOperation">
            <wsdl:input message="tns:InMessage"/>
            <wsdl:output message="tns:OutMessage"/>
    <wsdl:binding name="AddPortEndpoint1Binding" type="tns:AddPort">
        <soap:binding style="document" transport="http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS"/>
        <jms:binding messageFormat="Text"/>
        <wsdl:operation name="AddOperation">
            <soap:operation style="document" soapAction="/Connections/JMSAddService.serviceagent/AddPortEndpoint2/AddOperation" soapActionRequired="true"/>
                <soap:body use="literal" parts="part1"/>
                <soap:body use="literal" parts="part1"/>
    <wsdl:message name="InMessage">
        <wsdl:part name="part1" element="ns0:add"/>
    <wsdl:message name="OutMessage">
        <wsdl:part name="part1" element="ns0:result"/>

Let get back to the issue of lack of standards for SOAP over JMS and why we need TIBCO at both ends.

For that we need to focus down into the Binding and Service elements of the WSDL.

Looking at the Service element (see below), where the method of connecting to the web-service is defined. We find that it contains information about the EMS server (from the Connection resource we set in the Transport box) as well as the queue name we set in the Transport sub-tab.

  <wsdl:service name="JMSAddService">
        <wsdl:port name="AddPortEndpoint1" binding="tns:AddPortEndpoint1Binding">
            <soap:address location=""/>
                <jndi:property name="java.naming.provider.url" type="java.lang.String">tibjmsnaming://localhost:7222</jndi:property>
                <jndi:property name="java.naming.factory.initial" type="java.lang.String">com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi:property>
            <jms:targetAddress destination="queue">inQueue</jms:targetAddress>
We also find two strange new namespaces being used - jms and jndi. Let us see what these namespace prefixes stand for. Scroll right up to the top of the WSDL and you will see the following entries:
These two namespaces have been defined by TIBCO so they are internal and are not 'standardized' as are other namespaces in the WSDL such as xs ( xmlns:xs="http://www.w3.org/2001/XMLSchema") for the schema in Types  or soap (xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/") for SOAP related properties in Binding.
Thus if you are a non-TIBCO client you will have no idea what jms:targetAddress element means in the WSDL. 
Once there is a standard for SOAP over JMS then instead of TIBCO specific namespaces we will see a prefix like soapjms with the definition xmlns:soapjms = "http://www.w3.org/2010/soapjms/" [1] .
Next we look at the Binding element (see below). Here also we find the TIBCO specific JMS namespace as well as SOAP over JMS transport definition (in bold).

<wsdl:binding name="AddPortEndpoint1Binding" type="tns:AddPort">
        <soap:binding style="document" transport="http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS"/>
    <jms:binding messageFormat="Text"/>
        <wsdl:operation name="AddOperation">
            <soap:operation style="document" soapAction="/Connections/JMSAddService.serviceagent/AddPortEndpoint2/AddOperation" soapActionRequired="true"/>
                <soap:body use="literal" parts="part1"/>
                <soap:body use="literal" parts="part1"/>

Again once we have a standardized way of binding SOAP to JMS then instead of the TIBCO specific listing in transport attribute we will have something like “http://www.w3.org/2010/soapjms/”[1].

If we compare the Service and Binding elements above to those in the same web-service but using HTTP instead of JMS we that all namespaces being used to define the connection and binding properties are standardized. That is what makes SOAP over HTTP web-services independent of vendors and implementation languages.

Next we test the web-service. Make sure you save the WSDL Source (i.e. the concrete WSDL) so that our test client can use it.


To test the web-service we will create a client using BusinessWorks. We will use a SOAP Request Reply activity to test the web-service. The images below show how to configure the activity to access the web-service.

SOAP Request Reply JMS Config Main Pane

In the configuration simply select the namespace from the concrete WSDL file we saved for the client. As we are using TIBCO to create the client once you set the WSDL everything will be auto-populated. Go to the Transport Details tab (see below) and there you will see the JNDI and JMS sub-tabs which have also been auto-populated from the WSDL. This is so because TIBCO understands the jms and jndi namespaces and knows what to do with the information in the WSDL.

JNDI Sub-tab:

JNDI Sub-tab in Transport Details


JMS Sub-tab:
JMS Sub-tab in Transport Details

After loading the WSDL and saving the changes the SOAP Request Reply activity will ask you for an input (the two integers to be added).

Test JMS Input

Save everything and load the relevant processes. On starting the test you should see the Request being fired. If you monitor the relevant queue you will see a message being posted on the queue. The message will be consumed by the web-service and it will return the result back to the queue which in turn will be consumed by the client and you will see the output in the process. As we provided ‘3’ and ‘4’ as the two integers to be added in the input (see image above) the result we get is ‘7’ (see below).


<?xml version = "1.0" encoding = "UTF-8"?>
	<ns0:result xmlns:SOAP-ENV = "http://www.w3.org/2003/05/soap-envelope" xmlns:ns0 = "http://www.tibco.com/schemas/WebServiceTest/Schema/Schema.xsd">7</ns0:result>
If you want to take a look at the actual messages being sent in the JMS Message you can always stop the server before sending the request or after sending the request stop the client. The request or response message will remain in the queue and you can view the content (as we are using JMS Message Type of Text) by browsing the queue.
That is the end of the tutorial. Let me know if I have made any mistakes or if you have any suggestions.
Thank you for reading!


How to: Quickly Edit Global Variables in TIBCO BW Designer

Version of Designer used:

Global Variables (GVs) are one of the most important bits of any BusinessWorks project. Every project will have at least one set of GVs, usually to store certain settings centrally. GVs also allow those settings to be changed on a running application without having to re-archive and re-deploy it.

A common usage scenario (which I will be using as an example as well) for GVs is to store connection settings for the EMS server. Basic set of connection settings for say a JMS Connection resource would be the Username and Password information and the JNDI information.

As it is very important to structure the GVs properly for easy reference and maintainability you should make good use of Groups. A common way of structuring GVs is to use the location path as a group.

For example if your JMS Connection resource is in /MyProject/Connections/JMS/ folder then you would create three groups. A main group for all the project GVs called MyProject, below that a sub-group for all Connections in your project and below that a group for all JMS connections and so on.

But if you have tried to use the GV editor in Designer and have been frustrated with forever expanding and collapsing nodes, re-sizing the window and not being able to copy-paste stuff then you will know what a nightmare it is to create complex group hierarchies. Don’t you wish you could just edit an XML file and create those GVs instead of using the built-in GV editor in Designer.

Fear not though, there is a quicker and easier way of  creating and edition GVs (otherwise no point in writing this post 😉

Lets start with a blank canvas so as to say. Open up the Designer and navigate to the Global Variables tab (see image below). Click the yellow pencil button to bring up the dreaded built-in GV editor.

Global Variables in Designer and the Global Variable Editor

Let us say we want to create a complex hierarchy of groups and values but we want to do it without getting frustrated with the built-in GV editor. It is possible to achieve this using the Windows Explorer (or the Linux equivalent) along with a text-editor (even Notepad will do but I prefer Notepad++ as it has XML support).

Basic Concept

Before we start the editing process it is important to understand how the GVs are stored in a project. One would have thought there would be a file with the GV hierarchy and values which we could edit. That thought is partially correct.

The main thing to understand is that every GV Group is a folder within the Global Variable root folder (more on this later). Furthermore every GV is an entry in a simple text file within the folder of the Group it belongs to.

Locate the Global Variable Root Folder

Open up your Windows Explorer and navigate to your TIBCO Designer Workspace folder. There navigate to the project for which you want to create GVs. Within the project folder there should be a folder called ‘defaultVars’. This is the ‘root’ folder for your global variables.

In the example the project name is WebServiceTest and  the path is: [TIBCO Workspace Folder]\WebServiceTest\defaultVars 

DefaultVars.substvar File

Within the ‘defaultVars’ folder you will find a file named defaultVars.substvar. This file can be opened in any text-editor and it contains all GVs belonging to the ‘root’ Group.

If you open this file in a text-editor you will find that it contains XML data. For the above set of GVs (see image) in the ‘root’ Group you will see entries like:



From the above listing we can see that each GV has its own globalVariable element. There are several child elements present for each global variable:

Name – is the ‘name’ of the GV which is also displayed in the Global Variable tree (see figure above).

Value – is the actual value of the GV.

DeploymentSettable – GV can be set during deployment.

ServiceSettable – GV is settable at per service level. Used for TIBCO Adapter archives.

Type – Data type of the GV. Possible data types: String, Integer, Password and Boolean.

ModTime – Time GV was modified.

So the root variable JmsProviderUrl is represented as:


Example Now if we want to create a new set of GVs for a JMS connection with the location WebServiceTest/Connections/JMS then we need to first create the folder structure within the root folder which will give us the corresponding Groups in the Global Variables tab. The folder structure will now look like below: Folder Structure for GV Next we need to add some GVs to the JMS group. To do this go down to the JMS sub-folder and in there create a defaultVars.substvar to store the GVs. Make sure the extension of the file is .substvar. Next open this file in a text-editor and add the following tags:

<repository xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns = "http://www.tibco.com/xmlns/repo/types/2002">

All variables will be defined within the globalVariables tag.

Next we create two GVs one for storing the EMS username (JMS_Username) and one for storing the password (JMS_Password) as below:

<repository xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns = "http://www.tibco.com/xmlns/repo/types/2002">

Save and close the file. Then close and reopen the project in Designer (required to refresh the Global Variable tab).

After reopening the project if you go to the GV tab you will see the following:

ResultAs you can see the two GVs we created in the file are now ready for use. Also notice each of the folders we created within the defaultVars root folder is shown as a Group.

Using this method you can also copy-paste GVs for things like JMS Queue Receiver and Senders to create separate set of GVs for different processes and/or services.

Example project: http://www.fisheyefocus.com/GVTest.zip

Overview with the created GVs on the left hand side and the JMS connection using one of the GVs on the right hand side:
Test Project - Global Variable

The project running:
Test Project - Running

Testing Web-Services in TIBCO Designer Using SOAP UI and Basic Authentication

Versions of software used:

TIBCO BusinessWorks Designer

SOAP UI 3.0.1

A quick round of testing within the Designer before packaging the project and deploying anything on a full scale test setup is always a good idea.

So you have just designed and implemented your first web-service in TIBCO Designer. But what about testing it from outside the TIBCO environment with a non-TIBCO client? After all the point of web-services is to be independent of implementation!

There are several ways of doing this. You could quickly create a client in your language of choice, especially with modern IDEs supporting auto-client generation from the WSDL file. Or you could use a software like SOAP UI and do everything in SOAP without bothering with the SOAP-to-Language API.

Now as such it is VERY EASY to test a web-service running under TIBCO Designer with SOAP UI:

1) Save the WSDL generated by TIBCO (how to save will depend on whether you are using a SOAP Event Source Starter Activity or a Service Resource for your Web-Service).

2) Start SOAP UI and create a new project.

3) It will ask for the WSDL associated with the Web-Service that you want to test, supply the saved WSDL.

4) Click OK and default SOAP requests for all operations will be created by SOAP UI.


Things get a bit complicated when it comes to testing Web-Services which require authentication. This is so because TIBCO leaves authentication with the BusinessWorks Administrator and credentials are defined in the domain (which makes sense). Then how can we check web-services with authentication without needing to package and deploy them?

There is an easy way, especially if you are using basic authentication.

Setting Web-Service to use Basic Authentication

To enable basic authentication in a Service Resource (see image below) you will need to go to the Endpoint Bindings tab within the Service for which you want to set the basic authentication. Select a SOAP endpoint for which you want to setup the authentication. This will give you two tabs, one for Transport and one for SOAP details.

Within the Transport tab you will find a check-box titled ‘Use Basic Authentication’. Select it to use basic authentication.

Basic Authentication in Service Resource


To achieve the same in a SOAP Event Source starter activity just go to the Transport Details tab within the configuration and you will see a similar ‘Use Basic Authentication’ checkbox.

One word of warning: once you select basic authentication your web-service clients will NOT work till you finish the next step and add a valid username and password to the request.

Enable Authentication in Designer

Now that your web-service is setup for using basic-authentication, you need to setup TIBCO Designer to authenticate incoming requests.

To do this copy tibco\tra\domain\[Domain Name]\AuthorizationDomain.properties to  tibco\tra\5.5 (x.x is the version number of the installed TRA, in my case it was version 5.5).

Found this solution here: http://eai.ittoolbox.com/groups/technical-functional/tibco-l/bw-http-basic-authentication-2526019



Final step is to test the web-service using basic authentication.

If you try and invoke the web-service without copying the properties file and without supplying the username and password you will get an ‘Internal Error’ response.

If you try and invoke the web-service without a username or password (irrespective of whether you copied the properties file or not) you will get a ‘This request requires HTTP authentication’ error response.

Once the properties file has been copied to the correct location the only thing that is left is to supply the username and password in the request.

In SOAP UI, navigate to the request generated for the web-service being tested. In the bottom left hand side there will be a Request Properties box (see image below). Scroll till you see the option for Username and Password. Enter the details for the username defined in the properties file (UserID property) and execute the request. This time if all is well then you should get the correct response from the web-service.

SOAP UI Basic Authentication Test

SOAP UI Basic Authentication Test

If you don’t get the correct response make sure you restart SOAP UI and Designer after copying the file.

Always remember to test your web-service WITHOUT basic authentication BEFORE testing with it. This will ensure there is nothing fundamentally wrong with the web-service.

You do not need to refresh the WSDL file for the web-service after enabling/disabling basic authentication. This is because basic-authentication operates at the level of the HTTP request and does not affect the SOAP content which is a payload of the request. Therefore basic authentication is available for HTTP transport only and not for JMS.


Creating a WSDL resource retriever for Service Resource

After developing a web-service using the Service resource from the TIBCO Designer palette (ver. 5.6) we need to develop a resource retriever to allow clients to access the service WSDL.

The basic idea behind getting the WSDL for a Service resource web-service is to use the SOAP Retrieve Resources activity (found within the SOAP menu) and point it to the Service resource for the web-service with the filter set to “wsdl”.

The screenshot below shows the basic process for retrieving the WSDL. We will use the HTTP Receiver process starter connected with the SOAP Retrieve Resources which sends its output to Send HTTP Response activity.


Here is how it works:

  1. A HTTP Receiver forwards the incoming request to a SOAP Retrieve Resources activity (SOAP-RRA).
  2. The SOAP-RRA retrieves the WSDL text and outputs it to the Send HTTP Response activity.
  3. The Send HTTP Response activity then sends the WSDL text as response to the HTTP request received by the HTTP Receiver.
  4. The process ends.

The HTTP Receiver will need an HTTP Connection to complete the configuration.

The key thing here is to configure the SOAP-RRA correctly. The HTTP Receiver even though connected to the SOAP-RRA provides no input to it.

Click on the SOAP-RRA and go to the Input tab in the properties (see the screenshot above). In the Activity Input section we need to configure the resourcePath and filter values.

The reourcePath should point to the Service resource. To get the Service resource path right-click the Service resource for the web-service whose WSDL is required and click on inspect resource.

The Resource Inspector window that pops up will show the resource path for the Service resource (see marked area in screenshot below). Remember to enclose the path in double-quotes!


In the filter value type in “wsdl” (double quotes included) as we want the WSDL to be retrieved.

SOAP-RRA connects next to the Send HTTP Response activity. We connect the resourceData output from SOAP-RRA to the Send HTTP Response asciiContent input as shown in the screenshot below.


The Send HTTP Response activity connects to the End Process activity which completes the process.

Testing the Retriever Process

To test the process start the process tester. Make sure you select the retriever process we have just created AS WELL AS the Service resource for the web-service whose WSDL is being retrieved.

Open up the browser and type in the address defined in the HTTP Connection used for the HTTP Receiver.

The WSDL should pop-up in the browser and if you check the process tester you will find the retriever process would have fired once.

Developing Web-Services with TIBCO ActiveMatrix BusinessWorks


In this post we are going to talk about developing web-services in TIBCO ActiveMatrix BusinessWorks (AMBW). We will be using the following software:

1) TIBCO Designer 5.6 to develop and test-deploy the web-service

2) SOAP-UI 3.0.1 (Freeware) to test the web-service

We are going to be looking at web-service development from a conceptual point of view rather than concentrating on specific implementations.

The TIBCO AMBW Process Design Guide and the Palette Reference do an excellent job of describing web-service implementations.

Before we get into web-service development in TIBCO AMBW let us just review what goes into developing a web-service. As there are many excellent books on web-services out there this section will be restricted to a brief overview.

A web-service consists of three basic components:

  1. Description – all the information about the web-service, including how to invoke it.
  2. Protocol – how to communicate with the web-service.
  3. Implementation – how to implement the operations defined by the web-service.

The Description of a web-service needs to address both, the abstract interface as well as its concrete implementation. As we all know this description is contained in the WSDL file associated with the web-service. With modern tools it is very easy to create client stubs for web-services using just the WSDL.

The WSDL also acts as a contract between the service provider and the consumer. Therefore a skeleton of the web-service implementation can also be created using just the WSDL. This approach towards service development is called the ‘contract-first’ approach where you define the interface before defining the implementation.

The opposite of the above process i.e. ‘implementation-first’ approach allows easy exposure of existing functionality as a web-service.

TIBCO AMBW allows for both styles of web-service development.

Before we go any further it will help to review the structure of a WSDL document.

There are two ways of implementing a web-service in TIBCO AMBW:

1) Service Resource

2) SOAP Event Source process starter

Which route you take depends on your specific requirements as well as the current state of development.

You would ideally use a SOAP Event Source process starter to expose a single process as a web-service over a single transport protocol. In case you need to expose multiple processes over multiple transport protocols and have a clean separation between web-service definition and implementation, use the Service Resource.

I will first focus on using the Service Resource as it (in my opinion) is a cleaner way of doing things and conforms well to the philosophy behind web-services of separation of interface and implementation.

SOAP Event Source will be covered in another post.

Now from the TIBCO AMBW Process Design Guide we have:

“A service joins an abstract WSDL interface to a concrete implementation and exposes them on one or more endpoints”

There are three main steps in setting up a web-service using the Service Resource:

1) Define the service interface using the WSDL and Schema Resource – involves definition of the abstract part of the WSDL as well as defining schema for input and output data using the Schema Resource

2) Setup the endpoint bindings to expose the service.

3) Implement the operations defined in the web-service.

Figure 1 shows the mapping between TIBCO AMBW components and various components of a web-service (as represented in the WSDL).


Figure 1: Mapping between TIBCO AMBW components and various components of a web-service.

Request Context

As the Service Resource separates the service definition from the implementation, there might be a requirement to access the ‘context’ of the request by the implementing process. This ‘context’ could be the client’s digital signature (for authentication) or something simpler like a client ID. The Context Resource allows us to do just this. We can define a schema to store the relevant ‘context’ which can then be accessed by the implementing process using the GetContext and SetContext activities.


I will take the example of a simple web-service for Customer Information Management (add and retrieve customer information). The web-service will contain two operations:

  1. Add Customer Information (name, age and ID).
  2. Retrieve Customer Information using Customer ID with a Request ID for logging purposes.

To get the customer information we supply the customer ID and a request ID to the web-service which will return the customer information.

To add information for a new customer we will supply the customer information (id, name and age).

Going back to the three step process for implementing a web-service using the Service Resource:

Step 1: Defining the web-service interface

We will use the Schema Resource and the WSDL Resource to define the web-service interface including the operations and the associated input/output schema.

The Schema

Firstly create the Schema for the input and output messages using the Schema Resource (within the XML menu).

Below we can see a simple CustomerInformation schema which defines the customer information structure (for both retrieval and addition) as well as a CustomerInformationRequest schema which defines the structure of the incoming request for customer information.


The Web-service Interface using WSDL

Next we define the interface for the web-service using the schema we defined above and a WSDL resource.

We will first define the input and output messages using the schema and then use them to define the operations. All the required resources are in the WSDL menu.

Create a new WSDL resource and double-click it. Add two new Messages: CustomerInformationRequest and CustomerInformation. The output message for the retrieve information operation has the same schema as the input for the add information operation.

Next we define the operations using previously defined Messages. Add a PortType resource to start defining operations. Double click the PortType resource and add two new Operations: AddCustomer and RequestCustomer.

In the AddCustomer operation configuration, add an input message with the message schema set to CustomerInformation (we are now connecting the schema with the interface). We don’t need any output message for this operation.

In the RequestCustomer operation configuration, add an input message with message schema set to CustomerInformationRequest and the output message with message schema set to CustomerInformation.

This can be seen in the screenshot below.


You will notice that till now we have been defining only the interface of the web-service (namely the operations and messages). We have not spoken about things like which transport protocol to use or the style of the web-service (document vs. RPC).

The next step is to use the Service resource to configure the concrete endpoints using the interface we have just defined. After that in the final step we will use the Service resource to join the abstract interface of the service with the actual implementation of the operations.

Step 2: Implementing the service endpoints using Service Resource

Add a Service resource from the Service menu.

The first thing we need to do is to give this service a ‘face’ (in other words define which interface it is going to ‘implement’).

Double-click it and within the Configuration tab click on the ‘+’ button in the ‘Implementation’ section. In the window that pops up locate the WSDL file (on the left side) with the abstract interface that you have defined in Step 1. The PortType, Namespace and Operations will be loaded from the WSDL on the right hand side. This is shown in the screenshot below.


Check the operations and the input and output for them. Click on ‘OK’.

The Service resource should contain a whole lot of new stuff now (see screenshot below). In Configuration tab, the Implementation will have two tabs: Operations and Endpoint Bindings.


The next thing to do is to create the endpoint for the service. This involves defining style and encoding of the service and the operations and selecting the transport for the service.

Click the ‘Endpoint Bindings’ tab and then the ‘+’ to add a new endpoint. Change the Endpoint Type to SOAP and two more tabs will come up: Transport and SOAP Details.

Transport tab requires you to select a HTTP connection (as we are going for SOAP over HTTP in this example), which is required to host the service. Once the transport connection is set up you will see the Endpoint URI appear below it.

Next move to the SOAP Details tab. Define the default service style (document or RPC – in present example document) and the styles and encoding for the different operations within the service (in our case document – literal). You can set style to ‘Use Default Style’ to make your life easier in case of multiple operations.

The screenshot below shows this.


The final step is to go ahead and implement the operations we have defined in interface.

Step 3: Implementing the service operations

Firstly we create the processes for adding customer information and requesting customer information. The only thing I will say about creating the processes is that the Start and End activities must have their outputs and inputs same as the WSDL messages setup for the corresponding web-service operation.

For example the process to handle request for customer information (i.e. RequestCustomerOperation) should have output for the Start activity a WSDL message: CustomerInformationRequest (that is the input going in to the RequestCustomerOperation). Same goes for the input to the End activity which should be a WSDL message: CustomerInformation.

Go back up to the Operations tab and click on the ‘binocular’ button in the Operation Implementation column next to the operation to be implemented. All processes which have input and output WSDL messages matching the operation to be implemented will be shown in the window that pops up. Select the relevant processes. Do the same for all the operations defined in the interface.

The screenshot below shows the two operations for the example being implemented.



Everything is now set for the web-service to be tested. But before we test the service it is worthwhile to see the WSDL for the service that we have just created. Go to the WSDL Source tab in the Service resource. This is the WSDL for the service. You will need this file to create a test client.

There are two ways to give a client access to the WSDL. First is to setup a WSDL retrieval process using SOAP Retrieve Resources resource with a HTTP Receiver process starter. Then the client will be able to download the WSDL as normal. The second option is to save the WSDL file (by clicking on Save WSDL in WSDL Source) and providing a local copy to the client.

We shall use SOAP UI  (free edition) to test the TIBCO web-service. We setup a new SOAP UI project with a local copy of the WSDL file. SOAP UI creates test requests for the web-service as a part of the project setup.

Make sure in the TIBCO Designer the Service resource and the processes implementing the operations have been selected and run.

In SOAP-UI, go to the test request for the operation to be tested and double-click it. A blank request will open up with ‘?’ where you need to fill in data to complete the request.

After filling in the data, execute the request by pressing the green ‘play’ button. On the right-hand side you will see the response of the request (if the operation has a response). In case of an error you will see an error response.

The screenshot below shows a test of the RequestCustomerOperation. The customer information request sent is on the left-hand side and the response from the example web-service received on the right-hand side.



Hope this limited example has explained how to setup a basic web-service in TIBCO AMBW using the Service resource. There are several things that I have left out including using the SOAP Event Source process starter, using Contexts and retrieval of WSDL. All these topics deserve complete posts in themselves that is why I aim to cover them as and when I get the time!

Note: If you are going to deploy to BW engine then you will need to create an archive file (.ear). Remember to include the Service Resource (if you are using it) in the Process Archive starter processes before building the archive.

Please leave comments and suggestions.


Have added a new post on WSDL retrieval for Service resource-based web-service.

Installing TIBCO iProcess Engine SQLServer (11.1.0) on Windows Server 2003


1) Administrator rights on the target server

2) iProcess Engine (version 11.1.0)

3) pthread.dll – POSIX thread implementation for Win32 environment. 

4) SQLServer instance with user account having the correct permissions (see below) – as we will install the SQLServer version of the iProcess Engine.

NOTE: The installation process may require several re-starts, especially if you also install SQLServer instance on the same server, so make sure that the server can be restarted without problems.

VERY IMPORTANT NOTE: During the install process you will be required to supply a lot of information including usernames, passwords, node names, port numbers etc. Make sure you note these down as you complete each screen of the install wizard. It is very easy to forget a password or username when you really need it!

Space requirements:

iProcess Engine ~ 370 – 400 MB

Installation process:

The installation process is quite straight forward with a wizard like interface.


1) Copy pthread.dll to the windows/system32 folder. This is required and the installation process will not start till the pthread.dll file is in the right place. On Windows 7 the folder to use for pthread.dll is windows/SysWOW64.

2) SQLServer access – make sure you can connect to the SQLServer instance and make a careful note of the connection parameters, username and password to be used. Also make sure the username you use has permission to create new databases/tables.

The installer will ask you for this information as the iProcess engine stores all its information in a database. The installer creates the main iProcess database and various tables, within it, as a part of the installation process. The easiest way of messing up the install is to give it a username which doesn’t have the required permissions to perform the table creation activity.

3) Log in as administrator.


The install section is fairly straight forward and is well covered in the TIBCO iProcess documentation. I will, therefore, not do a step by step description here but give an overall picture of the install process.

The install process starts off with various iProcess Engine related settings such as the node name (default: staffw_nod1).

NOTE: If you change the iProcess node name MAKE SURE you record it as you will be needing it almost everywhere.

Things done during the install process:

1) Define node name.

2) Define licensee name, which for some strange reason has to be at least 4 characters long.  

3) Define a new iProcess administrator account (username and password).

4) Option to require users to login using a password (it is a hard to miss checkbox at the bottom of the screen).

5) Setup a SQLServer connection and create two new SQLServer user accounts (usernames and passwords): swpro and swuser 

6) Setup Business Studio deployment (WebDAV), JMS connectivity, Email server as well as the iProcess web-server.


iProcess Objects Server Configuration –

This is where the fun really begins. Now is the time to configure the iProcess Objects Server. This bit is specially important if you are planning to install the TIBCO BusinessWorks iProcess plugin. Basically the plugin needs DB connection information. So you might want to select ‘ENABLED’ here.

A very important thing that you will need to do during this step is to setup the port for TCP. Open up the ‘services’ file in windows/system32/drivers/etc and scroll all the way to the bottom. There you should see two entries for iProcess similar to:

NODENAME_worker    PORTNUMBER/tcp      # Entry inserted by installer
NODENAME_watcher  PORTNUMBER/tcp      # Entry inserted by installer
Below the last entry add your own entry to define the TCP port to be used by the iProcess Objects Server (replace CAPPED entried with your values):

PORTNAME       PORTNUMBER/tcp               #Your comments

Copy-paste the PORTNAME to the TCP port textbox in TCP Settings tab in the iProcess Objects Server Configuration. 

Save all settings and close the Configuration panel. Then restart the server.

After restart go to the ‘Services’ section of the Administrative Tools panel and locate the iProcess service (there will be two services if you also installed the iProcess web server).

NOTE: Make sure the SQLServer on which the iProcess database was created is up and running.

Start up the ‘iProcess Process Sentinals’ service. 

 If everything has been installed properly then the service will start up normally (it takes some time to do so, don’t be worried if you don’t see the progress bar moving for some time).

In case the service does not start up normally (Windows will throw up an error message) the FIRST thing to check is whether the SQLServer instance, you created the database on, is reachable and you can login with the same credentials you provided (swpro) during the install.

Testing the install:

The best way to test the install (ONLY if you are the administrator AND you have studied the documentation) is to play around with ‘swadm’  in the ‘swserver/NODENAME/util’ directory.

One of the things you might want to do is allow addition of non-OS users to iProcess, especially important if you have enabled external authentication (e.g. through LDAP). 

Open up command line interface and go to the ‘util’ directory. Type in and press enter the following command:

swadm set_attribute 0 ALL 0 DISABLE_USER_CHECK 1

The above command sets up a new attribute called DISABLE_USER_CHECK with the value of ‘1’. It will allow the addition of non-OS users for all processes. 0 is the Logical Machine ID, ALL signifies do it for all processes (otherwise add process name) and 0 is for the process instance.

An easier way to check it is to install the Windows-based Workspace Browser (11.1.0) and point it to the new iProcess engine.

NOTE: I have done a similar install on Windows 7 – 64bit edition. While TIBCO does not support iProcess Engine SQLServer (11.1.0) on Windows 7, there were no problems in the installation and the performance was up to the mark.