BAM your own custom data

To me, one of BizTalk Server's most exciting features is definitely BAM (Business Activity Monitoring)!  In a very intuïtive way it allows you to do lots of great things...  Of course, out of the box, BizTalk can't anticipate on every need you'll ever have regarding business monitoring...  For example: as for now - out of the box - it is not possible to include variables as data in your BAM views and activities.  Let's change this!!  BizTalk Server actually DOES support inclusion of custom data in your BAM infrastructure!  So... let's get started!

(Note: following description is rather short, very short!  However it's just ment as a little reminder for those of you who occasionaly have used BAM already... For full explanations and in depth coverage please use the docs and of course, buy Scott's book!! :-))))

• Goto: C:\Program Files\Microsoft BizTalk Server 2004\Tracking\BAM.xls.
• Copy the .xls file to another directory and make sure its writeable
• Open the Excel file and
• Configure your BAM profile by:
  • Creating a new BAM activity
    • Giving it a suiteable name
    • Including all items with each their name and type (milestone, text, integer or float)
  • Create a BAM view on the activity you've just created by:
    • Give it a suiteable name
    • Including the items you'd wish to look upon in the view
    • If you'd wish to do so, provide aliases and/or configuring groups and durations
    • Creating dimensions and measures if they'd apply to your scenario
• Export the .XML from the BAM Excel sheet

Ok, so now you've created a file that explains to BizTalk Server what kind of data you are expecting to be BAMmed.  Let's give it to the server and tell it to prepare for that data, using the the "BAM Management Utility"

• Make sure to include the BizTalk tracking directory in your PATH:
  C:\Program Files\Microsoft BizTalk Server 2004\Tracking
• Open your command prompt  (Yes, you'll need to do this :-))  Believe me: there's no user interface that takes care of this, so: back to basics!)
• Enter bm deploy myExportedXMLBAMDefinitionsFile.xml "C:\Program Files\Microsoft BizTalk Server 2004\Tracking\BAMConfiguration.xml"

So, what exactly have we done now?  The bm utility actually has created all views, tables and a bunch of SQL Server constructs to make BizTalk ready to receive and compute your BAM data.  Accessing those constructs directly is only supported using the SQL Server views that end on: "_View".  (This does not include the views like: "_CompletedView" or "_ActiveView".)  All other access would be unsupported.

What you would normally do now is to open up the TPE (BizTalk Server Tracking Profile Editor) and configure which data in your orchestrations map to which BAM fields.  Which is exactly what we are not going to do for now :-).  Let's do somewhat more funky things: use BAM from within an orchestration expression shape!  (Note: following applies just as well for any .NET component you'd wich to leverage BAM in!)

The most exciting part actually turns out not being difficult at all, watch this:

• I'll be a good .NET citizen and store the connection string to the BAM database in a .NET configuration file.  (Curious how .config files apply to BizTalk Server orchestrations??  BizTalk actually allows you to tune it's appdomain configuration!  Use it!!!!)  You might fetch this like:
  
  var_BAMConnectString = System.Configuration.ConfigurationSettings.AppSettings.Get("BAMConnectionString");
  The connection string might look something like this:
  "Integrated Security=SSPI; Data Source=.;Initial Catalog=BAMPrimaryImport"
• Let's assume I'd want to track the contents of 2 variables inside my orchestration:
  var_myDate and var_myString.
• We need to initialise the BAM event stream like this:
  obj_eventstream = new Microsoft.BizTalk.Bam.EventObservation.DirectEventStream(var_BAMConnectString,0);
  The "0" in this case is the so called "flush threshold", which determines after how many BAM events need to happen before a commit will be done to the BAM databases.  By setting this value to zero, we'll need to call "flush" explicitly. 
• To begin doing cool things, just initiate the BAM activity like this:
  obj_eventstream.BeginActivity("MyActivityName", var_newUniqueGuid.ToString());
• Further, we're going to need a new unique ID in a variable.  A GUID will do fine:
  var_newUniqueGuid = System.Guid.NewGuid();
• Update the activity with any custom data you want:
  obj_eventstream.UpdateActivity("MyActivityName", var_newUniqueGuid.ToString(), "MyDateValue", var_myDate , "MyStringValue", var_myString);
  Obviously the first parameter is the name of your activity.  The second one is the activity instance ID or the contiuation token.  In this case, since we don't reference any other activities, I just created a new GUID.  All parameters after those initial two, is data that is stored for this activity.  BizTalk requires you to give this data as name-value pairs.  In this case I've added 2 fields called "MyDateValue" and "MyStringValue" that have their actual data values stored in var_myDate and var_myString.
• End the activity like this:
  obj_eventstream.EndActivity("MyActivityName", var_newUniqueGuid.ToString());
• Last, but certainly not least, don't forget to commit this data by using the flush method:
  obj_eventstream.Flush();

Surprisingly easy huh?  Great stuff in my humble opinion!!!!!!!!