While you may typically depend on a workflow designer to generate the XAML for you, we recommend that you should take a look at a sample XAML file to gain a basic understanding of the syntax. Example 12-4 demonstrates what a simple sequential workflow might look like in XAML.

<SequentialWorkflowActivity
    x:Class="SampleWorkflowProject.SampleWorkflow"
    x:Name="SampleWorkflow"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/workflow">

     <DelayActivity TimeoutDuration="00:01:00" x:Name="DelayOneMinute" />

</SequentialWorkflowActivity>

This sample is not very useful other than serving as a demonstration of the XAML syntax. It simply waits for one minute and then exits.

In this case, both of the element names (SequentialWorkflowActivity and DelayActivity) map to classes in the .NET Framework. The .NET namespace is determined from the element’s XML namespace. In this case the XML namespace http://schemas.microsoft.com/winfx/2006/xaml/workflow is mapped to the System.Workflow.Activities .NET namespace. This mapping comes from the application of the XmlnsdefinitionAttribute within the System.Workflow. Activities assembly.

The attributes with the x: prefix denote special XAML-specific properties that the XAML parser uses. The x:Name attribute assigns a name to the element that can be used to reference the elements later during execution. The x:Class attribute can only be assigned to the root element, and is used to define a class for that element that derives from the element’s natural type. This is used to create code-behind files similar to ASP.NET pages.

The TimeoutDuration attribute maps to a .NET property with the same name of type TimeSpan on the DelayActivity. Various type converters are available to the XAML parser that can convert string values into complex types such as TimeSpan. Properties can also be contained in child elements prefixed with the parent element’s name. For example, if you want to set a value to the Description property on the DelayActivity, you can add a Description attribute to the DelayActivity element, or you can assign a value by creating a child element inside the DelayActivity element shown by the following code:

<DelayActivity.Description>
    This is a one minute delay.
</DelayActivity.Description>

XAML is a powerful tool with an intuitive syntax that has many books and Web sites dedicated to it, but explaining the full details of XAML is outside the scope of this book. For more information on XAML, you can read about it at http://msdn.microsoft.com/en-us/library/ms747122.aspx. The topics in that section of MSDN specifically talk about XAML and its use in Windows Presentation Foundation (WPF), but the XAML syntax descriptions are excellent and still apply to WF.

Microsoft Dynamics CRM uses XAML behind the scenes during the publication of workflows defined within the native workflow designer. The XAML that describes the flow of activities is stored in the activities attribute in a workflow entity and the XAML that contains the policy rules are stored in the policy attribute (more on policy rules in a little bit).

The more interesting part is that Microsoft Dynamics CRM allows us to create workflow definitions and specify our own values for activities and rules.

The following benefits apply when you use XAML-based workflow definitions:

In this section, we’ll create a declarative workflow in Visual Studio .NET that creates three follow-up tasks for a newly created lead. Each follow-up task is due a week apart. We use a simple loop to accomplish this. Looping is something that can only be accomplished in the native workflow designer by recursively calling the same workflow definition as a child process. By using a simple activity to achieve the same thing, we can create a more maintainable workflow that has less overhead.

Because we will only be uploading the XAML to the Microsoft Dynamics CRM server, we will not need to compile the workflow into an assembly. But in order to take advantage of the workflow designer in Visual Studio .NET, we’ll still create a workflow project.

Creating a workflow project

Now that we set up our project, we can add our workflow definition. Because there is not a CRM-specific workflow template in Visual Studio, we will tweak the files produced by the default WF template after we add them.

Adding a workflow definition

You now have a workflow definition created that you can start to edit in the Visual Studio .NET workflow designer. Before we begin, though, let’s add the CRM-specific activities to the Toolbox so that you can easily access them.

Adding the Microsoft Dynamics CRM assemblies to the Toolbox

You should now see the Toolbox populated with the familiar Microsoft Dynamics CRM workflow activities:

