||This article is based on Sharepoint 2010 Workflows in Action by Phil Wicklund, to
be published December 2010. It is being reproduced here by permission from Manning Publications. Manning early access books and ebooks are sold exclusively through Manning. Visit
the book's page for more information. You can get an instant 40% discount on
this MEAP edition by simply clicking on the link above, and use promo code egghead40
The author discusses creating custom task processes in a SharePoint Designer workflow
using the Start Custom Task Process action.
With simple tasks, a task is assigned to a user and the workflow waits for the task
to be completed. The trouble with these tasks is that they don’t support complex
requirements. For example, what if your workflow needs to allow a task to be
reassigned to someone else? Or, what if you need to set an expiration date on
a task, and then react when the task expires? In these situations, custom task
processes are valuable. A custom task process works from a single task assigned
to one or more people. The main difference is the dozen or so events you can
respond to during that task’s lifecycle including task updates, expirations,
A custom task process can be created from within a SharePoint Designer workflow through
the Start Custom Task Process action. The action requires three parameters: the
task process instance, the item to start the task on, and the users to assign
the task to (figure 1).
Figure 1 A custom task process is used when requirements necessitate responding to events
beyond the completion of a task.
When that task instance is clicked (first parameter), a new custom task process is
created. You’ll also notice that, when you click the instance, you’ll be navigated
to the Settings tab of a new custom task process (figure 2), where the task process
is named Task X. It’s through this Settings tab that you can add functionality
to the task process. We’ll cover three main boxes on this Settings tab: the Customization
box, the Task Form Fields box, and the Task Outcomes box.
Notice the Customization box in this tab. In the box, you can click into three areas
where you can add conditions and actions into the task process. You can modify
the overall task process by responding to events like process cancellation or
completion. Secondly, you can respond to task events like task assignment, expiration,
deletion, or completion. And, lastly, you can set up conditions that must be
met for task completion. All three of these sections contain the shell for all
the events to which you can add actions to incorporate your unique business requirements.
Figure 2 When you add a Start Custom Task Process action, you are taken to the custom task
process settings tab where you can start to build a custom task process.
Another useful item on the tab (figure 2) is the Task Form Fields box, which can
be used to add custom fields to the Task Edit form. The Task Edit form is presented
to the task assignee when they click on the task. By default, they’ll see the
normal task fields and the custom fields you’ve added.
You can use the Task Outcomes section to specify custom task outcomes for your tasks.
A task outcome is the state of a task when it is completed. For example, Approved
and Rejected are default outcomes. You may want a custom task outcome called
Deferred. If you add a Deferred task outcome, users will see a third button called
Defer on the task edit form next to Approve and Reject. Having clicked on the
button, your workflow will flag the task with that outcome when the task completes.
The rest of this section will walk you through each of the three boxes in the custom
task processes settings tab. We’ll also discuss the subject of assignment stages
where we’ll give the end user the ability to choose who should be assigned the
tasks through an association form when the workflow first starts. This is useful
when, while you’re building the workflow, you don’t know who the appropriate
assignees should be and would rather let the user decide.
To explain the settings for a custom task process, I will use an example that deals
with capital expenditure requests. A capital expenditure request is used by a
company when a department or person needs to use some of the company’s capital
to fund a project or initiative. For example, a capital expenditure request might
be submitted to purchase and set up a new branch office. A capital expenditure
request is rarely simple. This is where the custom task process can help, because
you’ll be able to add your unique business logic into the approval of the expenditure
request that will guide the approval from start to finish.
To set up the example, first create a new generic list called Capital Expenditure
Requests. Add two new columns to the list, Request Description as a multiline
text field and Dollar Amount as a currency type. Then, within SharePoint Designer,
create a new List workflow called Expenditure Request Approval and select the
Capital Expenditure Requests list. You need to add only one activity onto the
workflow—the Start Custom Task Process activity. Leave the second parameter as
Current Item and assign a user as the approver for the expenditure requests.
Note that, when you assign a user, you’ll be prompted to fill out an email template.
The user will receive an email when the task process starts. At this stage, you
can also set up a due date for the task process if you wish. When completed,
your workflow surface should look something like figure 3. After you set up your
workflow to this point, click the first parameter of the action—the task process
instance. This will load the task process’s settings tab, and the sections that
follow will walk you through these settings.
Figure 3 The Start Custom Task Process action has three parameters: the process instance,
the item that on which to start the task, and the user(s) to which to assign
The example will cover the three boxes on the custom task process setting tab in
an alternating order. First, we discuss how to change the overall task process
from the Customization box. Then, we customize a task edit form and return to
the Customization box on the settings tab to discuss how to change the behavior
of a single task. Last, we complete the example by setting up custom task outcome
and assignment stages.
Customization box: changing the overall task process
With the Capital Expenditure Requests list created, the Expenditure Requests Approval
workflow set up, and the Start Custom Task Process activity added, it’s time
to bring the business logic into the custom task process. First, look at the
events surrounding the overall task process. In the Customization section in
the custom task process’s settings page, click on the link titled Change the
behavior of the overall task process.
When you click on this link, you go to a tab that contains four events to which you
can add actions (figure 4). With these events, you’ll be able to respond when
the task process first starts, when it’s running, when it’s been cancelled, and
after it completes.
Figure 4 Editing the overall task process, you can add actions that respond to events such
as task process start, running, cancellation, and completion.
Let’s first focus on task process completion. For the capital expenditure request
system, you want the approver to be able to Approve, Defer, or Reject the request.
In the When the Task Process Completes event, you want to identify the approver’s
action and email the requestor the outcome. The email should be context sensitive,
in that the language is specific to whether it was approved or not. Also, you
want to set the workflow’s status to Approved, Deferred, or Rejected; otherwise,
the status default will be set to Completed, which isn’t helpful if someone wants
to report on the rejected requests. Follow the steps in table 4.1 to set up this
Table 4.1 Email requestor and setting the workflow’s status when the task process
Create a new variable to hold the status of the approval.
1. Click Local Variables in the Ribbon, and create a new workflow variable called
ApprovalStatus and select the String option as the variable’s data type.
A new variable that will store the approval status of the capital expenditure request
Add an If any value equals value condition.
2. Add the If any value equals value condition into the When the Task Process Completes
3. Add an else-if condition by clicking the Else-If Branch button. The condition
branch will be labeled Else. To add the second condition, add another If any
value equals value condition into the Else branch, and it’ll be retitled Else-If…
4. Add an else condition again by clicking the Else-If Branch button a second time.
An if/ else if/ else series of conditions will be added to the event.
Complete the if conditions, checking to see if the ApprovalStatus variable is either
Approved or Deferred.
1. For the first if statement, check to see if the ApprovalStatus variable is equal
2. For the second if statement, check to see if the ApprovalStatus variable is equal
NOTE: For the last Else block, you’re assuming that, because the request was neither approved
nor deferred, it’s been rejected.
The first if condition will meet the condition if the status is Approved, and the
else-if condition will likewise meet if the status Is Deferred.
In each If-Else-Else block, add an email action to email the requestor of the status
and add the Set Workflow Status action to set the workflow’s status.
1. Drop the Send an Email action into each if and else-if conditions.
2. Fill out the email properties appropriately, like specifying a body for the email
with language specific to the approver’s response.
3. Use the Set Workflow Status activity to set the status of the workflow for each
Your When the Task Process Completes event should now look like figure 5.
Figure 5 In the When the Task Process Completes event, you add actions that determine if
the approver approved the request or not and whether an email should be sent
to the requestor accordingly.
The final task you complete in this section is to add to the approval notification
email a determination of when the requested funds will become available. We’ll
set this up later but, for now, create a new variable called DateFundsAvailable
that is of the DateTime type. In the approval email, refer to this variable.
For instance, your approval notification email may look something like figure
Figure 6 In the approval notification email, add a reference to the DateFundsAvailable variable,
informing requestors when their funds will be available.
Next, you react when the expenditure request list item changes. You don’t want the
user submitting the request to be able to change the amount after the request
has been approved. If the request is changed or deleted, you want the requestor
and approver to be notified that the request has been canceled.
To set this up, drop a parallel block (click on Parallel Block in the Ribbon) inside
the When the Task Process is Running event. Next, add two steps into this parallel
block and an event into each step: the Wait for Change in Task Process Item action
and the Wait for Deletion of Task Process Item action. The When the Task Process
is Running event is helpful because, if the request is edited anywhere in the
task process, the workflow will react and execute the Wait for Change and Wait
for Deletion actions. The parallel block is handy because you can listen for
multiple events simultaneously. Because you want to listen for two events (edit
and change), you need this parallel block.
After you add the parallel block, the steps, and the wait actions, follow them up
with an email to the requestor and the approver. Also, end the task process so
the workflow will complete and, for the changed action, set the workflow’s status
to canceled. Afterwards, your When the Task Process is Running action should
look like the one in figure 7.
Figure 7 At the When the Task Process in Running event, you can effectively listen
for changes made to the workflow’s item, such as its editing or deletion.
Task Form Fields box: customizing the task edit form
Before you continue modifying the task process through the Customization box, you
need to configure the task edit form. You need this form to prompt the user to
enter the Date Funds Available field that the approval notification email is
using. In the next section, you’ll take this date and assign it to the DateFundsAvailable
variable that was set up in the previous section. But, before you can assign
the variable, you need to prompt the approvers to enter it because they are approving
the task. On the custom task process settings tab, there’s a section called Task
Form Fields (figure 8) where you can add new fields onto the task edit form.
Figure 8 You can add more fields to the task edit form by entering them into the Task Form
Fields section on the custom task process settings tab.
To do this, click the New button. A pop-up will appear, asking you to specify the
field name, description, and data type. Add a new field called Date Funds Available
and set it as a DateTime type. Don’t publish yet; when you do, the approvers
will notice a new field at the top of the task edit form (figure 9).
Figure 9 After the workflow is published, the fields entered in the Task Form Fields section
will display on the task edit form.
Customization box: changing the behavior of a single Task
With the task form fields in place, you can now resume configuring the task process
through the Customization box. You add actions that respond to the approver of
the task. To do this, you add actions into the Change the Behavior of a Single
Task tab. To get to this tab, click the Change the Behavior of a Single Task
link in the Customization box. In this tab, you’ll see five events to which you
can add business logic when the task is first assigned, goes into a pending state,
expires, is deleted, and is completed (figure 10).
Figure 10 By changing the behavior of a single task, you can respond to events such as task
assignment, set to pending, expiration, deletion, and completion.
For the capital expenditure request workflow, let’s drop actions into three of these
events. For the first event, you want to react when the request expires. If the
approver doesn’t approve or rejects the request in an allotted amount of time,
you escalate the request to the approver’s manager. Drop the Escalate Task action
into the When a Task Expires event (figure 11). This action automatically figures
out the person to whom the approver reports and reassigns the task to that person.
Figure 11 At the When a Task Expires event, you can escalate the task to the assignee’s
It is also important to respond if the task is deleted. There’s nothing stopping
a user with full control of the tasks list from deleting tasks, and the workflow
should have logic that appropriately responds to a deletion. Inside the When
a Task is Deleted event, add the Set Workflow Variable action and choose the
ApprovalStatus variable to assign it a new status. Set the variable to Canceled.
Last, add the End Task Process action to cancel the task process and stop the
workflow (figure 12).
Figure 12 If a task that a workflow depends on is deleted, ensure a clean exit for the workflow.
In this case, you’re setting the workflow’s status and ending the task process.
The bulk of the logic lives in the When a Task Completes action. In the overall task
process set of events, you customized the When the Task Process Completes event.
In that event, you looked at a variable called ApprovalStatus and, depending
on how the status was set, you sent out different emails. In the When a Task
Completes event, you need to assign the ApprovalStatus variable to the outcome
of the task. If the task is approved, the capital expenditure request should
also be approved, and so on. Follow the steps in table 4.2 to set this up.
Table 4.2 Setting the ApprovalStatus variable in the When a Task Completes event
Add another if/else/if-else condition.
Follow the same steps as in the When the Task Process Completes example.
An if /else-if /else series of conditions will be added to the event.
Set the ApprovalStatus and the DateFundsAvailable variables in the first if condition.
1. In the first If condition, check whether the current task’s outcome is Approved,
and If so, assign the ApprovalStatus variable to Approved by using the Set a
Workflow Variable action.
NOTE: To get the current task’s outcome, click the ¦x box in the If condition and change the Data Source to be Current Task: Task; then
change the Field from source to be Outcome.
2. Add a second Set a Workflow Variable action in the first if condition and assign
the DateFundsAvailable variable to the current task’s Date Funds Available field
that you created when you edited the task’s edit form.
Both the ApprovalStatus and DateFundsAvailable variables will be set to values when
the status is approved.
Configure the else-if condition to check if the task was deferred
1. In the else-if statement, check if the current task’s outcome is set to Deferred
by using another If any value equal value condition.
2. Assign the ApprovalStatus variable to Deferred.
The else-if condition will now be set to check whether the task was deferred. If
so, the ApprovalStatus variable is set to Deferred.
In the Else block, set the ApprovalStatus variable to Rejected.
The ApprovalStatus variable is set to Rejected in the Else block.
End the task process by adding the End Task Process action below the If-Else action.
After completing these steps, your When a Task Completes event should look something
like figure 13.
Figure 13 In the When a Task Completes event, you’re assigning the ApprovalStatus variable
to its corresponding task outcome.
Task Outcomes box: defining custom task outcomes
The last step in the capital expenditure request’s journey is to set up a custom
task outcome for request deferrals. As mentioned, there are two default outcomes—Approved
and Rejected. A task outcome is the state at which a task is set after it is
completed. In the case of the capital expenditure request, after the approver
completes the task, its outcome will either be Approved, Deferred, or Rejected.
Notice the Task Outcomes section in the custom task process’s settings tab (figure
14). By default, the first two outcomes are present. To add the third, click
the New button and name the outcome Deferred and name the button Defer.
Figure 14 You can add custom outcomes, such as Deferred, to the Approved and Rejected outcomes.
When this third outcome is selected by the approver, the name Deferred will be stored
in the task’s Outcome variable. Defer refers to the name of the button on the
task edit form. Notice that, when the user approves the task, a new option becomes
available on the task edit form (figure 15). The user can now defer the request
until a later date, when the workflow will be re-initiated.
Figure 15 After the workflow is published, your custom task outcomes will appear as buttons
on the task edit form.
Request Change and Reassign Tasks buttons
You may wonder where the Request Change and Reassign Task buttons are coming from
in figure 16. These are called workflow modifications, whereby you can modify
the behavior of a workflow after it has started.
When the user clicks the Defer button, the task’s Status will be set to Completed,
and the task’s Outcome will be set to Deferred (figure 16). Click the Publish
button and test your custom task process.
Figure 16 After a task is completed, whichever task outcome is selected on the task edit
form will be populated in the task’s Outcome column.
Because the custom task process is waiting for the task to be completed, it will
respond to this button click as well. In the When Task is Completed event, the
if/else-if/else branch will determine that the approver deferred the request
and it will set the ApprovalStatus to Deferred. Then, back in the overall task
process events, the When the Task Process Completes event will look at the ApprovalStatus
variable and send an email to the requestor notifying them that their request
has been deferred. After that, the workflow will complete and the workflow’s
status will be set to Deferred (figure 17).
Figure 17 For the Expenditure Request workflow, after the task is completed, the outcome
is stored in the workflow’s Status column.
When you first set up the custom task process, you assign the task process to a specific
person. What if more than one person needs to approve the expenditure request?
What if you don’t know who the approvers should be at design time and you want
your user to specify the approver? For instance, you might have several teams
using the same workflow. Most likely, each team has a different manager. In this
case, you’d want the person initiating the workflow to determine which manager
should approve the process.
Assignment stages are an effective way to give the user the ability to determine
who should receive the tasks that are assigned. Rather than entering someone’s
name directly into the workflow, you can assign custom task process to an assignment
stage. Then, that assignment stage will appear on the workflow’s initiation form
and the user can edit the stage and specify all the users they think should be
assigned the tasks.
Figure 18 shows what this association form may look like when assignment stages are
enabled. The figure shows two stages configured, where the first stage has two
users assigned the task in tandem, and the second stage has a single user.
Figure 18 By enabling assignment stages, you can give your end users the ability to choose
the persons to whom to assign the tasks. The assignment stage appears on the
workflow’s initiation form when it’s first started.
With this assignment stage, the capital expenditure request will be executed three
times, the first two times in tandem. Notice in figure 18 that two users are
assigned in the first stage. After these two users have approved their requests,
the requests will go into the section stage, directed toward a third user for
approval. The user can specify that the requests occur in parallel or sequentially.
In the Start Custom Task Process action, instead of assigning the task process
to a specify individual, you can assign it to an assignment stage instead (figures
19 and 20).
Figure 19 Instead of entering the name of an individual, you can set the task to be assigned
to an Assignment Stage.
Figure 20 The third parameter is set to an assignment stage rather than to a specific user.
To make an assignment stage appear on the workflow’s association form, click the
Initiation Form Parameters button on the Ribbon within SharePoint Designer. Add
a new parameter by clicking the Add button on the pop-up window that appears.
Give the parameter a name and change the Information Type to be Assignment Stage
(figure 21). Click OK and, after you publish the workflow, the assignment stages
will appear on the workflow’s association form.
Figure 21 To enable assignment stages, add a new initiation parameter through the Initiation
Parameters button in the Ribbon.
For the most complex task processing needs, you can create a custom task process
in SharePoint designer using the Start Custom Task Process action. With a custom
task process, you can change the overall behavior of the process. For example,
you can drop actions that fire when the process first starts or is completed.
You can also modify the behavior of a single task by adding actions that respond
to a task’s assignment, completion, or expiration.