![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Web services and Service-Oriented Architectures (SOAs) are affecting major changes within the middleware integration landscape. While an open standards implementation of a SOA provides many advantages, leveraging the Web service specification to provide a positive experience when integrating the IT systems of two companies (and hence usually two business processes) requires attention to specific details. While developers can access a wide variety of articles on the technical side of the Web service integration, this article seeks to provide a larger, holistic view of the planning process.
Over the last several years, I've been putting together integration solutions between IBM® and their key network service providers. The project teams have managed to boil an integration methodology and process down to a degree that greatly reduces risk of failure. I think Plato was able to adequately address the greatest challenge that faces a team embarking down this road; there is still not an abundance of information available on how to plan these solutions. In other words, "you don't know what you don't know".
If you ask key questions and gather and sign off on the right artifacts in key phases of the project, then this methodology (as with any appropriate methodology) goes a long way to prevent errors caused by oversight or the unknown by gathering and signing off the right artifacts. Figure 1 below illustrates the details of the methodology. This article focuses on the first phase which includes:
- Planning
- Architecture
- Design
Figure 1. A high-level Web service integration project plan
Once you establish the requirement to provide a B2Bi Web service solution, assemble the project team tasked with the delivery of the solution. One thing to keep in mind here is the integration of assets from two companies to provide one working solution. In order to successfully accomplish this, you must form a joint project team from both companies. I’ve noticed that getting the team working as one from the initial phase is an important but difficult task to accomplish. Different companies and teams have a different culture and style of working. This is important because if you can succeed in creating a unified and cohesive project team, you’ll avoid a lot of unproductive finger pointing later on in test phase when issues inevitably occur. It is also important to make sure it’s clear to the joint team what the appropriate escalation paths are and how the decision making process is structured. If you’d like more information on which members are required for a successful project team, then take a look at Olaf Zimmermann’s article on "Web Services project roles", highlighted in the Resources section of this article.
The next step is to define and baseline all the requirements. Unless both teams from the companies are in the same town, you really have two choices here:
- Go through 4-6 weeks of several two hour long teleconferences a week
- Set up a series of well-planned, face-to-face meetings and workshops where all parties attend in one place
I highly favor the latter. If you plan it properly, you can really get a lot accomplished and make a solid start to your project. You need to complete and sign off on four project artifacts (very important for inevitable test phase issues and the allocation of responsibility) when you exit the week of meetings. These are:
- Requirements documents
- Business Process Integration document
- Technical Interface specification
- Data Mappings specification
These artifacts should ensure that the correct questions are asked at the right time. They also primarily cover issues that require agreement from both parties before either side can proceed with any changes needed within their integration middleware or system interface. As you move down the list of artifacts, you'll see that each document is the next layer of the onion.
The Requirements document is most likely the starting point for all the others. Since the core requirements are usually passed down with the request for work, it’s quite likely that this document is near completion before the meetings begin. It’s important to ensure items, such as use cases and the business rules, in these requirements.
Business Process Integration document
I have found that business process integration is a step that is often overlooked. What I mean is that one company might say to another company, "Lets partner on this contract. I’ll handle all incoming requests for service, and then I’ll route requests to you that I want you to service. In order to do that, we’ll need to integrate our Remedy Server with your e-ESM Server to automate the routing." What happens next is that the request for integration gets passed on to the joint team, and folks immediately start looking at obtaining their respective Web Services Description Language (WSDL) files, how to invoke each others Web services, and figuring out the messaging semantics. What they are overlooking is that at an operational level, the design of the two systems might process and provide information entirely differently.
An example of this would be in a helpdesk management scenario. You can design Remedy with a fixed set of options in a dropdown list. For example, a helpdesk agent updating tickets entered in the system has access only to the fixed set of options. The list is set and provides no means of freeform entry. The design of e-ESM Server logic is different. This design provides a freeform text box. The helpdesk agent updating tickets must manually type in what activities they have done to resolve an issue. How can you successfully map Remedy’s fixed list updates to the freeform concept in e-ESM?
Figure 2. Issues with business process integration
Figure 2 above illustrates an example of a business process integration issue. Business process subject matter experts from both companies can resolve these issues by going over what data to exchange and the high-level business process flows across the applications. You can use the WebSphere® Business Integration (WBI) Modeler (see Resources) tool to create these high-level flows to pass on to the Architects working on the system integration. This tool is part of the WebSphere Business Integration Suite of software and contains tools to help you model, simulate, and analyze complex business scenarios quickly and effectively before implementation.
This document should also discuss in detail how the two systems inter-operate at a business process level. For example, for each of the high-level business processes it should describe what should happen in all the various scenarios. This is extremely valuable information to the Technical Interface specification and Data Mappings team. Since this document is the one most likely to be referred to by non-technical operational and executive employees who want to know how the system works, it should also detail operational procedures to be used between the teams, such as contingency processes (who gets called for what and when), change control, and escalation procedures.
Technical Interface specification
At present, the WSDL does not provide enough information to be a conclusive source for a System Interface specification. This document supplements what the WSDL provides and can be highly technical in nature. It is also considered the system-level interface contract between both parties. Where appropriate, the document should provide references to pertinent external architecture documents, such as a Network Architecture document, which details the flow of network traffic between the two interfaces and other pertinent information (such as routers who need routing tables updated, the nature of the connection, and what firewalls need which ports opened).The document should also provide the WSDL files for the system interface of each company. It should then enumerate the system and integration attributes, which the WSDL does not cover. Examples of these would be:
- Whether the operation calls should be Document/Literal or Remote Procedure Call (RPC).
- Which protocols (Java™ Message Service (JMS) , HTTP, and so forth) are you using?
- Are there proprietary configurations that the partner has implemented (such as specific security information that needs to be provided in Simple Object Access Protocol (SOAP) or HTTP headers)?
- How will SOAP faults (client and server) be handled, and in what scenarios will they be generated?
- Will failed transactions be queued, or will a monitoring agent provide notifications (and to which parties)?
One should then seek to document the messaging protocol flows. This is of utmost importance as B2Bi systems have a slightly different use for Web services than the standard client proxy invoking a Web service to obtain an immediate response to a synchronous request. A B2Bi system typically sends a large complex XML payload to its service provider. The service provider often has to break the payload up and send it to one or more systems for processing before it can provide a response. For performance reasons, these exchanges are typically asynchronous, and the actual business service request can contain many asynchronous Web service operations before it is complete. It is important to lay this out as clearly as possible to avoid confusion between the teams. I have found that creating diagrams of the entire flow and all the operations involved has been a good way of avoiding confusion.
Once the joint team understands the flows, you need to document which Web service operations from one company map to which operations of the other company in order to accomplish the full lifecycle for a given service request. This requires careful discussion and the referencing of the case flows and business rules generated in the requirements discussions to make sure both systems have what they need to be integrated. Therefore, this is a good place to baseline the operations and their respective message schemas (and provides sample messages) for the different kinds of transactions so that the development teams can get a clear idea of exactly what comes over the wire.
Document the messaging security framework you use. For example, if you use Secure Sockets Layer (for example, SOAP over HTTPS), is it server only or client and server authentication? What kind of digital certificates formats do you plan to use? Will you test with self-signed certificates or real certificates? Lastly, what transaction limit can your system handle? It’s great to document this because once a system is up and working well; the tendency is for the project sponsors to direct more users to it. It’s important to set a fair expectation with the sponsors and the team on exactly what the system can do.
In the section describing the Technical Interface specification, I discussed that it is necessary to document which Web service operation needs to invoke which partner Web service operation in order to fulfill a given service request or response. Within these operations, an XML document literal payload is exchanged within the SOAP body. This payload needs to be in a specific format with specific data in order for the partner’s back end to be able to process your request. When your system initiates a transaction destined for the partner, you need to convert your literal XML request into the payload of your partner’s system. In order to do this, you need a mapping specification document detailing how every message schema for every Web service operation between the two of you is mapped. The development teams on either side can then later use this as the requirements for any XSLT mapping that needs to be done before the partner’s Web service is invoked.
As you can see in Figure 3 below, IBM sends the data to the partner in the format it expects it in, and the partner responds in the format IBM expects it in. You can accomplish this through data mappings.
Figure 3. An example of data translation
This article discussed how you might plan for a B2Bi Web service engagement. I took a holistic view of the planning process by examining which activities are intrinsic to success. I also discussed the reasoning for a methodology that provides you with specific baselined artifacts which can work to prevent oversights. Lastly, I took a look at what artifacts you need, their content, and their use within the solution.
- "On Demand integration with Web services" (developerWorks, July 2004) explains how Web Services and SOA fit into the On Demand Model.
- "Web Services project roles" (developerWorks, January 2004) discusses the different roles resources play in a WS Project.
- "Improve your SOA Project Plans" (developerWorks, July 2004) provides more information on planning and executing a Web Service related project.
- The WBI Modeler site has all the latest information on the product.
- Access Web services knowledge, tools, and skills with Speed-start Web services, which offers the latest Java-based software development tools and middleware from IBM (trial editions), plus online tutorials and articles, and an online technical forum.
- Browse for books on these and other technical topics.
- Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
Stephen Watt is a Software Architect working on middleware integration solutions with the IBM Network Service Providers. He works within the e-Technology Center for IBM Global Services at the lab in Austin,Texas. Steve works extensively with Web services and the latest WebSphere products and spends his time figuring out how emerging products and technologies can improve existing integration solutions within Service Delivery. Prior to working for IBM, Steve spent several years consulting in the Middle East and working for startups in the USA and his native South Africa. Steve is the co-author of Professional .NET Programming for J2EE Developers and The ASP Maintenance Handbook (Wrox Press) and has also published several articles at ASPToday. You can contact Steve at swatt@us.ibm.com
Table of contents
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