Now we are ready to start designing our workflow definition. One of the first things you should think about when starting on a new workflow definition is which local parameters you need. It is important to have these local parameters defined before you begin writing the workflow policies that reference them because the policy editor is not forgiving of invalid syntax. In our case we need two local parameters to serve as temporary storage for the task entities we will create and for the count of tasks we have created. We can use the existing PrimaryEntity property from the base CrmWorkflow class to hold the lead image we receive from CRM.

Ultimately these parameters will be defined using workflow dependencies, but to use the Visual Studio .NET workflow designer without errors, we need to define them in the code-behind file.

Important

You should not put anything in the code-behind file that cannot be emulated with workflow dependencies. The C# file is not uploaded to the CRM server when you deploy the XAML, so properties in the code-behind file need to be re-created using workflow dependencies.

Defining local parameters on the workflow

Now with our local parameters set up, we can begin designing our workflow. For now we will just lay out the activities and assign them names, and then come back and fill out the additional rules that control the local parameters.

Designing the LeadFollowUpWorkflow

The following image shows what your workflow should look like now:

The next step is to go through and tie all the various activities together through the local parameters. We will make heavy use of the policy activities to update the local parameters. PolicyActivity references declarative rules located within a separate rules file to execute statements when a condition evaluates to true. The rules file is also written in XAML and can perform simple programmatic statements without the need for a compiled assembly. Fortunately for us, the Microsoft Visual Studio .NET workflow designer automatically creates and maintains the rules file as we type in simple code statements.

Adding rules to the workflow definition

At this point, we completely defined our workflow and the only thing that remains is deploying it to the CRM server. Fortunately the ProgrammingWithDynamicsCrm4.WorkflowManager tool can help with this process. The tool does, however, require us to set up an XML file to describe how the workflow should be deployed. Add a new XML file to your project named LeadFollowUpWorkflow.config. Type in the configuration text as it is shown in Example 12-5 into the newly created file.

<?xml version="1.0" encoding="utf-8" ?>
<WorkflowConfiguration
  PrimaryEntity="lead"
  Name="Lead Follow Up">

  <Dependencies>
    <SdkAssociationDependency MessageName="Create" />
    <PrimaryEntityImageDependency
      ParameterName="PrimaryEntity" EntityAttributes="leadid" />
    <LocalParameterDependency
      ParameterName="TaskEntity" ParameterType="Microsoft.Crm.Sdk.DynamicEntity"/>
    <LocalParameterDependency
      ParameterName="TaskCount" ParameterType="System.Int32"/>
  </Dependencies>

</WorkflowConfiguration>

Here we define the name and primaryentity attributes for our workflow instance as well as four workflow dependencies. Notice that the two properties we created (TaskEntity and TaskCount) are represented here by the LocalParameterDependency elements. Programming-WithDynamicsCrm4.WorkflowManager looks for a .xoml and .rules file with the same name as the configuration file to assign the activities and rules attributes as well. If you have files that do not match that pattern for some reason, two attributes on the WorkflowConfiguration element, ActivitiesFile and RulesFile, allow you to specify the appropriate files.

Tip

If you edit your configuration file in Visual Studio .NET you can include a reference to the schema file to get IntelliSense while working with the XML. To include the schema information, modify the opening workflowConfiguration element to match the following code:

<WorkflowConfiguration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="workflow-config.xsd"
  PrimaryEntity="lead"
  Name="Lead Follow Up">

Copy the workflow-config.xsd file from the ProgrammingWithDynamicsCrm4.WorkflowManager folder into the folder that contains your workflow configuration file. Now when you start a new element or attribute you are prompted with possible values, as shown here:

Deploying the workflow

Now your declarative workflow is published and deployed. You can create a new lead in Microsoft Dynamics CRM, and after a few seconds the lead should have three tasks associated with it, each with due dates one week apart.

