Workflow Lifecycle

Tracking records are used to give transparency into a workflow instance’s execution path, but it is also important to understand the flow of the workflow’s lifecycle. A workflow’s tracked events include when a workflow instance

• Is aborted
• Updates a workflow definition (New in WF4.5)
• Suspends
• Terminates
• Encounters an unhandled exception

Therefore there are tracking records that are emitted to indicate when these events occur.

Activity Lifecycle

Tracking records are also used to provide transparency into a workflow activity’s lifecycle. A workflow’s tracked events include the following:

• Activity state
• Scheduled
• Cancelled
• Fault Propagation
• Bookmark Resumption
• Custom data tracking

Therefore these events have a tracking record that is emitted to indicate when an event occurs. The tracking records mentioned in the next section also inherit from TrackingRecord, so they also inherit the same properties indicated in Table 9-4.

ImplementationVisibility

Tracking profiles have a way of subscribing to child activity tracking records that are emitted for children activities contained within composite activities; however, by default it is turned off. ImplementationVisibility is the property that can be found of the following tracking profiles:

• ActivityScheduledRecord
• ActivityStateRecord
• FaultPropagationRecord
• CancelRequestedRecord

The ImplementationVisibility property can be set to either

• RootScope: The root activity of a composite activity emits tracking records.
• All: All activities within a composite activity emit tracking records.

Listing 9-3 shows a TrackingProfile object supplied with an ImplementationVisibility property changed to System.Activities.Tracking.ImplementationVisibility.All.

Listing 9-3.  Changing the Default ImplementationVisibility Property to All

var profile = new TrackingProfile
                {
                    Name = "Custom Tracking Profile",
               ImplementationVisibility =
            System.Activities.Tracking.ImplementationVisibility.All
                }

The same can be done through the configuration for a tracking profile, as indicated in Table 9-4.

<tracking>
      <trackingProfile name="Custom Tracking Profile" implementationVisibility="All">

TrackingQuery

An earlier section covered the different types of tracking records that are emitted through the WF runtime; however, to subscribe to certain types of tracking records, a TrackingQuery is required to be enlisted for identifying the type of tracking record that should be subscribed to as well as what characteristics of the tracking record should be filtered. Listing 9-2 illustrates that all WorkflowInstanceRecord types should be subscribed to by using the following syntax:

    Queries =
        {
                 new WorkflowInstanceQuery
                 {
                     States = {"*"}
                 }
             }

Each type of tracking query that is used for subscribing to tracking records inherits from System.Activities.Tracking.TrackingQuery:

• ActivityScheduledQuery
• ActivityStateQuery
• BookmarkResumtionQuery
• CancelRequestedQuery
• CustomTrackingQuery
• FaultPropagationQuery
• WorkflowInstanceQuery

In order to track multiple tracking records, the following C# syntax can be used:

    Queries =
                          {
                              new WorkflowInstanceQuery
                              {
                                 States = {"*"}
                              },
                new ActivityStateQuery
                {
                   States={"*"}
                }
                          }

And when the tracking profile is configured using XML, the queries can be stacked, like so:

<workflowInstanceQueries>
    <workflowInstanceQuery>
        <states>
            <state name="*"/>
        </states>
   </workflowInstanceQuery>
</workflowInstanceQueries>
<activityStateQueries>
    <activityStateQuery>
        <states>
            <state name="*"/>
        </states>
   </activityStateQuery>
</activityStateQueries>

WorkflowServiceHost Tracking

The Basic Tracking exercise demonstrated building the tracking profile and adding a tracking participant as a workflow extension through code because WorkflowInvoker was used to host the workflow as an application. But when a workflow is either hosted as a WCF service or the workflow is hosted using the WCF service host WorkflowServiceHost, tracking participants and tracking profiles can be configured using XML, as mentioned earlier. There is one caveat: a tracking participant still requires custom code for adding it as a workflow extension. Therefore a custom service behavior is required, which can be built within a custom class that implements the interface System.ServiceModel.Description.IServiceBehavior. In order to use the custom service behavior, a custom behavior extension element is required, too, that inherits from System.ServiceModel.Configuration.BehaviorExtensionElement.

BehaviorExtensionElement

Workflow Instance State

The WorkflowInstanceRecord uses the WorkflowInstanceQuery for filtering tracking records. However, let’s first demo all of the records that will be returned when “*” is used as a wildcard, demonstrated with the tracking profile illustrated in Listing 9-5 for pulling all of the workflow instance tracking records with the new tracking participant.

