Collect data from a user in a workflow

When you design a workflow, you often want to collect information from a participant in the workflow, and then use that information for making further decisions. For example, you might want a workflow to ask a participant to review a document, and then have the workflow perform different actions depending on whether the reviewer approves or rejects the document.

Flow chart that branches depending on the user response

To accomplish this, you add the Collect Data from a User action to your workflow. This action assigns a task to the participant, prompting them to provide the needed information in a custom task form. The information from the custom task form is stored in an item in the Tasks list. At a decision point in a later step, the workflow retrieves the stored information and evaluates it to decide which branch to run.

This article shows you how to collect data from a workflow participant, and then how to use that data in your workflow for making further decisions.

In this article


Which action should I use to create a task?

Tasks are the primary way for a workflow to interact with participants in the workflow. If you want your workflow to require work from people or to get information from them, you can have the workflow create and assign a task. Each time a workflow assigns a task, the workflow pauses until that task is completed. The workflow resumes only when a participant clicks the Complete Task button on the task form.

There are three different actions that create a task, and each action is designed for a specific kind of situation:

  • Collect Data from a User    This action assigns a task to a single user or group and returns the unique ID of the task item that stores the user's answers, so that the workflow can later look up this information by using the ID. With this action, you use the Custom Task Wizard to design a custom task form that collects the information you want. This action creates a task that can be assigned only to a single user or group. If you assign this task to a group, each member of the group receives a task notification, but only one task item is created, and the workflow pauses only until the first person to respond completes the task.
  • Assign a Form to a Group    This action assigns a form to one or more users, and then stores the responses as values in the Tasks list. Unlike the previous action, this action can assign a task separately to multiple people, and the workflow pauses until each person completes their task before it resumes. Also unlike the previous action, this action does not return the ID of the task item for any of the responses, so the workflow cannot look up and use that information later as the basis for making comparisons or decisions. With this action, you also use the Custom Task Wizard to create a custom task form. For more information, see the article Assign a form to a group in a workflow.
  • Assign a To-do Item    Unlike the other two task actions, this action creates a task form that has no form fields to fill out but instead uses a form where the user simply clicks a Complete Task button when the task is finished. This task can be assigned separately to multiple people, and the workflow pauses until each person marks their task as complete. This action does not return the ID of the task item — and doesn’t really need to because the task does not collect any information that you might want to reference later. For more information, see the article Assign a to-do item in a workflow.

The following table summarizes this information.

Action Returns the task ID for workflow lookups? Creates multiple tasks? Enables you to define fields on the task form?
Collect Data from a User Yes No Yes
Assign a Form to a Group No Yes Yes
Assign a To-do Item No Yes No

In addition, several limitations apply to all three task actions:

  • When a workflow assigns a task to a group that is identified by a single alias or address, the workflow creates only one task item, which is then shared by the entire group. Any member of the group can edit that single task form and click the Task Complete button. To assign individual tasks to multiple users (only possible with the Assign a Form to a Group or Assign a To-do Item action), enter each user individually in the Select Users dialog box.
  • All of the tasks assigned by a single workflow action must be completed before the workflow can continue. If the workflow action assigns individual tasks to six participants, for example, you cannot direct the workflow to continue after only three of the six tasks are completed.
  • After a task is assigned to a participant by the workflow, that task cannot be transferred to any other participant (by delegation, forwarding, etc.). However, anyone with the default Contribute permission level to the Tasks list can edit the task item and thus allow the workflow to continue.
  • A workflow can use each task only once. After you create a task by using the Custom Task Wizard, there is no way to reuse that task later in the workflow. You can create another task that performs the same function, but the task's name will have to be different and unique.

Top of Page Top of Page

What is a custom task form?

Each time that you use one of the three task actions to create a task, Microsoft Office SharePoint Designer 2007 automatically generates a custom task form for that task. The custom task form is the page that is presented to the workflow participant when they edit the task in the browser.

When you create a task by using the Collect Data from a User or Assign a Form to a Group action, the custom task form can have as many form fields as you choose to create. This example asks the user to enter information in only one field named "Review status".

Custom task form in browser

In Office SharePoint Designer 2007, the custom task form appears as an .aspx page in the folder for that workflow. The file name of the custom task form corresponds to the name that you give the task in the Custom Form Wizard.