Now that we have our first declarative workflow up and running, it is important to understand what is involved in deploying a declarative workflow. In this section we’ll examine the code behind the import functionality within the ProgrammingWithDynamicsCrm4.WorkflowManager tool. Example 12-6 shows the ImportWorkflow method of the WorkflowLogic class.

public void ImportWorkflow(string configurationFileName)
{
    WorkflowConfiguration config =
        WorkflowConfiguration.Load(configurationFileName);

    workflow workflow = config.ToEntity();

    Guid workflowId = this.CrmService.Create(workflow);
    foreach (WorkflowDependency dependencyConfig in config.Dependencies)
    {
        workflowdependency dependency = dependencyConfig.ToEntity(workflowId);

        if (dependency.sdkmessageid != null)
        {
            dependency.sdkmessageid.Value =
                GetSdkMessageId(dependency.sdkmessageid.name);
        }

        this.CrmService.Create(dependency);
    }
}

The method first loads the workflow configuration from the specified file and then asks the configuration class to generate a workflow instance, which it passes along to the CrmService Create method. Next, the method loops through the Dependencies property on the WorkflowConfiguration and gets a workflowdependency instance for each of them. If a value is provided for the sdkmessageid property, the actual ID is looked up by the GetSdkMessageId method based on the name of the SDK message. This is done so that the end user editing the configuration file does not need to know the message ID and can just specify the name. Finally, each workflowdependency is passed in to the CrmService Create method as well.

Let’s continue by taking a look at the WorkflowConfiguration class load method, as shown in Example 12-7.

public class WorkflowConfiguration
{
    [XmlAttribute]
    public string Name { get; set; }

    [XmlAttribute]
    public string Description { get; set; }

    [XmlAttribute]
    public string PrimaryEntity { get; set; }

    [XmlAttribute]
    public string ActivitiesFile { get; set; }

    [XmlAttribute]
    public string RulesFile { get; set; }

    [XmlArrayItem(typeof(AttributeDefinitionDependency))]
    [XmlArrayItem(typeof(CustomEntityDefinitionDependency))]
    [XmlArrayItem(typeof(SdkAssociationDependency))]
    [XmlArrayItem(typeof(PrimaryEntityImageDependency))]
    [XmlArrayItem(typeof(PrimaryEntityPreImageDependency))]
    [XmlArrayItem(typeof(PrimaryEntityPostImageDependency))]
    [XmlArrayItem(typeof(RelatedEntityImageDependency))]
    [XmlArrayItem(typeof(LocalParameterDependency))]
    public WorkflowDependency[] Dependencies { get; set; }

    public static WorkflowConfiguration Load(string configurationFileName)
    {
        ...
    }

    public workflow ToEntity()
    {
        ...
    }


    public void Save(string configFileName)
    {
        ...
    }
}

The WorkflowConfiguration class mainly represents the state of a workflow configuration, but it does have a few methods that help in the loading, saving, and conversion to a workflow instance. We’ll take a look at these methods shortly, but first notice the XmlAttribute and XmlArrayItem attributes assigned to the property definitions in WorkflowConfiguration. These attributes are used to aid serialization of the class to and from XML with the aid of the System.Xml.Serialization.XmlSerializer class. XmlAttribute tells XmlSerializer to use an xml attribute instead of a child element to contain the property value. XmlArrayItem is used to list the acceptable types that can be included in an array property. Example 12-8 demonstrates how simple it is to load an XML file into an instance of WorkflowConfiguration when using XmlSerializer.

