Troubleshoot Project Online workflows
It is common as a Project Web App admin to have to troubleshoot Project workflows. Depending on how the workflow process has been defined for the organization, there may be instances where an admin needs to act for the workflow instance to progress. There are fields that a user can add to the Project Center, query OData or the Project Online Rest endpoint to better understand the state of each Project workflow. With the information provided in these fields, a Project Web App admin can take the appropriate corrective action to unblock the progression of the Project workflow.
There are three steps on troubleshooting Project Online workflows:
Setting up views and reports to see the errors
An admin can see Project workflow errors in two ways:
Create a Project Center View to see workflow state
Query Project OData Service or the Project REST API
Create a Project Center View to see workflow state
We recommend creating a new Project Center view to troubleshoot Project workflows. To create the view or edit a Project Center view, the user will need to have the Global permission to Manage Project Web App Views
Note
For more information on how to manage security, please see Video series: How security permissions work in Project Server
To create the view
From Project Web App, click on the gear icon then ** PWA Settings **.
On the settings page, click Manage Views. A list of views will appear.
Click ** New View **.
In the Name and Type section, in the ** View Type ** list, select Project Center.
In the Name box, type the name of the new view. For example, " Project Workflows ".
In the Description box, type a description of the new view.
In the Table and Fields section, from the Displayed Fields list, remove the default Start and Finish fields. Add the following fields from the Available fields list:
Workflow Error Code
Workflow Error
Workflow Created
Workflow ID
Workflow Last Run
Workflow Owner
Workflow Phase Name
Workflow Stage Name
Workflow State
Checked Out
Checked Out By
Scroll to the bottom of the page and click Filter.
Add the filter using the field " Workflow Error Codeis greater than 1" and click OK .
Click Save.
Note
After clicking Save, you will receive the following message: " You have not assigned a security category to this view. Failure to do so will prevent anyone from seeing the view in the dropdown or from using the view. Do you want to save anyway? " Click OK, because only members of the PWA Administrators group will be able to view the Project Workflows Project Center view.
Query Project OData Service or the Project REST API
Optionally users can query for this information from the Project OData Service or programmatically through the Project REST API.
Project OData Service
Project Center Field | Entity | Property |
---|---|---|
Workflow Error Code |
Projects |
WorkflowErrorResponseCode |
Workflow Error |
Projects |
WorkflowError |
Workflow Created |
Projects |
WorkflowCreatedDate |
Workflow ID |
Projects |
WorkflowInstanceId |
Workflow Last Run |
ProjectWorkflowStageData |
StageLastSubmittedDate |
Workflow Owner |
Projects |
WorkflowOwnerName |
Workflow Phase Name |
ProjectWorkflowStageData |
PhaseName |
Workflow Stage Name |
ProjectWorkflowStageData |
StageName |
Workflow State |
ProjectWorkflowStageData |
StageStatus |
Note
For more information about the Project OData service, see ProjectData-Project OData service reference.
Project REST API
Project Center Field | Entity | Property |
---|---|---|
Workflow Error Code |
ProjectWorkflowInstance |
WorkflowErrorResponseCode |
Workflow Error |
ProjectWorkflowInstance |
WorkflowError |
Workflow Created |
ProjectWorkflowInstance |
WorkflowCreatedDate |
Workflow ID |
ProjectWorkflowInstance |
Id |
Workflow Last Run |
ProjectWorkflowInstance |
LastSubmittedDate |
Workflow Owner |
Projects |
ProjectOwnerName |
Workflow Phase Name |
ProjectWorkflowStageData |
PhaseName |
Workflow Stage Name |
ProjectWorkflowStageData |
StageName |
Workflow State |
ProjectWorkflowInstance |
WorkflowState |
Code Examples
Read a filtered set of projects and retrieve the project workflow instances. If the request includes more then 20 projects, you will need to add additional filtering otherwise the request will fail:
GET https://CONTOSO.sharepoint.com/teams/project/PWA/_api/projectserver/projects?$Filter=startswith(Name,'Budget')&$Expand=ProjectWorkflowInstance,ProjectWorkflowInstance/WorkflowInstance
Read all workflows with error response codes greater than or equal to 400, including the owner and minimal details about the project:
GET https://CONTOSO.sharepoint.com/teams/project/PWA/_api/projectserver/projectworkflowinstances?$FILTER=WorkflowErrorResponseCode ge 400&$SELECT=Id,WorkflowError,WorkflowErrorResponseCode,WorkflowState,Project/Id,Project/Name&$EXPAND=WorkflowInstanceOwner,Project
Note
For more information about developing against Project Online, please visit the Project Dev Center.
Reviewing the errors
If the admin created a Project Center view as described above, the view can be accessed following these steps:
From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.
Click on Projects in the ribbon.
Select the view that was created following the steps above from the View: dropdown.
This will provide the user with a list of all the projects and the current status of each project's workflow, including errors.
Optionally the user can review the errors through a custom report or programmatically as described above.
Note
The Workflow Created and Workflow Last Run display date and time in UTC.
Note
After acting on the errors it will take up to 24 hours for the status to be updated in Project Center, Project Service OData and through the Project REST AP.
Acting on the errors and taking additional steps
The following errors may happen with a Project workflow:
Error | Action |
---|---|
We were not able to update the status for project PROJECT_GUID |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, try How to Resume a SharePoint Workflow. |
We were not able to update the status for stage STAGE_GUID on project PROJECT_GUID |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, try How to Resume a SharePoint Workflow. |
Stage STAGE_GUID is not the current stage for project PROJECT_GUID |
This error happens when attempting to set workflow stage status for a workflow stage that is not in valid. In this situation, you need to How to Restart a Project Workflow. |
Custom field CUSTOM_FIELD_GUID does not have a value set for project PROJECT_GUID |
A custom field is not correctly set and the workflow is unable to progress until the custom field value is updated. To determine the name of the custom field that needs to be updated, see the section titled How to get a Custom Field from a Custom Field GUID. After updating the custom field, try How to Resume a SharePoint Workflow. > [!NOTE]> As a best practice, it is recommended for true/false custom fields involved in a workflow to use a lookup table opposed to a flag custom field to prevent this issue for custom fields of this type. |
The custom field CUSTOM_FIELD_GUID does not exist. |
This happens when the workflow attempts to read or write the value for a custom field which has been removed from PWA. You will need to edit the workflow and ensure proper custom field is associated with the workflow. |
Failure submitting Check-in job for project PROJECT_GUID |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Failure submitting Publish job for project PROJECT_GUID |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Failure submitting Publish Summary job for project PROJECT_GUID |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Failed to create a project from list item |
This is an error that is impacting the CreateProjectFromListItem activity. First, try How to Resume a SharePoint Workflow. If the issue persists, review the PWA queue to see if there is a failed queue job for the project creation. |
Could not find list item to create a project for web WEB_ID list LIST_ID item LIST_ITEM_ID |
The list item does not exist anymore. You can check the Recycle Bin to see if you can restore the list item. |
Could not find an idea associated with project PROJECT_GUID while trying to update status |
This happens when the idea that was initially used for project creation is deleted. You can check the Recycle Bin to see if you can restore the list item. |
Job id JOB_GUID is invalid |
Contact Microsoft Support if you get this error message. |
Workflow owner does not have permission to check-in project PROJECT_GUID |
Admin needs to grant check-in permissions to the workflow owner. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Workflow owner does not have Edit Project Summary Fields or Save Project to Project Server or Publish Project category permission on project PROJECT_GUID |
Admin needs to grant appropriate permission to the workflow owner. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Workflow owner does not have New Project global permission |
This happens when attempting to create a project from a SharePoint list item and the user that starts the workflow instance cannot create new projects in PWA. Admin needs grant appropriate permission to the user. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Workflow owner does not have Open and Save Project To Project Server category permissions on project PROJECT_GUID |
Admin needs to either grant appropriate permission to the user. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Workflow owner does not have Open Project category permission on project PROJECT_GUID |
Admin needs to either grant appropriate permission to the user. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Workflow owner does not have Publish Project category permission on project PROJECT_GUID |
Admin needs to either grant appropriate permission to the user. After granting permissions, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
The project workflow cannot have multiple stages in progress |
This error shows up if the workflow instance attempts to enter a stage without closing previous stage. Contact Microsoft Support for more help with this error. |
The project workflow must have one stage in progress |
This error shows up if the workflow instance attempts to leave a stage without setting the next stage in progress. Contact Microsoft Support for more help with this error. |
Project PROJECT_GUID cannot have a workflow |
This error occurs when trying to start a workflow instance on an unsupported project type. Contact Microsoft Support for more help with this error. |
Project PROJECT_GUID has failed to check-in |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
Project {0} has failed to check-in after the custom field {1} value was updated |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
Project PROJECT_GUID has failed to check-in after the property PROPERTY value was updated |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
Project PROJECT_GUID is checked out in another session |
Admin needs to either force check-in the project or ask the user to check the project in. After the project is checked-in, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Project PROJECT_GUID is checked out to another user |
Admin needs to either force check-in the project or ask the user to check the project in. After the project is checked-in, try How to Resume a SharePoint Workflow. If the issue continues to persist, you will need to How to Restart a Project Workflow. |
Project PROJECT_GUID does not have a workflow |
Contact Microsoft Support if you get this error message. |
Project PROJECT_GUID is not checked out |
The admin will need to review the workflow definition and verify no project updates are attempted before the project is checked-out. |
Project PROJECT_GUID does not exist |
Contact Microsoft Support if you get this error message. |
Project PROJECT_GUID cannot be published because the PROJ_PWA_SHORT_NAME is in Read Only mode |
Typically this error will be resolved if no action is taken for a period of time. If you need the error to be resolved immediately, verify that the PWA site is not in read only mode by navigating to the site and seeing if there is a notification across the top of the page. If there is no notification, then try How to Resume a SharePoint Workflow. |
Failed to update project PROJECT_GUID |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
Property PROPERTY does not have a value set for project PROJECT_GUID |
The admin will need to review the workflow definition and verify properties are being set correctly. |
Property PROPRERTY does not exist |
Contact Microsoft Support if you get this error message. |
Failed performing a Publish operation on project PROJECT_GUID |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
Failed performing a Publish Summary operation on project PROJECT_GUID |
A PWA queue job has failed preventing the workflow from progressing. Review the failed queue job from the Manage Queue job page within PWA. |
401 User not found/user is inactive |
You will need to How to Restart a Project Workflow. |
System.InvalidOperationException: Incomplete closure detected while loading subroutines for workflow WORKFLOW_GUID in scope. |
You will need to How to Restart a Project Workflow. |
If your error is not listed or you want further details about the error you are getting, see the section How to get the detailed error message for a SharePoint Workflow.
If you find other areas not listed above, let us know by selecting the feedback link at the top of this page. Please provide the following details:
Project Name
Workflow Error Code
Workflow Error
Workflow Created
Workflow ID
Workflow Last Run
Workflow Owner
Failed queue message and timestamp if applicable
How to Resume a SharePoint Workflow
In some cases a workflow may need to be resumed to retry the current step of the workflow.
To resume a SharePoint workflow
From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.
Click on the project name.
Click on the project name from the Quick Launch.
Expand the All Workflow Stages section.
Click the Additional Workflow Data link.
Click the "i" icon beside the Internal Status.
Click the Resume this workflow link.
How to Restart a Project Workflow
Restarting a Project workflow will put it back to the start of the workflow. Users will need to advance the workflow back to it's current stage. Before restarting the Project workflow, you may want to first try resuming the workflow to retry the current steps. See How to Resume a SharePoint Workflow for steps on how to resume a workflow.
To restart a project workflow
From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.
Click on the project name.
From the Project tab, click on Options, then Restart Workflow.
Note
The project needs to be checked-in before the workflow can be restarted. For more information about checking in a project, please see Manually check in projects and resources that are checked out by another user.
Click OK
To restart project workflows for a set of projects
From Project Web App, click on the gear icon then PWA Settings.
Click on Change or Restart Workflows.
Choose the Enterprise Project Type from the list for the projects.
Select the set of projects that need to have their workflows restarted.
Note
Projects need to be checked-in for them to show up in the list. For more information about checking in a project, please see Manually check in projects and resources that are checked out by another user.
Select Restart current workflow for the selected projects.
Click OK.
Optionally Project workflows can be programmatically restarted. ProjectWorkflowInstance has two methods to restart Project Workflows:
- RestartWorkflow()
- RestartWorkflowSkipToStage(stageId)
Note
Restarting Project workflows in bulk may cause throttling to occur. To learn more, please see SharePoint 2013 workflow throttling and performance in SharePoint Online and Project Online.
How to get the detailed error message for a SharePoint Workflow
If the error message provided in the Project Center does not provide enough details for you to troubleshoot the issue, you may want to review the detailed SharePoint Workflow error message.
To get the detailed error message for a SharePoint Workflow
From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.
Click on the project name.
Click on the project name from the Quick Launch.
Expand the All Workflow Stages section.
Click the Additional Workflow Data link.
Click the "i" icon beside the Internal Status to see the detailed error message.
How to get a Custom Field from a Custom Field GUID
From Project Web App, click on the gear icon then PWA Settings.
Click Enterprise Custom Fields and Lookup Tables.
Click on a custom field.
Scroll to the bottom of the page.
Expand the System Identification Data section to review the Custom Field GUID.
How to Review PWA Queue Jobs
In some cases an error will be a result of a failed PWA queue job. PWA provides detailed error messages for failed queue jobs.
To review PWA queue Jobs
From Project Web App, click on the gear icon then PWA Settings.
Click Manage Queue Jobs.
Find the failed queue job related to the workflow error and click on the error for more details.
Note
You will need to change the Job History if the workflow error is older then a week for it to show up in the list.
Additional Steps
Workflow Last Run Date is far in the past for an active project
The project may be checked out in another session and the workflow is unable to progress until the project is checked in. The admin may want to consider force checking in the project to allow the workflow to progress. For more information about checking in a project, please see Manually check in projects and resources that are checked out by another user.
Note
Workflow Last Run Date is referred to Last Submitted Date in the Project Service OData and Project Service REST API.