Administrating multiple BizTalk 2004 environments from a single machine / Remote HAT

It can turn out to be useful to use Health and Activity Tracking (HAT) and the BizTalk
Server Administration Console “remotely” (that is, from a machine other
than one of the actual servers in the BizTalk group.)  This can be the case if
you have multiple environments to administer, and/or using Remote Desktop is not desirable
or available.

It should be noted that to accomplish this, you technically have to have the “administrating
machine” join the BizTalk Group – though since you won’t
have any host instances defined on the machine, that isn’t as significant as
it sounds.  You are essentially just configuring the machine to point at a particular
BizTalk management database, and configuring some WMI information.  The “administrating
machine” does not appear in the “Servers” node of the BizTalk
Administration Console.

It should also be noted that you will need to be in the “BizTalk Administrators”
Windows group for the BizTalk environment you want to manage. 

To get started, the “administrator” should do an “Admin-only”
install of BizTalk on the machine they will be using, where the installation options
for BizTalk look like this:

Then, on the desktop, the administrator should put a shortcut to a script that looks
like the script below.  This script simply reminds the user what BizTalk Group
they are currently administrating, and confirms they want to switch:

If you select OK, you get another warning:

This is basically warning someone who has a full-blown BizTalk installation on their
machine that they really don’t want to remove their current configuration unless
they happen to have a saved configuration file from their last run of ConfigFramework.exe.

If you select OK, the “ConfigFramework.exe” utility is run (from BizTalk’s
installation directory) with the /u switch, to remove the current configuration. 
Afterwards, ConfigFramework.exe is run normally, and the only option you will have
(for an admin-only install of BizTalk) is to select the database corresponding to
the environment you wish to administer:

Once you hit “Next”, the wizard will complete, and you will be presented
with a final confirmation dialog:


The VBScript as a text file is here.

How To Create Nodes from Flat Data in BizTalk Maps

It can sometimes be challenging when mapping schemas in BizTalk 2004.  One common problem is when the inbound document has one record and the source creates multiple records based on the data inside your single record.


The root problem arises because you have nothing to loop around in the inbound document and need to create multiple nodes on the output.

How can this be handled in the mapper?

Two ways: Functoids or XSLT Template

BizTalk 2004 introduces a new Functoid just for this situation.  It is called the Table Looping Functoid.  It is accompanied by the Table Looping Functoid Data Extractor.  The table looping functoid will take a flat row of data and produce multiple nodes of data on the destination schema.

CRITICAL: The key to working with the table looping functoid is to label your links.  This can be done by selecting the link and going to Properties.  Under General you can set the label.  This will show up inside the Input Parameters section of your functoids as the label name.

An alternative to the Table Looping Functoid is to use a custom XSLT Template call inside a scripting functoid. This requires error prone XSLT coding.

In both cases, the number of input parameters must be known ahead of time.

I have put together a sample showing both the Table Looping Functoid and XSLT Template solutions.

DOWLOAD: Sample Create Nodes in Maps


In addition to Node Creation, this sample includes a map called Map_RowSplit.  This sample takes an order item and evaluates the node for “Y” (meaning the item is gift wrapped).  If it is “Y” two line items are created on the output rather then one.  This uses the and XSLT element.

Creating Nodes Inside A Map

This mapping sample shows how to create repeating nodes from flat data inside the mapper.  This sample also shows the use of some custom XSLT code inside the BizTalk mapper.

This sample works with BizTalk 2004 and BizTalk 2006.

Get more information from the original blog post on this topic:

Using XPath Inside BizTalk Orchestrations

Working with XPath inside Orchestrations is a powerful and simple feature of BizTalk 2004.  The help guide does a good job describing the process (under Using XPath in Message Assignment).




I have found that the XPath queries can only be done against a Message and the results can be set to a Message, XML Document or other orchestration variables.  XPath queries can also be executed against untyped messages.  That is, a Message that is of type System.Xml.XmlDocument.




CRITICAL: BizTalk xpath can be used to both read values and set values inside your Message.  To set values in your message, you need to be inside a Message Construct shape.




Here are some of the things you can do with xpath and how to do them:


