Scenario overview

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 scenario is based on the merger of two insurance companies:

• Lord General Insurance (LGI), a general insurance company, is a large enterprise with over five million policy holders, looking to boost its auto insurance business and requiring 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:

• Improve the company's profitability by reducing overall administration costs, with an immediate goal of focusing on claims administration for existing products.
• Create an automated claims system for the joint customer base that connects the existing external services.
• Satisfy service-level agreements as defined in customer requirements (performance and security guidelines, for example).

Back to top

Introduction

Part 3 of our series describes the design approach for an extension to the consolidated claims system that automates an existing manual activity in an automobile insurance claims process. This article describes how to integrate a Microsoft .NET system-based external claims assessor into the LGI assessor automation scenario to help achieve part of the scenario's automation.

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, as detailed in Part 3.

An assessor is a person who works for a company external to LGI who is qualified to perform insurance claims assessments on motor vehicles. The basic assessor automation process is:

1. Potential assessors are identified by querying the Assessor Management system.
2. Potential assessors are polled to ask for their availability to do the assessment (by a Web service request).
3. The Assessor Management system selection rules are used to select the assessor to do the assessment.
4. The preferred assessor is requested to do the assessment.
5. The assessment is completed and the assessment report filed, completing the automated assessment subprocess.

The process is shown in Figure 1.

Most of the process shown in Figure 1 is internal to the newly merged LGI assessor automation system. The external assessors become involved for steps 2, 4, and 5.

The products used in this system are:

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

Back to top

Adding a new assessor

Assume that the merged assessor automation system in Figure 1 already exists and is fully operational. A new assessor company wants to perform claims assessment jobs for LGI. In this article, you'll learn the process for adding a new external assessor to the existing assessor automation system.

LGI cannot change implementation of its assessor automation system without disrupting its operations and existing assessors. To encourage seamless integration, LGI provides new assessors with details of the interface to the assessor automation system to which the assessors must conform. LGI is not concerned with how the external assessors implement their back-end code as long as they conform to the given interfaces. In this case, the new assessor company has strong Microsoft skills and wants to use a Microsoft .NET system-based implementation to interact with the existing LGI infrastructure.

LGI is interacting with external assessors using Web services. The operations involved suggest that Web services should be asynchronous. However, because asynchronous Web services are not yet widely supported and do not conform to the Web Services Interoperability (WS-I) group specifications, Web services are designed to simulate asynchronous behavior using two synchronous Web services. This means the external assessors receive a synchronous Web service request and return a simple acknowledgment message. At a future point, the external assessors can pass the reply data back to LGI using a separate synchronous Web service, which in turn sends a simple acknowledgement message back to the assessor.

Integrating with the scenario

Figure 1 shows the assessor automation system and its interactions with external assessors. Before any contact is made with assessors when a claim is made, LGI checks its systems for suitable assessors who can handle this claim (flow 1 in Figure 1). This requirement can be based on the location of the vehicle and the assessors or something more specific, such as needing a specialist assessor for a certain model of car.

After the LGI systems determine a list of assessors who can assess the vehicle, the company can contact them to find out who is available to do the assessment. This process is shown as flow 2 in Figure 1. WebSphere Process Choreographer sends a list of potential assessors to WebSphere Business Integration Message Broker, which fans out the availability requests to individual assessors using Web services.

Assessor availability

For a new assessor to receive work requests from LGI, the individual must implement a Web service that LGI can communicate with. Since the LGI systems are already in operation, external assessors must follow interfaces that interoperate with the LGI system, which are already defined, as shown in Figure 2.

The Web service needs a method called requestAssessorAvailability that accepts:

• A claim ID
• An assessor ID
• Location of the vehicle to be assessed
• Required date by which the assessment must be completed
• Details of the car (a complex data type called CarDetails consisting of the makeOfCar and automobile registration number)

The Web service must return an acknowledgement message containing the claim ID and a timestamp.

Once the assessor has created the Web service, the Web Services Description Language (WSDL) file created in .NET is then given to LGI. The WSDL file contains all information required for LGI to generate a proxy class to be able to invoke the Web service.

LGI can now deploy the WSDL file into IBM Web Services Gateway, which creates a new WSDL file that is imported into WebSphere Business Integration Message Broker. With the information in the WSDL file, Message Broker can invoke the assessor availability Web service (using Web Services Gateway) to request information about the availability of the .NET assessor.

When the .NET Web service is invoked, it returns an acknowledgement message back to Message Broker, which is also routed by Web Services Gateway.

