Custom task processes in SharePoint Designer Workflows

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.

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, and reassignments.

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 task.

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 event.

Table 4.1 Email requestor and setting the workflow’s status when the task process completes

Action

Steps

Result

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 is added.

Add an If any value equals value condition.

2. Add the If any value equals value condition into the When the Task Process Completes event.

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 to Approved.

2. For the second if statement, check to see if the ApprovalStatus variable is equal to Deferred.

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 approval response.

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 6.

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 manager.

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

Action

Steps

Result

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.

Assignment stages

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.

Summary

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.

By Peter Bromberg   Popularity  (8236 Views)