– Set a single values inside a Message using xpath


 xpath(SingleXML, “//LineTotal”) = nLineTotal;




– Extract a single piece of data out of a Message


 sCustomer = xpath(InXML,”string(//Customer)”);




– Extract a single node out of a large XML Document and assign it to a message or variable


 sXPath = System.String.Format(“//Item[{0}]”,nCount);

 xDoc = xpath(InXML, sXPath);




– Count the number of nodes or occurrences of something inside your message


 nNumberItems = System.Convert.ToInt32(xpath(InXML, “count(//Item)”));



A great resource for xpath functions and expressions is the W3Schools.




I have put together a sample that shows several different xpath uses inside the Orchestration.  This sample takes in an Order, calculates the total per line, sends out each line item as a single message, and sends out the whole order with an order total.  Note that the Item nodes are not updated on the Output document, only on the single documents.




DOWNLOAD: XPath Sample




The de-batching approach is based on Darren Jefford’s Blog about Manual Message Splitting.  Make sure you check it out and download his sample as well.

Accessing Message Data Inside an Orchestration using XPath

BizTalk 2004 allows simple access to data inside an Orchestration by using Xpath. This can be used to read and write data as well as total message assignment. This sample shows different ways to access data using Xpath inside the Orchestration.

This sample will work for both BizTalk 2004 and BizTalk 2006.

Get more information from the original blog post on this topic:

How To Assign an InfoPath Form to a Message in BizTalk

InfoPath is something I heard a lot about several months ago, but not much since then. 

Recently, I had to set an InfoPath template to a message in BizTalk 2004.  This is something that is rather simple, as long as you know what properties you need to set. 

To set an InfoPath template for use on an outgoing message just use this code inside the Message Assignment shape.  This is set up to use an InfoPath template that has been deployment to a Sharepoint site.  Other options are a Web Server or File Location.

// This sets new Processing Instructions on the Message

OutMessage(XMLNORM.ProcessingInstructionOption) = 1;

// This assigns an InfoPath template from a Sharepoint site to the document

OutMessage(XMLNORM.ProcessingInstruction) = “”;

That’s it!  Now, if you have InfoPath installed your Xml will be assigned to that template.

For more information on InfoPath and BizTalk 2004 make sure you view the MSDN On-Demand Webcast from April 19th.

BTSInstaller "bug"

After hours of fighting it, I have concluded that deploying a solution that utilizes Roles and Party’s can’t be installed using an MSI created with the BTSInstaller.  You can use the same binding file and assemblies and use BTSDeploy and it all works fine.

I plan on posting all my deployment scripts here in the next few days as the BTSInstaller gets you about 85% there, and you’re required to script the rest.

Take a look at Scott Colestock’s blog for a different option (Nant) to the BTSInstaller.


The "Use MSMQ Authentication" Option

I recently went through a really nast bout of troubleshooting with the client I currently
work with, related to MSMQT.  Hopefully, my tale can save you similar pain.

The core issues was this: The BizTalk MSMQT adapter can be configured during installation
to integrate with Active Directory.  The default is that it will not operate
in this fashion, but rather in “workgroup” mode.  There are (at least) two reasons
why you might want to have MSMQT integrate with Active Directory: 1) you want to make
use of an MSMQ router in your environment or 2) you want to use certificate-based
authentication at a protocol level (where the public certificate is managed by AD.)  (Note:
I know this now; I didn’t know it a couple weeks ago…)

We have been installing our servers in “workgroup” mode.  To install in Active
Directory mode requires a special permission granted by the domain administrator.

Now, when you a configure a Send Port within BizTalk and select MSMQT as the transport,
the property pages in the BizTalk Explorer offer a checkbox that is labeled “Use MSMQ
Authentication”.  If you hit the “Help” button on this dialog, the explanation
that is provided is this: “Identify whether BizTalk Message Queuing uses protocol
authentication every time it sends a message on this port.” 

As it turns out, although it isn’t documented as such, a Send Port with this
option checked can only work if MSMQT has been installed in Active Directory-integrated
mode.  If you have the “Use MSMQ Authentication” option checked on a Send Port
and you are not in Active Directory-integrated mode, then messages will not flow. 
When we eventually discovered this discrepency and fixed our bindings files, the problem
was resolved.  (Note: there is a similar option when configuring Receive Locations.)

This checkbox had been checked at the point our initial binding files were exported,
and became a part of our scripted deployment.  What was worse, when we encountered
this problem a few weeks ago in QA, we began troubleshooting the BizTalk configuration
on the server directly and wound up “fixing” the problem by creating an additional
Send Port (subscribing to the same traffic as the original) that simply had the MSMQ
Auth checkbox off.  But we didn’t realize that discrepancy at the time, so we
had to troubleshoot the same problem all over again a few weeks later.  We definitely
got ourselves into the wrong troubleshooting mindset by assuming that Biztalk was
flaky in some way.

Key lesson: If you don’t get into a given environment (QA, production, whatever) with
your scripted deployment, then you really didn’t get there at all….

A few more notes.  As I said above, if you have the “Use MSMQ Authentication”
option checked on a Send Port and you are not in Active Directory-integrated mode,
then messages will not flow.  What you will see is:

  • Messages will appear in the HAT “Queries-Messages Sent in Past Day” report, but they
    will not actually have arrived in the destination queue.  (Fixed in SP1?)
  • You will see strange behavior in the HAT “Operations-Messages” view, but nothing that
    indicates an error condition.  Retry count will increment on the original service
  • There will be no error condition reported in the event log.  (OK, Premier Support
    indicates in a phone conversation you might see something after 5 days have elapsed,
    when an exponential backoff algorithm has run its course.)

IMHO, Biztalk 2004 should be more serviceable in this regard, and should give better
error information.  And of course, the documentation for MSMQ Send Port configuration
should have mentioned that MSMQ Authentication would only work for Active Directory.

Microsoft Premier Support became involved, and after around 18 hours of analysis they
said “We see some certificate-related errors in the traces.  Do you use MSMQ
authentication?  Are you AD-integrated?”

We looked in our binding files (since the decision had long since been forgotten)
and saw this snippet:

<TransportType Name="MSMQT" Capabilities="16495"
lt;Authenticated vt="11"&gt;-1&lt;/Authenticated&gt;&lt;/CustomProps&gt;

See that in the escaped XML?  Yup, that is a property called “Authenticated”
that is an old-fashioned Variant of type bool, where “-1” means “true”.

Leaps out at you, right?  Determining if you are AD-integrated means looking


From all of this I (gently) conclude that the product instrumentation/tracing should
point out this condition more quickly to a support engineer.  In addition, the
MSMQT adapter should warn you of a mismatch during configuration with the Biztalk
Explorer and, ideally, when you deploy/import bindings.

Hindsight being 20/20, the support engineer should have asked to see our binding file
– and should have compared it with one exported from a server that was indeed sending
messages (since we had one.)  Of course, we should have made such a comparison,
too! (and much earlier…)  The engineer did look at the Biztalk Admin Console,
but of course that doesn’t give any of the detailed port configuration information
– only Visual Studio/BT Explorer does.

Having said that, the support engineers were great to work with and were certainly
dedicated to getting to the bottom of our issue.

Key lesson: Diffing binding files will prove to be a key troubleshooting technique
with Biztalk…