public static WorkflowConfiguration Load(string configurationFileName)
{
    XmlSerializer xmlSerializer = new XmlSerializer(typeof(WorkflowConfiguration));
    WorkflowConfiguration config;
    using(Stream file = File.OpenRead(configurationFileName))
    {
        config = (WorkflowConfiguration)xmlSerializer.Deserialize(file);
    }

    if (String.IsNullOrEmpty(config.PrimaryEntity))
    {
        throw new InvalidOperationException(
            "PrimaryEntity is a required attribute.");
    }

    if (String.IsNullOrEmpty(config.ActivitiesFile))
    {
        config.ActivitiesFile = Path.ChangeExtension(
            configurationFileName, ".xoml");
    }

    if (!Path.IsPathRooted(config.ActivitiesFile))
    {
        config.ActivitiesFile = Path.Combine(
            Path.GetDirectoryName(configurationFileName),
            config.ActivitiesFile);
    }

    if (String.IsNullOrEmpty(config.RulesFile))
    {
        string rulesFile = Path.ChangeExtension(config.ActivitiesFile, ".rules");
        if (File.Exists(rulesFile))
        {
            config.RulesFile = rulesFile;
        }
    }

    if (!String.IsNullOrEmpty(config.RulesFile) &&
           !Path.IsPathRooted(config.RulesFile))
    {
        config.RulesFile = Path.Combine(
            Path.GetDirectoryName(configurationFileName),
              config.RulesFile);
    }


    if (String.IsNullOrEmpty(config.Name))
    {
        config.Name = Path.GetFileNameWithoutExtension(config.ActivitiesFile);
    }

    return config;
}

The first six lines of the method de-serialize the XML file into a WorkflowConfiguration instance. Next the method confirms that a primary entity value was specified and then determines intelligent defaults for any other values that were omitted.

The ToEntity method is responsible for converting the WorkflowConfiguration into a workflow instance that can be passed along to CrmService’s Create method. After the Load method has set up all of the properties, performing this conversion is straightforward, as shown in Example 12-9.

public workflow ToEntity()
{
    workflow entity = new workflow();
    entity.name = this.Name;

    entity.type = new Picklist(WorkflowType.Definition);
    entity.primaryentity = new EntityNameReference(this.PrimaryEntity);
    entity.activities = File.ReadAllText(this.ActivitiesFile);

    if (!String.IsNullOrEmpty(this.RulesFile))
    {
        entity.rules = File.ReadAllText(this.RulesFile);
    }

    return entity;
}

The last method in WorkflowConfiguration is actually used during the workflow export process, and we examine it later in the chapter.

Next let’s look at the dependencies and how they are imported. If you recall from Example 12-6, the ImportWorkflow method loops through each of the WorkflowDependency instances in the WorkflowConfiguration.Dependencies property and calls ToEntity on each of them to generate a workflowdependency instance.

WorkflowDependency is an abstract base class that has no properties of its own. The ToEntity method it implements is only provided as a helper for the inherited classes. Example 12-10 shows the simple ToEntity implementation on WorkflowDependency.

public virtual workflowdependency ToEntity(Guid workflowId)
{
    workflowdependency entity = new workflowdependency();
    entity.workflowid = new Lookup("workflow", workflowId);
    return entity;
}

If you refer back to Example 12-7 you can see eight applications of the XmlArrayItem attribute on the WorkflowConfiguration.Dependencies property. Each application of this attribute specifies a class that can be entered into the XML-based configuration file and ultimately passed in as an item to the Dependencies property.

You can specify the following eight valid types for the Dependencies property:

You have probably noticed that these dependencies correspond very closely to the values found on WorkflowDependencyType as shown in Table 12-2. This is because each of these classes is used to specify one of the different dependency types in the workflow configuration file. Let’s take a brief look at each of the individual classes to get a better understanding of how the dependencies are mapped to their CRM counterparts.

The first of these classes, AttributedefinitionDependency, is used when you want to keep a custom attribute from being deleted when you have a workflow that depends on it. The full source for AttributedefinitionDependency is shown in Example 12-11.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class AttributeDefinitionDependency: WorkflowDependency
    {
        public AttributeDefinitionDependency()
        {

        }

        public AttributeDefinitionDependency(workflowdependency dependency)
        {
            this.DependentEntityName = dependency.dependententityname;
            this.DependentAttributeName = dependency.dependentattributename;
        }

        [XmlAttribute]
        public string DependentEntityName { get; set; }

        [XmlAttribute]
        public string DependentAttributeName { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new Picklist(WorkflowDependencyType.AttributeDefinition);
            entity.dependententityname = this.DependentEntityName;
            entity.dependentattributename = this.DependentAttributeName;
            return entity;
        }
    }
}

