Understanding Dictionary actions in SharePoint Designer 2013
Published: July 16, 2012
The Dictionary variable type is a new variable type in the SharePoint 2013 Workflow platform that you can use with SharePoint Designer 2013.
Applies to: SharePoint Designer 2013 | SharePoint Server 2013
A workflow is a series of actions that perform a desired outcome. As you build a workflow you often need to save values in a variable (storage container) to use in other parts of the workflow.
When you create a variable you need to tell the workflow engine what type of data will be contained in the variable. For example, you might want to save the name of an employee in a variable. The name of an employee is a string of characters so you would create a variable of type String. The workflow could then store the name of the employee, such as "John Doe," in the variable.
SharePoint Designer 2013 has a new variable type called Dictionary. The Dictionary variable type is a container designed to hold a collection of other variables. For example, your workflow might need to store more than just the name of the employee. It might also need to store his address and birth date. If you do not use the Dictionary variable you will have to create multiple stand-alone variables. This can quickly become difficult to organize and difficult to work with in the logic of the workflow. A Dictionary variable allows you to store multiple data points in a single variable.
The figure illustrates the concept.
A workflow consists of multiple actions that are executed as the workflow is processed. SharePoint Designer 2013 contains many different actions. For example, there is an action to send an email message, create a list item, and log messages to workflow history.
The following are the three actions specifically designed for the Dictionary variable type.
Count Items in a Dictionary
Get an Item from a Dictionary
The workflow actions for the Dictionary variable type can be found on the Action drop-down list, as shown in the figure.
Create variables with the "Build Dictionary" action
You use the Build Dictionary action to create a variable of type Dictionary. You enter the contents of the dictionary and then specify the name of the dictionary in the variable list.
The figure shows the Build a Dictionary dialog box. Notice that three variables have been added to the dictionary: a string, an integer, and a date/time.
A Dictionary can contain any type of variable available in the SharePoint 2013 Workflow platform. The following list defines the variable types available:
Boolean: A Yes or No value
Date/Time: A date and time
Dictionary: A collection of variables
Guid: A Globally Unique Identifier (GUID)
Integer: A whole number without decimals
Number: A number that can contain decimals
String: A string of characters
The Dictionary variable type is critical when you are using the Call HTTP Web Service action.
Using the Name field as a lookup is only supported when you are setting a value in a dictionary. Using the Name field as a lookup is not supported when you are building a dictionary.
A Dictionary variable can contain a variable of type Dictionary. The ability to store Dictionary variables within a Dictionary provides a number of benefits. For example, you might create a Dictionary to store information about employees. Within the Dictionary you might create another Dictionary entry for each employee. As you build the workflow you can use the Dictionary variable instead of constantly creating new stand-alone variables for each piece of information about each employee. As this example shows, a Dictionary can be used to organize complex information within the workflow.
Count and store variables with the "Count Items in a Dictionary" action
You use the Count Items in a Dictionary action to count the variables that a Dictionary contains and then store that number in an Integer variable. You can then use the item count to loop through the Dictionary.
The figure shows the Count Items in a Dictionary workflow action.
Retrieve variables with the "Get an Item from a Dictionary" action
You use the Get an Item from a Dictionary action to retrieve a variable stored in the Dictionary and place it in a variable. This is valuable when you need a value in the dictionary stored in a stand-alone variable. You can retrieve a value by entering the name of the variable.
The figure shows the Get an Item from a Dictionary workflow action. Notice that Age is the name of the variable in the Dictionary and it is being output to a new Integer variable.