Because Web services are intended to be asynchronous, at some point after the original request for availability, the .NET assessor is expected to send its availability back to Message Broker. This transaction occurs by means of another Web service that resides on the Message Broker itself and is deployed to Web Services Gateway. This Web service is used by all assessors to return their availability back to LGI. The WSDL from Web Services Gateway for this service is given to the .NET assessor, which can then create a client to invoke the service to send their availability. The interface that the new assessor must follow for this service is defined in Figure 3.

Using the WSDL file for the Web service, the .NET assessor is able to create a client to call the Web service to inform LGI of a predicted date when they can do the assessment on the vehicle and provide an estimated cost. When this service is invoked, it sends the availability of the assessor to the LGI system using Web Services Gateway and receives, in turn, an acknowledgment message from Message Broker to confirm delivery of the message.

After all assessors send their availability to do the assessment to Message Broker (or after a predetermined amount of time passes), the results are collated in Message Broker and sent to the LGI assessor automation system. One of the assessors who responded is chosen based on the business rules defined by LGI, shown as flow 3 in Figure 1. This decision is transparent to the assessors.

If the .NET assessor is chosen, flow 4 in Figure 1 is invoked to inform the assessor they have been chosen to do the assessment and to request confirmation that they can still do the assessment.

Request assessment

The operation to request the assessor to do the assessment is implemented similarly to that of the assessor availability flow just described. In this operation, LGI asks the assessor to confirm that they can do the assessment, again using a Web service. LGI sends a synchronous two-way Web service request to the assessor to confirm he can carry out the assessment. The assessor sends a simple acknowledgement message back to LGI to confirm receipt of the request. The assessor then sends a response using another synchronous Web service to LGI (either an acceptance to do the assessment or a rejection) and receives a simple acknowledgement message back. The interfaces for this flow are described in Figure 4 and Figure 5.

The request for confirmation to do assessment Web service (from LGI to the assessor) is shown in Figure 4.

The interface for the sending of confirmation back from the assessor to LGI is shown in Figure 5.

Assessment Report

If the assessor accepts the request to do the assessment, report of their assessment needs to be sent back to LGI by placing a simple JMS message on a WebSphere MQ queue, which is picked up by WebSphere MQ Everyplace®. WebSphere MQ Everyplace receives the message and creates a report in the desired format. At regular intervals (for example, at the end of every day), WebSphere MQ Everyplace sends all the day's reports to Message Broker, which are then handled appropriately.

The structure of the message to be placed on the WebSphere MQ queue must be in the format shown here. For example, 1234,1234,2004-07-02.

{claimId:integer
comma:
assessorID:integer
comma:
requiredDate:string}

Once the assessor has all the previously mentioned services in place, he is ready to be integrated with the assessor automation system. How you can achieve this is described in more detail in Developing the .NET assessor Web services.

Back to top

Making design decisions

This section describes the reasoning behind some of our design decisions.

Data types

When designing Web services, be careful not to pass language-specific data types as arguments to the Web service methods. This helps to achieve interoperability between Web services implemented in differing programming languages. For example, if a Java code-based Web service passes a java.util.Vector as a parameter, a .NET Web service has no concept of java.util.Vector and can have difficulties mapping it to a .NET data type. For this reason, in our scenario where Web service methods take or receive dates or timestamps as parameters, we chose to send the dates as string objects. This avoids any incompatibility between a java.util.Date and the .NET representation of dates.

To avoid confusion over the formatting of the date strings, LGI has specified that the ISO standard date format yyyy-MM-dd be used for the dates, and yyyy-MM-dd hh:mm:ss (ttt) to represent timestamps.

Threading

LGI has designed their Web services to achieve asynchronous behavior using two synchronous Web services: one for the request from LGI to the assessor and a second one to be invoked later to send the information from the assessor back to LGI.

In the real world, the second Web service (to send the information to LGI) is invoked after an undetermined amount of time from when the assessor receives the request for the information. However, this scenario focuses on the technologies involved rather than achieving total realism. The important thing is that after the assessor receives a request for information, it successfully manages to invoke the Web service in the LGI system to send the response.

An easy way to achieve this goal is to invoke the reply Web service from within the code of the request Web service. For example, when the assessor receives a request from LGI by having its Web service invoked as well as sending an acknowledgement message back to LGI, it is also responsible for instantiating the Web service to send the response.

