a. Automatic alerts when errors occur – when a workflow error occurs the user will need to be alerted immediately
b. One location error logging – when a workflow error occurs the user will want to go to one location where workflow error information is logged
c. Workflow error step identification – when a workflow error occurs the user will want to go be able to identify which workflow step caused the error
This article will help you develop a best practice solution for logging runtime workflow errors that meets all these requirements.
2. Overview: As an overview let’s first discuss the types of SharePoint Designer Workflow (SPDWF) error logging available to us, the types are listed below:
a. List Item Error Logging: When a SPDWF error occurs that error is logged to the list item’s metadata, and appears as the message “Error Occurred”.
b. Workflow History Error Logging: When a SPDWF error occurs that error is logged to the workflow history for that item, and appears as a variety of messages depending on the error that occurred.
c. Custom Workflow Logging: With properly designed custom workflow logging, the step in which an error occurred in a SPDWF can easily be identified.
3. Best Practice: So to develop our runtime error logging best practice solution we will need to use all three types of error logging capabilities available to us as well as some other out of the box (OOTB) SharePoint capabilities. Our solution will have the following components:
a. Automatic Alerts: We will create a workflow dashboard that alerts an identified user when a workflow error occurs.
b. Workflow History Error Logging: We will leverage the OOTB capabilities of SPDWF error logging to point the user to one error logging location.
c. Workflow Error Step Identification: We will develop a custom workflow log that helps to identify the workflow step that caused the error. (This log will be written to the same location as the OOTB workflow error log).
While the requirements of the solution appear in the order the user will experience them, the design and build for the solution will occur in the opposite order, and so we will discuss the solution components in this order.
4. Design the List and Workflow: For our solution we will develop a very simple list and workflow, just as a straw man to use to illustrate our logging design. The workflow will have three steps, each step with one condition, and two actions. We will use the first step to establish the context of the error (i.e. step one will not cause an error), and we will use the second step to identify an error (i.e. step two will cause an error), and we will use the third step to establish whether or not the workflow completed. Here are the steps to creating our list and workflow:
a. From the SharePoint suite create a new custom list, call it “Workflow Log List”
b. From “Workflow Log List” create a new custom text column, call it “Force Workflow Log Error”, click on “Add to default view” and click OK
c. From “Workflow Log List” create a new custom Boolean column, call it “Workflow Ran”, click on “Add to default view” and click OK
d. From Workflow Log List create two items, for item 1 in the list set the title to “Title 1”, and then set the “Force Workflow Log Error” column to “No Error”, and for item 2 in the list set the title to “Title 2”, and then set the “Force Workflow Log Error” column to “Error”
e. From SPD, create a new custom workflow for the Workflow Log list, call it “Workflow Log”
f. From the “Define your new workflow” screen of the “Workflow Log” workflow set the workflow start options to “Allow this workflow to be manually started from an item”, and “Automatically start this workflow when a new item is created”
g. From Workflow Log workflow, create a workflow step, call it “Workflow Step 1”
h. From Workflow Step 1, create one condition – “If Created By is not empty” – this step will run whenever a list item exist
i. From Workflow Step 1, create two actions – “Update item in this list” and “Log this message to the workflow history list”
j. From the Update item in this list action add logic to update the current item in the list so that the value of our custom text column “Title” is set to “Update Title”
k. From the Log this message to the workflow history list action add logic to write “Workflow Step 1 - Ran” to the History log
l. From Workflow Log workflow, create a second workflow step, call it “Workflow Step 2”
m. From Workflow Step 2, create one condition – “If Created By is not empty” – this step will run whenever a list item exist
n. From Workflow Step 2, create two actions – “Update item in this list” and “Log this message to the workflow history list”
o. From the Update item in this list action add logic to update the current item in the list so that the value of our custom text column “Force Workflow Log Error” is set to “Force Error”
p. From the Log this message to the workflow history list action add logic to write “Workflow Step 2 - Ran” to the History log
q. From Workflow Log workflow, create a third workflow step, call it “Workflow Step 3”
r. From Workflow Step 3, create one condition – “If Created By is not empty” – this step will run whenever a list item exist
s. From Workflow Step 3, create two actions – “Update item in this list” and “Log this message to the workflow history list”
t. From the Update item in this list action add logic to update the current item in the list so that the value of our custom Boolean column “Workflow Ran” is set to “Yes”
u. From the Log this message to the workflow history list action add logic to write “Workflow Step 3 - Ran” to the workflow history list
5. Design the Workflow Dashboard: In addition to our list and workflow we want to design a workflow dashboard, the purpose of the dashboard is to tell us whenever an error occurs in the workflow.
a. From the site create a custom list, call it “Workflow Dashboard”
b. From the Workflow Dashboard list click on Site Actions -> Edit Page
c. From the Edit Page view click on “Add a Web Part”
d. From the Add Web parts dialogue box choose Workflow Log List and then click Add – the Workflow Log List web part will be added
e. Click on the Workflow Dashboard web parts Edit menu and choose Delete – we will not need this list’s default web part
f. From the toolbar of the Workflow Log List web part choose Actions -> Alert Me, this will take you to the New Alert view
g. From the New Alert view accept all the default settings by clicking OK – This will create an Alert that is generated every time there is a change in any of the Workflow Log List items
6. Test the Solution Workflow – No Error: Now we are ready to test our workflow and demonstrate a simple logging message. Follow these steps to test the workflow and generate the logging message:
a. From the Workflow Log List, item 1 (Title 1), click on the list item drop down menu and choose the Workflows menu item
b. From the workflows view page, click on the “Workflow Log” item
c. From the workflow initiation page click on the “Start” button
d. When you are returned to the list item view page you should see the message “Completed” under the Workflow Log column.
e. Click on the “Completed” link under the Workflow Log column and you will be taken to the Workflow Status page
f. On the Workflow Status page under the “Workflow History” page you will find our three custom log entries:
i. Workflow Step 1 – Ran
ii. Workflow Step 2 – Ran
iii. Workflow Step 3 – Ran
g. You will receive an Alert like the one below, this alert informs you that something has changed in the Workflow Log List, notice that the Workflow Ran field has an entry - “Yes”
a. From the Workflow Log List tool bar, click on Settings, List Settings
b. From the Workflow Log List settings page, under the Columns heading, click on the Force Workflow Log Error column
c. From the Force Workflow Log Error column’s edit column page, at the bottom find the Delete button and click on it, and then choose OK when the warning message appears – This will delete our Force Workflow Log Error column and therefore force our workflow to throw an error when it attempts to update this column
d. From the Workflow Log List, item 2 (Title 2), click on the list item drop down menu and choose the Workflows menu item
e. From the workflows view page, click on the “Workflow Log” item
f. From the workflow initiation page click on the “Start” button
g. When you are returned to the list item view page you should see the message “Error Occurred” under the Workflow Log column
h. Click on the “Error Occurred” link under the Workflow Log column and you will be taken to the Workflow Status page
i. On the Workflow Status page under the “Workflow History” page you will find the following three log entries:
i. Error updating a list item: This is the message concerning the cause of the error – our error was caused by a problem that prevented the update of a list item
ii. Workflow Step 1 – Ran: This is the last step of the workflow that ran successfully
iii. An error has occurred in Workflow Log: This is where the error occurred, by interpretation we know we this is Step 2 because step 1 ran successfully but Step 2 did not
j. You will receive an Alert like the one below, this alert informs you that something has changed in the Workflow Log List, notice that the Workflow Ran field has an entry - “No”
8. Review of Our Design:
a. Workflow Error Step Identification – Custom Error Logs: SPDWF provide many useful conditions and actions, but for our best practice solution, one action is not only useful, it is essential - the “Log to History List” action. In our solution we ensured that each workflow step had a log that identified 1.) The workflow step name and 2.) The workflow step condition
b. Workflow History Error Logging – OOTB SPDWF Error Logging: By combining the OOTB SPDWF error logging with our custom logging, we are able to easily identify at which step the workflow failed
c. Automatic Alerts – Workflow Dashboard: By developing a custom workflow Dashboard we were able to alert the user to when a workflow failed
9. More Advanced Design: In addition to our rather simple alert system we can develop a more advanced alert system that sends a detailed error message with the list item ID, time of error, error message, last successful workflow step, etc. To implement this type of functionality will require developing a custom SharePoint event handler, however, this type of handler would be very useful and very reusable. I won’t cover how to develop that workflow event handler here, but maybe in future articles.
10. Conclusion: By combining both the OOTB SPDWF error logging system, with custom SPDWF logging and custom Alerts we are able to quickly and easily identify, log and track workflow errors.
No comments:
Post a Comment