Introduction

In Part 9 of this series about merging disparate IT systems of two insurance companies, you learned how to integrate an external assessor with an insurance claims system. We used Microsoft® .NET software to implement the assessor and IBM WebSphere Business Integration Message Broker (Message Broker) to manage the coordination between the internal insurance company systems and external assessor systems. Messages flowing within the insurance company and to and from the assessors were SOAP based and implemented as Web services. In this article, you learn how Message Broker models SOAP messages and implements Web services.

You can view a demonstration of the techniques described in this article at Supportpac IA81 - WebSphere Business Integration Message Broker and Web services.

This article assumes you have knowledge of:

• XML schemas
• Format of SOAP messages
• Message Broker components

Back to top

Revisit the scenario

Our scenario describes the evolution of two separate company policy systems to a consolidated eMerge policy system that handles the request and acceptance of car insurance quotes. The eMerge scenario is based on the merger of two companies:

• Lord General Insurance (LGI), a general insurance company, is a large enterprise with over five-million policy holders. The company wants to boost its auto insurance business and requires a quick entry to the e-business direct insurance market. LGI has a large legacy IT infrastructure based on IBM S/390® and IBM CICS® systems.
• DirectCar.com (DC) is a modern dot-com auto insurance company that sells insurance through the Internet and has less than one-million policy holders. It has an e-business-focused infrastructure based on IBM WebSphere Application Server, Oracle databases, and IBM TXSeries® systems.

The scenario focuses on the merger and has the following requirements:

• Reduce overall costs of policy administration across the two companies by eliminating administrative costs.
• Consolidate IT resources where possible, while providing an effective and integrated policy management system.
• Satisfy service-level agreements as defined in customer requirements (for example, performance and security guidelines).

As part of the merger, the two companies consolidated their individual claims systems into one automated claims-handling system. A subset of the claims-handling system is the automated external assessor solution, covered in Part 3 of this series.

An assessor is an individual who works for a company external to LGI who performs insurance claims assessments on motor vehicles. The basic assessor automation process includes the following:

• Identify potential assessors by querying the Assessor Management system.
• Poll potential assessors to request availability to perform the assessment.
• Choose an assessor based on selection rules in the Assessor Management system.
• Request that the preferred assessor perform the assessment.
• File the assessment report, completing the automated assessment subprocess.

Figure 1 shows the assessor automation process and Message Broker's position.

The products used in this system are:

• WebSphere Process Choreographer running on WebSphere Business Integration Server Foundation
• WebSphere Business Integration Message Broker
• Web Services Gateway running on WebSphere Application Server

Back to top

The role of Web services in the scenario

Figure 1 shows the assessor automation system with Message Broker and its interaction with Web Services Gateway and external assessors.

LGI checks its systems for suitable assessors who can handle this claim (step 1 in Figure 1). This decision could be based on location of the vehicle and the assessors, or something more specific, such as requiring a specialist assessor for a certain model of car. After the LGI systems compile a list of assessors who can assess the vehicle, they contact them to find out who is available to do the assessment (step 2 in Figure 1).

Steps 3, 4, and 5 select an assessor, and confirmation of the assessment is made. Steps 2, 4, and 5 all interface to Message Broker using Web services. This article describes step 2 in Figure 1 in detail, but the others are very similar in concept.

The type of Web service developed in this scenario is document/literal. Encoding styles are not used, and messages are mapped to XML schemas.

More details about Web services

In step 2 in Figure 1, WebSphere Process Choreographer sends a list of potential assessors to Message Broker. This is a Web service called RequestAssessorAvailability hosted by the Message Broker. WebSphere Process Choreographer is a Web services client.

Message Broker's RequestAssessorAvailability Web service acknowledges WebSphere Process Choreographer for receipt of the message and sends the availability requests to the individual assessors. This invokes a Web service called RequestAssessorAvailability hosted by the assessors. Message Broker is a Web service client.

Each assessor's RequestAssessorAvailability Web service acknowledges Message Broker for receipt of the message and sends the availability to the Message Broker. These invoke a Web service called AssessorAvailability hosted by the Message Broker. The assessors are Web services clients.

