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.
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).
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.
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).
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.