Editing User Permissions

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

This guide covers different ways to change permissions of both newly created annotations, form fields, and comments (referred to as records in the rest of the guide) and already existing ones while using Collaboration Permissions. Changing the permission of newly created records means creating records with permissions different from the default permission based on the existing JSON Web Token (JWT).

The permission attached to individual records is based on the permission string of the <content-type>:<action>:<scope> format present in the JWT. For example, the permission string annotations:edit:self means that the user has the permission to edit all the annotations that were created by the user (“self” scope). In this example, “self” is a scope that’s used to identify all the annotations for which the edit action should be allowed. The different possible values of scopes can be categorized as follows:

• creator based — Scopes like self and createdBy=<creator-name> fall under this category. This scoping depends on the user_id claim defined in the JWT. The claim cannot be changed once a record has been created, so this scope is immutable.

• group based — Scopes of the form group=<group-name> fall under this category. This scope is mutable, which means you can change the group of a record, provided you have the appropriate permission to do so.

This means that the permission attached to a record is either based on who created the record or the group of that record. Since the creator of the record is immutable, if we want to change the permissions of existing or newly created records, we’ll have to change the group.

In all the scenarios mentioned below, we’ll assume that the default_group claim set in the JWT is group1.

Creating Records with Different Groups

There are multiple ways you can override the default group of newly created annotations, form fields, or comments provided in the JWT. Regardless of how you create them, if you’re assigning a different group to them, you should have the necessary permission.

For example, if you want to create an annotation with the group set to group2 instead of group1 (which is the default group), you should have the permission string annotations:set-group:group=group2 in the collaboration_permissions claim of your JWT. If you don’t have this permission, all the methods described below will throw an error.

Once you create an annotation with a different group, the permissions applicable to that group will be applicable on it instead of the permissions that were applicable to the ones with the default group defined in the JWT.

The following sections will cover all the different ways you can create records with different groups.

For Individual Records

You can create individual annotations, comments, or form fields using the instance.create API:

const inkAnnotation = new PSPDFKit.Annotations.InkAnnotation({
  ...otherOptions,
  group: "group2"
});

const [createdAnnotationID] = await instance.create(inkAnnotation);

For Specific Annotation Types

You can set the group of all the annotations of a particular type using annotation presets. For example, if you want all ink annotations to be created with the group value newGroup, you can use the following code:

const annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  group: "newGroup"
};
PSPDFKit.load({ annotationPresets });

If you want to change the default group of ink annotations after PSPDFKit has loaded, you can use instance.setAnnotationPresets:

instance.setAnnotationPresets(presets => {
  presets.ink = {
    ...presets.ink,
    group: "newGroup"
  };
  return presets;
});

For All Records

There might be situations in which you want to change the default group for all the newly created annotations, comments, or form fields. In that case, you can use instance.setGroup():

instance.setGroup("newGroup");

Please keep in mind that this will change the default group for all record types in the local state. This doesn’t make any change on the server side, so once you refresh the page, the applicable group will revert back to the one set in the JWT.

When you want to reset the applicable group to the one set in the JWT, you can do so using instance.resetGroup():

instance.resetGroup();

One practical use case of this is the implementation of private mode, in which any newly created annotation, comment, or form field is visible only to you.

Changing the Group of an Existing Record

The only way to change the group of an existing record is to use the instance.update() API. Similar to the above case, you’ll need the appropriate permission to do this.

For example, if you want to change the annotation group from group1 to group2, make sure that the annotations:set-group:group=group1 permission string is present in the collaboration_permissions property of your JWT:

const inkAnnotation = (await instance.getAnnotations(0)).get(0);
const _inkAnnotation = inkAnnotation.set("group", "group2");

const [updateAnnotationID] = await instance.update(_inkAnnotation);

The above code will change the group of the ink annotation from "group1" to "group2".