BAM! BAM!....BAM! BAM!

Obligatory Rant

BAM is such a good name for this technology for a few reasons. The first is that it reminds me of the kid Bambam on the Flinstones (You know, the baby with the club that had a thing for Pebbles). Very powerful and also tough to handle at times.  Also because "BAM" is the sound my forehead makes while it collides with the palm of my hand as I discover an all too simple solution to some problem that has plagued me for hours or even days.

The Basics

This article will be a fairly unstructured summary of my recent experiences with BAM under BTS 2006.  If there is interest, I will create some more in-depth posts on the topic.

I'll be brief here because most of you know this allready. The basic way BAM works is the following:

1. Create a Business Activity showing the LOGICAL progression and points of interest in a process (using Excel, or Visio ODBA)
2. Deploy that Activity (as .xls or .xml to the biztalk server) using BM.exe
3. Associate low level technical events (i.e. hitting a shape in an orch or a method in a .net class) with items you defined in the activity (using the BAM API or the Tracking Profile Editor (TPE)

The end result of this is that you can take the mess of code, orchestrations etc and transform it back into a logical/business view that even a CEO could understand.  All in all, very cool.

Some Pragmatic Advice

"DO" List

1. Try both ODBA and Excel for creating activities (I like excel better, but hey, who cares?)
2. Become familiar with the BM.exe utility. You really only need the "deploy-all" and "remove-all" commands to start with
3. Keep your activity files versioned! If you deploy an activity, then change the activity file, then try to undeploy you may have problems. Then you have to undeploy by manually deleting tables and rows in the BAMPrimaryImport table.
1. I recommend that you manipulate your activity definition in Excel. When you are ready to deploy it, export it to xml and then deploy the xml. That way if you fiddle with the Excel file, you can still undeploy the activity using the same xml you used to deploy it.
2. Before you re-export your activity to XML, undeploy the activity. Or even better export your Activity to a new version of the xml (i.e. with a version number in the file name

"DON'T" List

1. Don't try to map milestones from Message Constructs or Loops (or other special cases). That is advanced and you may need to use the BAM API call to make that work as you would expect
2. Don't put spaces or special characters in your Activity Names. It can lead to problems later where the Event Log will say that "stored procedure does not exist" and your BAM Aggregation will not work.
3. Don't have a group shape as the last shape in the orchestration you are tracking in TPE. For some reason it won't work. Just add any shape after the group to fix the issue.

Continuations & Relationships

I can't do these justice in this entry so this will be a bit shallow. I will probably blog on this separately. The more comments i see below requesting this, the sooner I will get around to it.

1. Continuations allow a single activity defintion to span muliple orchestrations or even other classes/systems seamlessly. It can also allow you to use different unique identifiers accross those systems to  When using TPE to create a continuation. Create a continuation and name it, then create a continuationID and name it the exact same thing.  Map an some kind of ID value (PO ID, RequestID, etc.) from a messaging shape (receive, construct, send as described in the above DO List) in the first orchestration to the continuation. Then in the second orchestration map that same ID value to the continuationId. The idea is that the engine will recognized that those to values match and will correlate them so that both instances can contribute data to the same Activity instance
2. Use Continuations when the Relationship is 1:1
3. Use Relationships when the Relationship is 1:Many

RealTime vs. Scheduled Aggregations

There is a little button in the Excel view (if you have installed the BAM addon) that will mark the orchestration as RealTime or Scheduled.  Again, this is complex so I will summarize below.

Common Problems & Solutions

Problem: The BAM Activity and the Tracking Profile have been deployed, the process has been run, but there is no data displayed for the activity in the BAM portal or LiveData Excel sheet.

Solution: When you deploy a non-Real Time Aggregation (this is default) while using SQL 2005. It will create the <package>_DM and <package>_AN packages. These packages need to be run to populate the BAM tables and get you the BAM Data.  To run these packages you should select "Integration Services" in the SQL Management Console (not database engine). Once you have found them, run them. Hopefully, you're data will appear.

Problem: The BAM portal or LiveData Excel sheet shows "BLANK" for one column and one row in the Aggregation display. It seems like the measures, and the milestones are not being combined into the same activity. Also, the data shows up in two rows (or more) in the BAMPrimaryImport.dbo.bam_<ActivityName_Completed table.

Solution: This could be a number of things, but if it was the same problem that I had the solution is the following. When you are in the TPE and you are associating data from the message, be sure to use the orchestration schedule.  Right click on your receive, Message Construct, or Send shape and select Message Payload and map the items from there. Many people go to the "Select Event Source" and use the "Messaging Payload" from there. YOU ONLY WANT TO DO THAT IF YOU ARE JUST USING SEND RECEIVE PORTS TO MOVE MESSAGES. If you are using an orchestration, map everything from the orchestration schedule. 

Problem: Your BAM aggregation is not working and you see "Could not find stored procedure" in your event log.

Solution: This is probably caused becaues you have a "space" or some other bad character in your Activity Name. Undeploy your activity, rename it so it does not have the space. Redeploy it. Adjust your TPE (if required). This should fix the problem.