Provisioning

Rather than manually maintaining the employees and offices in Pexip Engage, it is possible to set up an automated provisioning mechanism that synchronizes with an external source.

There are two mechanisms that can be used for automated provisioning:

  1. Use our SCIM 2.0-compliant API in combination with a compatible user directory
  2. Build a custom provisioning integration using the Employee endpoints and Office endpoints

SCIM 2.0

A lot of user directory systems support provisioning users to other systems using SCIM 2.0, like Microsoft Azure Active Directory and Google Workspaces. This is the fastest way to get automated user provisioning set up as it requires no additional development.

Note that our SCIM-compliant API currently only supports provisioning employee information and roles but not offices and relations between offices and employees.

Contact your account manager to request more information and guidance.

Custom

A custom integration is needed when the user directory in use is not capable of provisioning users to Pexip Engage using 2.0 or when other resources need to be provisioned, such as offices or relations between offices and employees.

Provisioning is ideally done incrementally. This means that changes to employees/offices should be detected in the external system and then translated into the corresponding API call to Pexip Engage to synchronize the data.

Taking the provisioning of employees as an example, the following could be done:

  • On creation of a new employee, make a POST /employees request with request body

    {
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@acme.com",
  "function": "Advisor"
  "externalId": "ABC123",
  "availableRoles": ["AGENT"]
}

    where the externalId property contains the ID of the employee from the user directory.

  • On modification of an employee, first make a GET /employees?external-id=ABC123 request to find the employee ID in Pexip Engage (let's say 1234) and then make a PATCH /employees/1234 request with request body

    {
  "function": "Senior Advisor"
}

  • On deletion of an employee, first make a GET /employees?external-id=ABC123 request to find the employee ID in Pexip Engage (let's say 1234) and then make a DELETE /employees/1234 request.

It is recommended to work with an external ID (as shown in this example) instead of storing the Pexip Engage ID of the employee in the user directory as the Pexip Engage ID structure is subject to change, which would break the integration if relied upon.

Note that building a custom integration for user provisioning that hooks into our SCIM-compliant API, rather than the Employee endpoints, can still be recommended as it might ease a possible transition to a compatible user directory in the future.