Migrating from v1 to v2
Version 2 ships with some breaking changes.
#
New client APIVersion 2.0 ships with an entirely reworked client side API.
Breaking changes suck (we know!) - but this change was important to pave the path forwards for these modules.
Below is a list of all breaking changes:
- Login methods now return a User instance.
getUserSession
,loginAnonymously
,loginWithPassword
, andloginWithToken
now all return an instance ofUser
. client.getDocumentPaginator()
andclient.getAllDocuments()
have been moved onto theUser
class. An instance ofUser
must be obtained before you can fetch documents. See above for more info.client.loadDocument()
has been removed in favor ofUser.createDocument()
andDocument.view()
client.getDocumentInfo()
has been removed. Document information can be retrieved directly from the Document class.- Custom query functionality has been removed. This means
client.customQuery()
no longer exists client.isAnnotationUnread()
has been removed in favor of Annotation.isRead.client.getUnreadCountForDocument()
has been removed in favor of Document.unreadCountclient.logout()
has been moved to User.logout()client.isDocumentMember()
has been removed in favour of Document.isMember()client.canJoinDocument()
has been moved to Document.canJoin()client.joinDocument()
has been moved to Document.join()client.leaveDocument()
has been moved to Document.leave()client.getConnectedUsers()
has been removed in favour of Document.getConnectedUsers()client.editDocument()
has been removed in favour of Document.edit()client.getDocumentId()
was removed. Useclient.currentDocumentId
instead.client.inviteUsersToDocument()
was removed in favour of Document.inviteUsers()client.markAllAnnotationsAsRead()
was moved to Document.markAllAnnotationsAsRead()client.copyAnnotations()
was removed in favour of the new Snapshot featureclient.createSnapshot()
was moved to Document.createSnapshotclient.getSnapshotPaginator()
was moved to Document.getSnapshotPaginator()client.getSnapshot()
was removed.client.subscribe()
was moved to client.EventManager.subscribe().- Additionally, names of events have changed and the parameters the events are provided with have changed as well. Please see the events guide for more information on the new event system.
- The parameters passed into the notification callbacks have changed. See this guide for more info.
#
Upgrading WebViewerVersion 2.0 requires that WebViewer 8.0+ is installed and used. To learn how to migrate to WebViewer 8.0, please see this guide
#
Handling timestampsIn version 1, fields such as createdAt
and updatedAt
were provided a unix timestamp in MS (for example, 1622647081013
). However, this was not flexible enough for many databases.
Now, these fields will be set to the result of your getNow()
function.
We recommend setting this function to return a database constant that works with your database.
Now, your resolvers will receive "NOW()"
instead of a unix timestamp, meaning this value can be inserted directly.
V1:
V2:
For more info, view the timestamps guide.
#
Generating IDsIn version 1, IDs were generated internally and passed to the resolvers. However, this was not feasible for databases with auto-incrementing IDs.
Now, IDs are not provided to mutation resolvers that write data, and instead you must generate the ID yourself, or rely on your database to do so. This ID must then be returned from your resolver.
V1:
V2:
annotationId
column#
New Version 2 adds an annotationId
to the annotation entity. This is an optimization that makes handling annotations easier for cross platform use (coming soon).
The annotationId
column will be set to the ID given to the annotation by the client. It will always be a string, but might not necessarily be unique.
Annotations are now queried by annotationId
and pageNumber
rather than by id
.
This change only requires you to add an annotation_id
column to your annotations
table, and to update your annotation resolvers to use the new property.
note
If your database does currently not store this value, you can write a migration script using our utility
V1:
V2:
isPublic
parameter to documents
query resolver#
Added Version two adds a isPublic
parameter to the documents resolver.
Update your resolver to apply this additional field:
#
Updated properties on notification eventsIn version 1, notification events were sent with a sentBy
property that was equal to the users email. In v2, this property has been changed to an object containing both the users email
and userName
.
This change applies anywhere a notification event is passed.
V1
V2
documentId
parameter added to annotationMembers
query resolver.#
A documentId
was added to the annotationMembers
resolver. This allows us to fetch all annotation members for a document in a single query.
This is a simple change to make and is only required if using your own custom resolvers.
COLLAB_KEY
environment variable#
Create the If you do not have the COLLAB_KEY
environment variable set already, you must do so in v2.0.
In version 1, the COLLAB_KEY
environment variable was only required in certain situations. In version 2.0, it must now always be set.