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.

Structure of a Web-Services Description Language (WSDL) Document

 

Structure of a WSDL document:

Service

– Port definition

   – soap:address

Binding

– soap:binding

– operation

   – soap:operation

      – input

          – soap:body

      – output

          – soap:body

PortType

– operation

   – input

   – output

Message

– part

Types

WebServices

Figure 1: WSDL Structure – visual representation of various sections of a WSDL and the relationships between them.

Any WSDL document is a combination of an abstract service interface and its concrete implementation.

The PortType section represents the service in an abstract way, similar to an ‘interface’ in object-oriented programming (OOP). In other words, it lays down the ‘contract’ between the service provider and the consumer by listing the various operations supported by the web-service as well as the required input and the resulting output of each operation. The inputs and outputs are listed as messages which are described in the Message section of the WSDL.

The Binding section is similar to an interface implementation in OOP. The ‘type’ attribute in the Binding tag points to the PortType  name which is being implemented.

The thing to keep in mind is that the Binding section is where the abstract web-service contract is implemented or realised. Thus, among other things the Binding section describes operational level details such as which protocol to use for transporting SOAP packets (usually HTTP) and how the web-service will be called (style and encoding).

The Service section describes one or more concrete ‘endpoints’ where the functionality of the service can be found.

Figure 1 shows these various sections of the WSDL and how they connect with each other.

Finally the Types section contains schema information for the various inputs and outputs from the web-service operations.