Because this is our first activity, we’ll keep it simple. We’ll create an activity that calculates the difference between two times and displays this difference as text, such as "5 months" or "12 minutes".

To get started, we’ll need an assembly to hold our custom activities.

Creating a custom activity assembly

At this point you can compile the project, but of course without any classes the assembly isn’t too valuable. We’ll remedy that by adding our first custom activity class.

Creating your first custom activity

Now that we have a blank file ready to go, let’s start by including the following using statements at the top of the file:

using System;
using System.Workflow.ComponentModel;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.Workflow;

Now we need to add the class definition. Note two items of interest here. First, we inherit from System.Workflow.ComponentModel.Activity the way that all activities are required to do (either directly or indirectly). Second, we apply the CrmWorkflowActivity attribute to our class, which tells the Microsoft Dynamics CRM workflow designer how to display our custom activity in the user interface. Example 6-1 shows the simple, stubbed-out CalculateAgeActivity class definition.

namespace ProgrammingWithDynamicsCrm4.Workflow
{   
    [CrmWorkflowActivity("Calculate Age",
        "Programming Microsoft CRM 4")]
    public class CalculateAgeActivity: Activity
    {
    }
}

The next thing we need to do is define the properties for our class. We need two CrmDateTime properties that we can compare and a string property to contain our human-readable age output value. Normally you would implement them like this:

private CrmDateTime _earlierDate;
public CrmDateTime EarlierDate
{
    get { return _earlierDate; }
    set { _earlierDate = value; }
}

However, this implementation would not expose your properties to be bound to the values of other activities. To achieve this, we need to use a DependencyProperty for the backing store of the property. You can achieve this by implementing your properties as follows:

public static DependencyProperty EarlierDateProperty = DependencyProperty.Register(
    "EarlierDate", typeof(CrmDateTime), typeof(CalculateAgeActivity));

[CrmInput("Earlier Date")]
public CrmDateTime EarlierDate
{
    get { return (CrmDateTime)GetValue(EarlierDateProperty); }
    set { SetValue(EarlierDateProperty, value); }
}

Wow! That seems like quite a bit of code for a simple property. The first thing you probably noticed is that you no longer have a private field. It is replaced by a static public DependencyProperty. This DependencyProperty is used like a key for getting and setting the value of the property. The DependencyProperty is created by calling the static DependencyProperty.Register method, which takes arguments of the property name as a string, the property type, and the activity class type.

The addition of the CrmInput attribute on the property definition is also new. This attribute tells the workflow designer that the property is meant to be used as an input and also provides the label that should be presented in the designer’s user interface.

Finally, the property getter and setter use the GetValue and SetValue methods, which are defined on DependencyObject (Activity’s base class). Both GetValue and SetValue take a DependencyProperty as an argument to determine which property value should be retrieved or assigned.

Although these steps might seem like a burden, they allow Windows Workflow Foundation to efficiently bind activities together without those activities having any knowledge of each other.

Tip

You can use a snippet in Visual Studio 2008 to insert properties that use a DependencyProperty as the backing store by typing in propdp and then pressing the Tab key twice. As with all snippets, you can specify the different values, such as the property type and name, and then just press Tab to jump to the next input field. When you are done entering input fields, press Enter and you’ll return to the normal text input mode.

Unfortunately, the snippet was designed for use with Windows Presentation Foundation (WPF), which also uses dependency properties. Because of this, the snippet calls an overloaded version of DependencyProperty.Register passing in a System.Windows.UIPropertyMetadata, which is used to specify a default value for the property. You can just delete this last argument and it will work fine—it’s just an additional step.

Armed with this understanding of dependency properties, we can define the remaining two properties like this:

public static DependencyProperty LaterDateProperty = DependencyProperty.Register(
    "LaterDate", typeof(CrmDateTime), typeof(CalculateAgeActivity));

[CrmInput("Later Date")]
public CrmDateTime LaterDate
{
    get { return (CrmDateTime)GetValue(LaterDateProperty); }
    set { SetValue(LaterDateProperty, value); }
}

public static DependencyProperty AgeProperty = DependencyProperty.Register(
    "Age", typeof(string), typeof(CalculateAgeActivity));

[CrmOutput("Age")]
public string Age
{
    get { return (string)GetValue(AgeProperty); }
    set { SetValue(AgeProperty, value); }
}

The only thing worth noting here is that our Age property has been marked with the CrmOutput attribute, which tells the workflow designer that the property should be used for output and given the label "Age" in the user interface.

Now that our properties have been defined, we just need to implement the part of the activity that actually does something. The base Activity class defines an Execute method that is called by the workflow run time whenever the activity needs to be executed. Example 6-2 shows CalculateAgeActivity’s implementation of Execute.

