Workflow Kit: Implementing Custom Actions

Date: 11.01.2012

Within a MatchPoint Workflow Kit configuration file you can select from a number of 'action' config elements. Actions will be processed (depending on your configuration) either as EntryActions - when your workflow item enters a new workflow state. Or they are executed during the transition between two states.

You can use these workflow actions for defining the functionality of your workflow, e.g. to send an email to the next responsible user or to create a task item for the next workflow step. The following actions are available:

• Copy / delete file
• Create / delete / modify list item
• Create task / web
• Set field / permissions / tags / variable
• Send mail
• Evaluate expression (allows executing MatchPoint expressions within a workflow action)
• For each (allows specifying actions that will be executed for each element within an array)

In case the standard actions are not sufficient for your application scenario, you can implement additional workflow actions. The general scenario for a custom workflow action is identical to any custom extension to MatchPoint:

1. Implement you code and link against the assemblies Colygon.MatchPoint.dll and/or Colygon.MatchPoint.Server.dll.
2. Compile your VS project and deploy the resulting assembly to the GAC of the target system (e.g. using a SharePoint 'WSP' solution file).
3. Register the fully qualified name within the MatchPoint configuration file (ExternalAssemblies property).

For a workflow action, you need to extend the BaseAction class:

namespace Colygon.MatchPoint.WorkflowKit.Actions
{
  [Serializable]
  [XmlIncludeSubTypes]
  public abstract class BaseAction
  {
    protected static readonly Logger Logger;

    protected WorkflowScope Scope;

    [MemberDescriptor("If enabled, any exception during executing this action is ignored, otherwise an exception is thrown.")]
    public bool ContinueOnError;

    protected abstract void Run();
  }
}

• As you can see, the class provides access to the current Logger instance. This allows you to write messages to the SharePoint ULS log using MatchPoint's logging interface.
• You can also access the current WorkflowScope. This scope is important if you need to evaluate expression variables. Among the standard MatchPoint expression variables, you can use the WorkflowInstance expression variable for accessing workflow-specific values (e.g. the Variables property). The ListItem expression variable provides access to the workflow list item.
• The property ContinueOnError allows you to specify whether the workflow should continue if an exception occurs while the action is processed.
• The Run() method will of course contain your logic for the custom workflow action.

As an example for the application of custom workflow actions, let us take a look at a code sample: We would like to implement a CheckOut action that can be used to check out items from a SharePoint list (or document library):

[Serializable]
public class CheckOutAction : BaseAction
{
  [MemberDescriptor("Specifies the URL of the list the item is located. This URL can be relative to the workflow item's web.", true)]
  [CustomEditor(typeof(SPUrlEditor))]
  public string ListUrl;

  [MemberDescriptor("Specifies the ID of the item to modify.", true)]
  public ExpressionString ItemIdExpression;

  protected override void Run()
  {
    // Make the list URL absolute relative to the items web.
    string absListUrl = SPUrlUtility.CombineUrl(Scope.Web.Url, ListUrl);

    SPList list = SPHelper.GetList(absListUrl);
    SPListItem item = list.GetItemById(Convert.ToInt32(ItemIdExpression.Evaluate(Scope)));

    if (list.EnableVersioning)
    {
      item.Web.AllowUnsafeUpdates = true; 
      item.File.CheckOut();
    }
  }
}

• The ListUrl and the ItemIdExpression properties are used to specify the list item that should be checked out.
• The Run() method implements the logic for checking out the list item.
• Note how the value of ItemIdExpression is calculated: We use the Evaluate(...) method and the WorkflowScope property.