22.1. Understanding Workflow Designer Common Dialog Boxes

This section is intended to familiarize you with the specific user interface dialog boxes available in Workflow Designer. Many of these dialog boxes are used repeatedly across multiple actions and conditions. Understanding these dialog boxes should help you use them across Workflow Designer in a number of conditions and actions.

22.1.1. Using the Workflow Initiation Parameters dialog box

The Workflow Initiation Parameters dialog box is accessible by clicking the Initiation button on the designer surface of Workflow Designer. This dialog box mostly allows you to create initiation variables, values for which can be collected from a user initiating a workflow manually by using an initiation form. As shown in Figure 22.1, the Workflow Initiation Parameters dialog box, accessed by clicking Add, allows you to add fields of a single line of text, multiple lines of text, number, date and time, choice, and yes/no.

When the workflow is saved, these fields are mapped to corresponding input controls in an initiation form. For example, a field of type Choice can be configured to be shown as a dropdown menu on the initiation form.

If the workflow is started manually, an initiation form is displayed to the user that has input controls corresponding to the fields created by using the Workflow Initiation Parameters dialog box. Each field is mapped to a workflow initiation variable. When the user submits the form and starts the workflow, the values he or she types in the input controls are saved in the initiation variables in the workflow. These variables can then be used by using the Workflow Data option at various locations in Workflow Designer. In this manner, the Workflow Initiation Parameters dialog box helps implement the initial interaction of the user with the workflow.

Figure 22.1. Adding fields using the Workflow Initiation Parameters dialog box

22.1.2. Using the Workflow Local Variables dialog box

The Workflow Local Variables dialog box, available by clicking on the Variables button in Workflow Designer, is Workflow Designer's interface to create, edit, and delete variables that have been defined for a workflow. Workflow variables are pretty useful, as they can be used to store the state of an object, such as a field's value in a SharePoint list item, at a certain point of time. You can then reference the variable at a later point and use the value stored in it to perform the intended operation. As shown in Figure 22.2, the Edit Variable dialog box, accessible by clicking Add in the Workflow Local Variables dialog box, can be used to create and edit workflow variables.

Figure 22.2. Creating workflow variables by using the Workflow Local Variables dialog box

While creating a workflow variable, you can choose the type of data you want to store in the variable. For example, you might want to define the variable type as List Item ID if you want to store the ID of a list item in it for future use.

While the Edit Variable dialog box is accessible by using the Create a new variable option available while binding values to various conditions and actions, the Workflow Local Variables dialog box is the central location to view and manage all workflow variables.

22.1.3. Using the Define Workflow Lookup dialog box

The Define Workflow Lookup dialog box is the most commonly used dialog box in Workflow Designer. This dialog box is the primary interface in Workflow Designer to define a query that returns specific data. The data can then be used to set the value of a workflow variable, for comparison, etc. For example, the Set Workflow Variable action in Workflow Designer displays the Define Workflow Lookup dialog box to choose the field, the value of which should be stored in the workflow variable. In the example shown in Figure 22.3, you're electing to use the ID column in the Shared Documents document library based on the condition that the Approval Status column in the list item has the value 0;#Approved.

Figure 22.3. Use the Define Workflow Lookup dialog box to create a lookup query.

This means that if the Shared Documents document library has a document that has the Approval Status column set to the value 0;#Approved, the value of the ID column of that document would be returned by the lookup. In this manner, the workflow lookup is analogous to an SQL SELECT statement with a WHERE clause. Obviously, in the previous example, there could be multiple documents that have the Approval Status column set to the value 0;#Approved, and the lookup query would then return multiple items. In such a case, the message shown in Figure 22.4 is displayed to indicate that multiple items were returned as the result of the lookup and that the first one is used. Ideally, you should define the workflow lookup in a manner that's guaranteed to return a single item.

Figure 22.4. This message box displays whether the lookup returns multiple values.

It's also important to note that the Find the List Item section isn't displayed if the item for the lookup is expected to be unique. For example, if you choose Current Item as the value in the Source dropdown menu in the Lookup Details section, the Find the List Item section isn't displayed because it isn't required.

You can use the fx button in the Find the List Item section of the Define Workflow Lookup dialog box to perform a second lookup query to determine the value of the field that should be used in the first lookup query. Using the previous example illustration, rather than choosing the value of the Approval Status field from the dropdown menu, if you want to perform a lookup query to get the value to be used, you can use the fx button to open another Define Workflow Lookup dialog box and then use it to define the lookup query.

While using the Define Workflow Lookup dialog box, consider the Lookup Details section as the SELECT statement and the Find the List Item section as the WHERE clause. This helps you avoid a lot of confusion while defining lookup queries.

22.1.4. Using the Custom Task Wizard

The Custom Task Wizard is the Workflow Designer interface provided for facilitating task creation. Many workflow actions, such as Collect Data from a User, Assign a To-do Item, etc., depend on tasks that are assigned to specific users. The Custom Task Wizard allows you create these tasks and, for some workflow actions, provides for creating fields for requesting user input.

For example, if you use the Collect Data for a User action in a workflow, clicking the Data hyperlink in the action's sentence opens the Custom Task Wizard. As shown in Figure 22.5, you can use the Custom Task Wizard to create a task with input fields and then assign it to a specific user.

The data collected as the result of the user filling up the form is stored as an item in the Tasks list. The workflow action retrieves the ID of the item created in the Tasks list and then stores it in a workflow variable of type List Item ID. This workflow variable can later be used in the workflow for referencing the data collected from the user.

Figure 22.5. Using the Custom Task Wizard with the Collect Data from a User workflow action

22.1.5. Using the Select Users dialog box

The Select Users dialog box allows you to choose single or multiple users for performing a certain operation in a workflow condition or action. For example, the condition Modified by a Specific Person displays the Select Users dialog box to let you choose the user to be used in the condition. As shown in Figure 22.6, the Select Users dialog box allows you to either manually type the name or e-mail address of the user or choose from a list of users and SharePoint groups. You can specify the user by creating a lookup query by using the Define Workflow Lookup dialog box or choose the user who created the current item.

To add a user, type the username (or e-mail address) or select the user in the list and then click Add. Or simply double-click your choice in the Select from Existing Users and Groups list. To remove a user, select it in the Selected Users box and then click Remove.

22.1.6. Using the String Builder dialog box

The String Builder dialog box, available in the Build Dynamic String workflow action, is particularly useful for creating dynamic text strings by concatenating values retrieved from lookup queries. The String Builder dialog box, as shown in Figure 22.7, allows you to use the Define Workflow Lookup dialog box to create lookup queries.

Figure 22.6. Specifying a user by using the Select Users dialog box

Figure 22.7. Using the String Builder dialog box

While you can type any text in the text area provided, you click Add Lookup at the bottom of the String Builder dialog box to open the Define Workflow Lookup dialog box for creating the lookup queries. The values received from these queries can be joined together to form a single text string. This string is then stored in a workflow variable for future use in the workflow. In this manner, the String Builder dialog box is especially useful for creating subject lines for e-mail messages, logging information to history lists, etc.

22.1.7. Using the Define E-mail Message dialog box

The Define E-mail Message dialog box allows you to create an e-mail message for use in the Send an E-mail workflow action. As shown in Figure 22.8, the Define E-mail Message dialog box heavily uses the Select Users and Define Workflow Lookups dialog boxes for specifying the values for the To, CC, and Subject text fields.

You can format advanced formatting and change the look and feel of an e-mail message by adding valid HTML to the body of the message.

The buttons next to the To and CC text fields open the Select Users dialog box, which allows you to specify multiple recipients of an e-mail message. The fx button next to the Subject text field opens the Define Workflow Lookup dialog box and allows you to create a lookup query for creating the subject line of the e-mail. Also, the Add Lookup to Body button at the bottom of this dialog box allows you to add dynamic values created by using lookup queries to the body of an e-mail message.

Figure 22.8. Using the Define E-mail Message dialog box

22.1.8. Using the Create New List Item dialog box

Used by the Create List Item workflow action, the Create New List Item dialog box allows you to define the specifics of the list item that's created by the action. As shown in Figure 22.9, the List dropdown menu in the Create New List Item dialog box allows you to specify the SharePoint list or library where the item should be created.

Figure 22.9. Using the Create New List Item dialog box to create a new item

After you choose the list or library, the columns specific to it can be set with appropriate values by using the Value Assignment dialog box, which is accessible by clicking Add. For SharePoint libraries, the File Name Conflicts section is enabled and allows you to choose the course of action in case the item with the same name already exists. You can choose to either append a unique ID at the end of the new item or overwrite the existing item. Once you create the list item, the Create List Item action returns the ID of the newly created item, which is then stored in a workflow variable for future reference in the workflow.

A variant of the Create New List Item dialog box is the Update List Item dialog box, which is used by the Update List Item workflow action to allow for editing a selected list item. As shown in Figure 22.10, the Update List Item dialog box has a Find the List Item section (similar to the Define Workflow Lookup dialog box), which can be used to create a lookup query to determine the item that needs to be updated in the chosen list.

It's important to note that the Update List Item action should be used carefully when designing a workflow that's configured to start automatically on item update. If proper validation checks aren't put in place, you might end up in a workflow that runs in an infinite loop. For example, if you update a list item by using the Update List Item action without specifying any conditions on a workflow configured to automatically start on item update, the workflow keeps triggering itself on every item update. Although the SharePoint server is intelligent enough to terminate running such infinite workflows to avoid system overload, you should keep this behavior in mind while designing workflows.

Figure 22.10. Using the Update List Item dialog box to look up and update a list item