Trouble updating BizTalk BAM

BizTalk BAM isn't the easiest beast to tame, anybody who's tried to update an activity will have come across that issue.

I have recently tried to deploy some big additions to a BAM definition, by adding some new Activities. The problem is, when I came to deploy these additions with:

bm update-all -DefinitionFile:myexport.xml

I get presented with an error like this:

Updating Activity... ERROR: The BAM deployment failed.
Cannot remove or update an existing data item or milestone.

Somehow, somebody, didn't update our source-control correctly and the file I was working from was out-of-sync. I'm not entirely sure how anybody has ever updated things (which looking at the state of it, I doubt they have).

In typical Microsoft fashion, I have a cryptic error message. Whilst the cause of the error is fairly self-explanatory, the source is not. Like a Null Reference exception, the complaint is just *something* is wrong and never goes into detail of what.

In the end, I took the previous export of the bam definition:

bm get-defxml -FileName:olddef.xml

And compared the XML to my updated XML file (pro tip: use an XML comparison tool, or script out something to check each Activity) - indeed, I did find an activity that had an Milestone in the existing system but not in the new one.

As I had a lot of changes to add, I couldn't import the old XML and start again, so I wanted to hack the updated XML file with the missing field. I did this by adding it into the Activity through the Excel plugin and exporting as normal. When trying to import this, I continued to get the same error. The reason for this is that the unique ID/key for the field was not the same. So I then had to manually edit the XML file to use the ID attribute from the existing XML file.

It is important to note that the ID is used as an XML constraint and it is referenced elsewhere in the file, so you need to search and replace all instances. After that the updated XML imported ok and I could then export the definition file again to create a new Excel spreadsheet.