Listing 9-5.  Serializing the Tracking Records

    <trackingProfile name="CustomTrackingProfile">
      <workflow>
        <workflowInstanceQueries>
          <workflowInstanceQuery>
            <states>
                <state name="*"/>
            </states>
          </workflowInstanceQuery>
        </workflowInstanceQueries>
      </workflow>
    </trackingProfile>

Figure 9-17 shows that the workflow instance tracking records have been serialized, showing the properties that are provided on the tracking record.

To filter the tracking records for when the workflow instance starts, the tracking profile can be changed to

<states>
    <state name="Started"/>
</states>

The result is

    <WorkflowInstanceRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="
http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T00:32:56.4870156Z</EventTime>
      <InstanceId>3d4cc291-864c-40c3-9772-e5769ec7db60</InstanceId>
      <Level>Info</Level>
      <RecordNumber>0</RecordNumber>
      <ActivityDefinitionId>Workflow1</ActivityDefinitionId>
      <State>Started</State>
      <WorkflowDefinitionIdentity xmlns:d2p1="
http://schemas.datacontract.org/2004/07/System.Activities" i:nil="true" />
</WorkflowInstanceRecord>

Tracking when the workflow also ends requires the following change:

<states>
    <state name="Started"/>
    <state name="Completed"/>
</states>

The result is

    <WorkflowInstanceRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T00:45:00.3395546Z</EventTime>
      <InstanceId>026aa5d3-5457-4b1e-8d65-7d37904e2077</InstanceId>
      <Level>Info</Level>
      <RecordNumber>0</RecordNumber>
      <ActivityDefinitionId>Workflow1</ActivityDefinitionId>
      <State>Started</State>
      <WorkflowDefinitionIdentity xmlns:d2p1="http://schemas.datacontract.org/2004/07/System.Activities" i:nil="true" />
    </WorkflowInstanceRecord>
    <WorkflowInstanceRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T00:45:00.4176796Z</EventTime>
      <InstanceId>026aa5d3-5457-4b1e-8d65-7d37904e2077</InstanceId>
      <Level>Info</Level>
      <RecordNumber>5</RecordNumber>
      <ActivityDefinitionId>Workflow1</ActivityDefinitionId>
      <State>Completed</State>
      <WorkflowDefinitionIdentity xmlns:d2p1="http://schemas.datacontract.org/2004/07/System.Activities" i:nil="true" />
</WorkflowInstanceRecord>

This type of tracking filter is more practical for tracking starting and completing of a workflow instance. Note that the EventTime property is set and can be used to determine the length of time it took for one workflow instance over others, but what happens when unanticipated issues happen to a workflow instance? Without either tracking all workflow instance records or specifying aborted workflow instances within the tracking record, they won’t be seen. In fact, if the workflow throws an exception, the only indication that something might be wrong is that the Completed state tracking record is never received, therefore the tracking profile needs to add Aborted as a filtered state as well.

<states>
    <state name="Started"/>
    <state name="Aborted"/>
    <state name="Completed"/>
</states>

To test this, add a Throw activity that will simulate an exception within the workflow (see Figure 9-18).

Now the WorkflowInstanceAbortedRecord will be tracked, as illustrated in the following results:

<WorkflowInstanceRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
  <EventTime>2012-03-24T01:54:38.0475625Z</EventTime>
  <InstanceId>285ff549-67e2-4074-a56d-2c3ed596f014</InstanceId>
  <Level>Info</Level>
  <RecordNumber>0</RecordNumber>
  <ActivityDefinitionId>Workflow1</ActivityDefinitionId>
  <State>Started</State>
  <WorkflowDefinitionIdentity xmlns:d2p1="http://schemas.datacontract.org/2004/07/System.Activities" i:nil="true" />
</WorkflowInstanceRecord>
<WorkflowInstanceAbortedRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
  <EventTime>2012-03-24T01:54:38.1881875Z</EventTime>
  <InstanceId>285ff549-67e2-4074-a56d-2c3ed596f014</InstanceId>
  <Level>Info</Level>
  <RecordNumber>6</RecordNumber>
  <ActivityDefinitionId>Workflow1</ActivityDefinitionId>
  <State>Aborted</State>
  <WorkflowDefinitionIdentity xmlns:d2p1="http://schemas.datacontract.org/2004/07/System.Activities" i:nil="true" />
  <Reason>Here is an exception</Reason>
</WorkflowInstanceAbortedRecord>

Notice that there is not a Completed state record, because the workflow aborts rather than completes. The WorkflowInstanceAbortedRecord contains the reason, which maps back to the exception message. If an exception caused a workflow to abort, than the WorkflowInstanceUnhandledExceptionRecord can be tracked too by querying its state

<states>
    <state name="UnhandledExeption"/>
</states>

so additional information can be provided for debugging.

