Understanding workflow starting parameters - Part 1

Hello 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.

When you click on an item in a list,

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

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.

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

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!

How to set parameters in order to receive user input

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.

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

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?

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.

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.

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

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

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

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

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

The “Date and Time” type has few options to aid you in setting appropriate values. First of all, you can choosethe 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”.

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

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.

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.

7) Person or Group

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.

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

8) Hyperlink

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

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 “http://microsoft.com” and “Microsoft” respectively, this part of the form will become as below.

9) Picture

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

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.

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.

@Hemant - It's our pleasure to describe features, more so to have people who read the posts just like you. Thanks.

@Victor - Thanks a lot for the tweet!

Tom Holcomb

4 Aug 2011 2:15 PM

Thanks for the great post. Is there any way to suppress the initiation form if i don't need information from the user? I'm trying to eliminate that unnecessary click on "Start"

Soumya Chakrabarti

19 Sep 2011 5:41 AM

Hi John,

Can you please throw some light on "The “Show Field” option in Person or groups"?

Where we should use this field...

cherry

17 Oct 2011 1:16 AM

British reporters are known for doing almost anything to get a Mulberry Bags. But reports that a newspaper secretly listened to telephone messages of murdered schoolgirls and other private citizens have produced Mulberry Handbags and anger.

On Friday, British police arrested Andy Coulson, former editor of Mulberry Bag Britain's best-selling newspaper, News of Mulberry Outlet the World. The investigation led him to Mulberry UK Sale resign in January as communications director to Prime Minister David Cameron.

The arrest came in a widening investigation of Mulberry UK telephone hacking. Other accusations include paying police for mulberry shoulder bags information on stories. The Reuters news agency reported that Mr. Coulson was released on Mulberry Bag UK until a date in October.

Prime Minister Cameron promised Men's Mulberry Bags Friday that a judge will lead a full public inquiry into Women's Mulberry Bags the case after police complete their investigation.

DAVID CAMERON: "Murder victims, terrorist victims, families who have lost loved ones, sometimes defending our country, that these people could have had their phones hacked into, in order to generate stories for Mulberry Bags Mulberry Handbags Mulberry Bag Mulberry Outlet Mulberry UK mulberry bayswater bag Mulberry Alexa Bag, is simply disgusting."

Jon

17 Oct 2011 11:53 AM

Hi John,

Will you be completing part 2 of this posting? Bit of a cliff hanger with this mysterious "Office Task" only thing with the Assignment stages feature.

Sorry for this late response. We've been busy for a while, but are going to resume posting from this month.

@Tom : It is impossible within SPD as far as I know. I'll update information if any.

@Soumya : I've heard once that it has noticable difference on Infopath. I'll try to make it clear soon.

@Jon : Yes. (Actually, I had wanted to finish the posts-part2, and Office Task- around now, but it's being delayed.)

Shiva

20 Feb 2012 6:32 AM

Thank you for your information. It's really useful..

rkd993

23 Feb 2012 3:42 PM

Any further updates? Thanks.

Andrew

28 Feb 2012 4:42 AM

Part 2?

Kalai

19 Mar 2012 4:14 AM

@John, I need to update workflow status based on the current approval stage (pending with dept mgrs,pending with hr mgrs etc.). Is there any handy field in sharepoint 2010 approval workflow to do that.