SharePoint Workflow Power Pack User Guide — Language Features

Even though we have only recently released the Muhimbi Workflow Power Pack for SharePoint, we are already getting good feedback from users. Most of the questions we get are already covered in the User Guide, which is why we have decided to republish the user guide as a series of blog postings.

A quick introduction In case you are not familiar with the product: The Muhimbi Workflow Power Pack for SharePoint allows custom C# or VB.NET code to be embedded in SharePoint Designer Workflows without the need to resort to complex Visual Studio based workflows, the development of bespoke Workflow Activities or long development cycles.

The following Blog postings are part of this User Guide series:

1. Language Features (this article): Discusses the script like syntax, the generic workflow action and condition, passing parameters, returning values from a workflow and using the MyWorkflow property.

2. Embedding .net code in a Workflow Condition: Provides a number of examples of how to use the Evaluate Custom Code condition to carry out basic as well as complex conditional tasks.

3. Embedding .net code in a Workflow Action: Contains a number of examples of how to use the Execute Custom Code  to basically carry out any action you can think of in a SharePoint Designer Workflow.

4. Creating Custom Methods: Shows how to create your own methods in your scripts in order to keep the code organised and easy to maintain.

Script Like Syntax

To allow code to be entered in an easy fashion, without needing to worry about namespaces, class or method names, the WPP takes a script like approach. In essence the person designing the workflow can just enter a single line of code and the WPP will make sure it is wrapped in the appropriate class.

Even though the traditional structure of a typical C# or VB.net file is not used, it is still possible to add shortcuts to namespaces by adding Using (c#) or Imports (VB) statements to the top of the code.

A simple C# code sample looks as follows:

using System.Xml;

XmlDocument doc = new XmlDocument();

doc.LoadXml("<Test>Content</Test>");

MyWorkflow.ReturnValue = doc.SelectSingleNode("//Test").InnerText;

Note that in order to use System.XML, a reference will need to be added in Central Admin. For details see the Administration Guide

Workflow Action Structure

When adding a new Execute Custom Code action to a workflow you are presented with the following workflow sentence.

The fields are as follows.

Field

Type

Description

this code

Text

The C# or VB.net code to execute.

Language

C# or VB

The language the code is written in.

parameter 1

Object

An optional parameter to pass to the workflow.

parameter 2

Object

Another optional parameter to pass to the workflow.

this variable

Object

An optional workflow parameter to fill with the result.

Enter an optional comment

Text

An optional summary of what the code does.

Workflow Condition structure

When adding an Evaluate Custom Code Condition to a workflow, you are presented with the following.

The fields are as follows.

Field

Type

Description

this code

Text

The C# or VB.net code to execute.

Language

C# or VB

The language the code is written in.

parameter 1

Object

An optional parameter to pass to the condition.

parameter 2

Object

Another optional parameter to pass to the condition.

Enter an optional comment

Text

An optional summary of what the code does.

A condition should always evaluate to either True or False.

Passing values and Parameters

Workflow parameters and other values can be passed to the custom code in a number of ways.

Parameter 1 & 2: Use the Parameter 1 & 2 variables to pass a constant, workflow variable or any other kind of Workflow Lookup value. Note that these values are passed as type Object and may need to be cast into the correct data type in your code.

The Parameter1 and Parameter2 values can be accessed from the custom code using the MyWorkflow variable. For details see Using the MyWorkflow section below.

Embedding Workflow Lookup variables: Workflow Actions allow lookup variables to be directly embedded into the source code using the Add Lookup button.

At runtime all lookup variables are placed into the code as text, so please make sure that the generated syntax is still valid.

For example, the following code will not execute correctly:

String name = [%Variable: firstName%];

As this may result in the following code:

String name = John;

To solve this problem, add quotes around the variable as follows:

String name = “[%Variable: firstName%]”;

Which will result in to following, syntactically correct, code:

String name = “John”;

Note that SharePoint does not allow Workflow Lookups to be defined in the code for Custom Conditions as these are handled differently inside the workflow execution engine.

Returning Values

Variables or result values can be returned from your custom code by using the MyWorkflow.ReturnValue property.

Returning values using the return statement is not supported.

Using the MyWorkflow property

When developing workflows you frequently need access to data related to the workflow. To make accessing this data easy you can access the MyWorkflow property from your own code.

MyWorkflow underlying type

The MyWorkflow property has the following fields.

Field

Type

Description

ActivityExecutionContext

ActivityExecutionContext

Represents the execution environment of an Activity. This class selectively exposes workflow runtime capabilities and services to individual activities.

Item

SPListItem

Reference to the item the current workflow is acting on.

List

SPList

Reference to the SharePoint list the current item is located in.

Parameter1

Object

The first, optional, parameter passed in by the workflow.

Parameter2

Object

The second, optional, parameter passed in by the workflow.

Site

SPSite

Reference to the site collection the workflow is located in.

Web

SPWeb

Reference to the site the workflow is located in.

WorkflowContext

WorkflowContext

Reference to the SharePoint workflow Context.

WorkflowInstanceId

Guid

The ID of the current workflow instance.

The following code illustrates how to use some of the MyWorkflow fields from your own code.

using System.Workflow.ComponentModel;

using Microsoft.SharePoint.Workflow;

// ** Concatenate the strings

String message = String.Format(

    "SPSite: {0} - SPWeb: {1} - SPList: {2} - Item: {3} - P1: {4} - P2: {5} - User: {6}",

    MyWorkflow.Site.ServerRelativeUrl, MyWorkflow.Web.Title, MyWorkflow.List.Title,

    MyWorkflow.Item.Title, MyWorkflow.Parameter1, MyWorkflow.Parameter2,

    MyWorkflow.Web.CurrentUser.LoginName);

// ** Log to the workflow history

ISharePointService service = (ISharePointService)

    MyWorkflow.ActivityExecutionContext.GetService(typeof(ISharePointService));

service.LogToHistoryList(MyWorkflow.WorkflowInstanceId, SPWorkflowHistoryEventType.None,

    0, TimeSpan.MinValue, "", message, message);

// ** Pass the message back to the workflow for further processing

MyWorkflow.ReturnValue = message;

This is just an example. Rather than logging to the workflow history from your own code, you could simply pass the ReturnValue into a standard SharePoint Designer Log to History List activity.