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):

<property>
<name>BW Service Container</name>
<option>bw.container.service</option>
<default></default>
<description>Enables BW engine to be hosted within a container</description>
</property>

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: 5.5.2.2

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"
	 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">                   <!-- Request - two integers a and b to be added -->
		<xs:complexType>
			<xs:sequence>
				<xs:element name="a" type="xs:int"/>
				<xs:element name="b" type="xs:int"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="result" type="xs:int"/>  <!-- Response - the sum of a and b -->
</xs:schema>
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">
    <wsdl:types>
        <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:complexType>
                    <xs:sequence>
                        <xs:element name="a" type="xs:int"/>
                        <xs:element name="b" type="xs:int"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
            <xs:element name="result" type="xs:int"/>
        </xs:schema>
    </wsdl:types>
    <wsdl:service name="JMSAddService">
        <wsdl:port name="AddPortEndpoint1" binding="tns:AddPortEndpoint1Binding">
            <soap:address location=""/>
            <jndi:context>
                <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>
            </jndi:context>
            <jms:connectionFactory>QueueConnectionFactory</jms:connectionFactory>
            <jms:targetAddress destination="queue">inQueue</jms:targetAddress>
        </wsdl:port>
    </wsdl:service>
    <wsdl:portType name="AddPort">
        <wsdl:operation name="AddOperation">
            <wsdl:input message="tns:InMessage"/>
            <wsdl:output message="tns:OutMessage"/>
        </wsdl:operation>
    </wsdl:portType>
    <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"/>
            <wsdl:input>
                <soap:body use="literal" parts="part1"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" parts="part1"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:message name="InMessage">
        <wsdl:part name="part1" element="ns0:add"/>
    </wsdl:message>
    <wsdl:message name="OutMessage">
        <wsdl:part name="part1" element="ns0:result"/>
    </wsdl:message>
</wsdl:definitions>

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:context>
                <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>
            </jndi:context>
            <jms:connectionFactory>QueueConnectionFactory</jms:connectionFactory>
            <jms:targetAddress destination="queue">inQueue</jms:targetAddress>
        </wsdl:port>
    </wsdl:service>
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:
xmlns:jms="http://www.tibco.com/namespaces/ws/2004/soap/binding/JMS" 
xmlns:jndi="http://www.tibco.com/namespaces/ws/2004/soap/apis/jndi" 
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"/>
            <wsdl:input>
                <soap:body use="literal" parts="part1"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" parts="part1"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

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.

Testing

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"?>
<outputMessage>
	<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>
</outputMessage>
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!



					

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

Versions of software used:

TIBCO BusinessWorks Designer 5.5.2.2

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

 

Testing

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.

wsdlretriever

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!

resourcelocation

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.

resourceresponse

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).

WebServices_ServiceResource

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.

Example

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.

schema

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.

wsdl

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.

service1

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.

service2

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.

service3

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.

service4

Test

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.

test

 

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.

Update:

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

Pre-requisites:

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.

Pre-install:

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.

Install:

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.

Post-install:

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.

Preparing TIBCO iProcess to connect with Business Works in Windows 7

TIBCO iProcess and Business Works are very easy to work with ONCE you have everything set up. The big catch is ONCE. Especially when you are trying to set it up in an environment which is not supported (i.e. Windows 7 and MS SQL Express 2008).

ENVIRONMENT SETUP

OS: Windows 7

Database: MS SQL Express 2008.

Tibco: Active Matrix Business Works 5.7, iProcess Engine 11.1.0, Business Works iProcess Plugin 11.0.1

Connecting iProcess with Business Works requires the TIBCO Technology Plug-in (specifically the Business Works iProcess Plugin).

Once you install the plug-in you will see iProcess components on your Business Studio palette.

CREATING A CONNECTION

To work with iProcess you need to create an iProcess connection. It has a very helpful option to ‘test’ the iProcess connectivity. I would recommend creating a connection and using the connectivity test feature before you start any EAI project involving iProcess and BW.

If you get ‘icudt36’ or any other ‘UnsatisfiedLinkError’ you might be missing the location of the iProcess plug-in related files from your Windows PATH environment variable. All the required libraries for iProcess can be found in the business works plug-in directory within the bin sub-directory (e.g. tibco\bw\plugins\bin). 

The second issue you might face, if you have selected ‘auto config’ in the Database Connection tab,  is regarding ‘database connection information’ not being sent to the client. If you have tried setting DB connection information to ‘enabled’ in the User tab in the iProcess Object Server configuration utility ‘SWEntObjSvCfg’ and still no luck then you need to get into the Windows Registry and edit the settings there. The settings can be found in ‘Staff EntObj Server’ key. Locate your node and then set ‘DBConnectionAccess’ string data to ‘1’ if it is set to ‘0’.

STARTING AN iPROCESS CASE and CASE MANAGEMENT

Once you are able to connect to an iProcess engine the next thing is to start/stop cases and in general do some ‘case management’.

You might face problems related to ‘Distributed Management Objects’ (e.g. error BW-iProcess-001001) then you need to get ‘Microsoft SQL Server 2005 Backward Compatibility Components’ which contains the DMO component and ensure that the ‘swpr’o (or whichever database user you set up for iProcess) has sysadmin role in the database.

You may need to change the SQL configuration to enable OLE Automation using ‘sp_configure’ and change execution permissions for certain stored procedures if you get errors related to ‘not being able to execute stored procedure…’.