If anybody’s telling you that BizTalk Server 2004 (BTS) is
the best Microsoft product to come along in quite a spell, believe it. If they
tell you that it’s the closest thing to ERP that Microsoft has yet
accomplished, believe it. If they tell you it’s easy to use and sets the bar
higher for distributed application configuration, you can safely laugh in their
faces.

There’s a lot of irony in this, because the third BTS is by
far the best, is deeply integrated into Visual Studio .NET (where it ought to
be), and of course takes the very graphically friendly Orchestration feature to
a new level of versatility. The whole point of these features is ease-of-use.
But there’s almost no developers’ documentation yet available, so you’re pretty
much on your own in figuring out the best way to do things; and what little
documentation exists isn’t nearly detailed enough. The error handling also leaves
much to be desired: tracking down your mistakes can be
“pull-your-hair-out” frustrating.

Below, we’ll cover several bases: we’ll track down the
places where your errors are noted; we’ll look at some of the easy-to-make
mistakes; and consider some good practices to make interface development
easier.

Where the errors are

When you’ve built an interface in BTS 2004 and start testing,
you could find yourself submitting test messages to the server and having your
enabled solution swallowing them whole. Nothing seems to go wrong, but your
message doesn’t end up where it was supposed to. Here’s where to look:

Health and Activity Tracking

This powerful utility (Start | All Programs | Microsoft
BizTalk Server 2004 | Health and Activity Tracking) is your first line of
inquiry when a message vanishes. Select Operations | Messages to track down
your missing message (Figure A).
There are several options for refining a query to list messages, but leaving
the defaults in place is usually fine. Click on Run Query, and you’ll get a
list of messages. Look for your missing message, which should have a
“suspended” status. You can get more detail by selecting your message
in the list, then right-clicking—choose either Orchestration Debugger or
Message Flow.

Figure A

Operations messages

Event Viewer

If you’ve sent yourself a test message that is intended for
a receiving schema that will define it, or translate it, or reformat it, and
the incoming message is a little off in some way, the schema’s going to show a
parsing error or application-internal error (this is common in message
translation such as EDI or HL7). You’ll get no outward sign of it, just a
vanished message.

Go to Start | All Programs | BizTalk Server 2004 | BizTalk
Server Administration to bring up the BTS Administration Console. Then open the
Event Viewer (below Console Root) and click on Application. You’ll get an error
log that will tell you what happened in the parsing of the message (Figure B). Click on the error to get
the specific parsing error message. Warning: a parsing error will suspend
processing of your message upon occurrence. Therefore, your message could
contain many formatting mistakes or incorrect fields and you must discover them
one at a time via this technique (i.e., find an error, fix the data, run it
again, find an error, fix the date … and so on).

Figure B

Event properties

Not for your to-do list

Here are some things not to do when developing and testing a
messaging interface. There are many more, but these are a few that BizTalk
won’t give you any hints about.

Deploying the same schema twice

If you’re developing more than one interface at once, it
doesn’t matter that you’re using a different solution to store each interface’s
project components; if you deploy the same schema within different assemblies,
you’re going to run afoul with the fact that the namespace for both instances
is the same. (Example: Suppose you’re deploying two HL7 ADT interfaces, each
for a different ADT document. They’ll both probably use the same message header
parsing schema, since they’ll have those segments and elements in common.) Try
to deploy two header projects as assemblies, containing the same schema, and
neither will work! Solution: change the namespace—or, to your surprise, you may
find that one deployed assembly will do the job for both solutions.

Using the wrong pipeline

When setting up Send and Receive ports for message
transport, you’ll have various pipelines available to you, configurable within
the ports (See Figure C). These
pipelines are the circulatory system for your messages, and using the wrong one
can cause BTS to fail to process the incoming message (which pipeline to use
for particular steps in your particular interface or process is too detailed a
question to address here). In short, if a message didn’t show up where it was
supposed to, and you aren’t yet experienced in using BTS 2004, experiment with changing
the pipeline. If this gives you a good result, you’ll rapidly learn to match
the correct pipeline to the correct step in your processes.

Figure C

Port properties

Going from one message format to another in an orchestration

This kind of exercise is fraught with peril, but is exactly
the kind of capability you really need for true distributed application
messaging. There are many messaging transactions that BTS 2004 does painlessly—inbound
formatted document to XML document, XML document to an adapter, and then into a
SQL Server database, etc.—but jumping from an interim XML document to, say, a
set of objects in a .DLL defining a database record, with an associated method
for inserting a new record into a table—that’s tricky stuff, and BizTalk will
be very fussy about accommodating you.

You need to create an orchestration to do something that
complex, for a start. You’ll do a Construct Message for the receiving
object(s), which you must make XML-serializable (if you want to map from an XML
document). Moreover, if the method you’re using to add the elements to a
database table is in a different .DLL, that one will have to be
XML-serializable, too, even if it contains no objects with properties and even
if it compiles cleanly in other contexts. Do your element-to-element mapping in
a Transform expression (use xPath to pull data out of your XML document), and
use an Expression to execute the Add.

Make it easier on yourself

There are several tricks you use, in development, to help
make this whole process easier. Here are a few:

Set up multiple Sends with file capture

When you’re putting together messaging in BizTalk Explorer
(apart from any orchestrations), you can attach multiple Send ports (See Figure D) to a specific Party
(“Party” is how a pipeline identifies an external messaging source).

Figure D

Send ports

One of these Send ports will be the next step in your
business process, but you can create one or more for your own use. This not
only gives you a running breakpoint of sorts, but allows you to examine the
contents of a message at different points along its journey. To create such a
Send port, right-click on Send Ports in BizTalk Explorer and select Add Send
Port (let it be a Static One-Way Port). Set it up with Transport Type File and a
directory/file address. A copy of your message (or acknowledgment, or whatever
it is you’re processing) will be deposited in that file/directory (you can also
use this process within an orchestration, if it’s helpful, though the set-up of
the File transport will be done through a wizard when you create the port).

Isolate the orchestration from pipeline activity

If possible, do your receiving, qualifying, and
acknowledgment of messages in BizTalk Explorer, and do mapping and database
work in orchestrations. Why? First, your orchestrations will be all the more
complex if you do everything there. Second, the graphic display of those
portions of the process is really unnecessary, since the receiving, qualifying,
and acknowledgment steps are part of any messaging transaction with an outside
party. Third, debugging is simpler: the techniques above will help you debug
the pitch-and-catch with your messaging partner (call this the
“network” interface), as well as permitting you to enable multiple
partners in a collective process with less confusion (while confining the
business logic in the orchestration to exactly that, the business logic).

One of the powerful aspects of BTS 2004 is the pipelines;
let them do as much work as possible and keep the front-end messaging work
distinct from the crunch of mapping and database interface. (Note that this
concept should not apply to communication with other points in your internal
application system. Include them in your orchestrations or your solution design
will be incomprehensible to other developers.) It may not be what BTS 2004’s
creators intended, but in the long run, it’s tidier and easier to debug.