One way we considered doing this was to create a new thread to invoke the reply Web service after a specified amount of time. But, it was decided that spending development time achieving multithreading in .NET gave little value-add to the functions of the scenario. Instead, the response Web service is invoked in the main body of the Web service before the acknowledgement message is sent back. This does make the assessor interaction slightly unrealistic because the response to the request is received by LGI before the acknowledgement of the request, but it's a very minor issue in view of what the scenario is intended to demonstrate.

Web service transport

All internal operations inside the LGI assessor automation system are performed with Web services using a Simple Object Access Protocol (SOAP)-JMS transport to ensure guaranteed delivery of the messages. Ideally, LGI would also communicate with external assessors using SOAP/JMS transport.

However, there is currently no support for SOAP-JMS Web services in Microsoft .NET. In the absence of an alternative, it was decided that the .NET Web services should be developed to communicate using the .NET default, which is SOAP-HTTP.

To prevent LGI having to rewrite code in their assessor automation system to handle the new method of communication with the external .NET assessors, we use Web Services Gateway to convert between SOAP-HTTP and SOAP-JMS. LGI sends a message to an assessor using SOAP-JMS, and the Web Services Gateway automatically routes the request over SOAP-HTTP to the assessor. Similarly, when the assessor sends a message to LGI using SOAP-HTTP, the Web Services Gateway automatically routes the message over the SOAP-JMS transport into the internal LGI systems.

WebSphere MQ Everyplace

The aim of the scenario is not to create all of the back-end code that would exist in a real-world system. The business logic of the Web services is simplified in some areas. The most significant simplification is that the assessment reporting process is relocated outside of the Web service. Instead of the assessors themselves creating actual reports of their vehicle assessments, this is delegated to WebSphere MQ Everyplace. The assessor now sends a message to WebSphere MQ Everyplace after an assessment is done on the vehicle, and WebSphere MQ Everyplace is responsible for creating the actual report.

Because currently there is no support for Web services in WebSphere MQ Everyplace, communication between the assessors and WebSphere MQ Everyplace is achieved using simple JMS text messages on a WebSphere MQ queue.

Back to top

Developing the .NET assessor Web services

This section provides high-level decisions and the structure for creating the Web service. It presumes a reasonable familiarity with Web services and their terminology. Our first task involves writing the basic Web service code using Microsoft Visual Studio .NET, the latest Microsoft Development Environment available.

An ASP.NET Web Service Project is created, since this allows the service to be integrated with the Internet Information Service (IIS) used for testing. IIS is a component of the Microsoft Windows® (2000) operating system, and it allows a machine to easily host Web sites and services. Microsoft .NET Web services are defined in .asmx files, which are processed by the ASP.NET engine (provided by the .NET framework) in IIS, allowing the service to be used.

RequestAssessorAvailability

The first method to be developed is the requestAssessorAvailability method (flow 2 in Figure 1). In the design, the Web service must handle complex objects, such as the acknowledgement messages and the CarDetails object. The first task is to ensure that the Web service can send and receive complex type objects. A struct object must be used for this purpose, as shown below.

public struct RqAvailabilityAck
{
         public int claimID;
	public string timeStamp;
}

Enabling the service to send and receive information is managed using the method parameters, as shown in the following listing. WebMethod tag in C# denotes a method that is a publicly visible method of the Web service.

[WebMethod] 
public RqAvailabilityAck requestAssessorAvailability
( int claimID,int assessorID,string location,string requiredDate, 
CarDetails carDetails )

For this assessor to send her availability information back to LGI, the Web service method called another Web service residing on WebSphere Business Integration Message Broker. Web services between LGI and the external assessors go through Web Services Gateway. Web Services Gateway also has the ability to convert between different Web service transport protocols. In this case, it converts between the SOAP-JMS transport used in the internal LGI systems and SOAP-HTTP used by the .NET assessor.

The Web service in Message Broker is published to the Web Services Gateway by importing the WSDL files from the Web service into Web Services Gateway. Web Services Gateway, in turn, produces new WSDL files that allow a client to invoke the Web service.

We encountered a problem in our scenario because Web Services Gateway publishes its WSDL as two separate files, and Visual Studio cannot handle WSDL in this format. To solve the problem, we used an edited WSDL file and a command-line tool from Visual Studio to create a proxy for these services. The two WSDL files produced by the Web Services Gateway had to be manually edited together to produce a single WSDL file. This file was then passed through the wsdl.exe tool, which created a C# proxy for the services that could be called from the .NET assessor service. An instance of the proxy can be created in the service code, which means calls to the Message Broker Web services are possible, as shown below.

