More detailed examples of the following scenarios where an error may occur in a SharePoint Designer workflow are also provided later in this post:
- Exiting / Breaking a Looping Workflow using Workflow Errors
- Workflow Permissions
- Changing the name of a Document in a Document Library
If you come across a workflow error which is not explained below, please post details in a comment to this post. I will ammend the table and information below to include any additional errors, descriptions and possible causes to build a comprehensive list of workflow errors and resolutions when developing using SharePoint Designer.
Workflow Error Summary Table
| Status / Event Type | Description | Outcome | Possible Cause(s) |
| Error | Error updating a list item | List Item Not Found | No item in the list matching the critera used to find a list item being updated. |
| Error | Error updating a list item | Access Denied | Permissions of the user who initiated the workflow don't allow them to modify data in the list item. |
| - Stopped Event Type: Error | Error Deleting a list item | Access Denied | Permissions of the user who initiated the workflow don't allow the user to delete items from the list. |
| Error | Error updating a list item | Unknown Error | Attempting to update Approval Status of a list item from a Workflow initiated by a user without approve permissions on the list/library. |
| - Failed on Start (retrying) - Stopped (Event Type: Error) | Error updating a list item | Unknown Error | Incorrect data types. Eg. attempting to include illegal characters in the filename of a document by appending the date to the filename.
Permissions: Attempting to update a list item using the permissions of the user who initiated the workflow, who doesn't have access to update items in the list. |
| Error | An error has occured in ...Workflow Name | A previous workflow error has caused the workflow to halt. | |
| Error | Error updating a list item | Document must be checked out | The document or list item being updated is in a list or library with force checkout enabled.
First check out the document before making changes from a workflow, or disable force checkout.
Note: Setting the Approval Status via a Workflow created using SharePoint Designer is not possible when Force Checkout is enabled. |
Below are a series of scenarios where Workflows developed using SharePoint Designer will halt or stop due to a Workflow Error. An explanation of the cause of the error, as well as a resolution or workaround for the issue are also provided for each scenario. There are also instances where a workflow error can be caused intentionally to break a looping or repeating set of workflows once the looping sequence has completed (eg. processing all list items - see below).
Error Scenarios
Exiting / Breaking a Looping Workflow using Workflow Errors:
Looping Workflows developed using SharePoint Designer are often configured to stop due to a list item not being found. For example, when processing all items in a list using looping workflows, each instance may be initiated by updating a field from each item in the list being processed to initiate a separate iteration of the loop for each item. When all items have been processed, the workflow will not be able to find the next list item adn as a result will halt with an error ("Error updating a list item" : "List Item Not Found"). In cases similar to this, the workflow may not have stopped, as the workflow will sometimes retry the operation which caused an error depending on the type and severity of the error. Also, some errors will prevent new instances of the workflow initiating on the same list item with a workflow error. In scenarios where the workflow process should loop, this can be a problem as the workflow may not be able to move past the first iteration, or will cause the loop to stop if a workflow halts midway through the looping process.
Resolution / Workaround:
To ensure that a workflow loop continues until it has completed all required iterations, configuring the workflow initiate when an item is added to the list will result in each workflow initiated for each iteration of the loop being associated with a different list item. If one of the workflows halts due to an error (intentionally or unintentioanlly), the remaining iterations and components of the workflow can still continue as they will always be initiated on new list items added to the list. To help keep lists tidy, it may be a good idea to include an action late in the workflow to remove the current (temporary) list item once it has completed operations required for the current iteration and initiated the next iteration of the loop. After all items in the separate list have been processed. The workflow for the final list item created will stop due to a "List Item Not Found" error. As there will be not remaining items in the list which match the criteria required to find and initiate the next iteration, the loop will stop, breaking out of the looping sequence.
Workflow Permissions:
It is very common for developers of workflows in SharePoint to have elevated permissions on the SharePoint Site Collection in comparison to the general end-users of the SharePoint environment. This can lead to workflows not functioning as expected, or not working at all once in use, as testing may have been completed using the permissions of the workflow developer. To help prevent access / permission issues with workflows in SharePoint, you should always thoroughly test workflows using accounts with identical permissions to end-users of the SharePoint environment and workflow. In some cases this may require you to test using multiple accounts with varying permissions matching that of the end-users, or to change the permission level of one or two test accounts in order to test all possible scenarios.
As a workflow runs using the permissions of the user who initiated / triggered the workflow, in many cases during development it will be running using the credentials / permissions of the developer. If the developer has elevated access to components on the SharePoint site including lists associated with the workflow, the workflow will often function as expected during development, but not work once deployed into a production environment.
Resolution / Workaround:
When a workflow is initiated by a user with standard permissions, and the workflow needs to complete actions that would require the user to have a greater permission level on the site and lists, you can split the worklfow into components which are then initiated by users with the required permissions.
For example, a general user may make a change to a document stored in a document library with content approval enabled. A custom approval workflow is initiated to create and assign tasks to have the changes approved. As the Approval Task is created by the workflow running as the user who submitted the changes for approval, the user requires permissions that allow them to add items to the Approval Task list.
If using the "Collect data from user" action to get the approval status of the changes from an Approver, the workflow will continue to run as the user who initiated the worklfow (not the approver) once the approval status has been collected. This will result in a Workflow error if you try to update the approval status of the list item or document, as the user who made and submitted the changes for approval doesn't have approve permissions on the list/library. A solution for this problem is to split the workflow into two separate workflows. One to initiate the approval process and create the approval task item, and a second workflow on the Workflow task list which will be initiated by the approver when the approval status for the changes is set. You will not be able to use the "collect data from user" action, as this will result in the workflow continuing using the credentials of the user who initiated the workflow and a workflow error when attempting to set the Approval Status. Instead, you should create a new content type with only the fields required to collect the Approval Status for a modified list item and use the "Create List Item" action to create the Approval Task. Once created, associate the content type with a task or other list type, making it the default and only content type available on the "New" menu for the list. In the workflow associated with the content approval enabled list, you should use the "Create List Item" action to add an Approval Task item to the task list, then complete the workflow (Stop).
The Second workflow associated with the task list should be configured to initiate when an item in the Approval Task list is modified. The first step in the workflow should be to check to see if the Content approval status has been set by the approver. If not, then the workflow can stop as it will be reinitiated when the approval status is updated by an approver. If the approval Status has been set, then the workflow can continue to update the Approval Status of the list item or document that was changed and submitted for approval. The approval status can now be set by the workflow as it will be running using the permissions of the approver, not the user who initiated the approval process.
Column Data Types & Limitations
Attempting to set the value of a column in SharePoint that requires a specific data type such as a List Item ID, date or filename (Name) will result in a Workflow error when the incorrect data is assigned to a field/column in the list item or document. When developing workflows using SharePoint Designer, restrictions have been implemented to help ensure that the correct data type is used when setting workflow variables or fields in a list item. For example, when setting the value of a date/Time field, only a date variable or field can be set as the new date value. Similarly, when working with list items in SharePoint from a workflow, SharePoint Designer uses the List Item ID data type when retrieving or storing the ID of the current or another list item to ensure that only one (unique) item is returned.
Changing the name of Documents in a Document Library from a Workflow
- Difference between the "Name" and "Name (for use in forms)" fields
- Illegal / Special Characters in Document Filenames causing workflow errors.
- How to use calculated columns to remove illegal / special characters from a date or other field to be set or included in the document filename.
The "Name" and "Name (for use in forms)" columns in a SharePoint document library both refer to the same data, being the filename of the document of file, but function differently when updated by a Workflow Developed using SharePoint Designer. The main difference when using the Name columns in a Workflow is that the file extension for the document is included when using the "name (for use in forms)" column, but not the "Name" column.
- Name - Doesn't include file extension
- Name (for use in forms) - Includes file extension
When setting the value for the "Name" or "Name (for use in forms)" fields, special / illegal characters need to be considered, as the workflow will stop with an "Error updating a list item" error, with the outcome "Unknown Error". This is due to the fact the SharePoint doesn't allow specific characters to be included in the Name (filename) of a document stored in a Document Library. See Illegal Characters in SharePoint Document Libraries for more information about non-supported special characters for filenames in SharePoint.
Use calculated columns to format the created date to be appended to the filename (Name) of a document or form:
1. Configure a calculated column on the Sharepoint document library that formats the created date as a string with no illegal / special characters, that can then be included in the filename of the document.
Calculated Column: Generate a text string containing the created date in a specific format (dd-mm-yyyy : 03-02-2010)
=TEXT([Created],"dd-mm-yyyy")
2. Configure a workflow to append the value from the calculated column to the "Name (for use in forms)" fields of the document.
To append the date to an existing filename, you will need to use the value from the "Name" column, as it will not include the file extension. You would do this using the "Build dynamic string" workflow action, which would first take the original filename (without the file extension), then append the value from the calculated column containing the formatted date. The file extension can be included in the new filename string, but is not required. Once the new filename have been generated, you can set the "Name (for use in forms)" field for the current item using the "Update list Item" action, or the "Set field in current item" action.
Troubleshoot workflow errors
Access Denied when trying to upload multiple files to a SharePoint Library when one of the files contains an illegal character.
Posts