Activity State

Tracking can get even more granular by tracking workflow activities. A custom activity called DoSomeWork has been added to the workflow using the following code:

    public class DoSomeWork:CodeActivity
    {
        [RequiredArgument]
        public InArgument<int> MillaSecondsToWait{ get; set; }
     
        protected override void Execute(CodeActivityContext context)
        {
           Thread.Sleep(context.GetValue(SecondsToWait));
        }
        }

Adding the new activity, the milliseconds are set to 5000, simulating 5 seconds for work being processed (see Figure 9-19).

A new tracking profile is added to the configuration for just tracking activity records:

    <trackingProfile name="ActivityTrackingProfile">
      <workflow>
        <activityStateQueries>
          <activityStateQuery>
            <states>
                <state name="*"/>
            </states>
          </activityStateQuery>
        </activityStateQueries>
      </workflow>
    </trackingProfile>

The service behaviors custom property profileName is changed to ActivityTrackingProfile so the activity records can be tracked.

After running the workflow using the changed profile, all of the activity states for each activity in the workflow get tracked, but you’re interested in tracking just the custom DoSomeWork activity. So instead of getting all of the other records, you can just see the custom activity’s execution. The tracking profile needs to be changed to

   <activityStateQuery activityName="DoSomeWork">
        <states>
          <state name="*"/>
        </states>
   </activityStateQuery>

The results within the console show the DoSomeWork activity's execution.

    <ActivityStateRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="
    http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T16:29:04.2771797Z</EventTime>
      <InstanceId>5562743c-be60-428c-9751-d933636ee2de</InstanceId>
      <Level>Info</Level>
      <RecordNumber>4</RecordNumber>
      <Activity>
        <Id>1.3</Id>
        <InstanceId>7</InstanceId>
        <Name>DoSomeWork</Name>
        <TypeName>CustomTrackingQueries.DoSomeWork</TypeName>
      </Activity>
      <State>Executing</State>
      <arguments xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
      <variables xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
    </ActivityStateRecord>
    <ActivityStateRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="
http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T16:29:09.3240547Z</EventTime>
      <InstanceId>5562743c-be60-428c-9751-d933636ee2de</InstanceId>
      <Level>Info</Level>
      <RecordNumber>5</RecordNumber>
      <Activity>
        <Id>1.3</Id>
        <InstanceId>7</InstanceId>
        <Name>DoSomeWork</Name>
        <TypeName>CustomTrackingQueries.DoSomeWork</TypeName>
      </Activity>
      <State>Closed</State>
      <arguments xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
      <variables xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
</ActivityStateRecord>

Notice that the EventTime property is exactly 5 seconds, which represents the duration used to sleep the thread that simulated work being processed. The value MilliSecondsToWait is not included, so the tracking profile can be changed to query the arguments value, like so:

<arguments>
    <argument name="MilliSecondsToWait"/>
</arguments>

The results are

      <arguments xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <d2p1:KeyValueOfstringanyType>
          <d2p1:Key>MilliSecondsToWait</d2p1:Key>
          <d2p1:Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:int"
>5000</d2p1:Value>
        </d2p1:KeyValueOfstringanyType>
</arguments>

including the value of 5000 for the argument. Variables can also be tracked if required using the <variables> collection query.

Custom Data Tracking

Custom activities can also have custom data tracked that is neither a variable nor an argument. These are scenarios where data needs to be tracked because it either is retrieved from other sources outside of the workflow or it is data that is important to track so it can be referenced later—like transaction numbers or date stamps. A custom activity can create a CustomTrackingRecord and its data property can be used to hold data that needs to be published and later subscribed to using a CustomTrackingQuery.

The DoSomeWork activity has been changed and now includes a new using statement using System.Activities.Tracking; and the following code was added within the Execute method:

     
    var record = new CustomTrackingRecord("WorkingLevel")
                {
                       Data =
                            {
                               {"Scale", 10},
                                  {"ScaleDescription", "Pretty dawg on hard!"}
                               }
                            };
     
    context.Track(record);
     

This code builds a new CustomTrackingRecord  and sets the Data property to two IDictionary<string, Object> values, Scale and ScaleDescription. The tracking profile is changed to query all custom tracking records, like so:

<customTrackingQueries>
        <customTrackingQuery activityName="*"/>
</customTrackingQueries>

