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:
- Description – all the information about the web-service, including how to invoke it.
- Protocol – how to communicate with the web-service.
- 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.
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:
- Add Customer Information (name, age and ID).
- 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.
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.
It’s great to see these how-tos on the web for new starters to TIBCO, shipped documentation often falls short of telling you succinctly how to address your issue, so a big thanks.
A word of caution to anyone thinking of using SoapUI for testing though, it is extremely time consuming to set up any kind of automated testing. Green Hat’s GH Tester is a purpose built application for test automation of TIBCO projects and offers incredible time-savings and fast return on investment, we have many converts from SoapUI.
Its very useful
Could you please give an alternate version of the above example with JMS. I tried it and didint work. JMS worked with SOAPEventSource (means noting wrong with queue or messages in queue) not with service Resource.What I found is that the Http Transport is working and JMS is not working on the same SerivceResource.
Could you please describe what error do you get/what happens when you try and run it? Is it a Binding error?
i need to work on designing tibco webservice with two way SSL. wil you be be able to giuide me through a example of creating bw webservice with two way SSL enabled i will pay as required
Hi, I followed your steps in creating this CustomerInformation web-service. But sending test request from soapUI results in errors!
For AddCustomer I receive a BindException in the process starter, and for RequestCustomer I get an Internal SOAP Error.
Can you please provide your test-project as ZIP archive, so that I can see what I’m doing wrong?
Thanks and regards, rainer
Hi, again 😉
I got the service running after starting from scratch! I also deployed it to my BW test engine and retrieving the WSDL works fine. But how can I test the operations from soapUI? The retrieved WSDL contains localhost in the soap:address? Should I change the hostname by hand in the WSDL file?
Never make changes to the WSDL file by hand. Use global variables wherever possible. To test from Soap UI you will need the WSDL file (generated by TIBCO) which you can use to create a SOAP UI project. Then you can invoke each of the operations through SOAP UI by providing test data.
Hope this helps!
this is very useful who are initiate with webservice thanq.
Very useful How-to guide for TIBCO web service. It would be great if you can enhanced this post by adding some material which shows the use of Contexts in web services.
Can you please advice how to write the Processes AddCustomer and GetCustomer and also how to see them in Service – Operation Implementation. very very helpful to me if you can provide the source.
Thanks in advance.
The addCustomer and getCustomer processes were blank implementations because I was exploring the service creation side of things. The main thing to remember is – till you don’t define the process inputs and outputs as what is defined in your Operation, the process won’t be showing up in the Operation Implementation. The ‘signature’ of the process must match that of the operation. Let me know if you still need help.
awesome tutorial………….i cudn’t find nething better.this tutorial is
precise and clear.
please upload some more tutorial on web services.
thnx a lot !!
Will surely do… will try and post one on Contexts soon. Thank you for your comment!
Thanks a lot for this tutorial. I am very new to TIBCO and this was the best resource that helped me. I am stuck with creating process definition part adn am not able to get that visible on Service resource like Venkat. This is what i did.
1. I used basic celcius to fahrenheit conversion web service which takes one double paramter as input and gives back one double parameter.
2. I created process definition. The start activity has the output of WSDl message which is soapinput for the conversion process and the input for end activity is the soapoutput of the process. I followed what you mentioned on the blog, but a little blindly lol. May be I am missing something.
Can you please post on creating the process definition for this web service, please? It would really be helpful.
Thanks a lot
Thank you so much for such a detailed post.
I tried with this example, it worked very well. But I stuck with one doubt. is it possible to get the outputs from two operations at a time while running? Because it is giving output for the one operation which is selected in the concrete wsdl on soap request reply activity of client process.
Could you plz tell me that why we use soap action
We use the SOAP actions to implement web-services in TIBCO. When you use the SOAP process starter it ties in the interface to the implementation.
To get around this we have the Service Resource method of creating web-services.
The method chosen is usually determined by practical reasons (e.g. is it just one process that has to be exposed as a WS over a single protocol or are you looking to create a more complicated WS interface which may be exposed over multiple protocols)
If you wanted you could call the two processes from within the one process defined in the WSDL. Then you would have to somehow combine the two results.
As I do not know the specifics of the problem – the only thing I can advise is examine if you need to break it into two separate operations even in the WS interface.
can u plz share the project file….i m new to tibco…and i m stuck with addCustomer and getCustomer processe definations…plz reply
I am new to Tibco Designer – i tried this example however i am stuck at the service creation step …and see the following errors – in the WSDL Source tab of the Service ..
[Service = CustomerInformationService; Implementation = CustomerInformation; Operation = RequestCustomer]: The input type of the process does not match the input of the operation
[Service = CustomerInformationService; Implementation = CustomerInformation; Operation = RequestCustomer]: The output type of the process does not match the output of the operation
[Service = CustomerInformationService; Implementation = CustomerInformation; Operation = AddCustomerOperation]: The input type of the process does not match the input of the operation
[Service = CustomerInformationService; Implementation = CustomerInformation; Operation = AddCustomerOperation]: The output type of the process does not match the output of the operation
The Service has configuration errors. For more information, please validate the resource
Would it be possible for you to zip up your projects send it via email.. so that i can compare the same with mine.
Please check the input types as defined in the process and the WS interface operation. There would be a difference.
When you define and use a Service Resource – think of it like creating a mask. The back end implementations should line up exactly with the mask.
Hi, this is a great article! now everything is working inside my tibco designer following your steps, but I am confused what is my next step in order to let me client to consume my web service. I want to be able to give my client a link similar to this and then they can download the WSDL themself.
I checked my developement machine, I don’t see the servcie hosted there, I was using “localhost” as my HTTP connection.
Do I need to deploy the service? and then?
Thanks a lot for your help!.
Man, I usually never comment anything on this places, but you definitely deserve it. The tutorial cannot be clearer and it worked at the very first time. Thank you very much it is difficult to find so good go-straight tutorial on this matter. Thank a lot, best regards!