You have business users requesting metrics, visibility, and business data from the execution of a deployed BizTalk solution and the associated artifacts. The business users are interested when any of the BizTalk processes execute the following steps: process begins, process ends, or process encounters exceptions. The business users are also interested in the following attributes of the messages consumed by the BizTalk processes: the transaction ID and transaction type.

This recipe outlines how to use Excel to create a BAM workbook that tracks milestones and business data for reporting. This recipe addresses the four categories of steps required in creating a BAM solution. Each category of steps plays an integral role in developing a useful, rich, and powerful BAM solution:

Outline the BAM View

A BAM view is a representation of the milestones and business data tracked in one or more activities. A view may comprise multiple activities or multiple milestones from a single activity and can contain tracked data or milestones as well as provide aggregations or summaries of the tracked milestones and business data. Creating a BAM view is a necessary step because it defines which tracked milestones and business data to report. Typically, different views are created to show multiple audiences different aspects of the same tracked data.

This category of steps demonstrates how to outline your view and display tracked data items and milestones. The view created in this recipe summarizes how many processes execute successfully versus how many processes encounter an exception.

1. When the Business Activity Monitoring View Creation Wizard begins, click the Next button to advance the wizard and create a new view.

   Note

   If the wizard does not start, launch it by selecting BAM View from the BAM menu in the Add-ins section of Excel.

2. Name the view Process View, and select the Select All Activities box. The Business Activity Monitoring View Creation Wizard will resemble Figure 11-2. Click the Next button to advance the wizard.

   

   Figure 11.2. Business Activity Monitoring View Creation Wizard

3. On the New BAM View: View Items page of the Business Activity Monitoring View Creation Wizard, select the Select All Items box to add all the milestones and business data to the new view. Click the Next button to advance the wizard.

4. Click the New Group button to create a Group item, and select the box next to the milestones listed in Table 11-2. Figure 11-3 demonstrates the milestones to select.

   Note

   The Group milestone allows related milestones to be treated as a single milestone. In this example, grouping the EndSuccess and Exception milestones is useful to indicate the completion of the process regardless of whether it completed successfully or failed.

   Table 11.2. Business Milestone Group

   Business Milestone Alias	Name	Activity
   End	EndSuccess	ProcessActivity
   	Exception	ProcessActivity

   

   Figure 11.3. New business milestone group

5. Create a New Duration item with the parameters listed in Table 11-3 to record the total process execution time. Figure 11-4 demonstrates the New Duration creation dialog box.

   Note

   A duration calculates the time between two business milestones and is useful when reporting the time elapsed between two milestones is important. In this sample, the duration will display the time elapsed for the process execution from the beginning of the process to the End milestone group created earlier.

   Table 11.3. Duration Properties

   Duration Name	Start Milestone	End Milestone	Time Resolution
   ProcessDuration	Begin (Process Activity)	End (Process Activity)	Day

   

   Figure 11.4. New Duration dialog box

6. The completed Business Activity Monitoring View Creation Wizard should resemble Figure 11-5. Click the Next button to advance the wizard and create aggregations, dimensions, and measures.

Note

All names used for aliases, durations, groups, dimensions, and measures must be unique for a single view.

Figure 11.5. Completing the Business Activity Monitoring View Creation Wizard

Construct the Pivot Table

This final category of steps demonstrates how to lay out the computed items created in the earlier category of steps. If you did not complete the previous category of steps, you will not be presented with the option of creating a pivot table. The pivot table created in this recipe appears in the BAM portal and is the representation of the data for the user. An Excel pivot table allows you to lay out worksheet data in a grid to analyze trends over data as well as perform data aggregations. In this scenario, the progress dimension previously created is organized in the pivot table alongside the count measure also previously created.

After completing the Business Activity Monitoring View Creation Wizard, you will have a workbook with an empty pivot table that resembles Figure 11-8. The image displays the empty Pivot Table report and the Pivot Table Field List window. Data items from the Pivot Table Field List window are organized in the Pivot Table report.

Figure 11.8. Viewing the pivot table

1. In Excel, drag the ActivityProgress dimension from the Pivot Table Field List window onto the Drop Row Fields Here section of the pivot table.

2. From the Pivot Table Field List window, drag the Count item to the Drop Value Fields Here section of the pivot table. The pivot table should resemble Figure 11-9.

   

   Figure 11.9. Viewing the pivot table's data items

3. This step demonstrates how to expand the progress dimension to see all the defined stages and milestones. Double-click the Started milestone to expand and see the stages and milestones within the progress dimension. The completed pivot table will resemble Figure 11-10.

   Note

   If you receive an error message, verify that you clicked inside the Started milestone cell first before double-clicking the started milestone.

   

   Figure 11.10. Completed pivot table

4. Mark the pivot table as a real-time aggregation by clicking the Real-Time Aggregation button in BAM add-ins area of the Excel toolbar ribbon. Figure 11-11 shows where the Real-Time Aggregation button is located.

   

   Figure 11.11. The Real-Time Aggregation button is shown as the only button in the Toolbar Commands box

5. Save the workbook when you are finished.

BAM is a flexible framework to expose key metrics about business processes modeled within BizTalk. Creating a BAM solution using the BizTalk tool set is a straightforward process requiring little custom development. As outlined earlier, creating and deploying a BAM solution requires four basic categories of steps.

Create the BAM Activity Workbook

The first category of steps in creating a BAM solution is defining the structure for recording data about a BizTalk process. The structure for recording process data is created in an Excel workbook via the BAM add-in tool. The workbook captures key performance indicators or milestones as defined by the user as well as defines how a user views the milestones. Keep in mind that the Excel workbook is independent from any of the BizTalk solution artifacts and serves only as a container for recording information and computing aggregations.

Using the BAM Excel workbook removes the need for the user to have familiarity with the physical BizTalk solution artifacts. In actuality, the user may be more interested in a logical process implemented through multiple BizTalk artifacts versus the specifics for a single artifact. Consider when you tell someone about a trip you have taken. Do you relay the highlights of the trip or all the travel details (such as flight number, gas station fill-ups, and so on)? The BAM workbook allows the user to specify the BizTalk process highlights to monitor.

Note

As previously mentioned, the BAM workbook is an integrated add-in tool within Excel. If you have the BAM add-in tool enabled, you will be able to work on only a single Excel workbook at a time. If you try to open multiple workbooks, you will receive an Excel alert stating you cannot have multiple workbooks for the single Excel instance at the same time. However, you can open a new instance of Excel if you need multiple workbooks opened at the same time. Figure 11-12 shows the Excel exception alert.

Figure 11.12. Workbook alert message

After creating the BAM workbook, the next step is to identify the key data items, milestones, or key performance indicators implemented through data aggregations. Again, keep in mind that the milestones are logical markers and are not tied directly to physical BizTalk artifacts. For example, a milestone could signify the start or completion of a process. After creating the milestone and deploying the workbook, you map the multiple BizTalk artifacts to that milestone or data item. A BAM activity is a reference to a group or collection of milestones or data items and can span multiple BizTalk artifacts. Table 11-6 describes the four types of items that can be created in a BAM activity. Please review the "Considerations" section of this recipe for additional information about relating multiple activities and grouping of activity items.

Table 11.6. BAM Activity Items

Milestone	Name	Description
1	Business Data – Milestone	Placeholder for a date/time marker. Use this type of milestone when interested when an event occurred.
2	Business Data – Text	Placeholder for a text type of data item. Use this type of milestone when reporting a specific textual value piece of data (such as a promoted property) that is a textual value.
3	Business Data – Integer	Placeholder for an integer type of data item. Use this type of milestone when reporting a specific number piece of data (such as a transaction ID).
4	Business Data – Decimal	Placeholder for a decimal type of data item. Use this type of milestone when reporting a specific piece of data requiring decimal precision (such as a dollar amount).

You have created a BAM activity and view within a BAM Excel workbook and must deploy the BAM artifacts within your environment.

Successfully deploying a BAM activity and view involves a number of steps, typically performed by a few different users. After a business analyst creates the BAM activity and view within the BAM Excel workbook, an administrator deploys the artifacts to the BizTalk environment. The first set of steps to use the BAM Management Utility to deploy the activity and view defined in the BAM Excel workbook is as follows:

Deploying BAM activities and views involves two BizTalk tools: the BAM Management Utility and the Tracking Profile Editor. The BAM Management Utility is a command-line tool used for managing your BAM environment. It includes a number of commands, but the one we'll focus on is deploy-all. The deploy-all command takes the following parameters:

This command reads the BAM Excel workbook specified in the DefinitionFile parameter and creates SQL Server database artifacts based on the activities and view defined in the spreadsheet. Specifically, this command creates the following:

Use the Tracking Profile Editor to map the activities defined by the business analyst in the BAM Excel workbook to actual BizTalk artifacts, such as orchestration shapes and schema data fields. This task is absolutely critical in ensuring that the deployed BAM artifacts communicate the appropriate information. Although it is common to have a developer or administrator perform this task, this user should have a strong understanding of the business process. Applying the tracking profile places the hooks into the BizTalk Server environment used to record the necessary milestones and data fields, which map to the activities defined by the business analyst. The Tracking Profile Editor in BizTalk Server 2010 also provides functionality to feed BAM via pure-messaging scenarios (those that do not use orchestrations). To access schemas directly, click the Select Event Source drop-down list, and click Select Messaging Payload. This launches the Select Event Source Parent Assembly dialog box. Select the appropriate BizTalk assembly and then the appropriate schema.

Once the deployment steps have executed, you can see the activity data either through the live data copy of the BAM Excel workbook or through the BAM portal.

You need to create a solution that will track your company's business processes, compile the data into key performance indicators (KPIs), and develop a portal to display the information to executives. You have already created and deployed activities and views from a BAM worksheet to define and track the key performance indicators, and you would now like to consume that data from a portal.

Once you have developed and deployed BAM activities to track your KPIs, you may now consume the data from an ASP.NET portal without writing any code. You can accomplish this by utilizing out-of-the-box BizTalk reporting capabilities through the BAM portal. The BAM portal is a web-based portal built from ASP.NET that allows you to view and query cubed data created within the BAM framework. This recipe will cover three primary activities within the BAM portal:

Viewing Aggregations

Activity searches provide transactional business data from a specific point in time, and aggregations provide aggregated business data about a group of processes at a specific point in time. This aggregated data is processed and stored in OLAP cubes and accessed through pivot tables. The Aggregations page has two main sections, shown in Table 11-11.

Table 11.11. Sections of the Aggregations Page

Page Section	Description
Pivot Table View	Pivot tables provide for a way to summarize and work with data separate from the core spreadsheet. This section contains a standard pivot table. The table automatically points to the BAM framework and specifically the activities and views you have deployed.
Chart View	This section contains the chart view that displays, in chart form, the data filtering configured in the pivot table. It is also possible to change the chart view to any chart available through the office framework.

To view an aggregation, take the following actions in the BAM portal:

1. Under the My Views tree, expand the view that correlates to the deployed view name.

2. Expand the Aggregations node, and click a deployed pivot table. This action will open a window like the one displayed in Figure 11-21.

   

   Figure 11.21. Aggregations page

   Note

   If the BAM portal displays the "Safety settings on this machine prohibit accessing a data source on another domain" error in the pivot table, you need to change your security settings for Internet Explorer. Open the security settings by selecting the Tools

   

3. From the pivot table View toolbar, click the Field Chooser icon. This will display a list of fields available with your BAM view.

4. Drag one or more total or detail fields to the center of the pivot table.

5. Next, drag one or more column fields to the column section of the pivot table.

6. Close the Pivot Table Field List control. Figure 11-22 shows what the pivot table with data should look like.

Figure 11.22. Aggregations view

Note

The pivot table is a powerful tool, and this recipe does not go into the many features it provides. You should spend some time researching what this tool can provide and how to use it to its full potential.

The BAM portal is a feature in BizTalk 2010 that facilitates the rapid consumption of business transactional and aggregated data, without writing any code. The portal is self-configuring, fairly easy to set up, and provides rich data retrieval capabilities. This recipe has provided a high-level understanding of what you can do with the portal, but it has an additional powerful feature, BAM alerts. BAM alerts allow you to configure and receive alerts related to specific changes in business data.

The BAM portal provides several areas of configuration: the look and feel of the main or dashboard page, the web.config file, a network load balancing (NLB) clustering. By default, the main dashboard, or Getting Started page, displays navigation instructions to the user. The content for the main dashboard page is located in the MainPageContent.htm file, which is located in the root of the BAM portal web site folder and can be altered.

Another area of configuration is web.config. This configuration file is similar to standard web.config files and allows you to configure security as well as environment settings for the BAM portal. The web.config setting highlights include referencing the BAM web services that may be hosted on different machines in a distributed environment, referencing a different main dashboard page file, culture support, and service timeout configuration. Additionally, the types of alert notifications are customizable in web.config.

Finally, BAM fully supports high availability through clustering and can be scaled like other web applications through NLB. Please refer to the help file for specific instructions about how to change these settings.

You have to set up BAM to capture data analysis on your BizTalk processes. You need to monitor these processes and set up alerts based on business process conditions.

BizTalk's BAM tool enables alerts to be set up based on business data and associated query conditions. In this sample, you will be setting a BAM alert on a condition where the sales price of a good is less than $1.

The following steps show how to create a BAM alert:

Figure 11.27. BAM alert

BAM is a powerful tool in BizTalk that allows a solution that you can configure to monitor data passed through BizTalk without performing large amounts of custom development. BAM is based on SQL Server Reporting Services, and events are fundamentally triggered via SQL Server Notification Services. You must consider these prerequisites to successfully enable a BAM deployment:

You can configure BAM alerts for aggregate or individual data conditions. You can create an alert initially or modify one after creation. An alert can be fired based on a condition of a row of data or as a condition of a summary of data (aggregate). To enable this, you have to set up individual data conditions by setting the alert in the activity search page (demonstrated in this sample) and set up aggregate alerts via acting on the pivot table on the Aggregations tab. Figure 11-28 shows this step.

Figure 11.28. BAM alert

You can set subscribers for BAM alerts via two transport mechanisms:

A receive location can be set up to allow consumption back into the BizTalk process for further examination and process action. In addition, aggregate alerts can have threshold limits set to ensure that subscribers are not saturated with repeated messages.

When deploying alerts, it is important to remember the testing aspects and notification success. If a file alert cannot be published as a result of incorrect setup, the alert can be lost. An error will be indicated in the application event log. However, the alert instance itself cannot be salvaged.

You want to send custom events to BAM and be able to track these events as if they were published by a core BizTalk component (such as an orchestration).

The BAM Interceptor is part of the API that is available to interact with BAM from a .NET code base (BizTalk or otherwise). The Interceptor is used primarily by the core BizTalk components, such as orchestrations and pipelines, but can be tied to custom code by a developer. By calling the Interceptor and the associated API methods, you have full control over when and what is sent to deployed and tracked BAM instances.

When orchestrations execute, they constantly send events to the BAM Interceptor. Events that are being subscribed to (tracked events, set in the BAM Tracking Profile Editor) will be saved, and all others will be ignored. When external components to the orchestration are called (such as referenced assemblies), however, they do not log to BAM, and events that occur can be inferred only by the surrounding events sent from the orchestration.

This solution will walk through the sample that is included in the BizTalk SDK. You can find the SDK project files at Microsoft BizTalk Server 2010SDK SamplesBAMBamApiSample.

You must go through several key steps to interface with the BAM Interceptor:

The first thing to do is to import the BAM definition and understand how it corresponds to the rest of the files in the SDK:

The following code is directly from one of the SDK's #If Interceptor directives. It shows how the binary file is loaded and how the OnStep method in the BAM Interceptor is called. In this case, the dataExtractor contains information about how to extract the data from a given node (with the XPath from the binary file), and locNewPo maps to the Received Activity in the Tracking Profile Editor.

BAMInterceptor interceptor=Global.LoadInterceptor("BAMApiPo_interceptor.bin");
interceptor.OnStep(Global.dataExtractor,"locNewPo",xePO,Global.es);

The previous solution explored how to use the Interceptor API and introduced the concept of interaction with the BAM Interceptor. The functionality of this SDK sample is limited in use with true BizTalk implementations. The most likely use of calling the BAM Interceptor directly would be in the case of a custom assembly, which is called from an orchestration. Modifying the console application (BAMApiSample) to a .NET class is fairly straightforward.

Listing 11-2 shows a simplified approach to the application as a class that can be called directly from an Expression shape.

class Sample
{
 // the EventStream and DataExtractor tie into Interceptor events
 public static EventStream es=null;
 public static DataExtractor dataExtractor=new DataExtractor();

 public void PassDocument(System.Xml.XmlDocument xmlDoc)
 {
  // instantiate the interceptor by referencing the binary file
  Stream file=File.Open("C:BAMApiSample.bin", FileMode.Open, FileAccess.Read,

FileShare.Read);
  BinaryFormatter format=new BinaryFormatter();
  BAMInterceptor interceptor=(BAMInterceptor)format.Deserialize(file);
  file.Close();

  // send an event that will start the tracking
  // xmlDoc is the instance of the document passed in
  interceptor.OnStep(Sample.dataExtractor,"StartSample",xmlDoc,Sample.es);

  // end the tracking
  interceptor.OnStep(Sample.dataExtractor,"EndSample",xmlDoc,Sample.es);
 }

 // add functions for constructing the EventStream and the DataExtractor
}

You have a deployed BizTalk solution and associated BAM artifacts. You have users viewing the BAM views and associated activities. The user would like additional information about one of the activity line items. Specifically, the user notices the process has terminated with an exception and would like the technical support team to investigate the exception. For this recipe, the sample BizTalk solution and BAM artifacts demonstrated are from the BAMEndToEnd sample project included in the SDKBAMSamples folder created with the BizTalk software installation.

This solution outlines how to use the BAM portal to view an activity line item and issue a technical assistance request for that activity line item. The following instructions assume you have deployed a BizTalk solution and the associated BAM artifacts and that the BizTalk solution has processed transactions. This solution outlines the steps required for creating a technical assistance service request from the BAM portal:

Figure 11.33. Event Viewer entry

The Request Technical Assistance functionality included with the BAM portal allows the user to request additional information about a specific activity instance without having context to the business artifacts or the team supporting the solution. To take the greatest advantage of the Request Technical Assistance functionality, the support team should implement an automated solution to monitor Event Viewer entries or exceptions (such as the Microsoft Operations Manager). Via an automated tool, the support team could receive an e-mail or perform some automated action once receiving the technical assistance request.

By default, the Request Technical Assistance functionality creates an entry only in the Event Viewer of the BizTalk Server. For more advanced functionality, investigate how to use a tool that monitors the Event Viewer for new events and performs action based on those events.

You have deployed a BAM workbook and the associated BizTalk artifacts. You need to map the BizTalk artifacts to the deployed BAM workbook milestones, data items, and key performance indicators. Additionally, you need to save the mapped profile for deployment to other environments.

The example reviewed as part of this recipe outlines how to use BizTalk's Tracking Profile Editor to map BizTalk artifacts to an Excel BAM workbook. The following sections outline the category of steps required for creating a tracking profile, mapping BizTalk artifacts to the deployed workbook activities within the Tracking Profile Editor, and finally applying the tracking profile to the deployed BizTalk artifacts. The three main categories of steps are as follows:

Select the Activity and Artifacts

To select the activity and artifacts, follow these specific steps:

1. From the Start menu, open the Tracking Profile Editor by selecting Start

   

   Note

   This solution assumes you have deployed a BAM workbook and BizTalk artifacts.

   

   Figure 11.34. Tracking Profile Editor

2. Click the Click Here to Import BAM Activity Definition link to load the deployed BAM workbook and associated activity:

   1. The BAM Import Activity dialog box will ask you to choose the activity to use in the Tracking Profile Editor. If you have deployed the BAM workbook created in Recipe 11-1, choose the Process Activity BAM activity.

   2. Leave the Retrieve the Current Tracking Settings for This Activity Definition box unchecked, and click the OK button to select the activity.

   Note

   If you have already applied a tracking profile to the selected activity, you can retrieve the results by selecting the Retrieve the Current Tracking Settings for This Activity Definition box.

3. Click the Click Here to Select an Event Source to load the BizTalk artifacts that will be used during the mapping activity. Identify the assembly that contains the orchestration to map, and identify the specific orchestration that contains data for mapping.

   Note

   In this example, a basic orchestration has been created that performs a message receive and send and that implements a catch block for any exceptions. In this example, the name of the assembly is BizTalk Server BAM Test, and the name of the orchestration is BizTalk_Orchestration_BAM.

   1. On the Select Event Source Parent Assembly page, locate the assembly that contains the orchestration you would like to map to the activity. Click the Next button to continue and to select the orchestration to map.

   2. On the Select Orchestration page, select the name of the orchestration you would like to map to the activity. Click the OK button to complete the Event Source Wizard. Figure 11-35 displays the example with a sample orchestration.

Figure 11.35. Completed Event Source Wizard

Map Events and Data Items

To map events and data items, follow these steps:

1. Drag the orchestration shapes to the Activity nodes listed in Table 11-12.

   Table 11.12. Sample Orchestration Step Mapping

   Activity Node	Orchestration Step	Description
   Begin	Drag the Receive_Msg shape to the Begin activity node.	Captures the successful receipt of a message, which indicates that the process began successfully
   EndSuccess	Drag the Send_Msg shape to the End activity node.	Captures the successful sending of a message, which indicates that the process completed successfully
   EndException	Drag the LogException shape to the EndException activity node.	Logs an exception occurred in the process

2. Right-click the Receive_Msg shape, and choose Message Payload Schema.

   1. Expand the <Schema> folder icon, and navigate to the data items that are to be reported in BAM.

   2. Drag each reportable data item to the correct Activity node. Table 11-13 outlines the mapping of sample orchestrations to the deployed BAM activities.

Table 11.13. Sample Orchestration Data Item Mapping

Activity Node	Orchestration Step	Description
Transaction ID	Drag the Customer.MessageID node to the Transaction ID node.	MessageID is the unique identifier for the message received.
Transaction Type	Drag the Customer.TransactionType node to the TransactionType activity node.	TransactionType is the transaction identifier indicating the type of message received.

Figure 11-36 demonstrates the completed mapping between the sample orchestration and activity.

Figure 11.36. Completed mapped activity

As mentioned earlier in this chapter, BAM is a powerful tool and architecture for monitoring predetermined milestones and business data. Implementing BAM requires identifying the milestones and business data to report and then mapping those data points to the physical BizTalk solution artifacts. You can map milestones and business data to physical solution artifacts via the Tracking Profile Editor or via the BAM APIs and custom code.

This recipe outlined how to use the BizTalk Tracking Profile Editor to map between a deployed BAM workbook and physical BizTalk solution artifacts. This example outlined a simple scenario involving the mapping of a deployed activity to a single orchestration and data points contained within the message processed by the single orchestration. However, the Tracking Profile Editor can map multiple BizTalk artifacts to a single BizTalk activity or multiple activities. When using the Tracking Profile Editor, keep in mind the three categories of steps that were completed in this recipe, as outlined in the following sections.

Save and Apply the Tracking Profile

The final category of steps applies the tracking profile to the deployed BizTalk artifacts and allows you to save the tracking profile for deploying in other environments or making adjustments later.

Activity Tree Items

The activity tree typically lists the milestones and data items defined in an activity. However, you can also create four other types of items in the activity tree to further enrich your BAM solution. Table 11-14 outlines the items that are included as part of the deployed activity as well as the additional possible items available in the Tracking Profile Editor to help you map activity items to the solution artifacts.

Table 11.14. Activity Tree Items

Tracking Profile	Description	NotesEditor Item Icon
Stage	Automatically created in the activity tree when defining a milestone within an activity. The stages are listed when an activity is loaded.	Orchestration steps are mapped to this shape. Some orchestration steps cannot be mapped to this shape including Termination shapes and any steps included within a Loop shape.
Data Item	Automatically created in the activity tree when defining a data item within an activity. The data items are listed when an activity is loaded	You can specify data items from messages in orchestrations or pipelines. Additionally, you can specify context property information for those messages.
Activity ID	Uniquely identifies the instance of an activity that has executed and is automatically included within the activity tree.	This value can be user generated and identified from a message. However, the field must be unique, because it is a key in a SQL Server table. If no value is mapped in the Tracking Profile Editor, BAM will automatically generate this value.
Continuation	Inserts a new continuation folder within the activity tree.	Used in conjunction with ContinuationID to allow multiple components to populate the same activity. For example, if Orchestration A depends on Orchestration B and both contribute data to the same activity, then a continuation folder would be created and mapped to a data item in Orchestration A that is carried over to Orchestration B.
ContinuationID	Inserts a new continuation ID folder within the activity tree.	ContinuationID is mapped to the data item in Orchestration B that was passed from Orchestration A.
Relationship	Relationship folders are used to imply a relationship between one or more activities.	Relationships are especially useful in relating two activities for a single orchestration. For example, if you have an orchestration with a Loop shape, the orchestration and the Loop shape must be represented by separate activities. Via the relationship folder, you can create a relationship between the two activities.
Document Reference URL	Allows the linking of a document related to this instance of the activity.	The file name can be mapped from either a schema value or a context property on the message.

Activity Continuation

Activity continuation is the process of taking multiple BizTalk physical artifacts and combining data from those artifacts into a single activity. Combining data is a useful option when a business process spans multiple BizTalk solution artifacts. Think of the process of creating an activity as defining a database table structure with multiple columns representing the containers for the business data and milestones. When a process executes, it creates a new row in the activity database table recording the data as mapped in the Tracking Profile Editor. Multiple BizTalk artifacts reporting data to the same activity results in multiple rows created in the activity database table. For those artifacts to contribute to a single row in the activity, you need a continuation between the artifacts indicating their relationship.

A common business scenario where activity continuation is useful is the scenario of a life cycle of a purchase order. One company sends a purchase order to another company to purchase goods. The entity shipping the goods will typically send a shipment notice after receiving the purchase order. Additionally, the entity shipping the goods will usually send an invoice for payment of the shipped goods. Managing the sending a purchase order and the receipt of a shipment notice and invoice typically involves many BizTalk artifacts. However, it may be useful to have an end-to-end view of the purchase order life cycle (once issued to the receipt of an invoice) versus each artifact reporting independently. With activity continuation, all the artifacts involved in the life cycle of a purchase order can report information to a single activity, allowing for an end-to-end view of the purchase order life cycle.

Consider the following example: Orchestration A processes a message and transmits that message to Orchestration B for processing. When Orchestration B is finished, it sends a response message back to Orchestration A. When Orchestration A receives the response from Orchestration B, it completes processing. Figure 11-37 demonstrates the sample relationship between Orchestration A and B.

Figure 11.37. Continuation sample

Both Orchestration A and Orchestration B can be mapped to the sample activity. However, when the orchestrations execute, two data rows will be created in the activity table to record the information from the orchestrations (one for Orchestration A and one for Orchestration B). If both orchestrations need to contribute data to the same row in the activity, you must create a continuation in the activity tree to indicate the continuation of activity between Orchestration A and Orchestration B.

The following items are required to create an activity continuation between two orchestrations:

• A data item that relates the two orchestrations (or other BizTalk artifacts) and that can be an attribute in a message shared between the two orchestrations

• A continuation folder that specifies the data item in a parent orchestration that relates the two orchestrations

• A continuation ID folder identifies the data item in the child orchestration that relates the two orchestrations

Note

The name of continuation folder and the name of continuation ID folder must be identical in the activity tree. For example, if you create a continuation folder with the name of Continuation, you must create a continuation ID folder with the name of Continuation. You will receive an exception message if the continuation folder and continuation ID folder do not share the same name.

In the Orchestration A and Orchestration B example, the message ID in Orchestration A from the Send shape is mapped to the continuation folder. The same message ID in the Orchestration B Receive shape is mapped to the continuation ID folder. The message ID is the data item that links the two orchestrations and is also the data item in the continuation and continuation ID folders. The BAM end-to-end SDK sample included with the standard BizTalk installation provides a sample implementation of a continuation.

Activity Relationships

Activity relationships are different from activity continuations in that they allow implicit linking between multiple activities. Consider the Orchestration A and Orchestration B example. If both orchestrations represented different business processes, then it may not make sense to have them report to the same activity. If they report to different activities, it may be useful to represent that the activities have a relationship but are disparate. A real-world example of an activity relationship may be how a single purchase order represents multiple shipments. Each activity (purchase order and shipment) is a different activity but is related to the others.

Activity relationships are also necessary when needing to report on BizTalk orchestrations that contain the Loop shape. You can define the parent orchestration as one activity and the looping activity as a separate activity and still accurately report on the activity of the entire process.

When creating activity relationships, you must adhere to the following guidelines:

• Related activities should belong to the same BAM view.

• A relationship item must be created in each activity in the Tracking Profile Editor and must be given the appropriate name of the related activity.

Consider that Activity A reports on the activity in Orchestration A and Activity B reports on the activity in Orchestration B; you would create the relationships activity items listed in Table 11-15.

Table 11.15. Example Relationship

Orchestration Name	Activity Name	Relationship Item Name
Orchestration A	Activity A	Activity B
Orchestration B	Activity B	Activity A

After specifying the activity items in each activity, the data item that represents the relationship between the activities must be mapped to each activity item. After creating the relationship item in Activity A, a data item (for example, the message ID) that is shared between the activities would need to be mapped to Activity A. The same data item (that is, the message ID) is then mapped to the ActivityID item of Activity B. Mapping the data item to the ActivityID creates the relationship between the first and second activity.