Chapter 4. Understanding the ESB Web Services

One of the main goals of an ESB is to facilitate access to the services and capabilities exposed by IT solutions across an organization. In order to facilitate access to those services, the ESB Toolkit provides a set of services that enable consumers to participate in ESB message exchanges through a standardized API. At the same time, some of the ESB Toolkit core features are exposed as services.

In this chapter we will:

• Explore the different services exposed by the ESB Toolkit

• Analyze the scenarios where those services can be useful to external systems

The itinerary on-ramp services

The itinerary web services, also known as on-ramps, are the ones that allow clients trigger ESB exchanges and processes by delivering messages to the ESB for their processing.

The main inputs to trigger the message processing by an itinerary in the ESB are:

• The payload: It's the actual message that is meant to be processed. When using the out of the box Itinerary web services, this payload must be an XML document, but we could create our own itinerary service to receive non-XML payloads for processing through itineraries. These could be meant to process flat files or other kinds of files.

• The itinerary: We need to tell the service which itinerary the payload should go through. We can do it explicitly by attaching the actual itinerary XML representation, or by providing the information required to resolve the itinerary to be used. The ESB Toolkit provides two sets of services (in WCF and ASMX flavors) that support these two ways to specify the itinerary.

Itinerary...

The Resolver web service

The ESB Toolkit provides us with a powerful and dynamic resolution framework that helps us to discover how our ESB interactions should behave. For example, deciding which endpoint should be reached by some message or which transformation should be applied.

This capability can be very useful to be re-used by any external systems connected to the ESB, and so this Resolver web service exposes it to any consumer. Like the Itinerary services, this service is exposed in both ASMX and WCF flavors.

The service has two operations:

• Resolve: This operation executes the resolution using as an input the connection string exclusively, and so that's the only parameter it takes as an input. The service executes the corresponding resolver and returns the resolution result as a list of name-value pairs.

• ResolveMessage: This operation, apart from the resolution connection string, receives an XML message as a string. That message is used as an input for the resolution process (for example...

The Transformation web service

This service exposes the ESB feature of messages transformation. It does so without needing to persist the actual message into the message box to do it.

It has one single operation named Transform that takes as an input the XML message to be transformed and the fully qualified name of the map deployed in BizTalk. It returns the XML representation of the transformed message.

Systems consuming this service shouldn't necessarily need to know the format in which the maps' names are qualified in BizTalk, so it could be useful to use the Resolver service to resolve the name of the map, and then use the output of that resolution as an input for the fully qualified name of the map on the Transform call.

This service is also available in both ASMX and WCF flavors.

The Exception Handling web service

This service was already introduced in the Chapter 3, ESB Exception Handling, dedicated to the exception management in the ESB Toolkit.

In order to submit a fault into the ESB so it's handled by the standard ESB faults processing logic we might have in place in our ESB, we just need to instantiate the FaultMessage class defined in the service contract, fill its properties, and use it as an input for the SubmitFault operation of the service.

The properties on that fault message are the same as the ones we already described in the Chapter 3, ESB Exception Handling:

Ex.ExceptionHandling handleException = new ExceptionHandlingService.SubmitFault.ExceptionHandling();
                handleException.Credentials = System.Net.CredentialCache.DefaultCredentials;
               
                Ex.FaultMessage faultMsg = new Ex.FaultMessage();
                faultMsg.Header = new Ex.FaultMessageHeader();
                faultMsg.Header.Application = "Exception Handling...

The BizTalk Operations web service

The BizTalk Operations web service exposes to external systems information about our ESB environment, the artifacts deployed on it, and the messages flowing through our ESB.

This could be useful to provide information to our own operations and management systems.

It exposes the following operations:

• Applications: This method is without parameters. It returns the name and description of all the installed BizTalk applications as a collection of BTApplication objects.

• ApplicationStatus: This method has one parameter, the application name. It returns information about the specified BizTalk application as a BTSysStatus instance. This includes orchestrations, send ports, receive locations, and host details.

• GetLiveMessageBody: This method takes two parameters, message ID and instance ID. It returns the body of that message from the live environment as a BTMsgBody instance.

• GetMessageInstances: This method takes one parameter, the message type It returns all matching...

Summary

In this chapter, we went through the different web services exposed by the ESB Toolkit, learned what their capabilities are, and saw how we can consume them.

In the next chapter, we will further describe the features of the ESB Management Portal that were briefly introduced in the previous chapters.