Developing a Web service using an industry-specific messaging standard

Web services are a key ingredient of service-oriented computing and Service-Oriented Architecture (SOA). Interactions between service consumers and service providers are primarily message-based. The structure of these messages is defined in a service’s interface definition, specified in Web Services Description Language (WSDL). Organizations are increasingly moving toward supporting industry-specific messaging standards. This article describes an approach to developing a Web service that uses the ACORD messaging standard for an insurance industry client. With the help of an example, you can see how a Web service definition is created based on business process decomposition, including mapping data elements to their respective standard schema elements. You can also see considerations when dealing with schema maintenance, data binding, and data typing during runtime and build time. While this article offers only a glimpse into what is needed to fully utilize a standard message model, it tries to describe one key aspect of it and serves as a starting point for further discussion.

Abdul Allam (allam@us.ibm.com), Certified IT Architect, IBM

Abdul Allam is a Certified Executive IT Architect in the Application Development Practice of IBM. He is a core member of WS SOA COE. Abdul leads and helps in architecting and developing SOA solutions for IBM customers. He also focuses on developing SOA assets and best practices within IBM. He has over 20 years of experience in the IT and telecommunications fields providing consulting and development services.



Andre Tost, Senior Technical Staff Member, IBM

Andre Tost works as a Senior Technical Staff Member in the IBM Software Services for WebSphere organization, where he helps IBM customers establish Service-Oriented Architectures. His special focus is on Web services and Enterprise Service Bus technology. Before his current assignment, Andre spent ten years in various partner enablement, development, and architecture roles in IBM software development, most recently in the Enterprise Integration Solutions group.


developerWorks Master author
        level

05 July 2007

Also available in Russian

Introduction

Identifying and then specifying services is a core part of establishing a Service-Oriented Architecture. It starts with assessing and decomposing key business processes. This decomposition leads to identification of a set of services, each represented by a WSDL definition. Within this definition, references exist to XML schema type definitions that describe the message structure of the messages that the services exchange. Combined with protocol bindings that contain definitions for message protocol and network transport details (such as SOAP over HTTP), the WSDL definition provides a standardized, complete service contract that potential customers can use to access the service, without knowledge of how the actual service logic is implemented.

Figure 1 shows the key constituents of a service interface or service description. This article presents an approach that shows how to define this service contract, including use of industry standard message models. A fictional case study is used from the insurance industry: Acme insurance company.

Figure 1. Service interface (WSDL) constituents
Service interface (WSDL) constituents

Identifying services

Before any detailed analysis can begin, start by identifying the main business goals or current pain points within the enterprise. This list leads to a list of business processes that are appropriate for further decomposition. For the fictional insurance company, detailed discussions were held with client business and subject matter experts, resulting in the identification of the following business goal: Deliver underwriting excellence through improved increased operational efficiencies. Further analysis of this goal indicated that there was a requirement to improve underwriting efficiencies in the area of vehicle insurance, because the current systems carried the potential to make errors in premium calculations if retrieved vehicle information was not correct. Once the business goal was identified, it was easy to determine the relevant business process: order and aggregate information.

Furthermore, key input to the service interfaces are use cases, which provide information on the actions that need to be performed, the data elements associated with these operations, and any applicable business rules. The Order and Aggregate Information process was further decomposed to help identify relevant service candidates. The related operations were identified using business process analysis (primarily business process decomposition) and use case scenarios as inputs.

Figure 2. Process decomposition to identify services
Process decomposition to identify services