The Message Broker's AssessorAvailability Web service acknowledges the assessors for receipt of the message and sends the consolidated availability to WebSphere Process Choreographer. This invokes a Web service called ListAvailableAssessors hosted by WebSphere Process Choreographer. Message Broker is a Web service client.

Back to top

Overview of Message Broker

Message Broker development involves the creation of message flows, optionally referencing message sets. Message flows are executable programs comprising pre-assembled building blocks called nodes. They are developed using the WebSphere Business Integration Message Broker Toolkit.

Message sets are catalogs of message definitions that can be accessed in the development and execution of message flows. They are developed using the WebSphere Business Integration Message Broker Toolkit. Message sets provide the following advantages:

• WSDL generation of Message Broker-based Web services is simplified.
• Development of message flows is simplified. Use of mapping nodes and compute node command-assist is possible, eliminating coding errors in message field names.
• Validation of message instances in Message Broker against an XML schema is possible.
• Namespace definitions on output messages are generated automatically, eliminating coding errors on them.

Once development is complete, message flows and message sets are added to a message broker archive file (BAR) and deployed to one or more message brokers.

The role of Message Broker in the assessor automation process

Message Broker performs the following functions:

• Splits a list of assessors into separate assessor requests
• Sends these requests to individual assessors, either directly or though a gateway
• Coordinates the replies from the assessors
• Stores the status of each assessor request in a database
• Validates that all messages received conform to their appropriate XML schema
• Ensures all messages sent conform to an appropriate XML schema
• Implements a fault recording procedure.
• Facilitates the addition of new assessors without disruption

One message set project and one message flow project were developed for the assessor system. A second message flow project was developed to represent an assessor, which are described next.

Back to top

Message sets

A message set is created inside a message set project in the Message Broker Toolkit. Only one message set is allowed per message set project. Many message set projects can be used in a system, but only one message set can be used by Message Broker when parsing or writing a message instance.

Message sets can be namespace enabled. Because SOAP messages always use namespaces, any message sets used for modeling SOAP messages must be namespace enabled.

Message sets have one or more wire formats, which represent the style of message to be input or output. Wire formats fall into three categories:

• Custom (mapping C or COBOL structures)
• XML
• Tagged or delimited (mapping industry standards such as SWIFT)

SOAP messages require an XML wire format.

Message sets contain one or more message definition files (MDF), suffixed .mxsd. These are valid XML schema files, annotated with Message Broker-specific enhancements. They can be created by importing an XML schema, DTD, C header file, or COBOL copybook. There is a customized editor in the Message Broker Toolkit to manipulate the contents of MDFs.

Currently you cannot import WSDL into the Message Broker toolkit. If you have a WSDL file, you must extract the schema to a separate file and import that file. You many need to customize message set definitions after importing an XML schema, which can be done using the Message Broker Toolkit.

MDFs contain global or local elements, complex types, groups and attributes (global or local), much as XML schemas do. MDFs also contain messages, which are used by the Message Broker as a unit of processing in a message flow.

Within an MDF, messages can be grouped into categories. Categories are needed to enable WSDL generation from the Message Broker Toolkit.

MDFs also contain extra information that XML schemas do not. One example is a keyword of complex type known as composition. This can indicate known XML schema properties, such as sequence or choice. It also allows a Message Broker-specific property message, which means the same as choice, but the children of this complex type are messages rather than elements or attributes. This information is useful when modeling business messages, which are embedded within a standard envelope.

It is possible to INCLUDE or IMPORT one MDF within another. These have similar functions to the XML schema INCLUDE and IMPORT.

WSDL files can be generated from message sets, though these may need customization prior to use by other Web service development tools. Message categories need to be defined prior to WSDL generation.

Back to top

Message sets for SOAP message modeling

We created a single message set project containing a message set because. Message flow development is simpler when a single message set is used. However, if there are a large number of Web services, you should consider using multiple message sets.

The message set was namespace enabled. An XML wire format was added. The wire format was customized as follows:

• Suppress DOCTYPE was selected. DTD declarations are not needed, because the system is schema rather than DTD based.
• Root Tag Name was set to blank. Web services use SOAP messages, where the root tag name must be Envelope. Also, the system has the potential to use embedded messages. It doesn't make sense to have a hard-coded root tag name when embedded messages are used.

