SharePoint Workflow Best Practices

Note that I will add some screenshots in the near future.  Comment if there is something that I should expand on.

Automation is key to streamlining business processes to really leverage SharePoint and get a good return on investment in configuring SharePoint.  Most of the workflows you may have already seen were simple and only created an email notification, but out of the box SharePoint Designer workflows can do so much more.

There are two other ways to get a workflow.  You can use an out of the box workflow from SharePoint like Collect Signatures or the three-step workflow, but I’d advocate against them.  Like most things Microsoft did with these workflows or the Fab 40 templates if you can remember when Microsoft released those for SharePoint 2007, they are to be seen as examples of what you can do more than released into production.  You can also create workflows with Visual Studio.  I’d suggest that if you can do it with SPD, use SPD.  If you cannot use SPD or you don’t want to run the risk of having a site collection admin breaking something, use Visual Studio, but hire someone really smart to use Visual Studio and ensure that you work in an environment where it is allowed through governance before you start.  Using Visual Studio expands simple tasks such as inserting logic steps and breaks it down into actual code, making it difficult to debug if something goes wrong.  Save yourself the headache and just use SPD whenever possible.

Here are some of my best practices you should remember when designing a workflow.

1.      Draw out your business work process on paper before you begin.

Most people need this visual aid to show the start, goes to Mr. X, gets reviewed by Ms. Y, and published by Dr. Z.  Draw the stick figures and identify what the triggers are that take you from one to another and the next.  Identify what needs to happen at each stage.  If you know that the reality of the work is to tell Dr. Z that a package is on the way when Mr. X gets it, automate it.  Workflows can take multiple paths and can create, read, update, or delete items in other lists if necessary.  Want to make it pretty and don’t have Visio?—I use  Use PowerPoint if you really have no other alternative.  The first time you draw it out, however, should be all of the stakeholders in the room with a big white board.  Challenge everything about that workflow.  Be clear with them to identify the differences between their business processes and the workflow.  The way you need to build it in SharePoint probably won’t look exactly like the swimlane diagram someone hands you.

2.      Write out your workflow in plain words on paper to say what needs to happen at every step in the business work process to accomplish this.

Write out very simply something like this:

start workflow set workflow variable check flag for notification if flag not set, send notification, set flag, create item in package tracker list if status is publish, update tracker list, copy document to published library, and create announcement etc.

All of that will help you find the gaps in where you might need to create that column for each flag (hidden choice columns usually) so that when your workflow runs a second, third, or fourth time it does not create another email notification, another item in a tracker, or another announcement.  You need to identify where you do not want the workflow to run over and over and where you would need it to run over and over.

3.      Get your stakeholders to sign their name to the business process.

Time and time again I have seen pipe dreams sold to me as what the actual process is when it rarely if ever follows the documented process.  If there are more exceptions to the rule or the office cannot agree to what a process is, walk away until that office’s leadership can.  Note that you might be building this for one office who needs input from other offices, so ensure you really know who all of the stakeholders are.

4.      Use an index card to walk your item through the workflow on your desk.

Sometimes I use Post-It Notes ® or Sticky Notes on the computer to show the routing on my desktop if I’m using one of my better resolution screens.  This is just to get good visualizations to explain your user story back to the customer or just help you get your head wrapped around what your customer’s users are doing.  The index card is good so you have room to write down key column names so you can identify where things update.

5.      Name your workflow correctly.

On all of the list workflows, I make precede the workflow name with the name of the list.  It just makes it easier to find in case I have many other lists with their own worklfows.  If the workflow is to change the permissions on a personnel roster, it would look something like this: Personnel Roster – change permissions on change.  If you are using a content type workflow, precede it with the content type name.  If you are using a site workflow, precede it with the site name or Site WF.

6.      Fill in the description.

A good name doesn’t absolve you from adding content to your description.  I don’t know how many times I’ve seen similarly named workflows on the same list that I’ve had to read all of the steps to know which workflow does what.  Include in the description your name, maybe a link to the documentation you have on it, and a revision date.

These little things will not just help you when you are asked to make a change six months after you created the workflow, but it will keep people from badmouthing you if someone is looking at one of your workflows after you left an organization.  Imagine you were asked to change some complex workflow.  You open up SharePoint Designer to open it up and you see all of the documentation linked.  You would want the person who made that workflow on your team again.  Your reputation for how you do this will get around, especially if you speak at SharePoint user groups and remind them that this is what you do. 😉

7.      Rename your stages and steps.

This should be obvious, but I still do it often.  Especially if you have a longer workflow, rename the steps and stages so you can quickly find where things should happen.

8.      Name all of your variables up front and initialize their values.

