Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 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 you can use a WSDL import utility, which 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.
How Clients View the WSDL  When TIBCO BusinessEvents acts as a web service server, clients of the service can view the exported concrete WSDL for the web service using the URL to the document root folder (see HTTP Channel Advanced Configuration Settings for details about the document root setting). You must place the WSDL file in that location.
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.
Also, ensure that the default destination for the SOAP event uses com.tibco.cep.driver.http.serializer.SOAPMessageSerializer.
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.
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 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.
Re-importing a WSDL File
When you import a WSDL file, TIBCO BusinessEvents creates the project artifacts. If any changes are made to the WSDL file after the import, you must perform the following steps to use the updated WSDL:
1.
2.
3.
In Studio Explorer, select the WSDL file and then select Edit > Delete from the top menus to delete the WSDL file.
4.
Refresh the project (keyboard shortcut F5) and then select Project > Clean from the top menu.
5.
6.
Open the mapper and click on the Mapper Check and Repair button and check only the mappings in red.
7.
Click Ok to fix the mappings.
8.
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:
Table 21 shows how related project resources are exported as a WSDL file.
Forms the <wsdl:operation> operation.
SOAPEvent for the WSDL input argument
SOAPEvent for the WSDL output argument
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, 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
Copyright © TIBCO Software Inc. All Rights Reserved