Figure 2 shows an example of the process decomposition, resulting in identification of four operations associated with an activity called Retrieve Vehicle Request. For simplicity, this article uses the term Vehicle Service as the name for the service representing this activity. The Vehicle Service's four operations are described as follows:

  • GetYears(): GetYears provides the ability for vehicle drill-down capabilities. A call to this operation with no make or model parameters is like a SELECT DISTINCT ON YEAR operation that provides all of the years available for selection in the data. Calls to GetYears() with a model or make limit the returned values that pertain to the particular make or model.
  • GetModels(): GetModels provides the models that pertain to a make, a year or a make-and-year combination. GetModels provides the ability for vehicle drill-down capabilities.
  • GetMakes(): GetMakes provides a list of vehicle makes. A call to the operation with no parameters passed provides a listing of all the makes that the data store has to offer. If year is passed in as the parameter, the operation returns makes that existed for that particular year.
  • GetVehicleProfile(): GetVehicleProfile returns all of the information for a particular make, model, and year combination or for VIN number. A list can be returned.
Figure 3. Operations and associated data elements for service interface to support
Operations and associated data elements for service interface to support

Figure 3 shows a detailed listing of the operations of the vehicle service and its associated data elements. Note that the service you are designing in this case is very data centric, meaning it returns different variations of data that are related to vehicle information. The vehicle service also does not offer any update capability, so it will most likely be implemented as read-only. You can safely assume that this service will be usable across multiple business domains, even though it was identified through decomposition of one particular business process.

The information is captured in a spreadsheet. This spreadsheet can be used to capture other information, such as the backend system interfaces (not detailed in this article) and the data elements supported by industry-specific schemas.


Mapping data

For the example, a data mapping spreadsheet was used to capture all the data elements associated with the request and response messages associated with a specific service action or operation. Starting with an analysis of relevant use cases and involving line of business personnel ensured alignment between the design of the service and the business problem it is helping to solve.

There are two reasons to now look toward an industry-standard model to serve as the basis for the concrete service interface. One reason is that the service will most likely interact with external partners, both as consumers and providers of information, so using a standard message format makes the service more interoperable overall. Another reason is that a data-centric service like the vehicle service will end up being reused across the enterprise, and using a standard as the basis for an enterprise-wide canonical message model seems appropriate. For the example, the insurance company chooses ACORD as a standard that is relevant to define the vehicle service, because it contains predefined data types that can be reused.

The next step in the process is to identify the data elements in the ACORD schema that the actual service interface requires. Before you start this step, it is essential to determine which version of the ACORD standard the client organization supports. After you know the version, you need to identify the schema that is relevant to the service under consideration. Predictably, the ACORD vehicle schema is the focus of this article. Aggregate elements associated with the vehicle schema are analyzed to identify all the root elements that correspond with the data elements of the service interface. Figure 4 shows how the data elements identified through the use cases and the matching data elements in the vehicle schema are captured in the spreadsheet.

This data mapping helps to identify the following:

  • Data elements that are needed by the service (as required by the use cases), which are supported by the current version of the ACORD standard
  • Data elements that are not supported by the current version of the ACORD standard. These are the elements that are specific to a specific company’s business need.
Figure 4. Spreadsheet to capture information
Spreadsheet to capture information

Understanding mapping considerations

This section highlights some key considerations related to message schemas, schema maintenance, and data typing.

Exploring message schema considerations

Throughout the data mapping exercise, you might have observed the following:

  • Not all of the data elements that the use cases required were supported by the ACORD vehicle schema.
  • The ACORD schema supports a significantly large number of complex types. This results in various options to be considered. Pros and cons for each option are listed below:
Table 1. ACORD schema
OptionsProsCons
Option 1: Use the entire ACORD schema for the serviceFully compliant with the industry standard as you use the imported standard schema.Large number of classes generated by tooling. Results in large XML messages.
Option 2: Develop a client-organization-specific schemaResults in less generated code. Results in smaller XML messages, which take less time to be processed, validated, debugged, and so on.Not compliant with industry standard.
Option 3: Use a subset of the relevant ACORD schema and extend to accommodate client-specific data elementsResults in less generated code, because only a subset of the relevant ACORD schema is used (such as the vehicle ACORD schema). Results in smaller XML messages, which take less time to be processed, validated, debugged, and so on. Based on industry standard.Not fully standard compliant.

