Workflow debugging, really?
Those of us who develop workflows and scripts have in most cases longed for one of the main features that .NET and other language developers have had in their development kits – debugging tools! Wouldn’t it be great to actually be able to tell your workflow to move through each step, stopping, allowing the results of the step to be examined and then run the next step and so on? How about having a variable window so we can watch what value our variables hold, as each step is executed? How great would that be?
Alas, it’s not to be, not even in SharePoint 2013 or SharePoint Designer 2013. Unfortunately in SharePoint, we workflow developers are still waiting for a true debug tool and have to make do with what we have. All is not lost though, as there are several tools and procedures that can be used to create a sort of debugging method and process trail. If you know about these, great; If not, then I hope you find them useful.
Log to History List
In SharePoint Designer one of the most underutilized and overlooked tools for debugging is the Log to History List action. The Log to History List action is located in the Workflow tab under the Action drop down selection.
Let’s build two workflows to demonstrate the importance of the Log to History List action in workflows.
The first workflow is a simple two line workflow. With it, we’ll change a value in the list and report on the change via email.
I build my basic two line workflow as shown above. There’s not much to it. Update a list item column and send off an email. When run on a list item, the workflow appears to complete. To check on this, I click on the “Completed” that is in the workflow column.
What SharePoint returns is somewhat useless at telling me what the workflow has done. I pretty much get a web page of “it ran”, but nothing more.
Now take the same function of the workflow and add the Log to History List action, with plenty of detail.
Here’s the workflow.
As you can see, there are many Log to History List actions in this workflow.
This may seem to be a real pain, and I’ll admit, it’s a little time consuming up front. However, one of the most difficult issues that most people have is taking the time to do the appropriate work up front, which in most cases, saves a large amount of time towards the end for whatever project that’s in the works.
Running this workflow and then clicking on the “Completed” for the item in the workflow column, results in something much more useful.
What a difference a little logging made!
From this simple addition, taking the time to add detailed logging I know can see every step of my workflow and if this workflow were complex or had pauses in it, I’d know the time each step was executed.
More important is that if my workflow did not complete, experienced an error, or I had to stop it for some reason, I could open this same history list and see where in my workflow the issue occurred.
Another important reason to consider using the Log to History List action is not just for your debugging but for your fellow admins who may need to see what’s going on with a workflow, when you’re not available.
Add a Comment
Along with logging to history, another useful tool to help locate and fix issues is the Comment action.
Isn’t this the same as Log to History List? Nope, not at all and the reason for using it is also different.
In the Log to History List action, SharePoint is actually telling you step by step what it is doing based on how many Log to History List actions you include in the workflow. A Comment is nothing more than a remarks line that developers and scripters use to remind themselves of what the prior or next section of code is or was ‘supposed’ to do. Log to History List actions actually show you where the workflow is or stopped. The Comment action only tells you what the workflow was supposed to do, so how does this relate to debugging?
I have an example that occurred where an employee was entering data into a form, submitting the form but what SharePoint was recording was unexpected. I opened the workflow to try and figure out where the issue was and I found myself lost in a very large workflow. Not only did I not include the Log to History List actions, but I had absolutely no Comments in my workflow code – and the workflow was very large and complex. After putzing around in the workflow for over 30 minutes, I finally figured out that the employee was causing the error by entering incorrect data.
That ordeal wasted my time because I hadn’t looked at the workflow in such a long time, I couldn’t remember how it worked. I ended up having to go through the workflow step by step, figuring out variables and non-displayed column items to re-learn what the workflow does. If I had at least placed Comment lines in the workflow for each section and even each step, then I would have resolved the issue much faster.
Remember, debugging isn’t just for when the workflow application as created, but includes all issues that arise at a later time. Some might say “well the workflow has run for months with no issue, can’t be a workflow issue”. They would be correct most of the time in saying this, as in this case, it wasn’t a workflow issue that caused the problem. However there’s a big difference in just saying that and being able to prove it quickly. With the addition of a Comment action, I would have been able to prove the issue was not in the workflow much quicker than I did.
Step by Step
Another useful method that I use for debugging in workflows is to create a column which will be updated by the workflow for each step or section I choose as the workflow executes. This is sort of a developer created Log to History List action, but it’s located in the list itself, instead of the history list of the workflow. This works well for very complex multi-step workflows and it actually provides a pho-looping capability as a benefit.
In one such very complex workflow, I created a column named ProcessingStep. In this system, vendor information is entered into SharePoint. Routing an email to appropriate persons is done to gain approval for the request. As the emails are sent and received (processed), the list items ProcessingStep is incremented. By the legend at the bottom of the status view below shows anyone looking at the screen, where a vendor’s request is in the process.
These updates via the workflow to the item in the ProcessingStep column, directly correspond to steps in my workflow.
If a list item appears to be stuck in a particular ProcessingStep, I know where in my workflow the last process change took place. My issue should be somewhere between that point and the next update to the ProcessingStep column for that list item.
Using the ProcessingStep method, I am also able to re-submit an item as many times as I need through the workflow, and only the step “If CurrentItem:ProcessingStep equals #” in my workflow will act upon that list item. This means I can loop my list item as many times as I want through the workflow (my pho-looping capability).
Tracking All Workflow Activity
Inside of SharePoint Designer is the capability to view all activity generated by all workflows in a single list. Each SharePoint site has a Workflow History list. This list is generally hidden. The list has advantages and disadvantages of use. One advantage as mentioned is that all workflow history is logged in this list. If you have 4 workflows in a site on either the same or different lists, all the workflow activity is viewable. This is especially helpful if you have workflows that call other workflows, which can sometimes be problematic. In this list you can see the initial workflow running, what it does, and if the called workflow, follows. The disadvantage is that this list is usually very large. Sorting, and viewing just want you want to see is sometimes difficult. Added to this issue is that workflows are listed by their GUID, not by the name given to them when they were created.
If you use Log to History List, this will help to identify the workflow as you could Log to History List the name of the workflow like “Process_New_Entry_Workflow”. This would be displayed in the Description column in the Workflow History list and help to identify the workflow that created the entry in the Workflow History list.
Turning this feature on in a site is relatively simple.
1. Open SharePoint Designer and open the site you wish for this list to be available in.
2. Select Workflows
3. Select any active workflow
4. Under the Workflow Information is Customization. Select Open history list.
5. This will open the Workflow History and provide information and options. In the Settings box, the “Hide from browser” is default checked. Uncheck this box.
6. Close the site or just exit SharePoint Designer.
7. Open your browser to your site.
8. Select All Site Content. You should now have a Workflow History in the Lists.
You can treat this list just like any other list in your site, with the exception of creating workflows for it. Wouldn’t that be great though, a workflow that would send an email alert when the Workflow History had an error item placed in it! It should be possible to use a 3rd party tool to extract the data from the list on a timed base and place that data into an alternate list. Then a workflow could be created on that list to send an email and what the issue is. There’s more than one way to skin a cat in SharePoint.
Combining the methods above gives the SharePoint Workflow designer a few more tools to use to determine just what the heck is going on with a workflow. There is one additional method of debugging workflows that I’ll briefly mention – briefly because in my experience, it’s a pain to even try and determine what SharePoint is trying to tell me when I use it. In Central Administration under Monitoring > Reporting > Configure diagnostic logging you’ll find you can have SharePoint log workflow processes in 3 categories. Those categories are Document Management Server, SharePoint Foundation, and Web Analytics Services. You of course are welcome to spend as many hours as you wish trying to find the logged information in the SharePoint log file (this is the text log written to C: or whatever drive you specified during installation of SharePoint). I prefer the less time consuming and more informative methods I’ve described above.