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:
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.
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).
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 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.
There are two ways of implementing a web-service in TIBCO AMBW:
1) Service Resource
2) SOAP Event Source process starter
Which route you take depends on your specific requirements as well as the current state of development.
You would ideally use a SOAP Event Source process starter to expose a single process as a web-service over a single transport protocol. In case you need to expose multiple processes over multiple transport protocols and have a clean separation between web-service definition and implementation, use the Service Resource.
I will first focus on using the Service Resource as it (in my opinion) is a cleaner way of doing things and conforms well to the philosophy behind web-services of separation of interface and implementation.
SOAP Event Source will be covered in another post.
Now from the TIBCO AMBW Process Design Guide we have:
“A service joins an abstract WSDL interface to a concrete implementation and exposes them on one or more endpoints”
There are three main steps in setting up a web-service using the Service Resource:
1) Define the service interface using the WSDL and Schema Resource – involves definition of the abstract part of the WSDL as well as defining schema for input and output data using the Schema Resource
2) Setup the endpoint bindings to expose the service.
3) Implement the operations defined in the web-service.
Figure 1 shows the mapping between TIBCO AMBW components and various components of a web-service (as represented in the WSDL).
Figure 1: Mapping between TIBCO AMBW components and various components of a web-service.
Request Context
As the Service Resource separates the service definition from the implementation, there might be a requirement to access the ‘context’ of the request by the implementing process. This ‘context’ could be the client’s digital signature (for authentication) or something simpler like a client ID. The Context Resource allows us to do just this. We can define a schema to store the relevant ‘context’ which can then be accessed by the implementing process using the GetContext and SetContext activities.
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:
- Add Customer Information (name, age and ID).
- Retrieve Customer Information using Customer ID with a Request ID for logging purposes.
To add information for a new customer we will supply the customer information (id, name and age).
Going back to the three step process for implementing a web-service using the Service Resource:
Step 1: Defining the web-service interface
We will use the Schema Resource and the WSDL Resource to define the web-service interface including the operations and the associated input/output schema.
The Schema
Firstly create the Schema for the input and output messages using the Schema Resource (within the XML menu).
Below we can see a simple CustomerInformation schema which defines the customer information structure (for both retrieval and addition) as well as a CustomerInformationRequest schema which defines the structure of the incoming request for customer information.
The Web-service Interface using WSDL
Next we define the interface for the web-service using the schema we defined above and a WSDL resource.
We will first define the input and output messages using the schema and then use them to define the operations. All the required resources are in the WSDL menu.
Create a new WSDL resource and double-click it. Add two new Messages: Customer Information Request and Customer Information. 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 Port-type resource to start defining operations. Double click the Port-type resource and add two new Operations: Add Customer and Request Customer.
In the Add Customer operation configuration, add an input message with the message schema set to Customer Information (we are now connecting the schema with the interface). We don’t need any output message for this operation.
In the Request Customer operation configuration, add an input message with message schema set to Customer Information Request and the output message with message schema set to Customer Information.
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.
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.
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.
For training on TIBCO BusinessWorks mail us at [email protected]
RSS Feed
