Tracing and Tracking ESB events

Many a times one may feel the need to trace ESB events when using itineraries. This will enable you to see how a message is getting processed by the ESB itinerary resolver and if something is going wrong there. The process of enabling this switch is quite simple and it involves the following:


1) Open the BizTalk Configuration file, ie BTSNTSVC.exe.config

2) Add the following section (if one does not exist)  and save the file:



<source name=”BizTalk ESB Toolkit 2.0″ />



<add name=”BizTalkESBToolkit20″ value=”4″ />


<trace autoflush=”true” indentsize=”4″ >

<listeners >

<add name=”myListener”   type=”System.Diagnostics.EventLogTraceListener” initializeData=”BizTalk ESB Toolkit 2.0″ />




Add a Trace listener. If you don't already have a trace listener configured, add 1 of the many Trace listeners that come out of the box with the .Net framework: (Default, EventLog, TextWriter, Console, Text, etc.)
When using the EventLogTraceListener, the initializeData attribute must be set to the source of the Tracing Event. 
In this case it is the "BizTalk ESB Toolkit 2.0" source.

3) Restart the BizTalk Host Instance.

4) You will now see information and error events in the event viewer. Also if you have debugview running, you will see code traces there.


After enabling tracing, you might still feel the need for tracking. That is, what went where? Every Itinerary Service has a property called ‘Tracking Enabled’ which you’ve got to set it to ‘True’ during the design phase. This sets the stage for tracking an Itinerary Service. Set this property for every single service in an Itinerary as this is false by default. Only those services whose ‘Tracking Enabled’ property is set to true will show up in the database.

Ok, tracking is set to true and my itinerary is deployed. Where do I see this tracing information?

When a service in an itinerary is set for tracking, it is recorded in the BAMPrimaryImport database in the table bam_ItineraryServiceActivity_Completed. the column itineraryBeginTime should be used to sort the results by datetime.

This table gives a snapshot view of the trajectory of the message and if each stage in its path was completed or pending.

Dynamic Itinerary Resolution (ESB toolkit 2.0/2.1)

If you ever had a situation where you needed to attach an itinerary to your message dynamically, ESB toolkit just allows you to do that.

I recently worked on a project that involved various stages (which each stage having >1 orchestrations) and depending on the content of the message, it would get thrown out to a sharepoint portal for business exceptions. The support staff could then view the message, fix the contents of the message via infopath and resubmit the message into BizTalk. However, since there was a common entry point for all the messages into BizTalk, I needed a mechanism to dynamically attach the correct itinerary to the message depending on the progression made by that message just before it was thrown to Sharepoint. This is where the ESB toolkit comes in.

The ESB toolkit installs some receive and send pipelines which are designed for itineraries. One such receive pipeline is called ‘ItinerarySelectReceiveXml’ pipeline. This pipeline allows you to specify a BRI (not BRE) policy to determine which itinerary to use.

I created a file receive port and defined a new file location as under:

You can view the properties of this pipeline by clicking the button next the pipeline. Here you can set the fact key and the resolver connection string to point to your BRI policy.

The two important properties to set are:
ItineraryFactKey: The key in the dictionary returned by the resolver that contains the actual XML of the Itinerary selected. In most cases, it should be set to ‘Resolver.Itinerary’, unless a custom resolver is used.

ResolverConnectionString: Connection string to the itinerary that should be attached to the incoming message. This is a resolver connection string that contains name-value pairs that a resolver can use to select and/or look-up an itinerary. This in turn executes either the Static or Business Rules resolver, which provides an itinerary name (and version number). The ESB Itinerary Selector component then uses this name and version information to load the requested itinerary from the itinerary database.

Example ResolverConnectionString:

Name: The name of the itinerary to use.
Policy: In case the business rules engine is used to set the itinerary, the policy name is set here.
Version: Version of your policy to use. if this is left blank, the BRI engine uses the latest policy deployed.
useMsg: Set this to true if you need to pass the context of the message to the business rules engine (for content based routing).

Once these properties are set, you need to create and deploy a policy in the business rules composer. One of the rules in my policy is shown under:

My message stages would be something like:

Once this policy is deployed, it will be called by the pipeline and the message passed through.

Basically what I have done is first checked the target namespace and ensured that it matched the namespace of the message I was expecting. The second condition was to check if the message was thrown out to Sharepoint from one of the stages in this itinerary. I wanted that itinerary to be attached to this message only if the message dint go through all the stages in that itinerary. Once the message goes through the last stage in this itinerary, the messagestage it set to something like “PhaseAProcessed” thus not meeting the above conditions for this itinerary.

You can create similar rules in your policy to match certain stages and attach the relevant itineraries.

Thats about it. You can now throw a message in your receive location and the correct itinerary will be attached to your message based on the content.