Export (0) Print
Expand All

How to Track Failed Messages in BAM

This white paper describes how to track failed messages in Microsoft® BizTalk® Server 2006 by using Business Activity Monitoring (BAM). It contains steps for creating a basic solution for tracking failed messages. It also provides tips for variations to track different types of failed messages.

Before you begin tracking failed messages by using BAM, it’s important to understand the concept of failed message routing in Microsoft® BizTalk® Server 2006.

With BizTalk Server 2004, messages that failed at a send port or a receive port, or due to routing failures, were suspended. If you wanted to use the suspended message information (for example, to analyze why the message was suspended or to generate a failure report), you could take actions like subscribing to NACK messages or using utilities written with Windows Management Instrumentation (WMI). However, these tasks were often seen as tedious.

With BizTalk Server 2006, new functionality was added. You can now route the failed messages simply by selecting the Enable routing for failed messages check box at both the receive port and the send port.

If routing for failed messages is enabled, failed messages are not suspended. Instead they are sent to the MessageBox database. An error message is created that is a clone of the original failed message, with all previously promoted properties demoted and with a set of error-specific properties promoted to the message context. (Previously promoted properties are demoted to avoid unintended delivery to subscribers that are not designated to receive the error message.) The error message is published for distribution to subscribers (orchestrations, send ports, and send port groups). Some error-specific properties that are promoted with failed messages are:

  • FailureCode
  • MessageType
  • ReceivePortName (name of the receive port where the failure happened)
  • SendPortName (name of the send port where the failure happened)
  • ErrorType (In BizTalk Server 2006 this property always contains the value FailedMessage.)
  • RoutingFailureReportID (This property provides the ID of the routing failure report that BizTalk Server generates when there is a routing failure.)
  • Description (the same diagnostic text that is written to the Application Event Log regarding this messaging failure)

You can track failed messages by using BAM and can view them in the BAM portal Web site. However, to track failed messages, you need to create subscribers for the failed messages; otherwise you will not get the values of the error-specific properties.

Subscribers to failed messages can be either send ports or orchestrations. By using the error-specific properties, you can filter which messages you want to subscribe to.


  • To track failed messages, you must have BizTalk Server 2006 with BAM configured.
  • This document assumes that you are familiar with using BizTalk Server 2006 and the BizTalk Server Administration console.

Tracking Failed Messages in BAM by Using the Tracking Profile Editor (TPE)

  • Create a BAM activity and a BAM view that can be used to view the tracked messages in the BAM portal.
  • Create a tracking profile to track failed messages.
  • Enable failed message routing at receive and send ports for which failed messages are to be tracked.
  • Create a subscriber for the failed messages. The subscriber can be a send port or an orchestration.
To create a send port as a subscriber for the failed messages
  1. Create a send port. For more detailed information, see “How to Create a Send Port” in the BizTalk Server 2006 documentation at http://go.microsoft.com/fwlink/?LinkId=118275.

  2. Set the filter as: ErrorReport.ErrorType == FailedMessage

    Send Port Properties Dialog
  3. Enlist and start the send port. This send port is used to subscribe to the failed messages.

To create an orchestration as a subscriber for the failed messages
  1. Create an orchestration and add a Receive shape to it.

  2. Configure the Receive shape as follows:

    • Set the Activate property to True.
    • Set Filter Expression to (ErrorReport.ErrorType == “FailedMessage”).
      Receive Properties Dialog
  3. Drag a Port shape from the Toolbox to the orchestration. In the Port Configuration Wizard, on the Port Binding page, do the following:

    1. For Port Binding, select Direct.
    2. Select Routing between the ports will be defined by filter expressions on incoming messages in the Message Box database.
      Port Bindings
  4. Add a send port to the orchestration for sending the failed message to a file location.

The preceding steps are sufficient to subscribe to the failed messages. You can add more functionality to your orchestration for processing the failed messages.

To create a BAM activity and a BAM view
  1. Create a BAM activity in Microsoft Office Excel® and add items according to what needs to be tracked. For example, you might track FailureCode or FailureCategory.

    New Activity
  2. Create the BAM view for this activity.

    Business Activity Monitoring View Creation
  3. Select the items you want this view to show.

    New BAM View
  4. Click Export XML and specify a location for this XML file. Make sure that the File Type selected is .xml.

  5. Deploy this activity:

    • Open a command prompt and change the directory to %Installation folder for BizTalk%\Tracking.
    • At the command prompt, type: bm deploy-all -DefinitionFile :< complete file name to the .xml file exported in Step 4 including the path>.
To create a tracking profile to track failed messages
  1. Open the Tracking Profile Editor and in the left pane, click Click here to import a BAM Activity Definition. In the Import BAM Activity Definition dialog box, select the BAM activity that you created in the preceding procedure.

    Import BAM Activity Definition
  2. In the right pane, click Select Event Source and select Select Context Property.

    Select Context Property
  3. In the Select Schema box, in the In string text box, type error, and then click Search.

    Select Schemas
  4. Select the ErrorReport.ErrorType property. This opens the ErrorReporting schema in the right pane.

    Failure Codes
  5. Map the BAM Activity items with the Schema elements. After mapping, the schema elements can be seen in the left pane, associated with the Activity item.

    Receive Port Name
  6. In the left pane, right-click the schema property and select Set Port Mappings.

  7. In the Select Ports dialog box, select the send port that you created in the earlier procedure “To create a send port as a subscriber for the failed messages.”

    Select Ports
  8. Save the tracking profile, and on the Tools menu in the TPE, click Apply Tracking Profile.

To enable failed message routing
  1. Enable routing for failed messages for all the send or receive ports for which tracking is required.

  2. At a receive port:

    Receive Port Properties
  3. At a send port:

    Transport Advanced Options
To test the scenarios
  1. Create a failure scenario for the test message (for example, unenlist the send port for a message).

  2. Open the BAM portal and check the view created in the earlier procedure, “To create a BAM activity and a BAM view.” A row should be entered for this failed message containing the details.

Points to Remember

Though the failed message routing is enabled, the error context properties are not persisted. The reason is there are no subscribers to subscribe to the message. Creating a subscriber ensures that properties are persisted and can be used.

In the preceding sample, you created a common subscriber for all the failed messages. However, you can use different error context properties to track specific failed messages.

To learn more about the properties that are promoted to the context of an error message:  http://go.microsoft.com/fwlink/?LinkId=118276

To learn more about the failure behavior: http://go.microsoft.com/fwlink/?LinkId=118277

For information about the Tracking Profile Editor: http://go.microsoft.com/fwlink/?LinkId=118278

For information about creating BAM activities: http://go.microsoft.com/fwlink/?LinkId=118279

© 2014 Microsoft