Windows Workflow Tracking Services

Article
10/14/2009

Windows Workflow Foundation enables you to track workflow-related information in a consistent, reliable, and flexible manner. The Windows Workflow Foundation tracking framework is designed to enable hosts to observe workflow instances during execution by capturing events that are raised during workflow execution. The framework is a pluggable design that enables hosts to either write their own tracking service or use an out-of-box or third-party tracking service. Additionally, because the Windows Workflow Foundation runtime engine lets you add several runtime services during its lifetime, multiple tracking services of different types can be enabled simultaneously. For example, Windows Workflow Foundation contains an out-of-box SqlTrackingService service that writes a configurable amount of tracking information to a SQL Server database. The Windows Workflow Foundation samples also contain a sample, ConsoleTrackingService Sample, that listens for events and outputs those events to the console. Both of these services can be run in conjunction to enable both end-user visibility into workflow execution and debugging information during development.

Tracking Features in Windows Workflow Foundation

The Windows Workflow Foundation contains several built-in features to enable tracking in a workflow-enabled application.

Feature	Description
Makes sure that tracking occurs in a consistent manner.	Users and applications can track workflow state and history for live workflows and workflows that have been archived to disk. A consistent framework for tracking services ensures that custom tracking services follow a logical and coherent pattern.
Provides scalability and reliability.	The tracking framework is lightweight enough to be deployed on a single computer, but at the same time it can be scaled to meet the requirements of most enterprise businesses, such as those that require a clustered and distributed data center environment.
Enables workflow data to be tracked regardless of the underlying data store.	The tracking framework is agnostic to the data store that manages the tracking events. A well-defined schema for tracking events is available to end users; however, the data store ultimately controls the schema for the underlying persisted data.
Provides one location to query for workflow-related data across hosting environments.	Windows Workflow Foundation can be hosted within multiple environments; applications need a consistent interface through which workflow information can be queried.

Provides the ability to query on past and present workflow life cycles, and determine possible future execution paths of workflow instances.	The tracking framework provides a way for emitting workflow definition and metadata that is associated with a workflow to enable guidance-type queries. It also provides a way for emitting data-state changes so that user-defined states can be tracked.
Provides support for programmatic change to tracking profiles.	You can create tracking profiles by using the Tracking Profile Object Model. This lets you load custom profiles as needed during the execution of your active workflows.

Tracking Profiles

Tracking services determine the amount of data they receive by using a tracking profile to filter that data. A tracking service can receive workflow events, activity execution status, and custom user tracking data items. The tracking service is responsible for the tracking data that it receives from the runtime engine when a workflow instance is running. It can store the data in a file or in a database, create an in-memory query store, write the data to the system event log, or just output the tracking data to the console.

You can author tracking profiles declaratively by using a Tracking Profile XML schema, or programmatically using the Tracking Profile Object Model. Additionally, XML based Tracking Profiles can be deserialized to a TrackingProfile instance by using the TrackingProfileSerializer APIs.

For more information about tracking profiles, see Creating and Using Tracking Profiles.

Tracking Event Types

When you use tracking in Windows Workflow Foundation, you can track a single event or a group of events that are raised during workflow execution. The events that can be tracked for activities are defined in the ActivityExecutionStatus enumeration:

Initialized
Executing
Canceling
Closed
Compensating
Faulting

In addition to tracking events for activities, the tracking infrastructure also enables you to track events that occur at the workflow-instance level. The instance level events that can be tracked are defined in the TrackingWorkflowEvent enumeration:

Created
Completed
Idle
Suspended
Resumed
Persisted
Unloaded
Loaded
Exception
Terminated
Aborted
Changed
Started

For information about tracking individual events, see Creating and Using Tracking Profiles.

Explicit Code-Level Tracking

Developers who build workflows and tasks may want to instrument their code with explicit tracking events. This should be done only if the tracking profile cannot be used to instrument the runtime for the desired tracking event.

The workflow author can use one of the TrackData overloaded methods on ActivityExecutionContext to track any kind of information. There is no limit to the number of user tracking points, and there is no limitation on the kind of data that can be sent from the track method. In the SqlTrackingService implementation, if an object that is passed into the second parameter of the TrackData method is not binary serializable, the data that is saved is the result of calling that object's ToString method.

For example, the following class is a custom object that can be used to track debugging messages during activity execution. The class contains a Message property and a MessageType property that signifies if the message being tracked is informational, a warning, an error, or for debugging, and therefore not displayed to the end user. Additionally, a static helper method is used to return a newly constructed UserEventData object that is used during the call to the TrackData method.

[C#]

using System;
using System.Collections.Generic;
using System.Text;

namespace Microsoft.Samples.Workflow.TrackData
{
    [Serializable]
    public class UserEventData
    {
        private UserEventType type = 0;
        private string message = "";

        public enum UserEventType
        {
            Info = 0,
            Warning = 1,
            Error = 2,
            Debug = 4
        };

        public UserEventType MessageType
        {
            get { return type; }
            set { type = value; }
        }

        public string Message
        {
            get { return message; }
            set { message = value; }
        }

        public static UserEventData NewMessage(UserEventType type, string message)
        {
            UserEventData ret = new UserEventData();
            ret.MessageType = type;
            ret.Message = message;
            return ret;
        }
    }
}

The UserEventData class that is defined in the example can be used as a custom tracking object when you author a custom activity. To track a UserEventData object, call the TrackData method, passing a new UserEventData object as the object to track. The following code shows how to do this in a custom activity by overriding the Execute method:

[C#]

protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)
{
    this.TrackData(UserEventData.NewMessage(UserEventData.UserEventType.Debug, "Activity executing"));
}

For more information about tracking custom data, see the Tracking Using User Track Points Sample.

Tracking Markup-Only Workflows

With workflow markup-only workflows and Windows Workflow Foundation tracking functionality, you can either use a generic tracking profile or use ReloadTrackingProfiles on every workflow instance before you start the instance - if you want to track specific events/items from this instance. If you decide to use ReloadTrackingProfiles, you must create a workflow instance for the XML BLOB, get the instance GUID, build a tracking profile specific to that instance, and then ask the instance to reload its profiles. The tracking service should return this profile back to the workflow runtime engine when GetProfile with the instance ID is called. This is where the correlation between instance and profile occurs.

Tracking Rules

When a RuleSet executes, tracking events are sent to tracking services that are configured on the hosts that have registered for these events by adding a UserTrackPoint to their tracking profile. A RuleActionTrackingEvent is sent, which provides the name of the rule that was evaluated, as well as the condition evaluation result (true/false). For more information, see the RuleActionTrackingEvent Sample.

The evaluation results of rule conditions on activities can be implicitly tracked by tracking activity execution.

Custom Tracking Services

Windows Workflow Foundation contains a SqlTrackingService service that you can use to track data that is stored in a SQL Server database. However, because of the extensibility model that is used by Windows Workflow Foundation, you can create custom tracking services that use a different storage medium, such as a local file, because the runtime engine has no concern for the end destination of the data or the format in which it is delivered. For more information about how to create a custom tracking service, see Creating Custom Tracking Services.