Click here to Skip to main content
14,158,288 members
Click here to Skip to main content
Add your own
alternative version

Tagged as


16 bookmarked
Posted 22 Nov 2011
Licenced CPOL

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

, 1 Dec 2011
Rate this:
Please Sign up or sign in to vote.
This article attempts to explain BizTalk ESB Itinerary simple routing slip pattern using a Purchase Order processing sample

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?


  1. ESB On-Ramp: An ESB on-ramp receives a message. The message may not contain a itinerary.
  2. 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.
  3. 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.
  4. 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:


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

  1. When a message is received on the on-ramp, the receive handlers are configured to Transform and Route the message.
  2. The first receive handler transforms the PO message and creates the PO-Acknowledgement message.
  3. The second receive handler routes the message using a STATIC resolver to send the message to various folders (Acknowledgement and Archive folders).
  4. An Off-ramp extender is used to configure an off-ramp.
  5. 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] 

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

  1. You can have multiple off-ramps in your Itinerary, but you can have only one on-ramp.
  2. Observe the 'RouteToARecepient' shape in the itinerary, there are multiple resolvers, note that by default, only one resolver gets executed at any time.
  3. The way to execute multiple resolvers is to write a custom pipeline. Observe the custom pipeline screen shot.


  4. 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.


  5. 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.


  6. 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.



This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Naveen Karamchetti
Architect AT&T Wi-Fi Services
United States United States
Naveen has done his Masters (M.S.) in Computer science, has started his career programming the mainframes and now has more than a decade of programming, development and design experience. Naveen has a sharp eye and keen observation skills. Naveen has worked for several companies and strived hard to build large scale business applications and bringing better solutions to the table.
Quite recently Naveen has built a fairly complex integration platform for a large bank. His hobbies include training, mentoring and research. Naveen spends his free time visiting National Parks nationwide.

Naveen has developed the BizTalk Control Center (BCC)

You may also be interested in...


Comments and Discussions

Questiondid it work for any one. I couldn't unzip .MSI Pin
Member 110245479-Sep-14 1:31
memberMember 110245479-Sep-14 1:31 
QuestionUsage of components in receive pipeline Pin
Member 83083827-Jul-14 10:00
memberMember 83083827-Jul-14 10:00 
GeneralMy vote of 1 Pin
jeegarparmar16-Apr-14 23:59
memberjeegarparmar16-Apr-14 23:59 
QuestionGreat Post Pin
Surfzgr82-Feb-14 1:28
memberSurfzgr82-Feb-14 1:28 
GeneralGood Explanation : My vote 5 Pin
Shrilata Ellaboina1-Nov-12 1:51
memberShrilata Ellaboina1-Nov-12 1:51 
QuestionDoes this work for anyone Pin
arungopalam18-Jan-12 6:32
memberarungopalam18-Jan-12 6:32 
AnswerRe: Does this work for anyone Pin
Naveen Karamchetti18-Jan-12 11:35
professionalNaveen Karamchetti18-Jan-12 11:35 
Refer to point 3 in the 'Points of Interest' section. You have to write a simple custom pipeline to route it to multiple resolvers.

Always be there....| MCSD.NET | Sun Certified...
GeneralRe: Does this work for anyone Pin
arungopalam18-Jan-12 23:59
memberarungopalam18-Jan-12 23:59 
GeneralRe: Does this work for anyone Pin
arungopalam19-Jan-12 0:23
memberarungopalam19-Jan-12 0:23 
GeneralRe: Does this work for anyone Pin
arungopalam19-Jan-12 4:34
memberarungopalam19-Jan-12 4:34 
QuestionRe: Does this work for anyone Pin
Me.Monks26-Jul-12 22:30
memberMe.Monks26-Jul-12 22:30 
GeneralMy vote of 5 Pin
Kanasz Robert29-Nov-11 22:37
memberKanasz Robert29-Nov-11 22:37 
GeneralMy vote of 5 Pin
hedidin25-Nov-11 15:25
professionalhedidin25-Nov-11 15:25 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web02 | 2.8.190518.1 | Last Updated 1 Dec 2011
Article Copyright 2011 by Naveen Karamchetti
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid