Introducing the 'Hello World' of BizTalk ESB Itinerary

In this article, we shall be looking at a simple itinerary which processes a PO message and produces a PO-Acknowledgement. Basically a PO is transformed into a POA and written to various locations.

What are BizTalk ESB Itineraries?

In simple words, an Itinerary is a sequence of operations performed on message, which can involve routing and transformation. An Itinerary is an implementation of Routing-slip pattern, which is essentially an execution of sequence of processing steps for a particular message. For more information, see the references section at the end of the article.

What Comprises an Itinerary life cycle?

ESB On-Ramp: An ESB on-ramp receives a message. The message may not contain a itinerary.
ESB Pipeline Components: ESB pipeline component copies the itinerary into the context of the message as a promoted property. The itinerary resides in the message context during the entire lifetime of the message.
BizTalk Message box: The message is published to the Microsoft BizTalk Server Message Box database where BizTalk evaluates the promoted properties of the message and queues the message for one or more subscribers.
ESB Off-Ramp: The subscribers can be either a directly bound orchestration (with some filter properties set on the receive shape) or a dynamic BizTalk Server send port, which is also referred to as an ESB off-ramp.

Itinerary Concepts

What is an on-ramp?

A BizTalk receive location responsible for receiving ESB-destined messages is referred to as an on-ramp.

What is an off-ramp?

An ESB off-ramp corresponds to a BizTalk dynamic send port with filters set for ESB promoted properties.

What are ESB Resolvers?

The purpose of a resolver is to support resolution and routing at the messaging level, without requiring the use of BizTalk orchestrations. The BizTalk ESB Toolkit includes the following resolvers: STATIC, UDDI, UDDI3, XPATH, BRE, BRI, ITINERARY, ITINERARY-STATIC and LDAP. For more information, see the references section at the end of the article.

Common ESB Resolvers

A resolver's connection string comprises of a moniker followed by ":\\" and the processing details. See some examples below:

ITINERARY:\\name=TwoWayTestItinerary;version=;
BRE:\\policy=GetCanadaEndPoint;version=;useMsg=False;
BRI:\\policy=ResolveItinerary;version=;useMsg=True;

NOTE: Set the property usgMsg to 'True', if you need to pass the context and the body of the message to the rules engine.

Do you know the difference between BRE resolver and a BRI resolver?

The definition goes like this, the BRE stands for 'Business Rules Engine Resolver', while BRI stands for 'Business Rules Itinerary Resolver'.

The BRI resolver is used for resolving itineraries from the data store while the BRE resolver is concerned only with resolving transport information and transform information.

Our 'Hello World' like PO Processing Itinerary

What does this Itinerary Achieve?

The objective of this itinerary is to process a PO. The PO shall be transformed into a PO-Ack and routed to a PO archive folder and a PO-Ack folder.

Explanation of Various Steps

When a message is received on the on-ramp, the receive handlers are configured to Transform and Route the message.
The first receive handler transforms the PO message and creates the PO-Acknowledgement message.
The second receive handler routes the message using a STATIC resolver to send the message to various folders (Acknowledgement and Archive folders).
An Off-ramp extender is used to configure an off-ramp.
Finally the off-ramp transmits the message to various folders using Dynamic routing.

Development Notes

Common Errors during Itinerary Development

Scenario 1: What happens when the filters for a dynamic send port which is used as a off-ramp are NOT set.

The 'ServiceType' property value should not be empty or null. Location: SendPortFilter    
The 'ServiceName' property value should not be empty or null. Location: SendPortFilter
The 'ServiceState' property value should not be empty or null. Location: SendPortFilter

Scenario 2: Requested value 'Transformation' was not found.

Requested value 'Transformation' was not found. 
Source: Microsoft.Practices.ESB.Itinerary.OM.V1.ItineraryV1 
Method: System.String AdvanceByOrder
(Microsoft.Practices.ESB.Itinerary.ItineraryMessageDirection, System.String, 
Microsoft.Practices.ESB.Itinerary.IItineraryStep, System.Action, Boolean)

Resolution: The solution is to look at the Itinerary XML file. In the XML file, have a look at the Service element, and the name attribute, this must match with the name of the Itinerary. There might be a case where, you might rename the Itinerary after its been created, this shall lead to the above error.

Scenario 3: Procedure or function 'Itinerary_getitinerary' expects parameter '@name', which was not supplied.

Procedure or function 'Itinerary_getitinerary' expects parameter 
'@name', which was not supplied.  
Source: Microsoft.Practices.ESB.Resolver.ResolverMgr 
Method: System.Collections.Generic.Dictionary`2[System.String,System.String] 
Resolve(Microsoft.Practices.ESB.Resolver.ResolverInfo, 
Microsoft.BizTalk.Message.Interop.IBaseMessage, 
Microsoft.BizTalk.Component.Interop.IPipelineContext)

Cause: This happens when the ESB system is unable to resolve an Itinerary due to an incorrect message placed on the bus while using a BRI resolver. Use the BizTalk administration console and check the message and its promoted properties.

Scenario 4: Error 135008: The itinerary was not found in the repository

Resolution: Check the [nStatus] column in the table [EsbItineraryDb].[dbo].[Itinerary] for the respective Itineraries, it must be set to 1.
NOTE: You would want to restart the host instance(s), since the Itineraries are cached.

Itinerary Deployment Notes

Its recommended to export all your itineraries into XML from the designer before deployment.

EsbImportUtil Command Line Tool for Itinerary Deployment

You can find it in C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.1\Bin:

esbimportutil.exe /f:simpleroutingslip.xml /c:deployed /o

Points of Interest

You can have multiple off-ramps in your Itinerary, but you can have only one on-ramp.
Observe the 'RouteToARecepient' shape in the itinerary, there are multiple resolvers, note that by default, only one resolver gets executed at any time.
The way to execute multiple resolvers is to write a custom pipeline. Observe the custom pipeline screen shot.
The itinerary applied for a message is set in the receive location itself using the ResolverConnectionString property. This can be a static value or can dynamically determined using a BRE resolver.
You can easily deploy a itinerary using Visual Studio, just right-click on the itinerary designer and select Export model. Note that the Itinerary status must be in Deployed state.
Note the filter settings required for a dynamic send port to be an off-ramp.

Downloadable Code

The code was developed in Visual Studio 2010 using BizTalk Server 2010 and ESB Toolkit 2.1.

References

Hello World in BizTalk ESB Itinerary using a Purchase Order (PO) Process