The results are

    <CustomTrackingRecord xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns=
    "http://schemas.datacontract.org/2004/07/System.Activities.Tracking">
      <EventTime>2012-03-24T17:25:26.4978828Z</EventTime>
      <InstanceId>5b64b301-201b-49c4-9ee1-4f5d10cc4234</InstanceId>
      <Level>Info</Level>
      <RecordNumber>4</RecordNumber>
      <Activity>
        <Id>1.5</Id>
        <InstanceId>7</InstanceId>
        <Name>DoSomeWork</Name>
        <TypeName>CustomTrackingQueries.DoSomeWork</TypeName>
      </Activity>
      <Name>WorkingLevel</Name>
      <data xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <d2p1:KeyValueOfstringanyType>
          <d2p1:Key>Scale</d2p1:Key>
          <d2p1:Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:int">10</d2p1:Value>
        </d2p1:KeyValueOfstringanyType>
        <d2p1:KeyValueOfstringanyType>
          <d2p1:Key>ScaleDescription</d2p1:Key>
          <d2p1:Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Pretty dawg on hard!</d2p1:Value>
        </d2p1:KeyValueOfstringanyType>
      </data>
</CustomTrackingRecord>

This shows the data values that were set within the custom activity DoSomeWork. If there were other custom activities but only custom data from the DoSomeWork activity is required, the tracking profile’s activtyName can be changed, like so:

        <customTrackingQuery activityName="DoSomeWork"/>

Or, if other custom activities within the workflow have a tracking record called WorkingLevel that needs to be tracked, the profile can be changed to

        <customTrackingQuery activityName="*" name="WorkingLevel"/>

which will return back tracked data for WorkingLevel for each activity.

Record Annotations

Tracking stores that are either kept within files or database stores will more than likely contain large amounts of records based on a couple of factors. There can be a large number of workflow instances being tracked depending on the activity for workflow hosted application, or a single tracking store can store tracking for multiple workflow types. For instance, one file could contain all unhandled exceptions, or a general approach for subscribing to all published tracking records may be taken where all workflow activity is tracked. With a high volume of tracking data, there might be times when tracked data needs to be flagged. Some examples could be workflows that are running a particular server and the server IP needs to be added, or indicating workflows that are processing work for certain clients. Annotations can be added within tracking queries, so once tracking information is tracked, it can be given annotations describing what the tracked information is so it can be flagged and referenced for later use. Annotations can be added within a tracking profile in the following manner:

<annotations>
        <annotation name="LevelOfWork" value="These records indicate how hard the author is working!"/>
</annotations>

Annotations can even be used to categorize records, like so:

<annotations>
        <annotation name="Publisher" value="Apress"/>
        <annotation name="BookName" value="Pro WF4.5"/>
        <annotation name="LevelOfWork" value="These records indicate how hard the author is working!"/>
</annotations>

This way other tracking records can share the same categories like Publisher and BookName for consolidating how hard other authors are working.

ETW Tracking Participant

Tracking workflows within Event Tracing for Windows (ETW) is provided out of the box with WF4.x and provides a natural way for viewing tracked workflows within the Event Viewer, a centralized place that provides visualization into the health for the system and custom applications. Many internal processes are logged to the Event Viewer, so it can be used to monitor the health of internal and external processes.

There are two ways of setting up the ETW tracking participant while using it to track workflow services or workflows hosted using WorkflowServiceHost. One way is to use code for workflow applications, hosted by WorkflowApplication or WorkflowInvoker, as demonstrated here:

Activity workflow1 = new Workflow1();
WorkflowInvoker invoker = new WorkflowInvoker(workflow1);
var tracker =
new EtwTrackingParticipant
{
    TrackingProfile = BuildTrackingProfile()
};
Invoker.Extensions.Add(tracker);
Invoker.Invoke();

Another way is through a configuration file when using WorkflowServiceHost:

<behaviors>
   <serviceBehaviors>
        <behavior>
          <etwTracking profileName="Sample Tracking Profile" />
        </behavior>
   </serviceBehaviors>
<behaviors>

Setting up the configuration for the ETW tracking participant is different than setting up other custom tracking participants because there is no need to add it as a custom extension to the WF runtime. Therefore, custom service behavior and element extensions do not need to be built.

The Event Viewer is provided within the operating system and can be found by clicking Start on Windows and typing “Event Viewer” (see Figure 9-20).

After opening the Event Viewer, tracking records can be found by expanding the Applications and Services Logs Microsoft Windows Application Server-Applications Microsoft-Windows-Application Server Applications/Analytic node (see Figure 9-21).

If the logs are disabled, they can be enabled by right-clicking on the node and selecting Enable Log (see Figure 9-22).

Using the same project as before to demonstrate tracking queries, the custom service behavior is commented out and the etwTracking is included as well as the same tracking profile for tracking custom tracking data (see Figure 9-23).

Running the project again will query the same tracking records for custom data like before, but this time the records will be viewable through the Event Viewer (see Figure 9-24).