[WebMethod] 
public RqAvailabilityAck requestAssessorAvailability
( int claimID,int assessorID,string location,string requiredDate, 
CarDetails carDetails )
{
	// {variable initialization left out of article}

	//Instantiate service to send availability
         BrokerService availabilityService = new BrokerService();

         //Call web service method
         availabilityService.assessorAvailability(claimID,assID,
         predictedDate, predictedCost);

	//Return ACK for web method
	RqAvailabilityAck ACK = new RqAvailabilityAck();
	ACK.claimID = claimID;
	ACK.timeStamp = System.DateTime.Now.ToString(); 
	return ACK;
}

To summarize, the Web service in .NET consists of a method requestAssessorAvailability that is invoked by the LGI assessor automation system when LGI needs to request information about the availability of this assessor. Inside this Web service method, a separate call is made to a Web service residing in the LGI system (Web Services Gateway) to inform Message Broker of the assessor's availability.

Figure 7 shows the overall flow between Message Broker and this .NET assessor Web service method through Web Services Gateway and the transport protocol conversions.

DeliverAssessorRequest

The next method to be developed is deliverAssessorRequest (flow 4 in Figure 1). As with the requestAssessorAvailability Web service, this service is invoked from Message Broker by way of Web Services Gateway. The deliverAssessorRequest Web service is invoked to ask the assessor to confirm they can do an assessment. Within the Web service method, a call is made to a separate Web service running on Message Broker (using Web Services Gateway) to respond with either an acceptance or rejection of the request to do the assessment. This method also shows the problem of Web Services Gateway producing two WSDL files and Visual Studio .NET being unable to interpret this, but as explained earlier, manual editing of the file gets around the problem.

The main difference between this Web service and the previous one is that this method needs to send a message to WebSphere MQ Everyplace, as described previously in Assessment report. To do this within a .NET service requires using the .NET Support Classes for WebSphere MQ. These are included as part of WebSphere MQ Version 5.3 CSD04 and later, and provide the service with the ability to create and send WebSphere MQ messages. This message is sent every time an assessor accepts a job, to ensure the reporting process is up to date. Note that this is different from being able to use WebSphere MQ as a transport for Web services.

To use the WebSphere MQ support classes correctly, the ASP.NET user on the machine where the service runs must be made part of the MQ Managers (mqm) group; otherwise, a security error occurs when the ASP engine tries to access an MQ Queue Manager.

The following listing shows the code for the .NET Web service method, including use of the WebSphere MQ .NET support classes.

using IBM.WMQ;
[WebMethod]
public DeliverRequestAck deliverAssessorRequest(int claimID,int assessorID,
string location,string requiredDate, CarDetails carDetails)
{
	// {variable initialization left out of article}
	
	//always accept the job to test functionality
	bool acceptJob = true;
		
	BrokerService confirmService = new BrokerService();
	
	//call Web Service to confirm (or reject) assessment request
         RequestAck rqACK = confirmService.assessorResponse(claimID,assID,
  		accepted.ToString(),confirmDate);
						
	//Define MQ objects
	MQQueueManager queueMan = null;
	MQQueue queue;
	MQMessage mqMsg;
	MQPutMessageOptions mqPutMsgOpts;

	//Connect to Queue Manager
	queueMan = new MQQueueManager(outputQueueManager);	
      
	//Write info message to output queue for MQe
	
         //Connect to output queue 
	queue = queueMan.AccessQueue(outputQueue, MQC.MQOO_OUTPUT);
         
         //Create Message in the format "claimID,assessorID,date" 
	mqMsg = new MQMessage();
	string messageString = claimID.ToString()+ "," 
         + assessorID.ToString()+ "," 
         + requiredDate.ToString();

	mqMsg.WriteString(messageString);
	mqMsg.Format = MQC.MQFMT_STRING;
	mqMsg.ReplyToQueueManagerName = outputQueueManager;
	mqMsg.ReplyToQueueName = replyQueue;
	mqPutMsgOpts = new MQPutMessageOptions();

	//Send Message
	queue.Put( mqMsg, mqPutMsgOpts );
	
         //Close Queue Manager
	queueMan.Disconnect();
	
	//Construct ack 
	DeliverRequestAck ACK = new DeliverRequestAck();
	ACK.claimID = claimID;
	ACK.assessorID = assessorID;
	ACK.timeStamp = System.DateTime.Now.ToString(); 

         return ACK;
}

Figure 8 shows the overall flows between Message Broker and the .NET assessor Web service method through Web Services Gateway. It also shows the transport protocol conversions and the message going to WebSphere MQ Everyplace to prepare the assessment report.

Back to top

Creating effective deployment