Given this analysis, the Acme insurance company chooses option 3:

  • The vehicle ACORD schema is to be used instead of the entire ACORD schema.
  • The schema is extended to support additional parameters the vehicle service requires. This allows the schema to be based on the standard while keeping the number of objects created to a minimum.
Figure 5. Example schema extension
Example schema extension

Figure 5 shows an example of how the standard type acord:PersVehInfo_Type was extended to support two new data elements, RegionalCostNewAmt and Cylinders, by taking advantage of XML schema type inheritance.

Exploring data binding considerations

When implementing a Web service in Java™, the most common approach is to use tooling to generate code artifacts using the JAX-RPC standard. A common tool for generating code that maps to a given WSDL definition is called WSDL2Java. JAX-RPC also defines how XML schema constructs are to be mapped and deserialized in Java. For example, WebSphere® Application Server provides a WSDL2Java tool and runtime classes for serializing Java objects into XML and for deserializing XML documents into Java. This makes the fact that SOAP messages are exchanged on the outside of a service transparent to the developer of the actual service logic.

However, JAX-RPC defines support for some XML schema constructs as optional, and many of these are used in industry schemas, such as ACORD. There is no standard way of handling these. In fact, WebSphere Application Server does not support common elements such as group or choice. Moreover, large and heavily nested schemas can also lead to generation of many Java classes that are complex and hard to use.

There are several options to overcome this:

  • During generation of code artifacts, you can turn off the Java-to-XML mapping. In that case, the pure XML content is passed into the service implementation class and can be parsed and handled there. While this requires more code to be developed, it allows full control over if and how XML content is used.
  • WebSphere Application Server supports plugging in a custom data binding mechanism instead of using the default, JAX-RPC-based data binding mechanism. You can then implement your own version of serialization or reuse any other mechanism that serves your needs. For example, you can leverage any existing JAXB implementation this way.
  • You can also modify the schema beyond the custom extensions already discussed. In other words, you start out with the standard and modify it until it meets your needs. However, note that this leads to an interface that is most likely closely related to, but not compliant with, the standard.
  • You can replace the most complex types in the schema with the generic <xsd:any/> element before you run the WSDL2Java tool. This avoids creating many Java classes as mentioned, but just like in the first option in this list, it leaves parsing and handling of these types to the service implementation logic.

In the future, the JAX-WS 2.0 standard API will replace the JAX-RPC standard API. The 2.0 version completely delegates Java-to-XML mapping to JAXB 2.0, which supports the full set of XML schema elements. While this solves the problem of unsupported schema, it still leaves the risk of generating a large amount of Java code, especially when using complex schemas.

Understanding data typing considerations

As mentioned, adopting an industry-standard message structure helps to support reusability of services overall and provides for easier integration with both internal and external applications, such as third party databases. However, highlighted below is an issue that might arise due to data typing, forcing you to further augment the industry-standard schema.

Typically, industry standards are W3C XML schema compliant. They often leverage ways offered by the XML Schema specification to constrain data types, in order to make them as specific as possible. For example, the length element, which is used frequently throughout the ACORD standard, is generally typed to xsd:decimal. In many cases, though, when mapping this element to an existing database or application interface, you notice that it is defined as a string instead, and it includes character data, such as 5ft10in. Other examples are enumerations or other restrictions of a data type's valid range of values, which can be defined in the standard but which cannot be mapped properly to existing data.

In order to address this type of discrepancy, it is important to enhance data mapping documentation with additional information about any extensions that need to be made.

Understanding schema maintenance considerations

The majority of industry-standard message specifications consist of a single large schema. For example, the ACORD schema is 1.5 MB. Slicing the schema into smaller, more manageable slices for both maintenance and implementation reasons is recommended. Typically, the schema can be split along the lines of business (LOB) or along business entity lines for even more granularity (such as vehicle, client or customer). In the case of the vehicle service, assume that the associated schema will be reused across multiple business processes and domains, so you need to isolate it in its own schema and namespace.