Custom task form in Folder List

Custom task forms are attached to the site's default master page and contain a Data Form Web Part to interact with the workflow. The custom task form can be customized for layout and appearance — for example, you can attach a different master page or modify the styles. However, to change what fields appear on the form, you must use the Custom Task Wizard in the Workflow Designer. You cannot change the form fields by editing the Data Form Web Part directly. If you make other customizations to the Data Form Web Part (for presentation and not for functionality), note that those changes are lost each time that the workflow is recompiled. Customizations to the rest of page are preserved.

To change the fields on the custom task form, you must open the workflow in Office SharePoint Designer 2007 (File menu, Open Workflow command). When you open the workflow and edit the task by using the Custom Task Wizard, you see the following warning.

Warning message

If you modify the custom task form and recompile the workflow, all running instances of the workflow continue to run using the new form. If you delete or modify fields (for example, by changing their type or renaming them), a workflow error will occur if the running instances of the workflow reference data that is not what is expected. For example, a running workflow may do a lookup and expect a field to contain data (be non-empty) but now it is empty, or the field may have changed type. Therefore, it is important not to make any change that deletes, renames, or otherwise alters form fields that currently running workflow instances may attempt to reference.

In addition to the custom task form, each time that you use one of the three task actions to create a task, Office SharePoint Designer 2007 automatically generates a content type for that task in the Tasks list. The content type defines the available fields and what format they use, as you specified in the Custom Task Wizard. The name of the content type matches the name that you give the task in the Custom Form Wizard. For example, if you create a task named "Review document", you will see a content type with that name on the Settings page of the Tasks list.

Task content type in the browser

We recommend that you modify workflow content types only by opening the workflow in Office SharePoint Designer 2007, and not by modifying the columns or other settings for the content type in the browser. Modifying the content type in the browser can potentially break the custom task form that it is associated with.

Top of Page Top of Page

What is a list item ID?

A list item ID is a unique row number. When a workflow participant clicks either Complete Task or Save Draft on the custom task form, the information submitted in the form is stored in an item in the Tasks list. The content type for that task defines the columns, and the list item ID identifies a specific item, or row. Each item in the Tasks list (or any list or library) has a unique ID. In the browser, you can add the ID column to any view of a list or library.

ID column added to default view

In addition, when you view a list item on a page in the browser — for example, when you click View Properties to see the item details on DispForm.aspx — the ID of that list item is visible in the URL as part of the query string. All standard SharePoint forms contain an ID parameter in the query string section of the URL.

List item ID highlighted in the URL of a task item

When a workflow runs the Collect Data from a User action, the workflow creates a single task and stores the list item ID of that task in a variable. The workflow can later use that variable to look up the specific task item.

Top of Page Top of Page

Step 1: Collect data from a user

First you want to use the Collect Data from a User action to create the custom task form, assign the task to a single user or group, and then store the ID of the task item in a variable. The workflow will later use the task item ID to look up the values submitted by the user in the task form.

In this example, your team uploads documents to a library named "Documents for review". When a document is added to the library, the workflow creates a task named "Review document". The person to whom the task is assigned must choose one of two options from a drop-down menu when they edit the task: Approved or Rejected.

 Note   This workflow is a custom approval workflow, but it does not use the Content Approval feature in Windows SharePoint Services and does not change the Approval Status field of the document. The Content Approval feature in Windows SharePoint Services presumes two different permission levels: one that does not include the Approve Items permission (for people submitting content for approval), and a second that does include the Approve Items permission (for people approving content). However, a workflow designed in Office SharePoint Designer 2007 always impersonates the permission level of the person who starts the workflow. If a person who does not have the Approve Items permission starts a custom workflow that tries to update the Approval Status field of the current item, the workflow will stop because the person who started the workflow does not have permission to approve items.

  1. On the File menu, point to New, and then click Workflow.
  2. On the first page of the Workflow Designer, name the workflow, choose the list or library that the workflow will be attached to, and then select the check boxes for the start options that you want.

First page of Workflow Designer

  1. Click Next.
  2. Click Actions, and then click Collect Data from a User.

