BAM API – Using OrchestrationEventStream to write BAM Events from BizTalk orchestration

Posted: August 23, 2010 in BizTalk
Tags: , ,

The OrchestrationEventStream (OES) is one of the artifacts developers should consider in order to programmatically populate a BAM activity model from within a BizTalk orchestration.

The OES writes BAM Activity data into the state of the BizTalk orchestration and does not require a database roundtrip each time. When the orchestration completes or reaches a persistence point, the BAM activity data is written into the MessageBox along with the orchestration state.

Because this data is part of the orchestration state, all data is rolled back along with the orchestration if an error condition is reached. This method gives you complete transactional integrity, unlike the other event stream options, and offers the best performance for an orchestration-based solution.

The OES API stores tracking data first in the BizTalk MessageBox database. Periodically the data is processed and persisted to the BAM Primary Import database by the Tracking Data Decode Service (TDDS).

It is found in the Microsoft.BizTalk.Bam.EventObservation namespace. To use the API you must add the Microsoft.Biztalk.BAM.Xlangs.dll to your project.

So in your BizTalk project, include references to the following assemblies:

Microsoft.BizTalk.Bam.EventObservation and Microsoft.BizTalk.Bam.XLANGs.

These assemblies may be found in your “Microsoft BizTalk Server 2006\Tracking” folder.

The OrchestrationEventStream is utilized by the TPE tool. In BizTalk Server 2004, it was an internal component used by TPE and not exposed for general use. The transactional integrity requirement came up during a customer engagement, so it was later exposed in the 2004 release by a hotfix and is in the box with BizTalk Server 2006.

Sample code:

Note that because the OrchestrationEventStream is implemented as a static class, there is no need to manually create an event stream each time, and a connection string isn’t required, because the OrchestrationEventStream piggybacks the persistence of the orchestration.

//Create a new, unique activity identifier to use as the ActivityID in BAM
string activityId = Guid.NewGuid().ToString() + "_" + DateTime.Now;

//Start the activity record identified by activityId
Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity(“MyTrackingDemo”, activityID);

// Updates the activity record.
Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.UpdateActivity(“MyTrackingDemo”, activityID, “MESSAGE_ID”, msg(BTS.MessageID), "TRANSACTION_CREATED", DateTime.UtcNow);

// End the activity record.
Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EndActivity(“MyTrackingDemo”, activityID);

Tags: BizTalk | BAM | OrchestrationEventStream

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s