This class is not very complex. During workflow import only the parameterless constructor is used. The other constructor, which accepts a workflowdependency, is used during workflow export. The two properties are both tagged with XmlAttribute again to ensure that they are both serialized as attributes instead of child elements.

The method of most interest, however, is ToEntity, which calls the base implementation to create an instance of workflowdependency and assign the proper workflowid. It then proceeds to set the type attribute to WorkflowDependencyType.Attributedefinition. The remaining attribute assignments, dependententityname and dependentattributename both have one-to-one mappings with properties on AttributedefinitionDependency.

The next workflow dependency configuration class is CustomEntitydefinitionDependency, which you use when you want to keep users from deleting custom entities that your workflow depends on. Example 12-12 shows CustomEntityDefinitionDependency in its entirety.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class CustomEntityDefinitionDependency: WorkflowDependency
    {
        public CustomEntityDefinitionDependency()
        {

        }

        public CustomEntityDefinitionDependency(workflowdependency dependency)
        {
            this.CustomEntityName = dependency.customentityname;
        }

        [XmlAttribute]
        public string CustomEntityName { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type =
                new Picklist(WorkflowDependencyType.CustomEntityDefinition);
            entity.customentityname = this.CustomEntityName;
            return entity;
        }
    }
}

CustomEntityDefinitionDependency follows the same pattern as AttributeDefinitionDependency, but assigns a different value to the type attribute and then only populates the customentityname attribute.

Both CustomEntityDefinitionDependency and AttributeDefinitionDependency define workflow dependencies on the CRM metadata. You can use these to verify that the metadata is in an acceptable state for your workflow to execute, but they do not modify the workflow definition or change when it executes. Because of this, you only need to apply these dependencies to prevent a user from deleting custom entities and attributes that your workflow depends on. If you do not apply these dependencies, and a custom entity or attribute that your workflow requires is deleted, Microsoft Dynamics CRM 4.0 will raise an error and put the workflow instance in a suspended state when it tries to access the unavailable attribute or entity.

Next we take a look at SdkAssociationDependency. You can use this configuration entry to specify one or more system messages that should automatically trigger workflow execution. Example 12-13 shows the full source code for SdkAssociationDependency.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class SdkAssociationDependency : WorkflowDependency
    {
        public SdkAssociationDependency()
        {
        }

        public SdkAssociationDependency(workflowdependency dependency)
        {
            if (dependency.sdkmessageid != null)
            {
                this.MessageName = dependency.sdkmessageid.name;
            }
            this.EntityAttributes = dependency.entityattributes;
        }

        [XmlAttribute]
        public string MessageName { get; set; }

        [XmlAttribute]
        public string EntityAttributes { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);

            entity.type = new Picklist(WorkflowDependencyType.SdkAssociation);
            entity.sdkmessageid = new Lookup("message", Guid.Empty);
            entity.sdkmessageid.name = this.MessageName;
            entity.entityattributes = this.EntityAttributes;

            return entity;
        }
    }
}

SdkAssociationDependency is provided with a message name, but ultimately needs to map the human-readable name to the internal CRM SDK message ID. It creates the Lookup and populates the name property, but assumes that the caller will look up the ID if needed. SdkAssociationDependency also can assign a value to the entityattributes attribute. This is used for the Update message so that the workflow is only executed if the specified attributes are modified.

