Example: Understanding Collaboration Permissions

Information

Instant sync and collaboration is available when using the Web SDK with Document Engine in server-backed operational mode.

To understand Collaboration Permissions in detail, we’ll look at an example of a PDF with multiple form fields that have to be filled out by a tenant and a landlord.

In this example, there are three parties:

  • Estate agent

  • Landlord

  • Tenant

The estate agent adds the form fields to the document and assigns them to the landlord and the tenant. The landlord can only fill out the fields assigned to them, and the tenant can only fill out the fields assigned to them.

Estate Agent

The estate agent will take a PDF form and add form fields to it. They will need the following permissions in the JSON Web Token (JWT):

const token = {
  ...otherProperties,
  collaboration_permissions: [
    "annotations:view:all",
    "annotations:edit:self",
    "annotations:delete:self",
    "form-fields:view:all",
    "form-fields:edit:all",
    "form-fields:delete:all",
    "form-fields:set-group:group=estateAgent",
    "form-fields:set-group:group=assignedToLandlord",
    "form-fields:set-group:group=assignedToTenant"
  ],
  user_id: "id-1",
  default_group: "estateAgent"
};

The following permission strings are required by the tenant:

  • annotations:view:all — This will allow the estate agent to view all the annotations in the document.

  • annotations:edit:self — This will allow the estate agent to edit annotations they created.

  • annotations:delete:self — This will allow the estate agent to delete annotations they created.

  • form-fields:view:all — This will allow the estate agent to view all the form fields and the associated widget annotations.

  • form-fields:edit:all — This will allow the estate agent to edit all the widget annotations.

  • form-fields:delete:all — This will allow the estate agent to delete all the form fields and related widget annotations.

  • form-fields:set-group:group=estateAgent — This will allow the estate agent to change the group of all the form fields and widget annotations with the group estateAgent. Keep in mind that all the newly created form fields and widget annotations will have the group set to estateAgent, since the estate agent’s default_group set in the JWT is estateAgent.

  • form-fields:set-group:group=assignedToLandlord — This will allow the estate agent to create widget annotations and form fields with the group assignedToLandlord directly. Also, they’ll be able to change the value of the group if they made a mistake.

  • form-fields:set-group:group=assignedToTenant — This will allow the estate agent to create widget annotations and form fields with the group assignedToTenant directly. Also, they’ll be able to change the group if they made a mistake.

These groups will be used to grant permission to the landlord and the tenant.

Landlord

The landlord should be able see all the annotations and form fields but shouldn’t be able to edit them. The landlord will be able to fill out the form fields that have the group set to assignedToLandlord.

To achieve this, the landlord will require the following parameters in the JWT:

const token = {
  ...otherProperties,
  collaboration_permissions: [
    "annotations:view:all",
    "form-fields:view:all",
    "form-fields:fill:group=assignedToLandlord"
  ],
  user_id: "id-2",
  default_group: "landlord"
};

The following permission strings are required by the landlord:

  • annotations:view:all — This will allow the landlord to view all the annotations.

  • form-fields:view:all — This will allow the landlord to view all the form fields and associated widget annotations.

  • form-fields:fill:group=assignedToLandlord — This will allow the landlord to fill out all the form fields in the document with the group set to assignedToLandlord. All other form fields will be read-only.

Tenant

The tenant should be able to view all the annotations and form fields but shouldn’t be able to edit them. The tenant will be able to fill out the form fields that have the group value set to assignedToTenant.

To achieve this, the landlord will require the following JWT parameters:

const token = {
  ...otherProperties,
  collaboration_permissions: [
    "annotations:view:all",
    "form-fields:view:all",
    "form-fields:fill:group=assignedToTenant"
  ],
  user_id: "id-3",
  default_group: "tenant"
};

The following permission strings are required by the tenant:

  • annotations:view:all — This will allow the tenant to view all the annotations.

  • form-fields:view:all — This will allow the tenant to view all the form fields and associated widget annotations.

  • form-fields:fill:group=assignedToTenant — This will allow the tenant to fill out all the form fields in the document with the group set to assignedToTenant. All other form fields will be read-only.

In this way, you can define different permissions for different users based on the parameters you include in the JWT.