Moreover, in order to promote reusability of schemas at the enterprise level, any reusable schemas need to be stored in a repository in the enterprise domain. You need to develop a strategy for maintaining, storing, and discovering the schema. This, then, becomes part of overall service governance.


Relating XSD and WSDL

This section examines the relationships between the ACORD standard XML schema and the schema of your Acme insurance company, as well as its relationship with the WSDL definition for the vehicle Web service.

Figure 6. Relationships between XSDs and WSDL
Relationships between XSDs and WSDL

Step 1: The standard schema

Figure 7 shows a partial list of the elements and types defined in the ACORD standard schema related to vehicles.

Figure 7. ACORD XML schema extract
ACORD XML schema extract

All the elements and types of this schema belong to the namespace called http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/. Here is a snippet of the actual schema, stored in a file called vehicle_acord.xsd:

Listing 1. Snippet of vehicle_acord.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" 
    elementFormDefault="unqualified" attributeFormDefault="unqualified" version="1.8.0">
	<xsd:element name="SignonRq" type="SignonRq_Type"/>
	<xsd:complexType name="SignonRq_Type">
		<xsd:sequence>
			<!--
			<xsd:group ref="SIGNONENTITY" minOccurs="0"/>
            -->
			<xsd:element ref="SignonPswd" minOccurs="0"/>
			<xsd:element ref="SignonCert" minOccurs="0"/>
			<xsd:element ref="SignonTransport" minOccurs="0"/>
			<xsd:element ref="SessKey" minOccurs="0"/>
			<xsd:element ref="ClientDt"/>
			<xsd:element ref="CustLangPref"/>
			<xsd:element ref="ClientApp"/>
			<xsd:element ref="ProxyClient" minOccurs="0"/>
			<xsd:element ref="SuppressEcho" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>
	<!--
		<xsd:group name="SIGNONENTITY">
		<xsd:choice>
			<xsd:element ref="SignonPswd"/>
			<xsd:element ref="SignonCert"/>
			<xsd:element ref="SignonTransport"/>
			<xsd:element ref="SessKey"/>
		</xsd:choice>
	</xsd:group>
	………………

Step 2. Custom extensions

Next, take a look at the specific schema in a file called vehicle_acme.xsd that was developed for the Acme insurance example. This file defines new elements and types that are relevant to Acme in a new namespace, http://vehicle.gbo.acme.com. The file imports all the elements and types from the vehicle_acord.xsd file and extends some of the elements and types from it to support elements and types that are not found in the standard.

Figure 8. Partial list of elements and types from vehicle_acme.xsd file
Partial list of elements and types from vehicle_acme.xsd file

Listing 2 shows a snippet of the vehicle_acme.xsd file. It highlights the import statement for the standard schema.

Listing 2. The vehicle_acme.xsd file
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://vehicle.gbo.acme.com" 
    xmlns:acord="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    targetNamespace="http://vehicle.gbo.acme.com" 
    elementFormDefault="qualified" attributeFormDefault="unqualified">
	<xsd:import namespace="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" 
      schemaLocation="vehicle_acord.xsd"/>
	<xsd:complexType name="VehInfo_Type">
		<xsd:complexContent<
			<xsd:extension base="acord:VehInfo_Type">
				<xsd:sequence>
					<xsd:element ref="SubModel" minOccurs="0"/>
					<xsd:element ref="BaseModel" minOccurs="0"/>
					<xsd:element ref="ModelNumber" minOccurs="0"/>
					<xsd:element ref="RetailAmt" minOccurs="0"/>
					<xsd:element ref="PolicyType" minOccurs="0"/>
					<xsd:element ref="BusinessTransactionType" minOccurs="0"/>
					<xsd:element ref="RegionalCostNewInd" minOccurs="0"/>
					<xsd:element ref="State" minOccurs="0"/>
					<xsd:element ref="MotorcycleType" minOccurs="0"/>
					<xsd:element ref="RecreationalVehicleType" minOccurs="0"/>
					<xsd:element ref="BoatType" minOccurs="0"/>
					<xsd:element ref="Hull" minOccurs="0"/>
					<xsd:element ref="LivestockTrailerType" minOccurs="0"/>
					<xsd:element ref="LivestockTrailerSubType" minOccurs="0"/>
				</xsd:sequence>
			</xsd:extension>
		</xsd:complexContent>
	</xsd:complexType>
	……