protected override ActivityExecutionStatus Execute(
    ActivityExecutionContext executionContext)
{
    CrmDateTime earlierDate = this.EarlierDate;

    if (earlierDate != null)
    {
        CrmDateTime laterDate = this.LaterDate ?? CrmDateTime.Now;
        this.Age = GenerateHumanReadableAge(
            laterDate.UniversalTime - earlierDate.UniversalTime);
    }

    return ActivityExecutionStatus.Closed;
}

This method simply gets the values from our two input CrmDateTime parameters and passes their difference into the GenerateHumanReadableAge method, which does all the work. The return value is assigned to our output Age parameter. Also, if the LaterDate property is null, it uses the current date and time for that value. Notice that we use the UTC version of both dates through the UniversalTime property. We are not using the ActivityExecutionContext object that is passed in at this point, but we’ll cover it later in the chapter.

More Info

The return value for the Execute method is of type ActivityExecutionStatus. You almost always want to return ActivityExecutionStatus.Closed, which indicates to the workflow run time that this activity is complete and the next activity can begin executing. However, you can use several other states to indicate that either something has gone wrong or that your activity is temporarily suspended. See http://msdn.microsoft.com/en-us/library/system.workflow.componentmodel.activityexecutionstatus.aspx for more information on the ActivityExecutionStatus enumeration.

Example 6-3 shows the implementation of the GenerateHumanReadableAge method, which is actually not specific to WF or Microsoft Dynamics CRM in any way.

private string GenerateHumanReadableAge(TimeSpan age)
{
    string result;
    int years = age.Days / 365;
    int months = age.Days / 30;
    int weeks = age.Days / 7;

    if (years > 1)
    {
        result = String.Format("{0} years", years);
    }
    else if (months > 1)
    {
        result = String.Format("{0} months", months);
    }
    else if (weeks > 1)
    {
        result = String.Format("{0} weeks", weeks);
    }
    else if (age.Days > 1)
    {
        result = String.Format("{0} days", age.Days);
    }
    else if (age.Hours > 1)
    {
        result = String.Format("{0} hours", age.Hours);
    }
    else if (age.Minutes > 1)
    {
        result = String.Format("{0} minutes", age.Minutes);
    }
    else
    {
        result = String.Format("{0} seconds", age.Seconds);
    }

    return result;
}

This method follows a fairly simple algorithm to convert a TimeSpan into some text that gives an approximate age that is more human-readable.

Now that our custom activity is implemented (and should compile without errors), we need to register the assembly with the Microsoft Dynamics CRM server. Registering a custom workflow assembly is very similar to registering a plug-in assembly. In fact, the plugintype and pluginassembly entities are used to store information about custom workflow activities and their assemblies, respectively.

We will take a look at registering assemblies both by using the PluginRegistration tool from the CRM SDK and by extending the ProgrammingWithDynamicsCrm4.PluginDeploy tool we implemented in Chapter 5.

Now that our assembly is registered with the server, we can create a new workflow to test it. Our new workflow will be triggered by a case changing to the resolved state. It will then send an e-mail to the manager of the case’s owner, letting her know how long the case was open.

Creating the case age notifier workflow

At this point you should be able to create a test case in the Service area. After resolving it, you (or your manager if you have one set up) should receive an e-mail with the case’s age in the subject line.

This sample, although simple, demonstrates some of the flexibility available to you when extending the native workflow functionality within Microsoft Dynamics CRM. In the "CRM Workflow Attributes" section, we’ll take a look back at some of the attributes and classes we used to implement this sample and explore them in more detail.

When implementing custom activities, you will inevitably come across a workflow that has a status of "Waiting" in the workflow grids. If you open the workflow, you will see a generic error message like this:

A message such as this typically means that an exception has not been handled in your custom activity and the workflow instance has been suspended so that a system administrator can deal with it appropriately. You can use three fairly straightforward techniques to retrieve the exception information from a suspended workflow: Advanced Find, a SQL query, and a CrmService query

All these techniques are valid ways to retrieve the exception information from a workflow instance. Determining which is best suited to your situation is up to you.

As you have seen in the preceding samples, you can apply several attributes to your custom activity classes and dependency properties. Understanding these attributes is critical if you want your custom activities to work correctly the first time they are deployed. The full list of custom workflow attributes is shown in Table 6-6.

When your custom activity executes, you frequently need information about the current state of the workflow that your dependency properties cannot provide. For example, if you need to know the type of entity the current workflow is executing for, or the message that triggered the workflow, you need something more than the dependency properties. This is where the ActivityExecutionContext argument comes in. Passed in to the Execute method as an argument, ActivityExecutionContext can be used to retrieve information about the workflow or request additional services provided by the host application.

More Info

ActivityExecutionContext is a class provided by Windows Workflow Foundation that has many capabilities. For more information on the ActivityExecutionContext class, please see http://msdn.microsoft.com/en-us/library/system.workflow.componentmodel.activityexecutioncontext.aspx.

