Developing Web-Services with TIBCO ActiveMatrix BusinessWorks

 

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

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

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

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

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

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

A web-service consists of three basic components:

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

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

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

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

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

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

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

1) Service Resource

2) SOAP Event Source process starter

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

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

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

SOAP Event Source will be covered in another post.

Now from the TIBCO AMBW Process Design Guide we have:

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

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

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

2) Setup the endpoint bindings to expose the service.

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

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

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

Request Context

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

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.

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.

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.

Please leave comments and suggestions.

Update:

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