External Approval Workflow

Overview

You can configure an approval workflow in an external service such as Microsoft Power Automate. This functionality basically allows you to send the workspace request object to a REST endpoint of an external service. After processing the request in the external service you can call the approve or reject endpoints of the Workspaces API.

Enabling the external approval workflow

Config Editors can enable the approval workflow for a site type on the approvalWorkflow property on the WorkspaceTypeConfig. In order to do this, the isEnabled boolean needs to be set to true and a URL for the external service must be specified on the webhookUrl property.

approvalWorkflow configuration example:

...
  approvalWorkflow: {
    isEnabled: true,
    webhookUrl: "<your external service endpoint URL>"
  }
...

A new workspace is requested

When the external approval is enabled and a user requests a new workspace, a POST call is triggered to the external service endpoint and an object of the type IWorkspaceRequest is sent in the payload.

Payload example:

{
  "WorkspaceUrl": "https://<tenant>.sharepoint.com/sites/NewWorkspace",
  "Created": "2021-01-04T11:51:04.2582666Z",
  "ApprovalState": 0,
  "Requestor": {
    "Type": 0,
    "Key": "john.doe@<tenant>.sharepoint.com",
    "Name": "John Doe"
  },
  "Payload": {
    "EventType": "Create",
    "TenantUrl": "https://<tenant>.sharepoint.com",
    "WorkspaceTypeKey": "<typeKey>",
    "Values": {
      "Title": "A New Workspace",
      "Description": "The description for the new workspace"
    },
    "Lcid": 1033
  },
  "ShortGuid": "<shortGuid>"
}

Approving Or Rejecting A Workspace Request

After processing the request you can approve or reject it by performing a POST request to the Workspaces API. The procedure is the same for approving or rejecting a request. The only difference is the API endpoint that is called.

Workspace API Endpoints

• Workspace request approval: https://workspaces.matchpoint365.com/api/workspaces/request/approve/<shortGuid>

• Workspace request rejection: https://workspaces.matchpoint365.com/api/workspaces/request/reject/<shortGuid>

The <shortGuid> URL parameter is found on the payload recieved by the external service.

Request body

The contents of the body of the Workspaces API request must be a IWorkspaceApprovalPayload object. When approving a request, the workspace fields on the values property can be overridden if deemed necessary.

When rejecting a request, a reason can be provided using the comment property of the IWorkspaceApprovalPayload

Examples:

Reject a workspace with the shortGuid: xyz9abcTVP6OMK108OylCr:

Endpoint:

• POST: https://workspaces.matchpoint365.com/api/workspaces/request/reject/xyz9abcTVP6OMK108OylCr

Payload:

{
  comment: "There is no need to create a Workspace for this project as it has recently been cancelled."
}

Review and approve a workspace with the shortGuid: xyz9abcTVP6OMK108OylCr:

Endpoint:

• POST: https://workspaces.matchpoint365.com/api/workspaces/request/reject/xyz9abcTVP6OMK108OylCr

Payload:

{
  "comment": "",
  "payload": {
      "eventType": "Create",
      "tenantUrl": "https://<tenant>.sharepoint.com",
      "workspaceTypeKey": "team",
      "values": {
          "Title": "Contoso Legal",
          "Description": "This Workspace contains all the legal data related to Contoso"
      },
      "lcid": 1033
  },
  "targetWebUrl": "https://<tenant>.sharepoint.com/sites/ContosoLegal"
}