If this action does not appear in the list, click More Actions to see the full list.

  1. In the action, click data.
  2. On the first page of the Custom Task Wizard, click Next.
  3. In the Name box, type a name for this task.

 Note   The task name must be unique in the current site.

  1. In the Description box, type any general instructions to the recipient of the task.

This description appears at the top of the custom task form, so include here any instructions that you want the workflow participant to see, not just a general description.

Second page of Custom Task Wizard

  1. Click Next.
  2. Click Add to define a custom form field for this task.
  3. In the Field name box, type a name for this field.
  4. In the Description box, type the question for which this form field is storing the answer.
  5. In the Information type list, choose an option that formats the field appropriately for the type of information that you are collecting.

First page of Add Field dialog box

  1. Click Next.
  2. The next page of the wizard varies depending on the Information type that you chose on the previous page. Specify the settings that you want.

In this example, type Approved, press ENTER, and then type Rejected.

  1. In the Display as list, click Drop-down menu.
  2. Clear the Allow blank values check box because you want the reviewer to choose one of the two options.

Second page of Add Field dialog box

  1. Click Finish twice.

The following illustration shows how this task will be displayed to the workflow participant in the browser when they edit the task. This is the custom task form — Review document.aspx — that you just designed by using the Custom Task Wizard.

Custom task form in browser

Back in the Workflow Designer, you still need to set the second and third parameters in the Collect Data from a User action.

  1. In the action, click this user.
  2. In the Select Users dialog box, type a name or e-mail address, or click an existing user or group in the list, and then click Add.

 Notes 

  • With the Collect Data from a User action, the workflow creates only one task, which you can assign to only one person or group. For more information, see the earlier section Which action should I use to create a task?
  • Instead of entering a specific user name or e-mail address, you can store this information in a separate list, and then use a workflow lookup to get this information. This way, various users can be configured as workflow participants without you having to modify the workflow itself. Alternatively, you can create a new SharePoint group, and then add users to the group whom you want to be workflow participants. For example, you can create a group named Approvers, add one or more users to it, and then configure this group as part of the Collect Data from a User action (keeping in mind that only one task is created, which can be edited by only one person).
  1. Click OK.
  2. In the action, click the third parameter, and then click Create a new variable.

You want to create a new variable instead of using the default name (Variable: collect) when your workflow will have multiple variables and you want to give the variable a more descriptive name.

Create a new variable option

  1. In the Edit Variable dialog box, type a name that describes the value that the variable is storing.

Edit Variable dialog box

For this variable, List Item ID is the only choice in the Type list. For more information about list item IDs, see the earlier section What is a list item ID?

  1. Click OK.

At this point, your action should look like this.

Collect Data from User action

Top of Page Top of Page

Step 2: Set a workflow variable

At this point in the workflow, a workflow participant submits a completed task, and the review status that person submits is stored in a field or column in the Tasks list, as shown here.

Review status in completed task item

How do you get at this information to use it in another step in the workflow? You use the Set Workflow Variable action to look up the value of the Review status field for the task that the user edited, and you store the value of this field in a new variable — in this example, named Review status.

By looking up and storing the review status in a new variable, you can now use this variable as the basis for future comparisons. This is a best practice because the workflow now makes it clear where the data is coming from, and this data can be reused more easily — multiple times, if necessary.

  1. Click Actions, and then click Set Workflow Variable.

If this action does not appear in the list, click More Actions to see the full list.

  1. In the action, click workflow variable, and then click Create a new variable.

First parameter of the Set Workflow Variable option

  1. In the Edit Variable dialog box, type a name that describes the value that the variable is storing.
  2. In the Type list, click the type of data that the variable is storing.

In this example, click string because this variable will store the review status of Approved or Rejected, which are both text strings.

Edit Variable dialog box

  1. Click OK.
  2. In the action, click value, and then click Display data bindingButton image.
  3. In the Define Workflow Lookup dialog box, choose the following options:
    • Source: Tasks    If more than one tasks list is available, choose the list that contains the custom form field that you created in the previous section.
    • Field: Review status    Choose the custom form field that you created in the previous section.
    • Field: Tasks:ID
    • Value: Click Display data bindingButton image.
  4. In the second Define Workflow Lookup dialog box, choose the following options:
    • Source: Workflow Data
    • Field: Variable: ID of Review document task