Step 3. Creating the WSDL definition

Finally, examine the relationship between the WSDL and the schema. As shown in Figure 6, the VehicleInformationService.wsdl imports the vehicle_acme.xsd file to use the defined elements and types as message parts. Listing 3 shows an extract of the VehicleInformationService.wsdl file, which shows the appropriate import statement and the reuse of the elements.

Listing 3. An extract of the VehicleInformationService.wsdl file

Click to see code listing

Listing 3. An extract of the VehicleInformationService.wsdl file

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
    xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
    xmlns:tns="http://vehicle.service.acme.com" 
    targetNamespace="http://vehicle.service.acme.com">
	<types>
		<xs:schema xmlns="http://www.w3.org/2001/XMLSchema" 
        xmlns:acme="http://vehicle.gbo.acme.com" 
        elementFormDefault="qualified" targetNamespace="http://vehicle.service.acme.com">
			<xs:import namespace="http://vehicle.gbo.acme.com" schemaLocation="vehicle_acme.xsd"/>
			<xs:element name="GetVehInformationRequest" type="acme:VehInformationRequestType"/>
			<xs:element name="GetVehInformationResponse" type="acme:VehInformationResponseType"/>
			<xs:element name="GetModelYearsRequest" type="acme:VehInformationRequestType"/>
			<xs:element name="GetModelYearsResponse" type="acme:VehInformationResponseType"/>
			<xs:element name="GetModelsRequest" type="acme:VehInformationRequestType"/>
			<xs:element name="GetModelsResponse" type="acme:VehInformationResponseType"/>
			<xs:element name="GetMakesRequest" type="acme:VehInformationRequestType"/>
			<xs:element name="GetMakesResponse" type="acme:VehInformationResponseType"/>
		</xs:schema>
	</types>
	<message name="VehInformationRequestMessage">
		<part name="getVehInformationRequest" element="tns:GetVehInformationRequest"/>
	</message>
	<message name="VehInformationResponseMessage">
		<part name="getVehInformationResponse" element="tns:GetVehInformationResponse"/>
	</message>
	……

Note that the namespace of the actual service is different than the namespace of the imported elements and types in the schema. This is generally considered a best practice, because it allows reusing the schema artifacts across a number of different service definitions.


Conclusion

In this article, you saw an approach for supporting a standardized, industry-specific messaging standard. The article introduced an example based on the insurance industry, which led to the ACORD standard. You learned some of the key considerations associated with supporting an entire schema, a client-organization-specific schema, or a customized subset of the industry schema. The recommendation was to use a subset of the standardized schema and extend it to support customer-specific data elements. This allows the message specification to be compliant with the industry standard while keeping the number of generated artifacts for service development to a minimum. Moreover, you learned some key considerations for dealing with data typing and data binding issues. You also learned that a corporate-wide governance strategy needed to be developed for effective maintenance and versioning of the schema to promote re-usability.

Note that the use of industry standards varies widely, depending on the industry and the address business scenarios. Those solutions might look slightly different.

Acknowledgments

We want to thank Nina Chien from IBM Global Business Services and Shakeel Mahate of IBM Software Group for their help with this article.

Resources

Learn

Get products and technologies

  • Innovate your next development project with IBM trial software, available for download or on DVD.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=238761
ArticleTitle=Developing a Web service using an industry-specific messaging standard
publish-date=07052007