In this article, we will walk through the process of setting up API-based approvals for project stages.
API-based approvals allow an external approval process to be triggered when a user attempts to transition to the next stage. The transition will only occur once the external approval is completed and an API event is sent back to PPM Express, confirming the transition.
To enable and configure API-based approvals for project stages, follow these steps:
1. Enable API-Based Approvals for the Process
A PPM Express Administrator must enable API-based approvals for the required process.
- Navigate to the Process Management page.
- Open the Process where you need to configure API-based approval.
- Open the relevant stage for editing.
- Set the Approval for Transition option to API-based approval.
- Click Confirm in the popup and then Save Stage.
This must be done for all stages requiring approval for completion and transition to the next stage.
2. Configure the API-Based Approval Workflow URL
- Open the project where the process with API-based approvals is applied.
- Go to Project Settings -> Project Process.
- In the "API-based Approval Workflow URL" field, specify the URL of the external API-based approval workflow.
- Click Save.
The approval request/event will be sent to that endpoint when a user attempts to move to the next stage.
3. Stage Transition and Approval Process
When a user clicks the "Go to the next stage" button for a stage with API-based approval:
- A popup message will inform them that the API-based approval process has been triggered.
- The stage state will change to "Waiting for API-based approval".
- The "Go to the next stage" button will become inactive.
- The stage will transition to the next one once the external approval is granted.
4. API Triggering and Approval Actions
When the "Go to the next stage" action is triggered, an API request is sent to the URL specified in Project Settings -> Project Process. The request includes details such as:
- Tenant ID
- Current Stage ID and Name
- Next Stage ID and Name
- Project ID and Name
The transition request should then be approved or rejected by sending a corresponding POST API request. It also can be done using Swagger interactive API documentation -> Project Process section.
5. Approving or Rejecting the Transition
There are three available actions (API endpoints) for the Project Process:
- Get the list of stages
GET https://host/@{tenant}/v1.0/projects/{id}/process/stages - Approve transition to the next stage
POST https://host/@{tenant}/v1.0/projects/{id}/process/stages/{stageId}/approve - Reject transition to the next stage
POST https://host/@{tenant}/v1.0/projects/{id}/process/stages/{stageId}/reject
To approve a transition:
- Provide the Tenant ID, current Stage ID, and Project ID.
- Execute the request.
- The project will transition to the next stage, and the previous stage will be marked as Completed.
If the user moves back to a previous stage and attempts to advance again, the approval process will be triggered again.
If the approval is rejected, the stage will not change, and the current stage will remain active.
6. Permissions for Using API-Based Approvals
To use these actions for the Project Process, the API token must have Projects: Read & Write scopes.
In the Modified By field for a stage with approval, the user displayed will be the owner of the API token used to approve or reject the transition. This means that the API performs the stage action on behalf of this user.
If API-based approval is enabled, only a PPM Express Administrator can use the "Skip to Stage" option to bypass the approval process.
Users with Edit permission for projects can trigger the approval process. However, they cannot skip to any stage that follows the stage with approval. "Skip to Stage" action will be available only to stages before the one that requires approval.