Skip to main content

Approvals

The Verified Orchestration platform supports the presentation of credentials to approve (or reject) a request. This feature can be used to facilitate workflows that require approval from a human via the presentation of credentials. The approval request can include rich markdown content and a reference link to provide context to the approver.

Diagram of approvals​

approvals diagramapprovals diagram

Example Scenario​

In our fictitious organisation, Acme Software, deployments of software to production require approval from the change management team. The change management team is responsible for ensuring that the deployment is scheduled at an appropriate time, and that the deployment does not conflict with other planned changes.

Each of the change management team holds a credential of type ChangeManager, which can be used to approve the deployment.

Implementation​

Our fictitious organisation, Acme Software, uses GitHub to run their software deployments. A GitHub application is set up to listen for deployment events, and when a deployment is triggered, the application will request approval from the change management team.

Step 1. Request approval​

The GitHub application requests the approval of the deployment by calling the createApprovalRequest mutation.

createApprovalRequest mutation: will return the approval request ID and URL to action the approval
mutation CreateApprovalRequest($request: ApprovalRequestInput!) {
  createApprovalRequest(request: $request) {
    id
    portalUrl
    callbackSecret
  }
}
Example variables for createApprovalRequest mutation
{
  "request": {
    "callback": {
      "url": "https://github.acmesoftware.net/deployment-approval-callback"
    },
    "purpose": "Please provide ChangeManager approval for deployment to Production of the API repository.",
    "referenceUrl": "https://github.com/AcmeSoftware/api/actions/runs/8595211647",
    "requestType": "GitHubApprovalRequest",
    "presentationRequestInput": {
      "requestedCredentials": [
        {
          "type": "ChangeManager"
        }
      ]
    }
  }
}
tip

The purpose field can include markdown formatting to provide a richer context to the approval request.

Example response from createApprovalRequest mutation
{
  "data": {
    "createApprovalRequest": {
      "id": "a4207da5-3009-4e64-bdd4-cb046f5ffb46",
      "portalUrl": "https://instance.portal.verifiedorchestration.com/approval-request/a4207da5-3009-4e64-bdd4-cb046f5ffb46",
      "callbackSecret": "9456443c-4b74-4233-b8df-24670548e140"
    }
  }
}
tip

Additional contextual information for use in the post-approval callback can be included via the ApprovalRequestInput correlationId and requestData fields.

Step 2. Action approval​

The change management team receives a notification that approval is required. They click on the approval request URL to action the request.

  1. The approval request URL will open the Verified Orchestration Concierge in the browser (desktop or mobile).
  2. The change management team member will be prompted to present their ChangeManager credential.
  3. The approval request will be displayed, and the change management team member can approve or reject the request with an optional comment.

Step 3. Callback​

When the approval request is approved, rejected or cancelled, the GitHub application will receive an HTTP Post call to the URL provided in the callback.url field of the CreateApprovalRequest mutation. The posted JSON encoded data will include a status field with either an approved, rejected or cancelled value depending on the outcome. For a full definition of what data is posted, refer to the ActionedApprovalData type.

The GitHub application can then allow the deployment to proceed or cancel the deployment based on the approval status.

Example callback payload
{
  "approvalRequestId": "27091231-af65-42a9-a4c1-97604e04d018",
  "status": "approved",
  "actionedComment": "LGTM 👍",
  "actionedAt": "2024-04-04T02:20:15.856Z",
  "actionedBy": {
    "id": "b3a7f625-20d9-4fe7-9c23-5ddcb836a9b9",
    "name": "Jane Citizen"
  },
  "callbackSecret": "a3ed82cf-af21-40cc-bf7a-8a5369786777"
}
tip

The callbackSecret is a shared secret between the GitHub application and the Verified Orchestration platform. It is returned from the call to the CreateApprovalRequest mutation when creating the approval request, and can be used to verify the authenticity of the callback data.

Additionally, the GitHub application can call the actionedApprovalData query to obtain the actioned approval data by supplying the approvalRequestId.

note

Callbacks will be re-tried in case of error until a 200 response is received, with an exponential backoff allowing a maximum of 3 days for the final retry.

Callback or polling​

As an alternative to receiving a callback, applications coordinating approvals can poll for actioned approvals by calling the actionedApprovalData query and supplying the approvalRequestId. This query returns the ActionedApprovalData, which is the same data the callback receives.

Example query to retrieve actioned approval data
query ActionedApprovalData($approvalRequestId: ID!) {
  actionedApprovalData(id: $approvalRequestId) {
    status
    actionedComment
    actionedBy {
      id
      name
    }
    actionedAt
  }
}
Example variables for actionedApprovalData query
{
  "approvalRequestId": "27091231-af65-42a9-a4c1-97604e04d018"
}

Updating approval requests​

Applications can update the pending approval request's content via the updateApprovalRequest mutation.

updateApprovalRequest mutation
mutation UpdateApprovalRequest($updateApprovalRequestId: ID!, $input: UpdateApprovalRequestInput!) {
  updateApprovalRequest(id: $updateApprovalRequestId, input: $input)
}
Example variables for updateApprovalRequest mutation
{
  "updateApprovalRequestId": "27091231-af65-42a9-a4c1-97604e04d018",
  "input": {
    "purpose": "Please provide ChangeManager approval for deployment **at 6am Friday** to Production of the API repository."
  }
}
note

Only the application that created the approval request can update the request content.

Cancelling approval requests​

Applications can cancel pending approval requests via the cancelApprovalRequest mutation.

cancelApprovalRequest mutation
mutation CancelApprovalRequest($cancelApprovalRequestId: ID!) {
  cancelApprovalRequest(id: $cancelApprovalRequestId)
}
Example variables for cancelApprovalRequest mutation
{
  "cancelApprovalRequestId": "27091231-af65-42a9-a4c1-97604e04d018"
}
note

Only the application that created the approval request can cancel it.

tip

Admin users with the VerifiableCredential.ApprovalRequestAdmin roles are able to cancel approval requests via the Verified Orchestration Composer.

Authorization​

Access to create approval requests and read approval data can be controlled by application and user roles.

Approval applications​

Applications can be authorized to create approval requests, receive callbacks and poll for actioned approval data via the VerifiableCredential.RequestApproval application role.

Refer to Onboarding an app for more information on how to onboard an app.

Approval admin users​

Admin users can be authorized to view and cancel approval requests, via the VerifiableCredential.ApprovalRequestAdmin user role.

The Verified Orchestration Composer provides a feature for filtering, viewing and cancelling approval requests.

Refer to Onboarding users for more information on how to onboard a user.