Next up is the LocalParameterDependency class, which you can use to add local parameters to the workflow definition. We used these in our first declarative workflow sample to create the TaskEntity and TaskCount parameters. Example 12-14 shows the source code for the LocalParameterDependency class.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class LocalParameterDependency : WorkflowDependency
    {
        public LocalParameterDependency()
        {

        }

        public LocalParameterDependency(workflowdependency dependency)
        {
            this.ParameterName = dependency.parametername;
            this.ParameterType = dependency.parametertype;
        }

        [XmlAttribute]
        public string ParameterName { get; set; }

        [XmlAttribute]
        public string ParameterType { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new Picklist(WorkflowDependencyType.LocalParameter);
            entity.parametername = this.ParameterName;
            entity.parametertype = this.ParameterType;
            return entity;
        }
    }
}

The only unique aspect of LocalParameterDependency is the ParameterType property, which you use to specify the .NET type for the parameter. The name should include the namespace, but exclude the assembly information. You can find the full list of supported types in the CRM SDK under the topic "Supported Types for Workflow."

The remaining workflow dependency configuration classes are similar to each other because they are all related to entity images of one form or another. Therefore they have an additional abstract class they inherit from that implements the common functionality they share. EntityImageDependency is the base class that provides population of the parametername and entityattributes attributes on the workflowdependency. This class is shown in Example 12-15.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.SdkTypeProxy;
namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public abstract class EntityImageDependency : WorkflowDependency
    {
        public EntityImageDependency()
        {
        }

        public EntityImageDependency(workflowdependency dependency)
        {
            this.ParameterName = dependency.parametername;
            this.EntityAttributes = dependency.entityattributes;
        }

        [XmlAttribute]
        public string ParameterName { get; set; }

        [XmlAttribute]
        public string EntityAttributes { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.parametername = this.ParameterName;
            entity.entityattributes = this.EntityAttributes;
            return entity;
        }
    }
}

All of the entity image dependencies need to specify a local parameter name that will be populated with the entity image. This parameter is always of type DynamicEntity. The attributes that should be included in the image are also handled by the EntityImageDependency base class.

The first and most commonly used entity image dependency is PrimaryEntityImage-Dependency. By adding this dependency to your workflow you can request which attributes from the workflow’s primary entity should be populated on the CrmWorkflow’s PrimaryEntity property. You’ll frequently want to access attributes off of the primary entity, and your workflow can run faster if you register a dependency for those attributes instead of retrieving them during execution yourself. Example 12-16 shows the full source code for PrimaryEntityImageDependency.

using System;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class PrimaryEntityImageDependency : EntityImageDependency
    {
        public PrimaryEntityImageDependency()
        {

        }

        public PrimaryEntityImageDependency(workflowdependency dependency)
            : base(dependency)
        {

        }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new Picklist(WorkflowDependencyType.PrimaryEntityImage);
            return entity;
        }
    }
}

PrimaryEntityImageDependency has almost everything done by its base class. It is only responsible for setting the appropriate WorkflowDependencyType value.

The next two dependency configuration classes are very similar to PrimaryEntityImage-Dependency. You can use PrimaryEntityPreImageDependency and PrimaryEntityPostImage-Dependency to request images of the primary entity as it existed before the core operation is performed and after it is completed. Because these two classes are so similar to each other and to the previous example, they are both included in Example 12-17.

using System;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class PrimaryEntityPreImageDependency : EntityImageDependency
    {
        public PrimaryEntityPreImageDependency()
        {

        }

        public PrimaryEntityPreImageDependency(workflowdependency dependency)
            : base(dependency)
        {

        }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new
                Picklist(WorkflowDependencyType.PrimaryEntityPreImage);
            return entity;
        }
    }

    public class PrimaryEntityPostImageDependency : EntityImageDependency
    {
        public PrimaryEntityPostImageDependency()
        {

        }

        public PrimaryEntityPostImageDependency(workflowdependency dependency)
            : base(dependency)
        {

        }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new
                Picklist(WorkflowDependencyType.PrimaryEntityPostImage);
            return entity;
        }
    }
}