Figure 2 shows these settings in file messageSet.mset of message set soltestms2.

The SOAP V1.1 XML schema is imported into a message set in the Message Broker Toolkit, creating a file called soap11.mxsd. This schema is located at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/envelope-2000-04-18.xml.

During the import, the global element Envelope is defined as a message, so that message flows can select it to be processed.

The XML schemas representing Web services are imported -- including those that Message Broker hosts and those for which Message Broker is a client. It is necessary to define global elements as messages in these imports when Message Broker hosts the Web service, so that they can be included in the message-set categories.

The SOAP MDF is customized as follows:

• Wildcard elements are removed from elements Envelope, Header and Body and fault detail. In their place, amendments are made to complex type definitions (as shown below). This step removes warnings generated by the Message Broker Toolkit.
• The wildcard attribute is removed from the Body element.
• Namespaces are removed from wildcard attributes. This removed warnings generated by the Message Brokers Toolkit.
• The content validation of Envelope complex type was set to OpenDefined, from its original setting of Closed. This means that only elements and attributes defined in the message set are allowed as children of Envelope. The explicit children are Header and Body. A system design imperative was to tightly control the content of messages. This setting achieves this goal, while still satisfying the wildcard element removal.
• The content validation of Header and detail complex types is set to Open, from their original setting of Closed. This setting means any elements and attributes are allowed, yet it still satisfies the wildcard element removal. The Body element's complex type is changed to type composition Choice and type content OpenDefined. These types allow any one of the imported schema elements to be used as children of Body, but disallows elements not defined in any schema. Type composition message is normally the most appropriate setting here, but is not used in this case because it is currently not possible to have more than one message of the same name in a message set, even if the messages are based on global elements from different namespaces. In our solution, two assessors have identically named messages as part of their Web services.
• The pattern facet of the mustUnderstand global attribute is deleted, because it is not required and deleting it removed a warning generated by the Message Broker Toolkit .
• The MDFs representing the Web services are imported into the SOAP MDF, enabling the SOAP Envelope and any potential message body to be manipulated together in the Message Broker. Figure 3 shows the imported definitions.
• The Fault element of the SOAP schema was added as a child of Body.
• Global elements of Web services MDF are added as children to the SOAP Body, allowing the Web services message bodies to be used in compute node's Command Assist. The minOccurs of each is set to 0.

If duplicate global element names exist, but each has a different namespace, they can be implemented as messages only if each duplicate element is in a different message set.

All Web services hosted by the LGI message broker are placed in the same namespace. Each assessor has a different namespace, as did WebSphere Process Choreographer. Many assessors' message formats (tag names and so on) are slightly different, to simulate a business environment where rigid standards are not in place. However, notice the widespread duplication of tag names. One of the jobs of Message Broker is to handle these differences in message format.

Message category files are created for each Message Broker-hosted Web service. The Message Category Kind is set to wsdl, and messages are added to the category. Each message is assigned a role type of wsdl:input or wsdl:output. Then, for each category, a WSDL file is created.

Back to top

Message flows

A message flow is created inside a message flow project in the Message Broker Toolkit. Multiple message flows can reside in a message flow project and multiple message flow projects can be used in a system.

Message flows are composed of nodes, either supplied as part of Message Broker or user written. User-written nodes are often called plug-in nodes. Nodes have input and output terminals that can be wired between nodes, creating a flow, much as a flow chart does.

Message flows typically start with an input node, which provides a way of passing a message into the flow. Message Broker supplies several input nodes, including MQInput and HTTPInput. These are then wired to other nodes such as Filter (for logic branches), Compute (generic programming using ESQL), and Mapping (building messages using GUI components).

Message flows interact with message sets using four parameters:

• Message domain (must be set to MRM for message set enablement)
• Message set identifier
• Message identifier
• Wire format

For input messages, these parameters can be specified in all IBM-supplied input nodes and represent the message template against which the input message will be parsed.

For output messages, these parameters can be specified in a compute node using ESQL, or mapping node.

When messages are parsed (input) or built (output), it is possible to specify whether they are to be checked for adherence to an XML schema, which is contained in the message set. The level of validation against the schema is specified in the Validation properties of the node.

Back to top

Message flows for Web service provisioning