Because our workflows are going to be specifically for Microsoft Dynamics CRM, we frequently just want to get to the IWorkflowContext service, which provides access to the ICrmService and IMetadataService services as well as details about the primary entity for the workflow. Example 6-4 shows how to retrieve IWorkflowContext within the Execute method.

protected override ActivityExecutionStatus Execute(ActivityExecutionContext
    executionContext)
{
    IContextService contextService = executionContext.GetService<IContextService>();
    IWorkflowContext workflowContext = contextService.Context;

    ...

    return ActivityExecutionStatus.Closed;
}

As shown, the first step is to retrieve the IContextService from the ActivityExecutionContext and then access the IWorkflowContext from the IContextService’s Context property. IWorkflowContext exposes several methods, most of which are only used by Microsoft Dynamics CRM internally. The six methods and their descriptions are listed in Table 6-7.

Of these methods, you will likely only use CreateCrmService and CreateMetadataService. Both methods come in two flavors: one without any arguments, and one that takes a Boolean argument specifying whether the service should run as the admin user. If you use the parameterless version or pass in false to the overloaded version, you will be provided with a service that runs as the current user. By specifying true to the overloaded version, you can get a service that runs as the admin user. This allows your custom workflow activities to access data that the workflow owner may not typically have access to.

IWorkflowContext also exposes many properties. Although you may not use several of them frequently or at all, it is good to have a basic understanding of them. Table 6-8 lists the IWorkflowContext properties available to custom activities.

Although many of these properties have straightforward definitions, the image properties are worth taking a closer look at.

In Chapter 5 we discussed entity images as they pertain to plug-ins. You use entity images with plug-ins to get attribute values from an entity that would otherwise not be available. For instance, you can get attribute values on an entity that has already been deleted by registering for a pre-image in a plug-in. When registering a plug-in, you specify which images you want and which attributes should be included within it.

However, with workflows you cannot specify which images and entities to include when using the native workflow designer. The image registration information is determined by the messages that can trigger a workflow as well as which attributes are referenced within the various workflow steps.

More Info

The images and attributes to include are stored in an entity named workflowdependency. See Chapter 12 for a full explanation of this entity.

using System;
using System.IO;
using System.Reflection;
using System.Workflow.ComponentModel;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.Workflow;

namespace ProgrammingWithDynamicsCrm4.Workflow
{
    [CrmWorkflowActivity("Debug Entity Images", "Debug")]
    public class DebugEntityImagesActivity: Activity
    {
    }
}

public static DependencyProperty OutputFileNameProperty =
    DependencyProperty.Register("OutputFileName", typeof(string),
    typeof(DebugEntityImagesActivity));

[CrmInput("Ouput File Name")]
public string OutputFileName
{
    get { return (string)GetValue(OutputFileNameProperty); }
    set { SetValue(OutputFileNameProperty, value); }
}

protected override ActivityExecutionStatus Execute(
    ActivityExecutionContext executionContext)
{
    if (!String.IsNullOrEmpty(this.OutputFileName))
    {
        IContextService contextService =
            executionContext.GetService<IContextService>();
        IWorkflowContext workflowContext = contextService.Context;

        using (StreamWriter output = File.AppendText(this.OutputFileName))
        {
            output.WriteLine(DateTime.Now);

            SerializeDynamicEntity(output,
                "PrimaryEntityImage", workflowContext.PrimaryEntityImage);

            SerializeDynamicEntity(output,
                "PrimaryEntityPreImage", workflowContext.PrimaryEntityPreImage);

            SerializeDynamicEntity(output,
                "PrimaryEntityPostImage", workflowContext.PrimaryEntityPostImage);
        }
    }

    return ActivityExecutionStatus.Closed;
}

private void SerializeDynamicEntity(
    TextWriter output, string title, DynamicEntity dynamicEntity)
{
    if (dynamicEntity == null)
    {
        output.WriteLine("{0}: (null)", title);
    }
    else
    {
        output.WriteLine("{0}:", title);
        output.WriteLine("{");
        foreach (Property prop in dynamicEntity.Properties)
        {
            output.Write("    {0}: ", prop.Name);
            SerializePropertyValue(output, dynamicEntity[prop.Name]);
            output.WriteLine();
        }

        output.WriteLine("}");
    }
}

private void SerializePropertyValue(TextWriter output, object value)
{
    if (value == null)
    {
        output.Write("(null)");
    }
    else
    {
        PropertyInfo nameProperty = value.GetType().GetProperty("name");

        if (nameProperty != null && nameProperty.PropertyType == typeof(string))
        {
            output.Write("{0} ", nameProperty.GetValue(value, null));
        }

        PropertyInfo valueProperty = value.GetType().GetProperty("Value");
        if (valueProperty != null)
        {
            output.Write(valueProperty.GetValue(value, null));
        }
        else
        {
            output.Write(value);
        }
    }
}