The last of the entity image dependency classes is slightly different. You use RelatedEntityIma geDependency to specify that your workflow would like an image of an entity directly related to the workflow’s primary entity. This is useful when you need access to the attributes on the related entity. For example, if you want to generate an e-mail message when a case is open too long, you can use a RelatedEntityImageDependency in your configuration file to get the e-mail address of the case’s owner. Example 12-18 shows the full source code for the RelatedEntityImageDependency class.

using System;
using System.Xml.Serialization;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace ProgrammingWithDynamicsCrm4.WorkflowManager.Configuration
{
    public class RelatedEntityImageDependency : EntityImageDependency
    {
        public RelatedEntityImageDependency()
        {

        }

        public RelatedEntityImageDependency(workflowdependency dependency)
            : base(dependency)
        {
            this.RelatedEntityName = dependency.relatedentityname;
            this.RelatedAttributeName = dependency.relatedattributename;
        }

        [XmlAttribute]
        public string RelatedEntityName { get; set; }

        [XmlAttribute]
        public string RelatedAttributeName { get; set; }

        public override workflowdependency ToEntity(Guid workflowId)
        {
            workflowdependency entity = base.ToEntity(workflowId);
            entity.type = new Picklist(WorkflowDependencyType.RelatedEntityImage);
            entity.relatedentityname = this.RelatedEntityName;
            entity.relatedattributename = this.RelatedAttributeName;
            return entity;
        }
    }
}

RelatedEntityImageDependency has two additional attributes beyond the other EntityImageDependency-derived classes. RelatedAttributeName is the name of the Lookup attribute on the primary entity that references the related entity. RelatedEntityName is the name of the related entity type. The name of the local parameter that is populated—as well as which attributes are included in the image—are handled by the base EntityImageDependency class.

Workflow dependencies are fairly advanced and not well-documented in the CRM SDK. Although the approach used in ProgrammingWithDynamicsCrm4.WorkflowManager uses many classes to accomplish workflow dependency management, none of them is very complicated and the end result is a very user-friendly configuration file. Now that you have an understanding of declarative workflow deployment, you can use the concepts described in this section to implement your own deployment tools that may be more streamlined for your environment.

You may find yourself trying to emulate a workflow that you created in the native CRM workflow designer in a declarative workflow. The natively designed workflows still generate XAML behind the scenes during publication, and you can retrieve the XAML and inspect it when you need some inspiration for your own declarative workflows.

ProgrammingWithDynamicsCrm4.WorkflowManager has a feature that allows workflows to be exported as XAML even if they were originally created in the native designer. We’ll demonstrate this by exporting the Dependency Test workflow created earlier in this chapter and adding it to the sample workflow project we created.

Adding a natively designed workflow to a declarative workflow project

The code that allows ProgrammingWithDynamicsCrm4.WorkflowManager to export the XAML behind CRM’s workflows uses all of the same classes that we reviewed during our examination of the import process. However, a few unique methods are worth taking a look at.

The main method, ExportWorkflow, is found in the WorkflowLogic class. Example 12-19 displays the contents of this method.

