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!
“Introduction to designing and customizing workflows” describes workflow types and when to use them.
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.
“Workflow Association and Initiation Forms (SharePoint Foundation)”gives you technical information with regard to forms.
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 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” .
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 “https://microsoft.com” and “Microsoft” respectively, this part of the form will become as below.
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
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.
Please feel free to leave comments below.
Regards,
Chong Youn (John) Choe
Comments
Anonymous
July 07, 2011
Hi, I am Chong Youn Choe. You can also call me John. Sorry for being late. We are going to try our best to post continuously- once a month at least as promised. Any comment or suggestion is appreciated. :) P.S.) A few images, cracked while uploading, will be recovered in a couple of days.Anonymous
July 08, 2011
"- image to be inserted" Could you please ping @sharepointnow when images are fixed. Thanks.Anonymous
July 10, 2011
Hi, victor. Thanks for the comment. '@sharepointnow' might mean tweeter. But I could not ping since I'm not sure about it. Would you mind to explain it? Anyway, this post has been updated and is now complete. Thank you!Anonymous
July 12, 2011
Hello John, Great Post. Very well explained. Thanks HemantAnonymous
July 14, 2011
@spdblog, yes, twitter, i meant "please let me know via twitter when this is updated" Thank you for fixing images. I tweeted it out just now,Anonymous
July 17, 2011
@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!Anonymous
August 04, 2011
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"Anonymous
September 18, 2011
Hi John, Can you please throw some light on "The “Show Field” option in Person or groups"? Where we should use this field...Anonymous
October 16, 2011
The comment has been removedAnonymous
October 17, 2011
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. Thannks for posting this one! JonAnonymous
November 03, 2011
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.)Anonymous
February 19, 2012
Thank you for your information. It's really useful..Anonymous
February 23, 2012
Any further updates? Thanks.Anonymous
February 27, 2012
Part 2?Anonymous
March 18, 2012
@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. ThanksAnonymous
March 22, 2012
@ Kalai "Set workflow status" action sets the status of given workflow. while "Current Task:Assigned To" gets who is holding the task now. One example to take advantage of it is...
- Copy and Edit the OOB Approval
- Dig into Approval Workflow Task -> Task Behaviors -> spot "When a Task is Pending" block - the block is a chunk of actions executed every time a task is created.
- Add a chunk of actions to update the status depending on who the task is assigned to - you need to know how to use lookup, "if" comparison, and insert actions. The rest is straight forward. - Sample Code If Current Task:Assigned To equals "HR employee" Set workflow status to "Pending at HR" Thanks @ rkd993, Andrew Many sorries :( I haven't given up posting new ones but somehow I couldn't yet. Thanks for taking care, I'll try to put up part2 before it's too late.
Anonymous
March 26, 2012
Wow, I’ve definitely learned the techniques in this comprehensive tutorial. They help me in future projects.Thank you for sharing this information.Anonymous
March 28, 2012
Can attachments from local folders or a SharePoint library be selected by the end user (person initiating a specific instance of the workflow) from an initiation form and included in the workflow? If so, can this be configured without code? thanks, DavidAnonymous
May 06, 2012
@spdblog Many thanks. That helped me a lot. I used multiple approval processes to change the status text (instead of different stages on same process).Anonymous
June 26, 2012
i have created a work flow with the set of conditions. Email to the users. when i click users i just refer particular column which contains email ID in To field to send email. when i start the workflow only the first row is executed and email is sent for that field i refer. how can i start the work flow by selecting full list. Please helpAnonymous
July 04, 2012
Thanks for sharing. I have been article share for everybody about topic sharepoint2010template.com/.../GuideAnonymous
September 05, 2012
原文发布于 2012 年 8 月 18 日（星期六） 大家好！ 我是 Chong Youn (John) Choe，SharePoint Designer 团队的项目经理。SharePoint