Rasterex APINPM Package/docs/solutions/save-reload-markups-file-version

Save and Reload Markups per File Version

NPM SDK solution for confirming annotations, saving extracted data, and associating host records with an immutable file version.

NPM SDK scope and prerequisites

Mount the viewer, await viewer.ready(), open the intended document, and establish the active file identity before enabling annotation controls. Register annotation listeners before users can create or change markups.

Read the NPM Annotation Guide, Annotation Markup API, Data Extraction API, and Save API.

NPM implementation order

Use viewer-confirmed identifiers and result-backed operations to protect the host record.

  • 1Open the file version and retain the host-owned fileVersionId alongside the active document state.
  • 2Subscribe to viewer.annotations.on("created", handleCreated), viewer.annotations.on("selected", handleSelected), and viewer.annotations.on("deleted", handleDeleted) before enabling tools.
  • 3Activate a documented annotation action with viewer.tools.set({ action, enabled: true }).
  • 4Wait for the created event and use its guid before linking a host record.
  • 5Call viewer.annotations.getData({ filter: "annotations" }) or filter: "all" when the host needs a snapshot.
  • 6Call viewer.annotations.save() when the host needs Canvas save completion, and require result.success.
  • 7Persist the extracted snapshot or host metadata under the current fileVersionId only after the relevant operation succeeds.
  • 8On reload, open and confirm the matching file version before reading its host record.

Validate identifiers and persistence state

Host validation protects against cross-version updates and stale annotation references.

  • Require a non-empty, immutable host file-version identifier.
  • Require a viewer-provided annotation guid before saving dependent host metadata.
  • Do not use a filename, array index, timestamp, or generated placeholder as a Canvas annotation identifier.
  • Keep pending writes scoped to both fileVersionId and annotation guid.
  • Treat extracted items as a snapshot; preserve null and optional fields according to the schema reference.
  • Do not describe getData as an import or restore operation.

Separate Canvas save from host reload

Save annotations

Await completion and inspect the save result.

Extract annotation data

Read the current Canvas snapshot.

Annotation schema

Consume observed item fields without inventing import semantics.

viewer.annotations.save() confirms the documented Canvas save flow and returns a result with success and requestId. viewer.annotations.getData(...) reads current Canvas data. Neither method defines the host database schema or a generic annotation import method.

For reload, fetch the host record by the confirmed file-version key. If the deployed Canvas contract supports applying stored annotations, document and verify that capability separately; otherwise, present the stored host data as a record and do not claim that the viewer has restored markups.

Recovery and cleanup

On save or host persistence failure, keep the current viewer result and show retry without switching the active file version. On a version change, invalidate pending writes and clear stale selection or draft metadata.

Do not remove a host record until a confirmed delete event identifies the matching annotation. Unsubscribe listeners and destroy the viewer on route cleanup.

Continue with the NPM workflow

Annotation guide

Implement creation, selection, deletion, and cleanup.

React issue-management setup

Review host records associated with annotations.

Save annotations

Handle result-backed Canvas save completion.

Data extraction

Read a current annotation snapshot.

Use the annotation guide and reference example for the complete host UI sequence.