public void ExportWorkflow(Guid workflowId, string exportFolder)
{
    ColumnSet cols = new ColumnSet();
    cols.AddColumns(
        "name",
        "description",
        "primaryentity",
        "activities",
        "rules",
        "plugintypeid");

    workflow workflow = (workflow)this.CrmService.Retrieve(
        "workflow", workflowId, cols);

    String configFileName = Path.Combine(exportFolder, String.Concat(
        Regex.Replace(workflow.name, "[^a-zA-Z0-9]", ""),
        ".config"));

    WorkflowConfiguration config = new WorkflowConfiguration();
    config.Name = workflow.name;
    config.Description = workflow.description;
    config.PrimaryEntity = workflow.primaryentity.Value;

    File.WriteAllText(
        Path.ChangeExtension(configFileName, ".xoml"), workflow.activities,
        Encoding.Unicode);

    if (!String.IsNullOrEmpty(workflow.rules))
    {
        File.WriteAllText(
            Path.ChangeExtension(configFileName, ".rules"), workflow.rules,
            Encoding.Unicode);
    }

    IEnumerable<workflowdependency> dependencies =
        this.RetrieveWorkflowDependencies(workflowId,
        "type",
        "parametername",
        "parametertype",
        "relatedentityname",
        "relatedattributename",
        "sdkmessageid",
        "entityattributes",
        "customentityname",
        "dependententityname",
        "dependentattributename");

   List<WorkflowDependency> configDependencies = new List<WorkflowDependency>();
   foreach (workflowdependency dependency in dependencies)
   {
         WorkflowDependency configDependency =
         WorkflowDependency.FromEntity(dependency);

      if (configDependency != null)
      {
         configDependencies.Add(configDependency);
      }
   }

   config.Dependencies = configDependencies.ToArray();
   config.Save(configFileName);
}

ExportWorkflow starts by retrieving the workflow with all of the required attributes. It then strips out all non-alphanumeric characters from the workflow name to use as a base name for the three files that will be created. Next, the method creates an instance of WorkflowConfiguration and populates its properties using values from the retrieved workflow. After this, the activities (.xoml) and rules files are written from the appropriate attributes on the workflow.

The next section of ExportWorkflow retrieves the Workflowdependency entities associated with the workflow and uses the static WorkflowDependency FromEntity method to convert them into their WorkflowDependency-derived counterparts. All of these dependencies are passed in to the original WorkflowConfiguration object and the Save method is called, which is responsible for generating the .config file.

The Save method is quite simple, thanks to the XmlSerializer class. Example 12-20 shows the Save method using the XmlSerializer to generate an XML file based on a WorkflowConfiguration instance.

public void Save(string configFileName)
{
    XmlSerializer xmlSerializer = new XmlSerializer(typeof(WorkflowConfiguration));
    using (Stream file = File.Create(configFileName))
    {
        xmlSerializer.Serialize(file, this);
    }
}

The WorkflowDependency FromEntity method is a straightforward class factory that creates the appropriate instance of a WorkflowDependency-derived class. Example 12-21 demonstrates how this is accomplished.

public static WorkflowDependency FromEntity(workflowdependency dependency) 
{

    switch (dependency.type.Value)
    {
        case WorkflowDependencyType.SdkAssociation:
            return new SdkAssociationDependency(dependency);

        case WorkflowDependencyType.PrimaryEntityImage:
            return new PrimaryEntityImageDependency(dependency);

        case WorkflowDependencyType.PrimaryEntityPreImage:
            return new PrimaryEntityPreImageDependency(dependency);

        case WorkflowDependencyType.PrimaryEntityPostImage:
            return new PrimaryEntityPostImageDependency(dependency);

        case WorkflowDependencyType.RelatedEntityImage:
            return new RelatedEntityImageDependency(dependency);

        case WorkflowDependencyType.LocalParameter:
            return new LocalParameterDependency(dependency);

        case WorkflowDependencyType.CustomEntityDefinition:
            return new CustomEntityDefinitionDependency(dependency);

        case WorkflowDependencyType.AttributeDefinition:
            return new AttributeDefinitionDependency(dependency);

        default:
            return null;
    }
}

FromEntity uses the type attribute off the passed-in workflowdependency to determine which derived class to create. It uses the overloaded version of the constructor that takes a workflowdependency as an argument so that the derived class can populate its properties appropriately.

If at any point you need inspiration regarding how to re-create something in a declarative workflow that you know how to do in CRM’s native workflow designer, you can use the export functionality in ProgrammingWithDynamicsCrm4.WorkflowManager to export the workflow and then inspect the dependencies and declarative workflow definition generated by CRM.