Use variables in workflows

Workflows retrieve data from a data source at run time, and you want to be able to store this data somewhere in order to use it in the conditions and actions in your workflow. With variables, you can easily store different types of data. Later, you can reference that data anywhere in the workflow by using workflow lookups.

A variable is a data storage location or cache inside a workflow that contains data associated with a workflow. Two types of workflow data are available in Office SharePoint Designer 2007 — variables and initiation parameters. You can think of workflow data as a data source that is a list of variables where each variable holds a single value of a particular data type.

This article introduces variables and describes the different types that are available. It also shows you how to create new variables and presents a scenario that demonstrates using variables in a workflow.

In this article

Types of workflow variables

Workflow actions with an output clause

Design a workflow that creates a customized map based on user input in a list item

Best practices with variables

Types of workflow variables

There are two types of workflow variables:

  • Initiation parameters     Initiation forms are used to collect data from users when they manually start a workflow. When you create an initiation form, the details of a custom field such as the name, data type, and default value are stored in a variable. This variable always gets the Initiation: prefix.

    For more information on initiation forms, see the article Create a workflow initiation form.

    initiation form fields in define workflow lookup

  • Workflow local variables    The data cached in variables does not persist from one instance of a workflow to the next — this is why each variable always holds only a single value, and this is why workflow variables are always local variables. Workflow local variables hold some data associated to the current workflow. There are two ways to create a workflow variable in a workflow:

    • You can create a variable in a workflow, set it to a value, and reference the variable in a condition or action in your workflow.

    • When you use an action with an output clause such as Create List Item and Collect Data from a User, a variable is created automatically in the output clause as a part of the action.

      Note   You can rename the variable in an output clause, as you can any other variable.

  • For more information on actions with output clauses, see the later section Workflow actions with an output clause.

Data types

A variable must always be set to a data type. You cannot create a variable without specifying a data type.

To set a variable to a value, use the action Set Workflow Variable in your workflow. Refer to the following table for the values that you can assign to variables of different data types.

If your variable is of the data type

You can set the variable to this value

String

Specific text or a lookup to a value of any data type

Boolean

Yes or No value

Date/Time

Current date, specific date, or a lookup to a value of the Date/Time data type

Number

Lookup to a value of the Number or List Item ID data type. The number can be any decimal value.

List Item ID

Lookup to a value of the Number or List Item ID data type

View variables associated with the current workflow

Variables can be associated only to the current workflow; they cannot be used in another workflow.

There are two ways to view the variables in the current workflow:

  • View workflow local variables     To view all existing workflow local variables in a workflow, click Variables in the Workflow Designer. The Workflow Local Variables dialog box lists any existing variables for the current workflow along with the data type. You can add, modify or remove variables in the Workflow Local Variables dialog box.

    workflow local variables displays variables associated to a workflow

  • View initiation parameters     To view all initiation parameters in a workflow, click Initiation at the bottom of the Workflow Designer. The Workflow Initiation Parameters dialog box lists all of the initiation parameters for the current workflow.

    workflow initiation parameters

Top of Page

Workflow actions with an output clause

Actions with an output clause always return data at a workflow's run time. This data is stored in the variable in the output clause. When you add an action with an output clause, a variable is created automatically. The output clause is always denoted by (Output to Variable: Variable Name) in the action.

Notes   

  • The text that indicates the output clause in the action — for example, (Output to Variable: Variable Name) — is always defined in the workflow actions file (.ACTIONS file). The .ACTIONS file contains the set of rules and parameters for an action or a condition. In Office SharePoint Designer 2007, the out-of-the-box actions and conditions are defined in the WSS.ACTIONS file. Custom actions and conditions are defined in a custom .ACTIONS file. If you are implementing custom actions in Office SharePoint Designer 2007, and those custom actions define the text of the output clause differently, then the text renders accordingly in the Workflow Designer.

  • We recommend that you always rename the variable in the output clause with a meaningful name, appropriate to your workflow situation. When you modify the variable, make sure you do not change the data type.

Here is an example of an action with an output clause: Create List Item. When you use the action in your workflow, a variable named create appears in the action. The action also has the output clause which is denoted by (Output to Variable: create).

create list item action in workflow designer

At the workflow's run time, the variable create stores the list item ID of the item that is created in the other list.

