Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 7 HTTP and SOAP Channels : Configuring TIBCO BusinessEvents as a SOAP Server and Client

Configuring TIBCO BusinessEvents as a SOAP Server and Client
Using an HTTP channel and a destination configured to use a SOAP Serializer, TIBCO BusinessEvents can act as a web services platform, sending and receiving SOAP requests. You can configure the project manually or using a WSDL import utility, which greatly simplifies configuration.
This release supports SOAP version 1.1. Some understanding of SOAP protocol is required in order to work with this feature. See http://www.w3.org/TR/soap/ for details.
Overview of SOAP Related Resources
The following project resources must be configured so that TIBCO BusinessEvents can send and receive SOAP messages.
SOAP Destinations
When a correctly configured HTTP destination receives a SOAP request, the SOAP serializer deserializes the SOAP message to its corresponding event. That event has to be inherited from a SOAPEvent. The event payload contains the SOAP envelope.
SOAP Events
To create a SOAP event, create a SimpleEvent that inherits a SOAPEvent. It makes event configuration easier. Its payload has a message root element having an Envelope child element. The root element contains Header and Body elements, and the Body element has a Fault element. You can further configure these elements using the payload editor.
SOAP messages (and events) can have attachments.
SOAP Encoding
Only the SOAP document/literal form of encoding is supported.
Rules and Rule Functions
A rule in the project accesses the SOAP event payload as needed using the mapper or SOAP catalog functions. The rule puts the SOAP response into the payload of a SOAPEvent that is sent to the client. The SOAP serializer sends the SOAP response to the client.
SOAP Catalog Functions
SOAP catalog functions enable you to access and process the contents of the following elements in the event payload of an incoming SOAPEvent, and add elements to the outbound SOAPEvent:
See Parsing and Building SOAP Messages for more details.
Mapping of SOAP Request URI to Destination
For Soap requests, the header property SOAPAction represents the destination name, and the requestURI represents the channel URI. TIBCO BusinessEvents combines the SOAPAction and requestURI to create a destination URI. It maps the request with a destination having same URI as the newly created URI.
For example, if the requestURI of a request is /QueryBooks and the value of SOAPAcion is QueryBooksByAuthor, then TIBCO BusinessEvents engine maps the request with a destination having /QueryBooks/QueryBooksByAuthor URI if it exists.
Manually Creating Resources to Work with SOAP Services
This section explains how you can manually create and configure project resources to work with SOAP services
The section Creating Resources Using the WSDL Import Utility explains how to use the WSDL import feature to create the resources.
Also see Understanding the WSDL to Project Resource Mapping for details about how the WSDL elements correspond to project resources.
 
Task A Configure the HTTP Channel and SOAP Destination
Configure an HTTP channel, an HTTP connection resource for the channel. See Working with HTTP Requests for details. Connection configuration is the same for SOAP and HTTP channels, except for the serializer. For SOAP destinations, use the following serializer:
com.tibco.cep.driver.http.serializer.SOAPMessageSerializer
After you complete Task B, set that SOAPEvent as the default event for the destination.
Task B Add a SOAPEvent (and Other Ontology as Needed)
Configure the SOAPevents that will receive the SOAP requests and send out SOAP responses. Also configure any other ontology as needed. SOAPEvent is an event type provided with TIBCO BusinessEvents. However it is created in a two-step manner:
1.
2.
3.
The payload of a SOAPEvent is automatically configured with the structure of a SOAP message. It has Header and Body elements, and within the Body element, a Fault element. You can further configure the Header and Body elements using the payload editor.
Task C Configure Rules and Rule Functions using SOAP Functions
In general the procedure of serving requests and sending requests to other servers is the same for SOAP services as for other HTTP interactions. See Working with HTTP Requests. One rule function is used as the event preprocessor.
In addition, you must configure rules and rule functions to access information from the SOAP messages in the inbound events, and to populate outbound events with SOAP message details. Set two SOAPevents you configured in Task B as input and return arguments of the preprocessor. See Parsing and Building SOAP Messages for details.
Task D Configure an Event Preprocessor
Open the project CDD for editing, and configure an event preprocessor for the destination you configured in Task A. Use the rule function you configured in Task C.
Creating Resources Using the WSDL Import Utility
WSDL (Web Services Description Language) is an XML format for describing web services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.
TIBCO BusinessEvents can parse an imported WSDL file and create the required project artifacts based on its contents: the channels and destinations (concrete WSDLS only), events, rules, and rule functions.
Both abstract and concrete WSDL files can be used. When you import an abstract WSDL, channel and transport information is not available and you must create those resources manually. Concrete WSDLS contain information that is used to create these resources automatically.
You then implement the newly created rules and rule functions to provide the expected behavior for the web service described in the WSDL file.
See Understanding the WSDL to Project Resource Mapping to understand which sections of the WSDL are used to create each resource.
To Import a WSDL File
First you must import the WSDL file into the project. Then you can use the WSDL import utility.
1.
a.
In Studio Explorer, right-click the project folder (or the project root) where you want to store the WSDL file and select Import. You see the Import wizard.
b.
At the Select dialog, select General > From File System. Click Next.
c.
At the File system dialog, click Browse, select the directory that contains the WSDL file you want to use, and click OK.
d.
The File system dialog displays the directory in the left panel and its files in the right panel. Check the checkbox to select the file you want to use. Click Finish.
The WSDL file is imported into the project.
2.
a.
b.
At the Select dialog, select TIBCO BusinessEvents > WSDL. Click Next.
c.
At the WSDL Import dialog, click Browse and select the WSDL file you imported in step 1, then click OK.
d.
If the WSDL file you select is an abstract WSDL, you see a warning letting you know that a channel will not be created. See the section introduction for more details about abstract WSDL files.
The project artifacts are created within a folder named using part of the WSDL file name.
3.
Exporting Resources as a WSDL File
The WSDL export utility allows you to export rules and rule functions that have a SOAPEvent as a parameter, as a WSDL file.
WSDL Filenames must conform to the NCName datatype. See the following page for more details:
Some Japanese characters, such as half-width Katakana, have issues when they are used in XML names. See the following document for more details:
Table 21 shows how related project resources are exported as a WSDL file.
Use the rule function specified as the input event’s default destination as the SOAPEvent’s preprocessor.
That rule function must have the "SOAPEvent for input" as the input and the "SOAPEvent for output" as the return type.
Forms the <wsdl:operation> operation.
SOAPEvent for the WSDL input argument
SOAPEvent for the WSDL output argument
Creates a message. The contents of Envelope > Header > Body become message parts.
Channel with HTTP as the Driver, Resource as the Method of Configuration, with a pointer to the HTTP Connection.
The name of the connection forms the <wsdl:port>. Host and port of the connection form the <soap:address> host and port.
With SOAPMessageSerializer as the default serializer.
Forms the soapAction attribute of the operation.
The destination name becomes soapAction specified for that particular operation.
In the Agent Classes tab, Input Destination Collections list (or Collections tab, Input Destinations), the Preprocessor specified for the input SOAPEvent’s default destination.
Associates soapAction to the operation in the HTTP binding.
To Export a Rule or Rule Function as a WSDL
1.
2.
In the Export dialog, select WSDL under TIBCO BusinessEvents, and click Next.
3.
4.
5.
Click Finish.
6.

Copyright © TIBCO Software Inc. All Rights Reserved