Understanding workflow starting parameters - Part 2

Article
02/09/2012

Hello all, it’s been a long time since my last writing was posted.

I’m Chong Youn (John) Choe, a PM in SharePoint Designer team. As noticed, this is the second half of the workflow starting parameters blog entries. In this entry I will go over how to extract and manipulate the values passed in from a workflow starting form.

I’d like to begin with apologies for those of you who have long awaited this next post, and thanks to all who have read and sent back feedbacks to the Part 1.

Well then, let’s begin. Smile

What types of parameters exist in the workflow starting parameter?

I’ll briefly recap the types of workflows and workflow starting parameter types. Reading Part 1 is recommended if you can’t understand the following explanation.

There are 3 types of workflow in SharePoint Designer (which refers to SharePoint Designer 2010 from now on, since the post is targeting SharePoint Designer 2010, not any older and newer version) List Workflow, Site Workflow, and Reusable Workflow. While List Workflow and Site Workflow can have only initiation type parameters, Reusable Workflow can have initiation type parameters association type parameters, as well having both parameter types.

Initiation and Association type parameters are differentiated by the phases in which they receive values from the workflow users. Note that there is no difference in terms of supported parameter types, or field types.

Parameter types restriction at a glance

There are 10 types of parameters, this is with the assumption that “Hyperlink” and “Picture” are independent types, described in Part1. All of them can ask for user input during the initiation time, the association time, or during both times.

Field Type	Value Type	Value Range	Required / Optional	Other Settings
Single line of text	String	No limit (length limit 255 characters in 1 line)	Optional (Always allow blank values)
Multiple lines of text	String	No limit (multiple lines)	Optional (Always allow blank values)
Number	Double	Can set Minimum value and Maximum value	Required (Do not allow blank values)
Date and Time	Date and Time	No limit	Required/Optional depends on setting	· Default value can be today · Can restrict input values to be greater than the date/time in which the form was loaded
Choice	String	No limit	Required (One selection is a Must)	· Can differentiate internal data and display strings
Yes/No	Yes/No	Yes/No	Required
Person or Group	People/Group	All People/Group in AD or can restrict to certain Sharepoint Group	Required/Optional depends on setting	· Can allow either only individual person or people and groups · Can allow either only one Person/Group or multiple Person/Group
Hyperlink	URL	Valid URL for hyperlink	Required/Optional depends on setting	· No default value
Picture	URL	Valid URL for picture	Required/Optional depends on setting	· No default value
Assignment Stages	Assignment Stages	Stages of People/Group and Order type	Required (One stage is a Must)	· Parallel Approval, Signatures, etc

Each parameter type and coercion usage in workflow

Here goes the main part of the post. Since there are a lot of combinations for the different types of parameters and their coercion, every input parameter needs to be used via lookup in the workflow. Most users will have to use coercion with parameters. However, due to high level of complexity around coercion, many users find it difficult to fully understand it and as such, give up on making their workflows.

So what is “coercion”? It refers to the “Return field as” portion of the lookup dialog. By selecting the proper return field types, the lookup results can become useful components in workflows.

Every combination will be visited extensively below. In order to comprehend this information, you need to know how to add initiation parameters into workflows, please go through the Part 1 if you are not clear with this.

1) Single line of text

General purpose of using single line of text is for keeping string as itself or as part of a bigger string. As such, the “Log to History” action will be an excellent example to understand this related mechanism.

There are a couple of ways of using this parameter in the action. One is to insert the parameter value in a longer string via String Builder, and another is to pick just the parameter by direct lookup. The coercion options are the same in both methods.

I created loggings for every single option in order to make the results on workflow status page very easy to understand.

The string was designed to test comma and semicolon along with e-mail address style.

The results do not come out in one trial because there are some combinations that are not supported and stop the workflow’s execution during run time. The cumulative results follow.

As the result reveals, the default return field type “As string” can create usual usages for the text-type input parameter.

Note that Display Names, Semicolon Delimited | Email Addresses, Semicolon Delimited | Login name | Login Names, Semicolon Delimited | Lookup Ids, Comma Delimited | Lookup Value (as Text) | Lookup Values, Comma Delimited | User Ids, Semicolon Delimited all have high chances to break your run time behavior so make sure to use them only in the proper cases.

In addition, Description Text and URL create somewhat different results compared to other types that do no manipulation to the original string. We will revisit the two types in Hyperlink and Picture parts.

2) Multiple lines of text

As you might expect, the results are same between Multiple lines of text and Single line of text.

3) Number

Number to string conversion has only two options, As String | Formatted Currency as seen in the “Log to History” actions below.

I put “0.5” as the parameter input – it’s worthwhile to remember that numbers used in SharePoint Designer workflow are double type instead of integer. In general, the default value of “As String” should work for most scenarios. Also note that the workflow will modify the number value when type conversion is needed, for example, pause for duration action only takes in integer numbers and as such rounds 0.5 into 1. So take the type into account whenever you design a workflow where numbers are critical.

A couple other examples of number conversions can be seen in the “Do Calculation” and “Wait for Duration” actions, as they only serve single “As Double” conversion. They are quite straight forward as you can see in the following screenshot.

4) Date and Time

Three basic actions are closely related with Date and Time type variable. I made two initiation parameters one for Date and Time, and another for Date only type to compare their usage in a given workflow.

Date and Time lookup only support return field type of “As Date/Time”. Hence it is straight forward.

Watch how the sample workflow is designed, what the input is, and what the result is. This should help you understand how to play with the Date and Time type parameters.

Adding or setting time to Date and Time variable is very simple. Two things to address are that there is no “Date only” type conversion available for “Log to history” action for instance, and “Date only” type initiation parameter does have Time information but it is just hidden from the UI. The Time portion is set to equal the time in which the Date form is loaded. Remember this fact to avoid possible errors in your workflow design.

5) Choice

Choice type parameters are strings but have a unique attribute. They let you set its value and its display name separately. Here are some examples.

When you set the parameter, each choice should be in a line, and the value or display name should be separated by one “|”, there really should not be any reason to use “|” in either value nor display name, so I’ll skip further explanation on what happens when there are two or more “|”s.

Note that only display names are shown instead of the values. “display name1” for with a value of “value1” was set when the initiation parameter was created. I used the default value as it was and triggered the workflow.

There is no way of retrieving the display name in the workflow. A possible workaround is to create additional logic in your workflow that creates a separate string type variable which you can manually populate with the display name.

6) Yes/No

The primary purpose of using Yes/No parameters is for branching logic.

Workflow is smart enough to offer only Yes/No selection if you set left operand of If clause with Yes/No type parameter!

Yes/No to String type conversion has only a single return field type, nothing to worry about.

In short, this Boolean type is very easy to use. Let’s confirm it by observing the below workflow example and its execution result.

In the initiation/association form, users can check or uncheck the checkbox which refers to yes or no.

In the result, those are mapped to True/False. It feels natural since it’s a Boolean type indeed.

7) Person or Group

The Person or Group parameter is a bit more complex, reading Person or Group in Part 1 of this posting along with this section should hopefully be enough for your tasks.

In this example, we are leveraging the settings page. By choosing “People Only” , unchecking “Allow blank values?” and “Allow multiple values?” , only 1 person will be allowed to be set in the initiation form to start the workflow.

People’s information is required for activities that require participants, such as, the Task Actions or Sending an email action. Since finding a person takes a few steps and is not that intuitive, I’ll use the simple “Send an email” action to guide you.

Add the action and click “these users”. On the email message dialog, “To:” and “CC:” fields allow for people or group as input. Once the people picker is launched, the left side will display some related people and group, you will need to find the lookup option in amongst the list of People and Groups.

The lookup for Person or Group pops up by double clicking the “Workflow Lookup for a User…” string. Choose the parameter and leave the return field type as it is, and close the dialogs with the “OK” button.

The Person or Group lookup works as shown in the example regardless of the value of setting options in initiation parameters.

8) Hyperlink

In most cases, “Single line of text” can cover the scenarios whenever a “hyperlink” type is needed. Thus, I’m going to describe the differences of Hyperlink and Picture type parameters.

These user inputs have a couple of differences compared to the “Single line of text” parameter type. The first difference is that users can set the Address and Display text separately. The Address is validated if it’s a URL.

The display text is written on the form instead of the address.

What’s more, the conversion result is slightly different from that of “single line of text”.

You would already have caught that URL and Description Text types are designed for Hyperlink/Picture. Smile The data is passed as “Address” + “, “ + “Display name” format, and URL and Description Text type extracts only “Address” and “Display name” part, respectively. Actually, Description Text type detects “,” and takes string from two spots next to the “,” so you could play tricks with it for fun.

9) Picture

As you might expect, the results are same between Picture and Hyperlink.

10) Assignment Stages

The concept of the “Assignment Stages” is very complicated but it is a very powerful component. Things around Office Task will be made into another blog post. You can also search the technet.microsoft.com for related materials for now.

Summary

I strongly recommend you to read Part 1 before reading this material. Also whenever you feel some explanation is missing, please check Part 1 posting first.

For receiving and using normal text input parameters, use these in appropriate actions with the “As String” return type.

Number input parameters are double, while some actions take the parameters in integer format.

Date and Time input parameters are used in two formats but are actually a single type.

Choice input parameters have both value and display name. While end-users choose by the name, workflows only see the value that is matched with the name.

It’s best to think of the Yes/No input parameters as Boolean type parameters which are useful in condition statements.

Person or Group input parameter can be conveyed to workflow actions inside of email receivers or task participants. To fully utilize this capability, understanding the settings and steps in the lookup dialog are required.

Hyperlink/Picture type receives address and displaying text, these can be distinguished by the “URL” type and “Description Text” type, respectively.

Thank you! And sorry again for the long wait time between posts.

Chong Youn (John) Choe