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:

  1. Setting up views and reports to see the errors

  2. Reviewing the errors

  3. Acting on the errors and taking additional steps

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

  1. From Project Web App, click on the gear icon then ** PWA Settings **.

  2. On the settings page, click Manage Views. A list of views will appear.

  3. Click ** New View **.

  4. In the Name and Type section, in the ** View Type ** list, select Project Center.

  5. In the Name box, type the name of the new view. For example, " Project Workflows ".

  6. In the Description box, type a description of the new view.

  7. 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

  1. Scroll to the bottom of the page and click Filter.

  2. Add the filter using the field " Workflow Error Codeis greater than 1" and click OK .

  3. 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:

  1. From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.

  2. Click on Projects in the ribbon.

  3. 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 any other errors that are not listed above, please let us know. There are two ways to contact us, either through our User Voice forum or by contacting Microsoft support. Please provide us with 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

  1. From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.

  2. Click on the project name.

  3. Click on the project name from the Quick Launch.

  4. Expand the All Workflow Stages section.

  5. Click the Additional Workflow Data link.

  6. Click the "i" icon beside the Internal Status.

  7. 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

  1. From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.

  2. Click on the project name.

  3. 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.

  4. Click OK

To restart project workflows for a set of projects

  1. From Project Web App, click on the gear icon then PWA Settings.

  2. Click on Change or Restart Workflows.

  3. Choose the Enterprise Project Type from the list for the projects.

  4. 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.

  5. Select Restart current workflow for the selected projects.

  6. Click OK.

Optionally Project workflows can be programmatically restarted. ProjectWorkflowInstance has two methods to restart Project Workflows:

  • RestartWorkflow()

POST https://CONTOSO.sharepoint.com/teams/project/PWA/_api/projectserver/projects('PROJECT_GUID')/ProjectWorkflowInstance/RestartWorkflow()

  • RestartWorkflowSkipToStage(stageId)

POST https://CONTOSO.sharepoint.com/teams/project/PWA/_api/projectserver/projectworkflowinstances('WORKFLOW_INSTANCE_GUID')/RestartWorkflowSkipToStage('STAGE_GUID')

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

  1. From Project Web App, navigate to Project center by clicking Projects from the Quick Launch.

  2. Click on the project name.

  3. Click on the project name from the Quick Launch.

  4. Expand the All Workflow Stages section.

  5. Click the Additional Workflow Data link.

  6. 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

  1. From Project Web App, click on the gear icon then PWA Settings.

  2. Click Enterprise Custom Fields and Lookup Tables.

  3. Click on a custom field.

  4. Scroll to the bottom of the page.

  5. 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

  1. From Project Web App, click on the gear icon then PWA Settings.

  2. Click Manage Queue Jobs.

  3. 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.