The variable in the output clause is always of the data type appropriate to the data that will be returned by the workflow action. For example, the variable create in the action Create List Item is of the data type List Item ID.

The following table lists the actions with output clauses.

Action with an output clause

Default name of the variable in the output clause

Data type of the variable

What data is stored in the variable?

Add Time to Date

date

Date/Time

The calculated value of the time and the date that you enter in the action.

Build Dynamic String

variable

String

The string that you create in the action.

Collect Data from a User

collect

List Item ID

List Item ID of the task item created by the workflow.

For more information, see the article Collect data from a user in a workflow.

Create List Item

create

List Item ID

List Item ID of the item created by the workflow.

Do Calculation

calc

Number

The calculated value of the numbers that you enter in the action.

Set Time Portion of Date/Time Field

date

Date/Time

The calculated value of the time and the date that you enter in the action.

Note   If your workflow uses one of these actions more than once, the variable in the output clause for that instance shows an incrementing value — for example, create, create1, and so on.

Top of Page

Design a workflow that creates a customized map based on user input in a list item

Variables store specific data about the workflow so that you can reference this data wherever necessary in a workflow. In the following scenario, learn how to build a URL string and store it in a variable, and then use the variable in the workflow to populate a field with the URL.

You want to include a list of office locations as part of the contact information on your company's Web site. You also want to offer your Web visitors the ability to generate a map to your nearest office based on their city and zip code. You can have your workflow dynamically generate a link to directions on Live Search Maps, based on the address that your users provide.

First, create a custom list named Maps and include the following columns:

  • A Choice column that displays all of your office locations in a drop-down menu.

    Note   When you enter the address choices, take care not to enter a comma in the address; doing so may break the dynamic URL string.

  • A single line of text column for the visitor to enter their address.

  • A single line of text column for the visitor to enter their zip code.

  • A Hyperlink column that will display the link to the directions on Live Search Maps based on the user's input.

Note   You may want to mark all of these fields, except the hyperlink column, as required fields.

In this example, one column holds the value of the start address, which is the Office locations column, and two columns indicate the end address, which is the Your address and Zip columns. The Map column is a hyperlink column that will display the link to Live Search Maps, based on the data entered in the Office locations, Your address, and Zip columns.

maps list

Create the workflow

  1. On the File menu, point to New, and then click Workflow.

  2. On the first page of the Workflow Designer, name the workflow, select Maps in the list, and then select the check boxes that indicate that the workflow should start whenever an item is created and updated.

    first page of workflow designer

  3. Click Next.

  4. In the Step Name box, enter a meaningful name for the step such as Store URL.

  5. Click Actions, and then click Build Dynamic String.

    Note   If the action does not appear in the list, click More Actions to see the list of all actions.

    Build the URL string and store it in a variable

    The next step is to build the URL string that will display the link to the map on Live Search Maps.

  6. Click Actions, and then click Build Dynamic String.

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

    build dynamic string action in workflow designer

  7. In the action, click dynamic string.

    In the String Builder dialog box, you can now construct the URL string.

  8. Copy the following text and paste it in the String Builder. http://maps.live.com/default.aspx?v=2&rtp=adr.[[Starting Address]]~adr.[[Ending address]]%2c[[Ending Zip]]

  9. Replace the text inside the double brackets — including the double brackets — with the actual workflow lookups. Click Add Lookup in the String Builder dialog box.

  10. In the Define Workflow Lookup dialog box, choose the following options:

    • Source: Current Item

    • Value: Select the appropriate field names as shown in the following illustration.

      url string in string builder

      You can also add a friendly name to the URL, which is the text that is displayed in the hyperlink column. For the URL to appear with a friendly name in the column, type a comma after the URL string and then insert a space. Next, enter text that will be displayed as the link. This example uses the friendly name See the route.

      Now you need to create a variable to store this URL string.

  11. In the action, click Variable: variable, and then select Create a new variable in the list.

  12. Enter a meaningful name for the variable such as URL in the Name box, leave the Type as String, and then click OK.

    Your workflow should now look like this.

    completed first page of workflow designer

    Next you want to specify the hyperlink field that has to be updated when the workflow runs.

    Update the field in the current item

  13. In the Workflow Designer, click Step 2 under Workflow Steps. Then enter an appropriate name for the step such as Update Map field in the Step Name box.

  14. Click Actions, and then click Set Field in Current Item.

    Note   If the action does not appear in the list, click More Actions to see the list of all actions.

  15. Click field, and then select Map from the list.

  16. Click value, and then click Display Data Binding Button image.

  17. In the Define Workflow Lookup dialog box, choose the following options:

    • Source: Workflow Data

    • Value: Variable: URL

      Remember that this workflow is also set to start when an item gets updated. When this workflow subsequently updates fields in the item, it triggers another workflow, or a continuous loop. To prevent this from happening, you need to add the appropriate conditions to the workflow.

      Add conditions to the workflow

      You can prevent a continuous loop by adding conditions that will cause the workflow to check the latest value in the variable against the current value in the Map field. The workflow will update the field only if the values do not match.

      However, when you create a new item in the list, the workflow will not find a current value to be compared against the latest value in the Map field, because it is a new item. In this case the workflow will not update the field. So the first run of the workflow requires a second condition to check to see if the Map field is empty. If it is, the workflow will update the item.

      To add the first condition to the workflow:

  18. Click Conditions, and then click Compare any data source.

  19. In the condition, click the first value link, and then click Display Data Binding Button image.

  20. In the Define Workflow Lookup dialog box, choose the following options:

    • Source: Workflow Data

    • Value: Variable: URL

  21. Click OK.

  22. In the condition, click equals, and then select does not contain from the list.

  23. Click the second value link in the condition, and then click Display Data Binding Button image.

  24. In the Define Workflow Lookup Dialog box, choose the following options:

    • Source: Current Item

    • Value: Map

      Now add the second condition to the workflow.

  25. Click Conditions, and then click Compare Maps field.

  26. In the condition, click and so that it changes to or.

  27. In the condition, click field, and then select Map or the field that will contain the link to the map in the item.

  28. In the condition, click equals, and then select is empty in the list.

    When finished, the second step of the workflow should look like the following.

    completed second page of workflow designer

After a user creates or edits an item, the workflows runs and then displays the link text See the route in the Map column in the item, as shown here.

the map to the location entered by the user displays when the user clicks see the route link in the map column

Top of Page

Best practices with variables

Here are some tips and tricks to remember when working with variables:

  • When you rename a variable that is already in use, you should also update all existing lookups that point to the variable. A lookup that refers to an incorrect or empty variable returns the empty string ***** at a workflow's run time.

  • It is helpful to know when to use an initiation parameter or a variable in a workflow: Use an initiation parameter when you want the workflow to use information provided by the user, and a variable when you want the workflow to use the data generated by a workflow.

  • Use a variable when you want to use dynamic values throughout a workflow. For example, if you want to use a dynamic error message to be sent out in an e-mail message or logged to the History list, build the error message as a string and store it in a variable so that you can later reference it anywhere in the workflow. To take another example, if you want to use a dynamic subject line in the Define Email Message dialog box, first create a concatenated string of text and lookup values, and then store this string in a variable. You can then insert a lookup to the variable from the subject line in the e-mail message.

  • If you have conditions or lookups that are used frequently throughout the workflow and are not expected to change, try to store the value of the condition or the lookup in a variable. This improves workflow performance because it eliminates extra queries, and it also makes your workflow more readable.

    Note   When storing data in a variable, make sure that the variable always refers to a value that holds the most current data (such as a field in a list), especially when you use a delay action (Pause for Duration or Pause Until Date), a wait action (Wait for Field Change in Current Item), or a task action (Assign a Form to a Group or Assign a to-do Item). A variable will not refresh automatically if the data has changed while the workflow was paused, so it is important to make sure that the variable is always linked to a data source that holds the most current value.

  • You can use a variable to track what a workflow has done in early steps and then have the workflow perform an action based on the value in the variable. For example, in a conditional branch, after a workflow creates an item in a list, you can set a variable named ListItemWasCreated of the Boolean data type to record that the item was created. Then, in a later step, you can reference the ListItemWasCreated variable in a condition and determine whether the workflow should perform an action — for example, if the item was created in the previous step, then the workflow can update the item.

Top of Page

Applies To: SharePoint Designer 2007



Was this information helpful?

Yes No

How can we improve it?

255 characters remaining

To protect your privacy, please do not include contact information in your feedback. Review our privacy policy.

Thank you for your feedback!

Support resources

Change language