It is like traditional programming where you declare your variable.  It is just a good thing to do this up front to ensure that a null value doesn’t creep in somewhere.  Null values can suspend your workflows.  After you are done declaring all of these variables, use one logging statement to show all of their values in the history list.  Use good names for all of your variables, and ensure they stand out from the names of your columns.  I usually add var to the front of all of the names of my variables just to be certain not to confuse them with any columns.  I also CamelCase variable names to aid in knowing that these are never displayed.

9.      Comment your workflow before you go to add the actual conditions and actions.

All of the plain English you wrote up in step 2 should be in comments throughout.  If it is a rather simple workflow, you can just add this to the names of your steps, but it is a good practice to support your buddies when you are working with a team of people.

10. Create a load of logging statements.

Every time you set a column or variable’s value, you should log the old value and new value to see it took properly.  Data type mismatches happen a lot, especially if you are using some columns with similar names.  We all make mistakes while making things.  Using the logging statements will help you find your errors when a workflow suspends mysteriously.

11. Log things to a separate audit log list.

I will always use version control with my document libraries where I might need to see the previous version of things, but if I want to see the changes in a single column or a status change, I usually create a previous value column for it.  Assume you have a column, Status.  I would also have prvStatus and make it a hidden column.  When the item is created, I’d set prvStatus equal to Status.  On the workflows based on a change to the item, add the condition:

If Status is not equal to prvStatus Create Item   Title = [Modified by] changed the status from [prvStatus] to [Status] on [Modified].  ItemID = ID (This is the ID of the item you were working with so it can show the relationship.)
You can then add a web part to this audit log to the dispform.aspx page of the list and filter its values to show the history of an item.

12. Use a new workflow history list.

I’m guilty of often using the same history list, and it won’t kill you if you do use the same history lists, but it isn’t wise.  Say you have a lot of testing for a long workflow.  Say you have 20 log statements in the workflow.  You test.  You made a few mistakes, and you get requests to make a few changes.  How many tests do you think you can do?—Only 250.  By default, no history list has its columns indexed, so it will hit that 5,000 item limit threshold like any other list.  If you are using the same history list for a few workflows, you won’t be able to see the results of any of your tests in short time.  Use a new history list.  Index its columns.

In addition, you can create an easy way to turn on and off your logging.  This takes us to the 400-level training, but have another list with Title and a choice column for on and off.  Add an item and call it Workflow XYZ Logging and select on.  When you are initializing your variables, have one for varWFLogging.  Set it to Yes or No based on the value Workflow XYZ Logging in that other list.  In SPD 2013, you can copy and paste, so when you were going to set all of those logging statements, create If varWFLogging equals Yes.  Then put your logging statement inside of it.  Then you can flip it on and off as you test things.  Keep some logging outside of the condition.  It can be overkill for a simple workflow, but if you have a lot of steps, I’d suggest setting this up.

13.  When it is possible, cut up large workflows into small workflow.

Sometimes, just having your workflow cut into stages and steps is sufficient, but sometimes it is best to call a workflow from the first workflow to run only when the conditions are necessary and the steps are repeatable.  For instance, you can have a 2013 workflow that you use for everything when there is a change; but, if the logic calls for it, that workflow could call a 2010 workflow with its impersonation step to change the permissions on the item you are using.

14. Use only one workflow to execute on creation or change.

It can be the same workflow, but do not have two or three workflows that kick off at the same time when an item is created or changed.  It can cause collisions that make things ugly.

15. Add a workflow as an option in the context menu.

If you have a manual workflow to do something to an item, use SPD to create a link to it right in the context menu.  It adds to the UI/UX of the application for a little more spit and polish.

16.  Do not use a pause for more than five minutes.

I bring this up because I often see people try to put a pause of like a week or months even inside of a workflow to archive the item after a long period or to send out a reminder email.  Well, that doesn’t work very well.  When you reboot the services on the box, the workflows get lost.  They break.  You won’t know without checking through all of your content where these orphaned workflows are.  Use an information management policy to kick off a manual workflow to do these things instead.

So when should you use a pause?—At the beginning of a workflow that would start immediately after an item is created sometimes.  What I have found is that copy jobs from one list to another aren’t always complete by the time another workflow might start in the destination list, so it would be good to have a one-minute pause here to ensure all of the metadata is set properly before your workflow starts to run with it.

Other Pro Tips for SharePoint Designer

Use it to help manage your permission groups.  You could have hundreds of permission groups in your site collection.  Managing them all through the GUI could be painful.  Through SPD, you can click on Site Groups and see all of them in one view.  It’ll help you find misspelled and redundant groups.  It will help you update the descriptions of those groups if they are missing.

Use SPD to create your HTML, JS, and CSS files right in the libraries where you’ll keep them.  If you have clicked on All Files in the navigation on the left side of the screen, you can get into any library and look directly at files.  You can create or edit all of your client-side code with a nice UI.  It beats using Notepad most of the time.

Leave a Reply

Your email address will not be published. Required fields are marked *