Creating a SharePoint Designer workflow

By Peter Bromberg

Access over 40 UI widgets with everything from interactive menus to rich charts.

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.

This article is based on Sharepoint 2010 Workflows in Action by Phil Wicklund, to be published December 2010. It is being reproduced here by permission from Manning Publications. Manning early access books and ebooks are sold exclusively through Manning. Visit the book's page for more information. You can get an instant 40% discount on this MEAP edition by simply clicking on the link above, and use promo code egghead40

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.

The first 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.

Configuring a PTO calendar

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.

Table 1 Setting up your PTO Request Calendar list

Action

Steps

Result

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.

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

NOTE: 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.

After 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 workflow.

With our PTO calendar set up, employees can start submitting their PTO requests. Now, we build the workflow that helps facilitate their approval!

Creating a custom workflow that logs to the History List

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

Action

Steps

Result

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.

3. 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 information.

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.

NOTE: 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 fine.

A new list to which the workflow can log will be created.

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.

Table 2 Creating a new workflow that logs to the workflow history list, continued

Action	Steps	Result
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. 2. Click the title of Step 1 and rename the step PTO Workflow Initiation. 3. 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.	If 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 your steps.

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

Adding notifications to the custom PTO Request workflow

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

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

Action

Steps

Result

Add a manager lookup action to the workflow.

1. Add a step after the PTO Workflow Initiation step and name it PTO Workflow Approval.

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.

NOTE: 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.

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 ActionNOTE: 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 question.

4. Click OK to close the email action editor and save your changes.

The email subject and body are defined.

Action

Steps

Result

Add a pause action to wait for the request to be approved or rejected.

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.

Pausing 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 rejected.

Add an if condition to check if the PTO Request was approved.

1. Add another step to the workflow and name it PTO Workflow Notification.

2. Add an If current item field equals value condition to the new step.

3. Set the field parameter to Approval Status and the value to 0;#Approved.

4. Add a Send an email action to the if condition and configure it to notify the creating user that his request is approved.

Inside 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 as designed.

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

Table 3 Adding managerial approval notifications to the PTO Request workflow, continued

Action

Steps

Result

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 else-if branch.

3. Set the field parameter to Approval Status and the value to 1;#Rejected.

4. Add a Send an Email action to the condition and configure it to notify the creating user that their request was rejected.

Also, the else-if condition will contain a Send an Email action notifying the requestor that their request has been rejected.

If 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

Action

Steps

Result

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.

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

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

Adding calculation logic to the workflow

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

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

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

Action

Steps

Result

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.

2. 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 Hours.

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

Action	Steps	Result
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. 2. Set 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. NOTE: 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 Time. 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 used.	1. Modify the Send an Email action to include the available hours, used hours, and requested hours in the message body.

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

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 is approved

Action

Steps

Result

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

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 requested hours.

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

The Available Hours variable will be updated by subtracting the Requested Hours.

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 Notification step.

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

4. Set the Output to field to the Used Hours variable.

The Used Hours variable will be updated by adding itself to the Requested Hours.

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

Action

Steps

Result

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. Click OK.

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

2. Set the Value field to Current Item:Created By using the ¦x button.

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 Tracker list.

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.

Summary

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.

Popularity (4815 Views)