BizTalk Server Enterprise Service Bus: Model Elements and Extenders in the Itinerary Designer

Article
1/17/2024

Introduction

The Itinerary Designer in the BizTalk Server ESB Toolkit is a powerful tool that greatly simplifies the creation of itineraries. It provides a visual representation of the flow of a message through BizTalk and allows manipulation of that representation. The shapes that make up this representation are called Model Elements. Each model element has various extenders that can be used to determine which properties can be associated with the model element. This article provides a description and listing of the model elements available in the Itinerary Designer Toolbox and also provides a description of the extenders that can be selected for each model element type.

On-Ramp Model Element

Not serialized as part of itinerary XML, instead just used for design-time validation to validate that proper pipeline components are available in one of the receive locations in the associated port. Also used as a visual cue to show where services are running.

On-Ramp Extender (Pink)

This is the only option. Every model element has to have an extender though to determine the properties that can be set.

Usage: On-Ramps can be preceded by nothing, and can be followed by a Messaging Service, an Orchestration Service, or an Itinerary Service with an Off-Ramp extender.

Itinerary Service Model Element

Itinerary services are the units of work of the ESB Toolkit. They must all be registered in the esb.config file in the install directory. Each service is implemented either as a .NET class that implements the IMessagingService interface (which is invoked in the pipeline by the ESB Dispatcher Pipeline component) or as a BizTalk Orchestration beginning with a direct bound activatable receive with a special filter.

See this article for choosing extenders: Choosing Between Messaging and Orchestration Itinerary Services

Messaging Extender (Faded Blue)

Use this extender to indicate that you wish to execute the service in the pipeline during the ESB Dispatcher pipeline component execution. This is only available for services that have been written as .NET classes that implement the IMessagingService interface and have been registered in esb.config. Messaging Services expose a container property that is used to indicate which pipeline they are to be executed in. The main point at which this becomes useful is when you have a two-way off-ramp and you wish to specify if the operations need to happen on the send pipeline or receive pipeline. Other model elements visually disambiguate other circumstances, but the container property is always still required. Routing* and Transformation services are available out-of-the-box, and custom services can be developed.

A note about the Routing service: The messaging routing service and orchestration routing service has a different implementation. The orchestration routing service takes in a message, sends that message out of BizTalk, and returns the original message to the bus. The messaging version of the service simply promotes the properties necessary for adapter configuration in the dynamic port that is the off-ramp, and the actual message transmission occurs in a later step in the itinerary (at the point that the Off-Ramp shape is reached).

Usage: An Itinerary Service with the Messaging extender can be preceded by an On-Ramp shape, Messaging Services (from the same pipeline) or an Itinerary Service with an Off-Ramp extender, and can be followed either by another Orchestration service, an Itinerary Service with an Off-Ramp extender, or an Off-Ramp model element.

Orchestration Extender (Green)

Use this extender to indicate that you wish to execute a BizTalk orchestration after a message has been persisted to the message box. By nature of the BizTalk architecture, it is not possible to include messaging services between orchestration services when there is no send/receive pipeline between them. ESB Itineraries are all about the processing instructions for the path of a single message. Orchestrations are all about coordinating multiple send and receive operations. Orchestration-based services give you the best of both worlds and allow you to start using itineraries to compose together integration patterns to form a complete solution. Routing* and Transformation are available out-of-the-box, two-way routing, message enrichment, and scatter-gather are available in samples (maybe others I'm forgetting), and custom services can be developed.

Usage: An Itinerary Service with the Orchestration extender can be preceded by either Messaging Services (from another pipeline) or Orchestration services, and can be followed either by another Orchestration service, or an Itinerary Service with an Off-Ramp extender.

Off-Ramp Extender (Yellow)

Use this extender to indicate that you wish to invoke an off-ramp at this point in the message life-cycle. Even though you could include a resolver for routing on this service ... don't include a resolver on this service. The itinerary will not work if exported in strict mode. Since on-ramp and off-ramp model elements are not serialized as part of the XML itinerary, this is the model element that is serialized to indicate which off-ramp will be invoked. It must be linked (via the properties window, not necessarily a connection) to an Off-Ramp model element, and it will pull its properties from the specified Off-Ramp. The properties are pulled from the filter on the Dynamic Send Port that the off-ramp represents. The properties ESB in general cares about are ServiceName, ServiceState, and ServiceType. In the designer, the state will always be "Pending". The Type for anything involving a pipeline is "Messaging", and the name is typically unique per service, and per port.

The Off-Ramp extender for the "Itinerary Service" model element is by far the most misunderstood (and even loathed by some) part of the itinerary design experience. But it is necessitated by the design.

Usage: An Itinerary Service with the Off-Ramp extender can be preceded by either Messaging Services (from another pipeline) or Orchestration services, and can be followed either by Messaging Services (in the Off-Ramp's pipeline) or an Off-Ramp model element.

Itinerary Broker Service Model Element

Use this extender to select the next Itinerary Service by creating XPath filters on context properties. No orchestration-based broker service is provided in the current implementations.

Off-Ramp Model Element

Not serialized as part of itinerary XML, instead just used for design-time validation to validate that proper pipeline components are available in the send port. Also used as a visual cue to show where services are running.

Off-Ramp Extender (Gold)