To allow for effective deployment of the service, a new Web Setup Project is created in Visual Studio. These projects allow for efficient packaging of Web services, as well as providing customizable settings and an install program. To assist in the portability of the service, a properties file (in XML format) is integrated with the service. This allows for variables such as Web service destinations and WebSphere MQ queue definitions to be collected at run time. It is very straightforward, using the XML read/write features in .NET, as shown below.

XmlTextReader reader = null;

// Read the file and parse to ensure well formed XML.
reader = new XmlTextReader (@"C:\NETAssessorService\NETServiceConfig.xml");

//Get node tree from file
XmlDocument doc = new XmlDocument();
doc.Load(reader);

//Get XML Node for property to retrieve
XmlNode logLevelNode = doc.GetElementsByTagName("LogLevel").Item(0);

//Get text in tag and set to variable
if (logLevelNode != null)
{	logLevel = Convert.ToInt32(logLevelNode.InnerText);	}
else
{	writeLog("*** WARNING - No valid <LogLevel> tag in config file, 
   using level 2 default***",1);}

A copy of the properties file and other essential components are packaged upon building the setup project. The result is a .msi installer package and a couple of support files that can be run on any Windows machine to install the service (provided that the prerequisites are met). This makes for rapid development-to-deployment time, and the installer packages require little expertise to deploy. Any information essential to the deployer can be included in the readme file, which is displayed at the beginning of the install and subsequently copied to the target machine.

Back to top

Understanding the lessons learned

This section briefly points out a few of the major lessons learned.

Namespaces

When developing Web services in .NET, you must pay special attention to the namespaces used. The Web service itself is contained in a namespace, which can often be arbitrarily assigned by Visual Studio. This is more for a convenience for grouping and reference within Visual Studio. To ensure correct operation of the service, you should add a namespace attribute to the Web service directive at the top of the class, as in the following listing. The addition of http:// to the attribute was simply a convention, but it is important to note that the namespace given in this attribute is what is present in the WSDL generated by the service. If you omit this, the namespace defaults to http://tempuri.org, which is undesirable.

namespace wpst.hursley.assessor.net

[WebService (Namespace="http://wpst.hursley.assessor.net")]
public class NETAssessorService: System.Web.Services.WebService

Data types

When developing the service, structs are the only method of exchanging complex types, which places limitations on what can be transferred. Currently, only structs composed of basic data types or containing other structs with basic data types (see the following code) are known to be correctly represented in WSDL.

public struct CarDetails
{
	public string makeOfCar;
	public string registration;
}

Back to top

Summary

In this article, you learned how:

• The LGI systems were designed to enable new assessors to interoperate with the assessor automation system
• A Microsoft .NET system-based assessor can be integrated with the system

Resources

• See Part 1 of this series, "Use business process management to create integrated solutions" (developerWorks, January 2004), for an overview of a mergers and acquisitions solution.
  
  
• See Part 3 of this series, "Design the external assessors solution" (developerWorks, March 2004), for a more detailed description of the external assessors solution.
  
  
• Visit the WebSphere Business Integration zone on the WebSphere section of developerWorks to search, download, learn, and get more information.
  
  
• Find out more about Business Integration on IBM Software.
  
  
• Learn how IBM WebSphere Business Integration for Insurance solutions enable firms to increase underwriting effectiveness, streamline policy administration, reduce cost of claims processing, and optimize agents by improving market reach with integrated prospect and client information.
  
  
• Get an overview and learn about IBM WebSphere MQ Workflow tools and components.
  
  
• Learn all you need to know about IBM WebSphere Business Integration Message Broker.
  
  
• Read the Redbook WebSphere and .NET Coexistence to learn more about interoperability between the two technologies.
  
  
• Browse for books on these and other technical topics.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Scenario overview
• Introduction
• Adding a new assessor
• Making design decisions
• Developing the .NET assessor Web services
• Creating effective deployment
• Understanding the lessons learned
• Summary
• Resources
• About the authors
• Comments

Next steps from IBM

WebSphere Application Server can leverage its built in Web Services support to expose services to remote consumers in an industry-standard way.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and includes built in Web Services support.
• Article: Learn how to use of the JAX-WS programming model to create dispatch and dynamic proxy clients and how to create an asynchronous Web service client.
• Tutorial: This tutorial takes you through the steps to deploy Data Web Services to the WebSphere Application Server Community Edition.
• Demo: This demo shows how to extract and install the IBM Java Platform, Java EE 5 SDK with WebSphere Application Server.
• Buy: WebSphere Application Server - Express