Define Workflow Lookup dialog box

  1. Click OK.

The final workflow lookup should resemble the following. This lookup says, "Go to the Review status field in the Tasks list. Then go to the row in the Tasks list whose ID matches the ID stored in the variable for this instance of the workflow." If the workflow runs and creates a task whose ID is 3, this lookup retrieves the value of the Review status column from the third row in the Tasks list. The next time the workflow runs, this ID may be 4, so the lookup goes to the fourth row, and so on.

Define Workflow Lookup dialog box

  1. Click OK.

At this point, your rule should look like this.

Rule in Workflow Designer

Top of Page Top of Page

Step 3: Use the variable to make decisions

In step 1, you created a custom task form to collect data from a user and store the ID of the task item in a variable. In step 2, you used the task ID variable to look up the user response and store that particular response in a new variable. Now that you have this variable — in this example, Variable: Review status — you are ready to use it as the basis for making decisions in the workflow. To do this, use the Compare any data source condition.

For example, you can add a step to your workflow that says if Variable: Review status equals Approved, run these actions. But if Variable: Review status equals Rejected, run different actions.

Create the first conditional branch

The first conditional branch compares the value that is stored in Variable: Review status. If the value equals Approved, the workflow will perform any actions associated with this condition.

  1. In the Workflow Designer, under Workflow Steps, click Add workflow step.
  2. Click Conditions, and then click Compare any data source.
  3. In the condition, click the first value hyperlink, and then click Display data bindingButton image.
  4. In the Define Workflow Lookup dialog box, choose the following options:
    • Source: Workflow Data
    • Field: Variable: Review status.

Define Workflow Lookup dialog box

  1. Click OK.
  2. In the condition, leave equals as the value for the second parameter.
  3. In the condition, click the second value hyperlink, type Approved, and then press ENTER.

Condition in Workflow Designer

Create the second conditional branch

The second conditional branch handles the case where the value stored in Variable: Review status equals Rejected.

  1. Click Add 'Else If' Conditional Branch.
  2. Click Conditions, and then click Compare any data source.
  3. In the condition, click the first value hyperlink, and then click Display data bindingButton image.
  4. In the Define Workflow Lookup dialog box, choose the following options:
    • Source: Workflow Data
    • Field: Variable: Review status.

Define Workflow Lookup dialog box

  1. Click OK.
  2. In the condition, leave equals as the value for the second parameter.
  3. In the condition, click the second value hyperlink, type Rejected, and then press ENTER.

Before you add any actions to the condition in each branch, this step of the workflow should look like this.

Else If conditional branch in Workflow Designer

  1. To complete this step in the workflow, click Actions, and then add whatever actions you want to each conditional branch.

Top of Page Top of Page

Quick reference: A summary of the steps

For quick reference, here is a summary of the steps presented in the three preceding sections:

  1. Add the Collect Data from a User action:
    • For the first link, use the Custom Task Wizard to create the custom task form.
    • For the second link, select a single user a group to assign the task to.
    • For the third link, create a variable of the List Item ID type to store the ID of the task item that the user edits.
  2. Add the Set Workflow Variable action:
    • For the first link, create a variable to store the actual value (not just the ID) of a specific field from a specific row in the Tasks list.
    • For the second link, look up the field whose value you want in the Tasks list, by using the value stored in the List Item ID variable to retrieve the specific list item (or row).

This lookup should resemble the following example. This lookup says, "Go to the Review status field in the Tasks list. Then go to the row in the Tasks list whose ID matches the ID stored in the variable for this instance of the workflow." If the workflow runs and creates a task whose ID is 3, this lookup retrieves the value of the Review status column from the third row in the Tasks list. The next time the workflow runs, this ID may be 4, so the lookup goes to the fourth row, and so on.

Define Workflow Lookup dialog box

  1. Create a new workflow step.
  2. Add the Compare any data source condition:
    • For the first link, choose the variable that you set to an actual value in step 2.
    • For the second link, click a comparison.
    • For the third link, enter a value that you want to compare with the value stored in the variable.
  3. Add any actions that you want to run if this condition is satisfied.
  4. Click Add 'Else If' Conditional Branch and repeat steps 4–5 to create additional branches.

Top of Page Top of Page

 
 
Applies to:
SharePoint Designer 2007