SharePoint Associating a Workflow to a list

Continuing from my last post, one thing that you also may want to do when programmatically creating a list is associating a workflow with a given configuration (e.g. Approval workflow when a new item is created in a document library).
In the SharePoint interface we can do this association very easily but if you want to do it using the object model there are a few steps that you should have into consideration.

First what we need to create is a SPWorkflowAssociation more specifically SPWorkflowAssociation.CreateListAssociation. For this we need to give information like:

  • Workflow template – Template to use for the workflow (e.g. Approval);
  • Workflow Title – Name of the workflow;
  • Workflow task list – Name of the workflow task list (should be based on the Tasks list template);
  • Workflow history list – Name of the workflow history list (should be based on the Workflow History list template).

After creating the SPWorkflowAssociation we can set general workflow parameters that are nothing more than configurations available in all workflow templates:

  • AllowManual – Allow manual start of the workflow;
  • AutoStartCreate – Auto start the workflow on item creation;
  • AutoStartChange – Auto start the workflow on item change;
  • AssociationData – Association data to be passed to the workflow instance.

The key parameter here is the AssociationData that contains workflow template specific configurations to be passed to the corresponding workflow instances. For example referring to the out-of-box Approval workflow, its association data is something like this (in XML because the Approval workflow uses an InfoPath form for its configuration page):

<my:myFields xml:lang="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xmlns:my="http://schemas.microsoft.com/office/infopath/2003/myXSD">

    <my:Reviewers>
        <my:Person>
            <my:DisplayName>Administrator</my:DisplayName>
            <my:AccountId>Administrator</my:AccountId>
            <my:AccountType>User</my:AccountType>
        </my:Person>
    </my:Reviewers>

    <my:CC></my:CC>
    <my:DueDate xsi:nil="true"></my:DueDate>
    <my:Description xsi:nil="true"></my:Description>
    <my:Title></my:Title>
    <my:DefaultTaskType>1</my:DefaultTaskType>
    <my:CreateTasksInSerial>true</my:CreateTasksInSerial>
    <my:AllowDelegation>false</my:AllowDelegation>
    <my:AllowChangeRequests>true</my:AllowChangeRequests>
    <my:StopOnAnyReject xsi:nil="true"></my:StopOnAnyReject>
    <my:WantedTasks xsi:nil="true"></my:WantedTasks>
    <my:SetMetadataOnSuccess>false</my:SetMetadataOnSuccess>
    <my:MetadataSuccessField></my:MetadataSuccessField>
    <my:MetadataSuccessValue></my:MetadataSuccessValue>
    <my:ApproveWhenComplete>false</my:ApproveWhenComplete>
    <my:TimePerTaskVal xsi:nil="true"></my:TimePerTaskVal>
    <my:TimePerTaskType xsi:nil="true"></my:TimePerTaskType>
    <my:Voting>false</my:Voting>
    <my:MetadataTriggerField></my:MetadataTriggerField>
    <my:MetadataTriggerValue></my:MetadataTriggerValue>
    <my:InitLock>true</my:InitLock>
    <my:MetadataStop>false</my:MetadataStop>
    <my:ItemChangeStop>false</my:ItemChangeStop>
    <my:GroupTasks>true</my:GroupTasks>
</my:myFields> 

As you can see this association data contains the rest of the configuration parameters regarding the workflow template and in the case of the Approval workflow it contains something as important as the Approvers list (Reviewers).

With this you have all the information that is needed to correctly configure and associate an workflow to a list. Just don’t forget in the end to do something like SPList.AddWorkflowAssociation(SPWorkflowAssociation).

I leave you here an example method to accomplish what was described.

public SPWorkflowAssociation AddListWorkflowAssociation(SPWeb parentWeb, SPList parentList, String title, String workflowTemplateName, String workflowTaskListName, String workflowHistoryListName,Boolean workflowAllowManualStart, Boolean workflowAutoStartOnCreate, Boolean workflowAutoStartOnChange, String workflowAssociationData)
{
    // Search for workflow template in site
    foreach (SPWorkflowTemplate workflowTemplate in parentWeb.WorkflowTemplates)
    {
        if (workflowTemplate.Name == workflowTemplateName)
        { // Found

          // Check is task and history lists already exist
          SPList taskList;
          SPList historyList;
          try
          {
              taskList = parentWeb.Lists[workflowTaskListName];
          }
          catch (System.ArgumentException)
          { // Does not exist in site. Add
            taskList = SPHelper.AddList(parentWeb, workflowTaskListName, "Task list for workflow.", "Tasks", false);
          }

          try
          {
              historyList = parentWeb.Lists[workflowHistoryListName];
          }
          catch (System.ArgumentException)
          { // Does not exist in site. Add
            historyList = SPHelper.AddList(parentWeb, workflowHistoryListName, "History list for workflow.", "Workflow History", false);
          }

          // Create workflow list association
          SPWorkflowAssociation workflowAssociation = SPWorkflowAssociation.CreateListAssociation(workflowTemplate, title, taskList, historyList);

          // Set workflow parameters
          workflowAssociation.AllowManual = workflowAllowManualStart;
          workflowAssociation.AutoStartCreate = workflowAutoStartOnCreate;
          workflowAssociation.AutoStartChange = workflowAutoStartOnChange;
          workflowAssociation.AssociationData = workflowAssociationData;

          // Add workflow to list
          workflowAssociation = parentList.AddWorkflowAssociation(workflowAssociation);
          workflowAssociation.Enabled = true;

          // Return workflow object
          return workflowAssociation;
       }
    }

    // Error if reach here
    return null;

}