Approval Requests
Overview
This functionality requires PPA version 3.3.0
The approval requests feature can add an extra layer of auditing & security to your tasks.
You can use it when a change needs to be reviewed before it is actioned by the task.
This page explains how they work & gives usage examples.
How It Works
Basics
Approval requests are effectively a controlled & audited way of saying 'yes' or 'no' to a task.
A request is created & activated by a task, & a response is provided by an assignee.
The assignees can respond either via the:
- Requests page in the PPA interface
- Unique request link which can be pushed elsewhere by the task (e.g. via email)
The assignee must provide a reason if rejecting a request.
If they are approving the request, the reason is optional.
Once the response has been provided, it is sent back to the task.
A full audit trail of approval requests is available in the PPA interface 'Requests' page.
Remember
What the task does after the response has been received is controlled by the playbook.
This is to give you flexibility in how your tasks respond to approved & rejected requests.
Make sure your tasks do not apply changes that have been rejected!
Workflow
The approval request workflow consists of 3 stages:
Stages 1 & 2 are performed by task, stage 3 is performed by a user.
The response from stage 3 is sent to the task so it can alter its behaviour accordingly.
Why are creation & activation separate stages?
Once a request is activated, the task is paused & cannot do anything until a response is received.
Creation & activation are separated so you can push a request elsewhere before activating it.
For example, your task could:
- Create an approval request
- Send the request via email to all assignees
- Push that request to a private Slack channel
- Activate the request & wait for a response
Request Creation
This stage prepares a new approval request that can be activated when needed.
Created requests are only visible in PPA once they have been activated
Required Details
To create an approval request, the task must supply the following details.
Requester
PPA knows which user started the task, so this is established automatically.
You do not need to do anything in your task playbook.
Message
This should outline the change the task will make if the request is approved.
It should be as informative as possible; as the assignees may not be able to view the task.
This could be generated automatically by the task playbook, or supplied by the user.
Output
Each created approval request contains the following details:
Requester
Message
Unique Link
These details are used in the activation stage.
Example
- ppa.events.create_approval_request:
request_message: >
**User Account:** Dave Rowlands
**Ticket Number:** SD-845
**Operations:**
- Reset Password
- Force Password Change on Next Logon
save: approval_request
Request Activation
Activating a request will immediately pause the task until a response to that request is received.
The response is sent back to the task, allowing it to alter its behaviour based on the decision.
Activating a request will make it visible in PPA
Required Details
To activate a request, the task must supply the following details.
Created Request
An approval request (output from the creation stage).
Assignees
Assignees are the PPA users able to respond to the request.
At least one valid assignee must be provided when the request is created.
Valid assignees are users who are:
- Imported in PPA
- Not the user running the task
There is no upper limit to the number of assignees you can provide.
See here for more information on assignees & permissions.
Users cannot assign themselves to their own approval requests
-
If the user running the task is supplied as an assignee, they will be ignored
-
If the only assignee supplied is the user running the task, the request will fail
Output
Responses to approval requests contain the following details:
Approved
Indicates whether the request was approved & its value will be true or false.
Responder
The name of the PPA user who responded to the request.
Response Comment
A comment supplied by the responder explaining the decision.
This field is mandatory when rejecting requests & optional when approving them.
Example
- ppa.events.wait_approval_response:
assignees:
- antonio.adams
- colton.collins
- estevan.lowe
- devyn.hessel
load:
approval_request: approval_request
save: response
Responding to Requests
You can respond to approval requests via the PPA interface or a unique request link.
Requests Page
Navigate to the 'Requests' page in the PPA interface.
Open the response form by clicking on the 'Pending' text or the 'Respond' button.
Unique Request Link
When creating an approval request in a task, a unique link will be generated for the request.
Your task can push this link to other platforms, for example:
- Slack or Teams channels
- Ticketing Systems
Using a unique link will prompt the user to authenticate to PPA first.
Approving
Simply click 'Approve' then 'Submit' to approve a request.
You can provide a comment if you wish, but this is optional.
Any reason you supply will be sent to the task, & may be visible to the user running it.
Response Form
Summary
Rejecting
To reject a request you will need to select 'Reject', provide a reason, then click 'Submit'.
The reason you supply will be sent to the task, & may be visible to the user running it.
Response Form
Summary
Auditing
The 'Requests' page contains a full audit trail of every approval request on the system.
By default the user will only be shown requests they are/were assigned to.
If they have either of the special permissions, they will be able to see all of them.
The user is only able to click 'View Task' if they have the permissions to do so.
Permissions
Basic Usage
No role permissions are required in order to use this feature in its basic form.
User access to this feature follows these rules:
- Any user can raise an approval request from a task
- Any user can view & respond to approval requests assigned to them
- Any user can view the approval requests they created, but they cannot respond to them
Special Permissions
These permissions can override some of the rules above.
1. Can view all approval requests
Users with this permission will be able to view all approval requests.
They do not need to be assigned to a request in order to view it.
However, they will only be able to respond to those assigned to them.
2. Can respond to all approval requests
Users with this permission will be able to view & respond to all approval requests.
They do not need to be assigned to a request in order to view & respond to it.