Control review permissions

Control editor review actions with CreateEditorOptions.canPerformTrackedChange. Assign a participant role to enforce document-wide permissions in editor and programmatic workflows.

Before you start, install Nutrient Document Authoring SDK and load it in your app. If you haven’t set it up, refer to the getting started guide.

Deny revision decisions in the editor

The following example returns true for new tracked changes when the editor is already creating them. It limits revision decisions to IDs from a list maintained by your application.

import type {
  DocAuthDocument,
  DocAuthEditor,
  DocAuthSystem,
} from '@nutrient-sdk/document-authoring';

export async function createRestrictedReviewEditor(
  system: DocAuthSystem,
  document: DocAuthDocument,
  target: HTMLElement,
  allowedRevisionIds: ReadonlySet<string>,
): Promise<DocAuthEditor> {
  try {
    return await system.createEditor(target, {
      document,
      canPerformTrackedChange(operation, revisionId) {
        if (operation === 'create') {
          return true;
        }

        return revisionId !== undefined && allowedRevisionIds.has(revisionId);
      },
    });
  } catch (error) {
    console.error('Failed to create the review editor.', error);
    throw error;
  }
}

The callback receives create, accept, or reject. The revisionId argument is present for accept and reject operations.

The callback is synchronous: Returning false or throwing denies the operation and leaves the document unchanged. Make it idempotent and free of side effects — return the same result for the same input, and don’t change application state inside it — since the editor may call it more than once while updating controls or processing input.

This callback applies only to tracked change operations that start in the editor. Transactions started by the host through DocAuthDocument.transaction() don’t call it.

Assign a document participant role

Set LoadDocumentOptions.participant when you load a document. The role applies to programmatic transactions and editor input for that document.

import type {
  DocAuthDocument,
  DocAuthDocumentInput,
  DocAuthSystem,
} from '@nutrient-sdk/document-authoring';

export async function loadForReviewer(
  system: DocAuthSystem,
  input: DocAuthDocumentInput,
): Promise<DocAuthDocument> {
  try {
    return await system.loadDocument(input, {
      participant: {
        author: 'Dana Reviewer',
        role: 'reviewer',
      },
    });
  } catch (error) {
    console.error('Failed to load the document for review.', error);
    throw error;
  }
}

Nutrient Document Authoring SDK supports these ParticipantRole values:

• The owner role edits content, creates comments and tracked changes, and accepts or rejects revisions.
• The reviewer role creates comments and tracked changes. It also withdraws the reviewer’s pending revisions.
• The reader role reads the document without changing it.

A reviewer transaction that changes the document requires TransactionOptions.review. Its author must match the participant author. This requirement also applies to programmatic comment changes.

Use document.getParticipant() to read the current participant. Use document.setParticipant() to change it without reloading the document. A document without an explicit participant uses the owner role and an empty author label.

Bind participant labels to authenticated users

The participant author is a host-supplied label that Document Authoring records on suggestions and comments — it doesn’t authenticate the participant or verify authorship.

Bind each Participant to an authenticated application user. Don’t treat an author label as proof of identity.

Combine participant roles with the editor callback

Participant policy and canPerformTrackedChange are independent checks. An operation proceeds only when both checks pass.

The editor doesn’t automatically hide or disable every control a participant can’t use — a control can remain available even when the participant’s role blocks the operation — so keep application controls aligned with the authenticated user’s role.

Learn more

Use these guides for related review workflows:

• Refer to the tracked changes and editor modes guide to configure editor review behavior.
• Refer to the manage tracked changes programmatically guide to manage revisions in transactions.
• Refer to the observe review events guide to listen for review workflow events.