Workflows Reference

Introduction

The process of creating a workflow in Visual Studio, deploying it to EPiServer and then registering it is easy. In this guide we will create a simple workflow that assigns a task to a group of users whenever a page is created in a specific node in the site structure.

Creating the Workflow

The first step will be to create the workflow project in Visual Studio.

Create your Workflow DLL

  1. Select New->Project from the File menu in Visual Studio.
  2. Find and select the Workflow node under the Visual C# root in the Project types area.
  3. Select Sequential Workflow library in the Templates area
  4. Name it (in this example the project will be called TaskWorkflow) and click OK

Creating a workflow project.

Visual Studio will now create a project for you containing an empty workflow definition with a canvas that you can drag and drop workflow items on to.

Renaming the Class

By default, Visual Studio has named the workflow class Workflow1. To rename and refactor your class:

  1. Start by entering the code-behind by right-clicking the canvas and selecting View Code.
  2. Right-click the class name in the type definition declaration and select Refactor->Rename.

    Renaming the class.
  3. Enter an appropriate name for your class (in this example the class will have the same name as the namespace, i.e. TaskWorkflow).
  4. Select the Workflow1.cs file in the solution explorer and press F2 to rename it to match your class name.

Adding an Activity

At this point Visual Studio has created a workflow for you, ready to compile and deploy. But let’s add and modify a CreateTask activity to the workflow before deploying it to the site. With the design canvas open, drag a CreateTask activity from the toolbox and drop it on the canvas between the starting and ending points of the workflow (see Developing Workflows for information on how to add the workflow items to your toolbox).

We now need to add some code to make it possible for the workflow to let the user know what page started the instance. This will also make it possible to see this page when clicking the task.

Add the following code to your class declaration in the code-behind file:

CopyC#
private WorkflowPageEventArgs _pageArgs;

public WorkflowPageEventArgs PageArgs
{
    get { return _pageArgs; }
    set { _pageArgs = value; }
}

The compiler will not recognize the WorkflowPageEventArgs type at first. To add the right using statement, right-click the WorkflowPageEventArgs declaration and select Resolve. In the drop-down menu that appears, select EPiServer.WorkflowFoundation.Activities. The correct using statement will be added to your code and the declaration will become properly highlighted to indicate that the compiler recognizes it.

Adding the correct using statement to the code-behind.

If you try to build the project at this point you will receive a compiler error letting you know that your project is missing a reference. To solve this, right-click the References node in your solution explorer and select Add Reference. Select the Browse tab and locate the EPiServer.dll file in the bin folder of your site. Click OK and build the project. The process should now complete without errors and you will receive the “Build succeeded” message in the status bar.

Adding a reference to EPiServer.dll.

Before we deploy the .dll to the site we need to perform to final tasks. What we need to do is to connect the CreateTask activity to the page that invoked it (made possible by the code previously added in the code-behind) and to add a TaskSubject for the task to make sense to the receiving user.

  1. Select the CreateTask activity on the designer canvas.
  2. On the properties tab, click the expand button next to the PageLink field (if no properties window is visible, right-click the task and select Properties).
  3. On the dialog that pops up, expand PageArgs and select PageLink.

    Associating the PageLink property with the invoking page.
  4. For the purpose of this example we will add the group to receive the task directly in Visual Studio, in a live scenario this would most likely be done in a more dynamic manner. In the AssignTo field, enter “Administrators” to let EPiServer know that all users that are members of the Administrators group should receive this task when the workflow is activated.
  5. To add a TaskSubject we simply click in the TaskSubject field in the properties dialog and enter an appropriate text. For this example we will write “A workflow created task”. Finally save and build your project.
    Entering a TaskSubject

Adding and Enabling the Workflow in EPiServer

The process of deploying your workflow to EPiServer is simply a matter of copying the recently built .dll to the bin folder of your site. To register it with EPiServer:

  1. Browse to your site and enter Admin Mode.
  2. Click Workflows under the Tools section on the Admin tab.
  3. Click the green Plus sign on the Workflow working area, this will open up the Workflow definition section where you can add a workflow to EPiServer.
  4. Under Definition name, enter an appropriate name.
  5. Class name consists of the namespace path and name of your class.
  6. Assembly name is the name of the assembly containing your workflow, in this case it will be "TaskWorkflow".

Image of the workflow definition in EPiServer.

To make this workflow start automatically every time a page is created:

  1. Click the Automatic start tab
  2. Select CreatedPage in the “Choose events that should start instance”-list
  3. On this view there are several other options. You can for instance tell EPiServer that this workflow should only be executed when pages are created under a specific folder by clicking the expand button (…) next to the “Given a pagerelated event, the page root where definition should be applied”-field and selecting the folder in the dialog that opens up.