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 snapshotA snapshot of a document can be created with the Document.createSnapshot() API.
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 snapshotsSnapshots can be retrieved in two ways: Document.getSnapshotPaginator()
or Document.getAllSnapshots()
.
getSnapshotPaginator
#
options
(Paginator options) - Options to feed to the Paginatoroptions.before
(number - optional) - Only fetch items created before this dataoptions.limit
(number) - How many items to fetch at a timeoptions.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
getAllSnapshots
#
Returns an array of Snapshot
#
Previewing a snapshotOnce 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 modeTo 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 snapshotIf you want to revert a document to the state of a snapshot, you can use the Snapshot.restore()
API.
restore
#
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 restoringBy 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.
This also gives you the opportunity to warn the user that annotations have been restored: