This article is taken from the book
SharePoint 2010 Workflows in Action. The author uses a practical
example to show how to employ the components of a SharePoint workflow.
Get 40% off any version of
SharePoint 2010 Workflows in Action with the checkout code dnspark40. Offer is only valid through
We're going to create a PTO request system using SharePoint lists and workflows.
The example is divided into several sections, with each section focusing on
different workflow components. Also, each section builds on the previous
sections, so make sure to go through the example in order.
section will concentrate on building the lists necessary to support the PTO
workflow. In the second section, we'll create a simple logging workflow. Then,
we'll add basic functionality that handles notifications when a PTO request is
submitted and, lastly, we'll add advanced functionality that tracks the
available hours of PTO.
The sample PTO request
calendar will allow employees to go to a calendar and create a new item that
spans the length of their requested PTO. The workflow that will be built in the
next section will route that request to the employee's manager. But before we
build that workflow we first need to create the calendar, and set up content
approval. Follow the steps in table 1 to create this PTO Calendar list.
1 Setting up your PTO Request Calendar list
|Create a new Calendar list in SharePoint Designer.
||Open SharePoint Designer from the desktop or Start menu and connect
to your SharePoint site using the Open Site button.
Click the Lists and
Libraries under Site Objects. Click the SharePoint List Ribbon button (see
figure) and select the Calendar list.
the new calendar PTO Calendar and click OK.
|A new calendar will be created.|
|Set up content approval on the PTO Request Calendar.
||Click the PTO Calendar link under Lists.
After creating a new list, it will appear on the Lists and Libraries tab.
Opening the list from here does not give you access to the data within the list
but allows you to adjust the lists settings.
Under Settings, check the box
for Require content approval for submitted items, and then save your work by
clicking on the Save button.
opening the list, you can adjust a variety of list aspects. The Settings section
allows you to enable content approval, which is needed for the PTO
With our PTO calendar set up,
employees can start submitting their PTO requests. Now, we build the workflow
that helps facilitate their approval!
Having set up our calendar, we can now build the PTO request
workflow. Before adding logic to the workflow, let's build a simple workflow
that performs logging and publish that workflow to the calendar to make sure
everything is deploying properly. Follow the steps in table 2 to create a basic
SPD workflow and publish that workflow to the PTO Calendar.Table 2
Creating a new workflow that logs to the workflow history list
|Create a new list workflow off the PTO Calendar.
||1. Connect to your SharePoint site with SPD and click on the
workflow's Site Objects button on the left.
2. Click the List Workflow
button on the Ribbon and choose the PTO Calendar.
Name the new workflow PTO Workflow and click OK.
|A new list workflow will be bound to the PTO Calendar after it's
published. At this point, the workflow will be empty.|
|Set up a dedicated History List that you can use to log workflow
||4. In the breadcrumb (figure 1), click on the PTO Workflow link to
access the workflow settings.
5. Select New History List. for History List.
Click OK on any pop-up dialogs. After you click OK, a new history list called
PTO History List will be created automatically.
Instead of creating a new history list we could use the predefined history list.
In some cases, this is OK, but, in other cases, it's helpful to log each
workflow's history to a dedicated list. This is true for complex workflows that
are generating numerous log messages. Having the history logged to a dedicated
history list can make troubleshooting easier because you will not be sifting
through the log messages of multiple workflows. For simple workflows or
workflows that do not have many log messages, a shared history list is
|A new list to which the workflow can log will be
Figure 1 As you dig deeper into the workflow
settings and editor, you will need to use the breadcrumbs displayed beneath the
tabs. The breadcrumbs not only show you exactly where you are, but they allow
you to move to different levels of the workflow editing process.
Creating a new workflow that logs to the workflow history list,
|Specify that the workflow should start automatically when a new PTO
request is created.
||While you are still in the PTO Workflow tab via the breadcrumb
(figure 3.17), under Start Options, check Start workflow automatically when a
new item is created.
|Add a logging action to log that the workflow has started.
||1. Under Customization, click on the Edit Workflow link.
Click the title of Step 1 and rename the step PTO Workflow Initiation.
Click inside the step and then click on the action dropdown (in the Ribbon) to
show the list of actions. Click Log to History List action and change the
message to PTO Workflow Started.
|A single action will be in the workflow that logs to the history
list. After the publishing, the workflow is bound to the PTO Calendar and will
fire when new requests are created.|
|Click the Publish button in the Ribbon and test the workflow.
||1. Click the Publish button, open the SharePoint site using Internet
Explorer, and browse to the PTO Calendar.
2. Create a new calendar item.
Then, verify the workflow ran successfully.
3. Navigate to the workflow
status page by clicking the Completed text in the status column and verify the
workflow's history was populated from your logging action.
the workflow ran successfully and the PTO Workflow Started message was logged to
the history list, you're ready to move on to the second example. If not, recheck
We now have a simple workflow deployed
onto our PTO calendar. The workflow isn't powerful yet. In fact, it only logs to
the history log. Now, it's time to start sending emails when PTO requests are
Now that the workflow is running automatically and logging
successfully, it's time to add more advanced functionality. We'll add conditions
and actions to notify the user's manager that a PTO request was submitted. We'll
also add logic and actions to notify the user whether or not their request was
approved or rejected. Finally, we'll add error handling in case something goes
wrong with the approval. The approval of the PTO Request will be done through
the out-of-the-box content approval features. Follow the steps in table 3 to add
this managerial approval to the PTO Request workflow.
Table 3 Adding
managerial approval notifications to the PTO Request workflow
|Add a manager lookup action to the workflow.
||1. Add a step after the PTO Workflow Initiation step and name it PTO
2. Within this new step, add a Lookup Manager of a User
action using the Actions button on the Ribbon.
NOTE: The lookup manager
action is under the Relational Actions category.
3. Set the action to look
up the manager of the user who created the PTO Calendar item by clicking the
This User link, and then click OK.
The Select Users dialog box allows you to select a dynamic user, such as the
User who created the current item, or a specific user. You can also perform a
look based on workflow data.
|Add a Send Email action.
||NOTE: If your environment does not have outgoing email
configured or you cannot use email for any reason, use a Log to History action
instead of the Send an Email Action. Be sure to configure the Log message to
include references to the same data, such as Manager and Created By, to ensure
that these components are working.
Add a Send an Email action to the step
after the Manager Lookup action.
|Specify sending the email to the manager.
||1. Click the These Users link on the email action to open the email
2. Click the address book icon next to the To: field
to select a user to be emailed.
3. Select Workflow Lookup for a User. and
click the Add button in the center of the dialog.
4. Change the Data source
to Workflow variables and Parameters in order to select the manager
5. Select Variable: manager for the Field from source. Then change
the Return field as dropdown to Email Address, and click OK twice.
|The email is now configured for sending to the requestor's
|Configure the contents of the email message, including the subject
and the body of the email.
||1. In the email configuration dialog box, click the ellipsis after
the Subject field to add subject line text.
2. Add text and a lookup for the
Created By field to the subject line using the Add or Change lookup
The Subject line of the email action can include workflow data. In this case,
the Created By field has been added to the subject line along with some static
3. Add text and a lookup to the body, including a link to the PTO
Calendar item, again using the Add or Change lookup button.
Like the Subject line, the email body can include static text and workflow data.
Including all relevant data in the email will allow the end user to take action
or make a decision without necessarily having to open the SharePoint item in
4. Click OK to close the email action editor and save your
|The email subject and body are
At this point, we want to pause the
workflow until the user's manager either approves or rejects the PTO request. We
will also need to check the Approval Status field on the item to determine how
the manager responded to the request. Note that the values in the Approval
Status field contain special characters along with the text; these are required
for an equals comparison. You could use a contains comparison instead, but the
equals comparison is more efficient because it does not need to examine the
string characters one by one.
Table 3 Adding managerial approval
notifications to the PTO Request workflow, continued
|Add a pause action to wait for the request to be approved or
||1. Add a Wait for field change in the current item to the PTO
Workflow Approval step.
2. Set the field to Approval Status, the operator to
not equal, and the value to 2#;Pending.
a workflow: The Wait for field change in the current item action allows you to
suspend the operation of the workflow until certain criteria are met. In this
case, the workflow will pause until the PTO request is either approved or
|Add an if condition to check if the PTO Request was approved.
||1. Add another step to the workflow and name it PTO Workflow
2. Add an If current item field equals value condition to the
3. Set the field parameter to Approval Status and the value to
4. Add a Send an email action to the if condition and configure
it to notify the creating user that his request is approved.
the if condition will be a Send an email action notifying the requestor that his
request has been approved.
Again, if email is not
available, use a Log to History instead of the Send an Email action. Include all
of the referenced fields in the log message to ensure that everything is working
We now need to add an email notification that will go to
the user that created the PTO request when the request is approved. We also need
to create an else-if condition to check for a rejected request and send an email
Table 3 Adding managerial approval notifications to the PTO
Request workflow, continued
|Add an else-if branch to check if the PTO request was rejected.
||1. Add an else-if branch to the condition using the Else-If button
on the Ribbon.
2. Add an If current item field equals value condition to the
3. Set the field parameter to Approval Status and the value
4. Add a Send an Email action to the condition and configure
it to notify the creating user that their request was rejected.
the else-if condition will contain a Send an Email action notifying the
requestor that their request has been rejected.
the Approval Status field is not equal to Approved or Rejected at this point,
something went wrong with the workflow. Instead of stopping the workflow, it's
important to let the users know. In the real world, it would also be beneficial
to notify whoever is responsible for maintaining the workflow that an error
occurred. These notifications can be done by adding another else-if with no
conditions. Table 3 Adding managerial approval notifications to the PTO
Request workflow, continued
|Add another else-if to notify both the manager and the requestor that
an error occurred.
||1. Add another else-if branch to the end of the step.
2. Add a
Send an Email action to the final else-if branch.
3. Configure it to notify
both the user and the manager that an error occurred.
the workflow and create two test items on the PTO calendar as your test user.
The manager of the test user will receive two emails, one for each PTO calendar
item. As the manager, approve one request and reject the other. The test user
will receive two email notifications, one for each PTO request.
options for managing approvals
There are multiple approaches to getting
approval within workflows. This example uses the built-in content approval
functionality, but instead we could have used the out-of-the-box Approval
workflow. In this scenario, the manager would be assigned a new task in the task
list instead of being sent an email. The manager could then use this task to
approve or reject the PTO request.
The last step will be to configure a second
list to track how many remaining PTO hours each employee has. This list will
help the manager to decide whether to approve or reject the request because it
tracks the cumulative and the remaining PTO hours for each user. If the PTO
request is approved, this new list will be updated to reflect the number of
remaining and used PTO hours for the requestor.
To get started, let's first
set up this PTO tracker list. In SharePoint Designer, click on the Lists and
Libraries site object menu. Click on the Custom List Ribbon button to create a
new custom list named PTO Tracker. After the list is created, add a column of
type Person or Group, and name the column Employee.
Click OK to save the
changes to the Employee column. Switch back to SharePoint Designer and add two
Number columns to the PTO Tracker list. One list should be named Available
Hours, and the other column should be named Used Hours (figure 2).Figure 2 List columns can be added to a list
in SharePoint Designer. It's much easier to add numerous columns to a list with
Designer because you do not need to wait for page refreshes that occur when
adding columns using the browser-based settings page.
Changes to lists
made in SharePoint Designer do not take effect until you press the Save button.
The result is that any workflows you are editing will not be aware of the newly
added columns until the changes to the list have been saved. When making changes
to lists directly in SharePoint, those changes take effect immediately and
clicking on a Save button is not required. These different behaviors can be
confusing when switching back and forth from SharePoint Designer to SharePoint,
so make it a habit to always save list changes when working in SharePoint
Click on the Save button to save the changes to the list. Open
the PTO Tracker list in SharePoint and add an item for your test user. For the
test user, set Available Hours to 80 and the used hours to 0 and save the item
(figure 3).Figure 3
Add a new item to the list using the
SharePoint interface to mimic how the end users will interact with the system.
This test item will allow you to test the calculation of Available and Used
To use and modify the data from the PTO Tracker list in your
workflow, you need to capture the data using variables. These variables can then
be modified as required and eventually applied back to the PTO Tracker list. You
can also add these variables into the email message body, so the manager will be
able to see in the email if the PTO requestor has a positive PTO balance. Follow
the steps in table 4 to set up these variables pointing to the PTO Tracker list
and to reference them in the email body.Table 4 Updating Request
Notification to include available and used hours
|Add a Set Workflow Variable action and reference a new variable
titled Available Hours.
||1. Switch back to SharePoint Designer and add a Set Workflow
Variable action as the first action in the PTO Workflow Approval step.
Click the Workflow Variable link in the action and choose Create New Variable at
the bottom of the dropdown.
3. Name this variable Available Hours and give
it the type Number.
|The Set Workflow variable action will be added to the workflow and
will be configured to assign data to a new variable titled Available
To find the correct item on the PTO Tracker
list you need to tell the workflow which item you are looking for. Setting the
Ensure Unique Values option earlier will prevent duplicate entries, which would
confuse the workflow.Table 4 Updating Request Notification to include
available hours and used hours, continued
Figure 4 The Find Interval action is used to
find the days, hours, and minutes between two Date and Time fields. In this
example you are calculating the hours between the PTO request's start and end
time to determine how many hours to subtract from the employee's available
|Set the value of the Available Hours variable with the requestor's
available hours from the PTO Tracker list.
||1. Click the Value link on the action. Click the Ã‚Â¦x button in the
popup. Set the Data source to the PTO Tracker list.
NOTE: The Lookup dialog
allows you to use the data from one list to find a specific record in another
list. In this case, you are looking for a specific row in the PTO Tracker list,
identified by the data in the Created By field of the current list.
the Field from source to Available Hours to capture the PTO hours remaining for
the specified user.
3. Set the Field to Employee and the value to the
Current Item:Created By (Ã‚Â¦x button), then click OK.
When you click OK, you will see a warning about ensuring unique lookups; click
OK to the warning.
4. Repeat steps 1 and 2 to store the used hours from the
PTO Tracker in a variable named Used Hours.
|You'll have two new variables, one called Available Hours and one
called Used Hours. These variables are referenced in an email to the manager so
they can make an informed decision.|
|Use the Find Interval action to calculate the amount of PTO
requested. Store the number of hours in a variable called Requested Hours.
||1. Add a Find interval between dates action. Set it to find the
number of hours between the Current Item:Start Time and Current Item:End
2. Configure the Find Interval action to store the hours in a new
variable called Requested Hours. This will be used to calculate the available
and used hours later.
|The Find Interval action (figure 4) is used to calculate the number
of hours that were requested as PTO. The action is looking at the start and end
times on the PTO Calendar item.|
|Update the email message body to include how many hours of PTO the
employee is requesting, how many they have available, and how many they have
||1. Modify the Send an Email action to include the available hours,
used hours, and requested hours in the message body.
With the email message going to the manager now updated and
showing the data, you need to obtain the manager's response. If the manager
approves the request, the requested PTO hours need to be deducted from the PTO
Tracker list. Follow the steps in table 5 to accomplish this
action.Table 5 Updating the employee's available hours when the request
|Add a Do Calculation action that subtracts the Requested Hours
variable from the Available Hours variable.
||1. Add a Do Calculation action to the PTO Workflow Notification
2. Click on the First Value link and set it to the variable Available
Hours. Set the Operator to minus to subtract the available hours from the
NOTE: To select a workflow variable, change the Data Source
to Workflow Variables and Parameters.
3. Set the Second Value link to the
Requested Hours variable.
4. Set the Output to field to the Available Hours
|The Available Hours variable will be updated by subtracting the
|Add another Do Calculation that adds the Requested Hours variable and
the Used Hours variable.
||1. Add another Do Calculation action to the PTO Workflow
2. Click the First Value link and set it to the Used
Hours variable. Set the Operator to Plus in order to add the requested hours to
the used hours.
3. Set the Second Value link to the variable Requested
4. Set the Output to field to the Used Hours variable.
|The Used Hours variable will be updated by adding itself to the
Now that you have updated the data
within the variables, you need to write this data back to the PTO Tracker list
to store it permanently. Remember that when the workflow finishes, the data in
the variables is lost. Using the Update List Item action you can set the values
of multiple fields of an item with a single action. You only want to save the
data back to the PTO Tracker list if the PTO request was approved. If it was
rejected, you don't need to save the data. Perform the following steps to save
the data back into the PTO Tracker list.Table 5 Updating the employee's
available hours when the request is approved, continued
|Within the Notification Step and inside the Approved If-else
condition, add an Update List Item action to update the PTO hours data.
||1. Add an Update List Item action. Click the This List link. Change
the list dropdown to PTO Tracker.
2. Click on the Add button. Set the
dropdown to Available Hours. Set the value to the Available Hours variable.
3. Click on the Add button again. Set the dropdown to Used Hours.
Set the value to the Used Hours variable.
4. Click OK.
|The Update List Item action will write back to the PTO Tracker list,
updating the requestor's available PTO. |
|In the Update List Item action's This List popup, use a lookup to
find the correct item in the PTO Tracker list.
||1. In the Find the List Item section, set the Field dropdown to
2. Set the Value field to Current Item:Created By using the Ã‚Â¦x
3. Click OK on the This List pop-up.
NOTE: You will again see the
message about ensuring unique values. Click Yes because you are enforcing unique
items on the list.
|The Update List Item action will be configured and, when PTO requests
are approved, the data stored in the variables will be written back to the PTO
Publish the workflow and create a new
item on the PTO Calendar as a test user. Approve this item as the test user's
manager. On the PTO Tracker list, you should notice that the available and used
hours were updated correctly (figure 5).Figure 5 After running the workflow with the
advanced functionality, the PTO Tracker list will be updated to show how many
PTO hours each employee has used and how many are still available.
Steps and conditions can be used to
organize your workflows and make them easier to read and maintain. Actions allow
you to build workflows that do a variety of tasks, including creating and
updating list items and sending notifications to users. In addition, if and
else-if statements are available to add logic to your workflows, allowing them
to make decisions. Variables can be used to store data, which can later be
referenced throughout your workflow such as within an if/else condition. All of
these components can combine to build powerful workflows, including the example
described in this article, a PTO request system