Understanding workflow starting parameters - Part 1

John's PicHello all, I’m Chong Youn (John) Choe, a PM on the SharePoint Designer team. SharePoint Designer is a handy tool and is designed to embrace those who are not developers. I will be creating a series of posts about fundamental features that can help you become confident in using SharePoint Designer. What’s even better is that these features are enough for you to create powerful workflows!

I’m going to begin with the starting parameters. A couple of posts will be created on this topic, the concept behind and understanding how to gather user input will be explained in this post. How to extract the values and manipulate them will be demonstrated in the next post.

Let’s get to the point then.

What are these for?

Certain type of data cannot be determined when you are designing a workflow. For example, the amount of money in an expense report or the target date in a vacation request are examples of data that cannot be determined while creating a workflow. As such, we should design starting parameters to receive such data when needed.

When does a workflow receive user input? (What is initiation and association?)

Assume a paper-based working circumstance. The amount of money or a target date could be written when an employee hands in the expense report sheets or vacation request sheets. This is an example of information being filled up at the moment the workflow starts.

Imagine a basic format of a sheet used in a company, and its variations are used in different parts of the company. In our example company, sheets submitted to the CEO have to be one-page, and the marketing department has made a rule to review any approval requests within 3 days. In SharePoint, this is comparable to setting different values when a workflow is applied to a list. This way, items can share common values within the list but not outside the list even though the workflow can be associated with any list in a site.

All SharePoint Designer created workflows will display initiation forms to users for setting parameters when the workflow initiates, which is why it is named ‘initiation parameter’. Reusable workflows provide one additional starting form and parameter when it is associated with a list, which is called the ‘association parameter’. The parameters can be displayed at the association time and the initiation time, these parameters at initiation time show values preset at the association time even though they are editable.

 
For now, let’s say that list workflows and site workflows have only initiation parameters, while reusable workflows have initiation parameters, association parameters, and parameters included at both times.

In case you are confused what initiation and association are, here are some brief examples.

Click on a list item

When you click on an item in a list,

Edit item view
Edit item view pops up, the “Workflows” button is selectable there

Workflows dialog

Then another layer pops up with the workflow information that is controllable for the chosen item. When you choose a workflow to start, the form that comes up next is the initiation form. This is a list workflow or associated reusable workflow example, however the forms of site workflow or globally reusable workflows are also initiation forms.

On the contrary, association forms however, face users only when a reusable workflow is being associated.

Add a workflow - from List Tools

Choosing “Add a Workflow” as shown above from a list,

Workflow association page

Here, you are able to see the workflow association page. Select a workflow template and give each field an appropriate value, and click OK. The association form will then show up.

Note that initiation forms and association forms are not easily distinguishable by their looks!

“Introduction to designing and customizing workflows” describes workflow types and when to use them.

 
How to set parameters in order to receive user input

Initiation Form Parameters button

First step for setting input parameters is to find the “Initiation Form Parameters” button in the “Variables” section in the ribbon. Pressing it will pop up an “Association and Initiation Form Parameters” dialog.

Association and Initiation Form Parameters dialog
Click on the “Add” button to insert a new parameter in “Add Field” dialog. The other buttons will be covered below.

Add field dialog
As you can see, there are 4 fields which can be filled, “Field name”, “Description”, “Information type” and “Collect from parameter during”.

Field name and description will be displayed as strings to users and have no impact functionally, where any texts can be inserted. I recommend you to fill in the fields with descriptive expressions.

Information type is a predefined set of data types that are part of the initiation and association data. The value here can be:

· Single line of text

· Multiple lines of text

· Number (1, 1.0, 100)

· Date and Time

· Choice (menu to choose from)

· Yes/No (check box)

· Person or Group

· Hyperlink or Picture

· Assignment Stages

Last but not least, the last field asks when its data should be set. The value here can be “Initiation (starting the workflow)”, “Association (attaching to a list)” or both. This field does not exist on the dialog opened from a List, Site, or Globally Reusable workflow since its data can only be set during initiation.

You can set the initial value for this field or leave it blank on the next page and complete this section.

What happens if you add one initiation parameter as shown above?

Starting Form Parameters dialog - after adding a parameter

A new field has just emerged. There are 3 values for “Show on Form”, these values are “Initiation”, “Association”, and “Both”. These options pertain to what is chosen in the “collect from parameter during” field. You can add another parameter by the “Add” button. Selecting a field will enable the “Modify” and the “Remove” buttons. The “Modify” button will open the “Modify Field” dialog which is exactly the same as the “Add Field” dialog but with the values preset to what you initially added. The “Remove” button will erase the field selected. When there are at least two or more fields in the dialog and if you select a field the “Move” buttons will become enabled and let you adjust the order of the fields. Changing the order here will directly make the same changes in the starting forms which are automatically built and also modifiable.

“Workflow Association and Initiation Forms (SharePoint Foundation)”gives you technical information with regard to forms.

Default form example 
This is the default form made by SharePoint Designer, which is displayable and modifiable by InfoPath. You can also take it as a preview of what users will see during the workflow instance initiation.

Default form example match

As you can see, the field name and the description are explicitly displayed in the default form. “Start” and “Cancel” buttons are used to confirm and call off an initiation of the given workflow instance, respectively.

Details on every field type

Details on every field type
Listed here are all the possible starting parameter type instances in a page. Currently 10 types are supported as the starting parameter although there are more variable types in SharePoint Designer.

Each type can have a default value, description, and other restrictions such as valid input range. Moreover, the automated initial form is customizable with InfoPath with which you can modify the text, image and layout.

1) Single line of text

Image 1

The “Single line of text” is a field to receive one line of string. Default value can be set from the dialog above, which will be displayed in a line. Although the character limit for this field is quite long, I recommend you to use “Multiple lines of text” field instead of this if the string cannot fit on one line.

2) Multiple lines of text

Image 2

This is for receiving long strings. The “Single line of text” and the “Multiple lines of text” are visually different, but treated as the same SharePoint Designer string variable type.

3) Number

Image 3

The “Number” field is able to receive a number as a ‘double’ type. This means that not only can integers and positive number be accepted, but fractional values and negative values can also be injected. A default value can be set or left blank. You can also set minimum or maximum values for this field to prevent users from entering numbers that are too small or too large.

4) Date and Time

Image 4

The “Date and Time” type has few options to aid you in setting appropriate values. First of all, you can choose the value type between “Date only” and “Date and Time” . If “Date only” is chosen here, only date values will be displayed and modifiable on the form, while both date and time will be available for “Date and Time” .

Image 4-2

The very bottom check box option restricts user input values to be no earlier than the moment the form is opened. This is beneficial in many real scenarios to avoid mistakes. For instance, when it comes to setting approval deadlines or vacation dates, usually the date and time have to be a date or time in the future.

Of course, initial values can also be set for data and time to guide users. Today’s date and current time are also given as options.

5) Choice

Image 5

The “Choice” type allows you to use dropdown menus. Each choice has to be written as a line of text, and a default value can be set or left empty.

Image 5-2
For the text-based designer’s sake, it provides an option to separate the text displayed on the form and the string value being used during design time within SharePoint Designer text-based designer. If a vertical bar is inserted into a line, the left string will become the value within the text-based designer, while the other side will be shown during the initiation and association.

6) Yes/No

This provides a check box to users when the workflow starts. The only thing to set is the default value.

Image 6

7) Person or Group

Image 7 
The “Show Field” option can be ignored for now, since every time a user or group is selected, the user or group will always be shown via their display name. Not allowing blank values can force users to select at least one person or group to complete the given form and proceed.

You can decide whether to allow groups to be selected or not. It is also possible to limit which SharePoint Groups can be used to pick a person or group. Choosing “All Users” will allow users to pick from all accessible sources.

Image 7-2

“People and Groups” should be selected and “Allow multiple values” must be checked in order to receive the user input above.

Image 8

You can decide if you would like the URL to be displayed as a “Hyperlink” or a static “Picture”.

Image 8-2

This option will inject a button and a text based hyperlink into the target form. After clicking on this option, users will need to specify the URL and its description. For example, if you put “https://microsoft.com” and “Microsoft” respectively, this part of the form will become as below.

Image 8-3

The link is already set to link to https://www.microsoft.com/en-us/default.aspx. The user can still modify the link by clicking on the button on the left side.

9) Picture

Image 9

You can decide if you would like the URL to be displayed as a “Hyperlink” or a static “Picture”.

Image 9-2

A picture can be set with a URL and a description just the same as a hyperlink. This will inserts the target picture into the form right away, which can be replaced by clicking on it and writing another URL. The description is shown when the cursor is hovered above the picture. The picture above shows an example of this where the “SPD blog” text is the description.

10) Assignment Stages

The “Assignment Stages” is useful only in the Office Task. Be sure not to take advantage of this parameter without the Office Task.

Image 10

Image 10-2

The “Assignment Stages” is unusual in a couple of aspects. It cannot be referenced from the text-based designer unless it is inherent from an Approval workflow, and it can expand stages dynamically. Each stage is a combination of the people picker and an assignment order type, either serial or parallel.

The concept of the “Assignment Stages” is a very complicated but powerful component which I won’t be able to fully explain in this one post. But I plan on making another blog post just on the Office Task soon, in which I will be able to talk further about this concept.

Summary

The starting parameters are used for receiving user input to workflows. There are two type of starting parameters, the initiation parameters and the association parameters. You can set ten types of starting parameters according to the scenario you are you using your workflows for. Each type of parameters has useful options to guide end users.

If you wish to know more about making and using the initiation parameters, “Create a workflow initiation form” office support document has a decent explanation. But please note that the document is for SharePoint Designer 2007 and is hence outdated.

In part 2, I will depict how to use the parameters received at designing workflows.

Thank you everyone for taking the time to read this blog posting. I hope it was helpful to you.

Please feel free to leave comments below.

Regards,

Chong Youn (John) Choe