Two message flow projects are created: one for the LGI message broker and one for the assessor message broker. The style of message flow development is the same in each. As a result, only the LGI Message Broker's flows are described here. The LGI message broker project contains message flows representing:

• Web service providers
• Web service client requests
• Web service client responses

Different message flows are developed for client requests and responses because the communication protocol of choice is WebSphere MQ, rather than HTTP. WebSphere MQ was chosen because of its ability to tolerate outages of Web services while still allowing requests of them to be made.

The response message flows enable SOAP responses to be sent to predefined WebSphere MQ queues; thus, the messages can be defined as persistent. It is a highly desirable system requirement that no messages are lost.

The preferred design is for a SOAP request/response model. The response is usually an acknowledgement of receipt. Because WebSphere MQ request/response implements a truly asynchronous model, comprising multiple sync points, we wondered if multiple one-way SOAP messages might be a better solution. However, we rejected this solution, because a one-way model has no way of reporting SOAP faults. Fault handling is an essential requirement for this system.

Table 1 shows a sample of the Web services message flows developed for LGI message broker. These represent the flows needed in step 2 of Figure 1. Step 4 in Figure 1 needs a similar set of message flows.

Table 1. Web service message flows

Examples of each type of Web service message flow (provider, client request, and client response) are described in more detail below.

Web service provider message flow

The Receive request availability message and acknowledge message flow is a Web service provider. It receives a message from WebSphere Process Choreographer, validates, acknowledges receipt, and invokes a Web service request message flow, as shown in Figure 4.

Web service providers must be aware that the input message may come from a source external to this system, possibly external to this company. Therefore the message flow does not assume that the input message is valid, and the first step is to validate the message. Most of the validation is done by using the message set. Input message set details are specified in the Properties of the MQInput node. The message is expected to have a root tag called Envelope (a SOAP message). Figure 5 shows how this is specified.

Input message validation settings are specified in the Properties of the MQInput node, as shown in Figure 6.

This validation option ensures that the input message maps to the SOAP schema, and to one of the elements defined as a child of the SOAP Body. Be sure that the correct element is defined in the SOAP Body. You can do this in two ways:

• Specify a message path in the MQInput node Message Type to include the expected body. This presumes the body is defined as a message in the message set.
• We adopted the approach that allows for checking of the input message body later in the message flow. It allows a choice of more than one body to be received by a single message flow.

All Web service message flows (provider, client request, and client response) use the SOAP message set, and all specify the validation properties shown in Figure 6. Only Web service providers perform the extra validation later in the message flow.

A performance cost is associated with message set validation, and you should balance this factor against user validation and increased development cost.

Web service client request message flow

The Request assessor availability message flow receives a validated message from the Web service provider and generates one or more request messages to be passed to assessors' Web services. This is the fan-out part of an aggregation. It also updates a database table with state information. Figure 7 shows the message flow.

If the assessor is to be accessed using the Web Services Gateway or is known to process JMS messages, an MQRFH2 header is generated with the message. If it does not, no MQRFH2 header is sent, and the message is forwarded directly to the assessor. This processing is done within the GenerateFlow4 compute node.

Web service client response message flow

The "Process assessor availability acknowledgment" message flow receives an acknowledgement from an assessor. Figure 8 shows this message flow.

Fault processing

All message flows use a common fault routine, which is wired from the failure and catch terminals of the MQInput nodes. All other failure terminals in the message flow remain unconnected, so any exceptions are routed by way of the MQInput node to the fault routine.

The fault routine also processes SOAP fault messages received from external Web services. The fault routine does the following:

• Builds a SOAP fault message describing the failure
• Sends the fault message as a reply if the fault happened in a Message Broker Web service (out of sync point)
• Puts the fault to a local troubleshooting queue (out of sync point)
• Throws an exception, to ensure other resources updated in the message flow are rolled back

Resources

• Visit the series overview page to see the current list of articles in this series.
  
  
• IBM WebSphere MQ family SupportPacs provide a wide range of downloadable code and documentation that complements the WebSphere MQ family of products.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Revisit the scenario
• The role of Web services in the scenario
• Overview of Message Broker
• Message sets
• Message sets for SOAP message modeling
• Message flows
• Message flows for Web service provisioning
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality