BAM API (BizTalk Server Sample)

The BAM API sample demonstrates how a team works to implement Business Activity Monitoring (BAM) in BizTalk Server 2004. The following graphic illustrates the workflow used in this sample.

The following table discusses the team member roles and responsibilities.

To download the updated BizTalk Server 2004 SDK, go to http://go.microsoft.com/fwlink/?LinkId=24723.

Location in SDK

<Samples Path>\BAM\BAMapiSample

File Inventory

The following table shows the files in this sample and describes their purpose.

To Build and Initialize This Sample

For the BAM API sample, each role (business analyst, IT administrator, and software developer) has tasks to perform.

Business Analyst

The first step in implementing BAM is for the business analyst to create a BAM definition in Microsoft® Excel.

Note  A BAM definition (BAMapiSample.xls) has been provided for use with this sample. Use the following steps if you want to re-create the BAM definition.

To create a BAM definition in Excel

1. Copy <Installation Path>\Tracking\Bam.xls to the <Samples Path>\BAM\BAMapiSample folder.
2. Right-click BAM.xls, select Properties, and clear the Read-only check box.
3. In Excel, from the File menu, select Open.
4. In the Open dialog box, navigate to <Samples Path>\BAM\BAMapiSample, and select BAM.xls.
5. In the Security Warning dialog box, select the Always trust macros from this publisher check box, and then click Enable Macros.
6. On the BAM menu, select BAM Activity.
7. In the Business Activity Monitoring Activity Wizard, click New Activity.
8. In the New Activity dialog box, enter BAMApiPo as the activity name.
9. In the New Activity dialog box, click New Item to open the New Activity Item dialog box.
10. Populate the Items in this activity section with the following values.

    Name	Item Type	Data Type	Max Length
    Amount	Business Data	Float
    Approved	Business Milestones	DATETIME
    Delivered	Business Milestones	DATETIME
    Denied	Business Milestones	DATETIME
    Packaged	Business Milestones	DATETIME
    Product	Business Data	TEXT	50
    Received	Business Milestones	DATETIME
    Shipped	Business Milestones	DATETIME

    The New Activity box appears as follows.

    

11. Click OK.
12. Follow steps 6 through 9 to create a BAMApiInvoice activity. Use the following values for the activity items.

    Name	Item Type	Data Type
    Paid	Business Milestones	DATETIME
    Send	Business Milestones	DATETIME
    Total	Business Milestones	FLOAT

    The New Activity Box appears as follows:

    

Next, you need to create a BAM view using the BAM Activity Wizard.

To create a BAM view

1. In the Business Activity Monitoring Activity Wizard dialog box, select the BAMapiPO activity, and then click OK.
2. In the Welcome to the Business Activity Monitoring View Wizard dialog box, click Next.
3. In the BAM View dialog box, select the Create a new view button, and then click Next.
4. In the New BAM View: Name and Activities dialog box, enter the view name ApiSampleSalesMgr.
5. Check the Select all activities check box, and then click Next.
6. In the New BAM View: View Items dialog box, check the Select all items check box, and then click Next.

   The New BAM View: View Items dialog box appears as follows.

   

7. In the New BAM View: View Items dialog box, click New Duration.
8. In the New Duration dialog box, enter the name for your duration: PoDuration.

   The New Duration dialog box appears as follows.

   

9. In the Start business milestone box, select BAMApiPo.Received.
10. In the End business milestone box, select BAMApiPo.Delivered, click OK, and then click Next.
11. In the New BAM View: Aggregation Dimensions and Measures dialog box, click New Dimension.
12. In the Dimension name box, enter a name (POProgress is used by the sample).

    The New Dimension dialog box appears as follows.

    

13. In the Dimension type box, select Progress Dimension.

    Use the information in the following table to create the progress dimension.

    Stage	Business Milestone	Purpose
    All	BAMApiPo.Received	All POs are known to BAM immediately after they are received.
    Evaluation (child of All)	BAMApiPo.Received	A new PO is in the transient stage Evaluation until it is approved or denied.
    Approved (child of All)	BAMApiPo.Approved	This is a final stage. After a PO is approved, it cannot return to any other stage at that level.
    Fulfillment (child of Approved)	BAMApiPo.Approved	An approved PO is in a transient Fulfillment stage until it is delivered.
    Delivered (child of Approved)	BAMApiPo.Delivered	This is a final stage. After a PO is delivered, it cannot return to any other stage at that level.
    Denied (child of All)	BAMApiPo.Denied	This is a final stage. After a PO is denied, it cannot return to any other stage at that level.

14. When you have finished creating the dimension, click OK.
15. In the New BAM View: Aggregation Dimensions and Measures dialog box, click New Dimension.
16. In the Dimension name box, enter the name for a new data dimension: Product
17. In the Dimension type box, select Data Dimension.

    The New Dimension dialog box appears as follows.

    

18. In the Available data items list, select BAMApiPo.Product, and then click Add to add it to the Dimension levels list, and then click OK.
19. In the New BAM View: Aggregation Dimensions and Measures dialog box, click New Dimension.
20. In the Dimension name box, enter the name for a new numeric range dimension: PoSize.
21. In the Dimension type box, select Numeric Range Dimension.
22. In the Base data item box, select BAMApiPo.Amount.
23. In the Available ranges box, enter the following values.

    Name	From(Incl.)	To(Excl.)
    Large	500	(blank)
    Medium	100	500
    Small	0	100

    The New Dimension dialog box appears as follows.

    

24. Click OK.
25. In the New BAM View: Aggregation Dimensions and Measures dialog box, click New Dimension.
26. In the Dimension name box, enter a name for a new time dimension: PoRecvTime.
27. In the Dimension type box, select Time Dimension.
28. In the Base business milestone box, select BAMApiPo.Received.
29. Under Display settings, select the Year, month, day, hour, minute button, and then click OK.

    The Edit Dimension dialog box appears as follows.

    

30. In the New BAM View: Aggregation Dimensions and Measures dialog box, click New Measure.
31. Create three measures using the following values.

    Measure name	Base	Aggregation Type
    PoCount	BAMApiPo	Count
    TotalAmount	BAMApiPo.Amount	Sum
    AvgDuration	PO Duration	Average

    The New Measure dialog boxes appear as follows.

    

    

    

32. In the New BAM View: Aggregation Dimensions and Measures dialog box, click Next, and then click Finish to exit the wizard.

You now have an empty pivot table with the structure described by using the wizard. The data in the sample pivot table is randomly generated to illustrate how a pivot table appears.

To create real-time aggregation

1. Click the original copy of the pivot table.
2. Select the PoProgress dimension, and drop it to Drop Row Fields Here.
3. Double-click All, and then double-click Approved to view the dimension structure.
4. Select the Product dimension, and drop it to Drop Column Fields Here.
5. Select PoCount, and drop it to Drop Data Items Here.

   The data in the pivot table is randomly generated as an example. From this, you can create charts, calculations, and so on.

6. Click the Real-Time Aggregation button.

   The Real-Time Aggregation button appears as follows.

   

7. This informs BAM to create a real-time aggregation for a {PoProgress x Product x PoCount} slice of the multidimensional structure rather than using data from an OLAP cube.
8. You can copy the pivot table into another area of the worksheet, and select other dimensions and measures. Without pressing the Real-Time Aggregation button, the table will read from the OLAP cube (that is, a scheduled report).
9. From the File menu, click Save to save the aggregation.

IT Administrator

For this sample, the IT administrator uses the BAM Management utility to create a dynamic infrastructure consisting of SQL tables, stored procedures, triggers, views, DTS packages, and OLAP cubes.

To create dynamic structure

1. Copy BAMapiSample.xls to <Installation Path>\Tracking.
2. At the command prompt, change directory (cd) to the \Tracking directory.
3. If you have not run Setup.bat to deploy BAMapiSample.xls, you can use the BAM utility to deploy the workbook:
   Copy

   bm deploy BAMapiSample.xls
   

   Note  If you created your own profile, be sure to deploy it rather than BAMapiSample.xls.

   Software Developer

After the business analyst has defined the interesting data, the developer must implement a solution to expose the data or, as is usually the case, the developer must instrument existing applications for BAM.

The following pseudo code illustrates different threads that run in the console application BAMapiSample.exe:

Purchase order thread

   Randomly generate PO XML
   Sleep random time //evaluating the PO
   Make decision
      If denied, End
   Sleep random time //packaging the PO
   Queue the PO for shipment and invoicing

Shipment thread

   Pick one shipment from the queue
   Sleep random time
   End //PO delivered
   //This thread illustrates cotinuation--shipment events are considered    //part of the PO activity.

Invoice thread

   Wait until several POs are in the queue
   Construct Invoice XML from multiple POs
   Sleep random time
      End //the invoice has been paid   
   //This thread illustrates relationship--some PO activities (that is,    //instances) are related to a given invoice activity (or instance).

You can instrument this application in two ways:

• Send explicit events to BAM (requires code modification to get more data).
• Use the BAM interceptor.

To send explicit events to BAM

1. In Microsoft® Visual Studio® .NET, open BAMapiSample.sln.
2. Add a reference to Microsoft.BizTalk.BAM.EventObservation.dll in the BAMapiSample and Interceptor projects.
3. Open BAMapiSample.cs. Make sure the first line is commented (as shown) or removed:
   Copy

   // #define Interceptor
   

4. Build the application. Run BAMapiSample.exe from <Samples Path>\BAM\BamApiSample\bin\debug. This generates data and displays new purchase order status.

   The output appears as follows.

   

Notice in the source code that an instance of DirectEventStream class is created, which the threads use to send explicit events to BAM. The constants (for example, number of threads, sleep time, and so on) are located in the Global class.

Using the interceptor

Instrumenting the code with explicit BAM events has the drawback that the code must be modified every time business monitoring requirements change. For example, a new requirement to monitor discounts may be added.

The BAM interceptor enables write-once instrumentation with event filtering driven by the interceptor configuration.

To enable the BAM interceptor

1. In Visual Studio .NET, open BAMapiSample.sln.
2. Add a reference to Microsoft.BizTalk.BAM.EventObservation.dll in the BAMapiSample and Interceptor projects.
3. Open BAMapiSample.cs. Make sure the first line is uncommented:
   Copy

   // #define Interceptor
   

4. Build the solution.

All threads retrieve interceptors from binary files on each iteration (activity instance). The interceptors are configured with information about what data to collect and at which step of program execution to gather it. The console application includes an implementation of the callback interface IBAMDataExtractor.

In every step of program execution, the console application calls the interceptor's OnStep method. The interceptor determines whether there is any interesting data to gather.

To create an interceptor configuration, launch InterceptorConfiguration.exe from <Samples Path>\BAM\BamApiSample\bin\debug. InterceptorConfiguration.exe prompts you for the activity milestone, location, and XPath of each activity or milestone, as shown in the following output.

Rather than entering information for each prompt, you can use the command:

InterceptorConfiguration.exe < Input.txt

To generate data, run BamApiSample.exe from <Samples Path>\BAM\BamApiSample\bin\debug.

To View the BAM Aggregate Data

Open the BAMapiSample_LiveData.xls (created either when you deployed the BAMapiSample.xls using the BAM Management utility (bm) or when you ran Setup.bat). This should be in the same folder as the original .xls that was deployed.

Note  If you created your own profile and deployed it, then open <your profile>_LiveData.xls. This workbook shows real-time aggregations and pivot tables.

To view the OLAP cubes (if you created them), you must manually run the DTS packages that have been dynamically created. For more information about running DTS packages, see SQL Server Books Online.

To Query BAM Instance Data

If you have Business Activity Services installed, go to http://<Server Name>/sites/BASSite and click Business Activity Search in the left pane to see the Instance data.

Remarks

This sample does not use orchestration schedules. It demonstrates how to use the BAM APIs directly from C# programs. To see how to use BAM with orchestrations and pipelines, see the BAM End-to-End (BizTalk Server Sample).

You can change the interceptor configuration as the sample runs, but only new purchase orders will include the change.

In addition to identifying locations by string, you can also identify location by an object as long as the object exposes efficient GetHashCode and IsEqual methods and is serializable.

Data items can be identified with XPath or a serializable object. Such objects are stored as opaque entities in the interceptor configuration and passed to the callback interface IBAMDataExtractor.

Custom objects for Location and Data Extraction Info should be implemented in a common assembly that is used by the bm utility and the interceptor configuration tool. In this case, serialize the configuration as XML using the constructor:

XmlSerializer(type t, type [] additionalTypes) 

Pass an array of custom types in the second parameter.

Interceptors are typically serialized in binary format rather than loading TraceInterceptorConfiguration and using the UpdateInterceptor method for performance reasons.

A single global interceptor is not used because the interceptor instance is stateful. It remembers the ActivityID (which may not always be available) and uses it when constructing BAM events.

See Also

Business Activity Monitoring (BizTalk Server Samples Folder)