Expression Evaluation Time: ms / Round trip: ms
Workflow Kit: Implementing Custom Actions
11. Jan
2012
by Tobias Pfanner Category:
Technical
1

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.

Attached to this post, you find the source file for the CheckOutAction class, as well as a source file for a `CheckInAction' class which implements similar logic for checking in a SharePoint list item.

CheckInAction.cs CheckOutAction.cs

Comments
Thomas.Stoller
02.05.2013 06:46
WorkflowScope does not seem to have a property named 'Web'.
The code line 'string absListUrl = SPUrlUtility.CombineUrl(Scope.Web.Url, ListUrl);' tells me 'Cannot access internal Field 'Web' here!'
ABOUT

This blog is about technical and non-technical aspects of the product MatchPoint and other SharePoint topics.

If you would like to post an article or if you have an idea for a post, please contact us.

ARCHIVE
COMMENTS
Matthias Weibel
09.04.2018 01:12
Link is updated and works now. | Goto Post
Dhanabalan
09.04.2018 12:21
Link doesn't work. Could anyone explain what does... | Goto Post
matthiaszbrun
14.03.2018 02:05
Hi Markus
We I use the config for SiteCollectionSe... | Goto Post
Reto Jeger
04.10.2017 09:15
Hello Reiner,
Thanks for pointing out the missing ... | Goto Post
rganser
29.09.2017 09:56
Hi, I downloaded the ZIP-file for MatchPoint Versi... | Goto Post