Using the DebugEntityImagesActivity

To use the DebugEntityImagesActivity, we’ll need to create a new workflow that includes a step for our custom activity. Using the steps previously defined in this chapter, create a workflow definition named Debug Images for the account entity that runs automatically whenever an account is created. Add our custom step, Debug Entity Images, as the only step in the workflow. Update the properties for the step to specify a file where the debug information will be written. The file does not need to exist, but the Microsoft CRM Asynchronous Processing Service must have write access to the folder. By default, the service runs as the Network Service user. When you are finished, your workflow should resemble Figure 6-5.

Figure 6-5. A workflow to test the DebugEntityImagesActivity

Once you publish the workflow, create an account, specifying Test as the account name. After you save the account, the output file you specified on the custom workflow step should be updated within a few seconds. Once it is updated, you will likely see something like the following upon opening it:

7/22/2008 8:28:50 PM
PrimaryEntityImage:
{
    name: Test
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}
PrimaryEntityPreImage: (null)
PrimaryEntityPostImage:
{
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    ownerid: Corey O'Brien 237d2b4e-191d-dd11-8839-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}

Although the details will be different in your output file, you should have the exact same attributes included. Based on this output, it would appear that for the Create message, Microsoft Dynamics CRM is including a post-image and minimal attributes. It makes sense that the pre-image is null, because as we learned in Chapter 5, the Create message cannot supply a pre-image.

Let’s take a look at what happens when we handle an Update message. Unpublish your workflow and change it to also run automatically when the record attributes change. Specify Account Name and Account Number as the attributes to monitor. Once you publish the workflow, open the Test account that you created previously. Change the name to Test 2, specify an account number of IL-123456, and then save the account. Once your workflow runs, you should have a new entry at the bottom of your output file similar to the following:

7/22/2008 9:42:08 PM
PrimaryEntityImage:
{
    name: Test
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}
PrimaryEntityPreImage:
{
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    ownerid: Corey O'Brien 237d2b4e-191d-dd11-8839-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
    name: Test 2
}
PrimaryEntityPostImage:
{
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    ownerid: Corey O'Brien 237d2b4e-191d-dd11-8839-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}

Now we have a pre-image, but why isn’t the accountnumber attribute included in any of the images? The accountnumber attribute isn’t included because Microsoft Dynamics CRM examines the workflow steps to determine which attributes are accessed by the workflow. Because it does not see a reference to accountnumber, it does not create a workflow dependency to include it in the image.

To prove this point, let’s edit the workflow one more time and reference accountnumber. Unpublish the workflow and add a Check Condition step after the existing Debug Entity Images step. Specify the condition to simply check that the account number contains data. The condition page should look like Table 6-6 when you are finished.

Figure 6-6. Referencing the account number attribute

Save the condition and then publish the workflow. Notice that we did not specify a step to execute if the condition evaluates to true. Next, edit the Test 2 account and change the account number to MI-654321. After you save the account and the workflow runs, open your output file and examine the results. You should see a new entry at the bottom similar to the following:

7/22/2008 9:56:56 PM
PrimaryEntityImage:
{
    name: Test 2
    accountnumber: MI-654321
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}
PrimaryEntityPreImage:
{
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    ownerid: Corey O'Brien 237d2b4e-191d-dd11-8839-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
    name: Test 2
    accountnumber: IL-123456
}
PrimaryEntityPostImage:
{
    accountid: c6a6b6ab-5658-dd11-b751-0019b9f8f548
    ownerid: Corey O'Brien 237d2b4e-191d-dd11-8839-0019b9f8f548
    owningbusinessunit:  23da3575-181d-dd11-8839-0019b9f8f548
}

Now we can see that the accountnumber attribute is included in the images even though we didn’t do anything more than add a step to see if it contained data. By referencing a property in a condition or as a dynamic value within a workflow, you can guarantee it will be included in the entity images and therefore available to your custom activities. In Chapter 12 we will examine setting up your own workflows and workflow dependencies from scratch without the Microsoft Dynamics CRM workflow designer. If, however, you prefer to design your workflows natively, you can use the DebugEntityImagesActivity to discover how Microsoft Dynamics CRM registers for images based on the message and workflow steps defined.

As powerful and flexible as the Microsoft Dynamics CRM workflow designer is, it does have a few limitations. For example, only the following preset list of property types can be assigned values in the designer:

In addition, although you can create composite activities—activities that can contain one or more child activities—the designer does not allow you to add child activities to them. For example, if you want to make a custom activity that continues to execute a list of child activities until an input parameter evaluates to true, you have to define the list of child activities at compile time, because the designer does not allow you to add child steps within a custom activity.