Skip to main content

Versioning / Snapshots

Versions of documents can be created by creating "Snapshots".

A snapshot is just a copy of a document at any point of time. A document can be reverted to a snapshot at any time.

note

All the snapshot resolvers must be provided to use this feature

Creating a snapshot#

A snapshot of a document can be created with the Document.createSnapshot() API.

await Document.createSnapshot(name)
  • name (string) The name of the snapshot. Required.

Returns an instance of Snapshot

When a snapshot is created, the server will take all the active annotations on the document, merge them into a single XFDF string, and store that xfdf in the Snapshots table in your database.

If your snapshot contains any large annotations (file attachments, images, etc), they will be extracted and stored separately in the SnapshotAssets table. The reason for this is because we found that SQL like databases are slow at returning large strings, and separating base64 images info their own table significantly improved read times.

Getting snapshots#

Snapshots can be retrieved in two ways: Document.getSnapshotPaginator() or Document.getAllSnapshots().

getSnapshotPaginator#

Document.getSnapshotPaginator(options)
  • options (Paginator options) - Options to feed to the Paginator
  • options.before (number - optional) - Only fetch items created before this data
  • options.limit (number) - How many items to fetch at a time
  • options.orderBy ("createdAt" | "updatedAt") - Which property to sort results by. Defaults to 'createdAt'
  • options.orderDirection ("ASC" | "DESC) - Order ascending or descending.

Return an instance of Paginator which can be used to fetch snapshots.

Example

const paginator = document.getSnapshotPaginator({
limit: 10 // Fetch 10 at a time
})
// Get the first ten snapshots
const firstTen = await paginator.next()

getAllSnapshots#

Document.getAllSnapshots()

Returns an array of Snapshot

Previewing a snapshot#

Once you get a snapshot, you can preview it by calling snapshot.preview().

Previewing a snapshot will place the viewer into preview mode - meaning no annotations can be created, and all real time events will be paused until preview mode is exited.

Entering preview mode will trigger the enteredPreviewMode event.

Exiting preview mode#

To leave preview mode, call snapshot.closePreview(). This will exit preview mode, resync all annotations that were missed while in preview mode, and trigger the exitedPreviewMode event.

Restoring a document to a snapshot#

If you want to revert a document to the state of a snapshot, you can use the Snapshot.restore() API.

restore#

Snapshot.restore(backupName)
  • backupName (string - optional) The name of the backup snapshot to be created. Defaults to "Restored {snapshot name}"

This function does a few things:

1) Creates a new snapshot of the current state of the document. This is created in case you want to revert the restoration you made.

2) Updates the live state of the document to the state represented by the snapshot. This is done by deleting all the annotations for that document from the database, and replacing them with the annotations in the snapshot. This is a destructive operation.

3) Triggers the snapshotRestored event for all users.

4) Updates the state of the document only for the current user - See below for more info

Notes about restoring#

By default, when a document is restored to a snapshot, the changes that take place do not get sent to other users. We believe it would be bad UX to randomly change all the annotations on a users document as they are working, which is why we made this functional decision.

If you want to sync a users screen after the snapshot is restored, you can call the sync function that is passed as the second parameter to snapshotRestored. Calling this function will update the users screen to the latest version of the document.

client.EventManager.subscribe('snapshotRestored', (snapshot, sync) => {
console.log(`Snapshot ${snapshot.id} was restored`);
// Sync the users screen with the latest annotations
sync()
});

This also gives you the opportunity to warn the user that annotations have been restored:

client.EventManager.subscribe('snapshotRestored', (snapshot, sync) => {
console.log(`Snapshot ${snapshot.id} was restored`);
if (window.confirm("A snapshot has been restored - do you want to update your annotations?")) {
sync()
}
});