Session Sync Modes and Querying Sessions
By default, all session data and media are synchronized to all users that are either participants of the session or have permissions to read all sessions. While this makes it easier to ensure that all data is synced between devices and users, this can lead to unnecessarily long download and processing times.
Session sync modes provide developers with more control over how much of a given session is synchronized.
The following sync modes can be specified for data:
nonewill prevent the session data and media from syncing. The session will not appear in
basicwill allow base session information (e.g. name, properties, creation date) to sync, but will prevent session data from syncing. The session will appear in
skylight.sessions, but without session data.
allwill allow all session information and session data for the session to sync. The session will appear in
skylight.sessionswith session data.
The following sync modes can be specified for media:
nonewill prevent all media metadata and content from syncing for the session.
session.mediawill be undefined or an empty list.
metadatawill allow media metadata to sync for the session, but will prevent media content from syncing.
session.mediawill contain a list of media items with metadata populated for each item. While
mediaIdwill be available, binding to or otherwise trying to access the media content will fail.
allwill allow media metadata and content to sync for the session.
session.mediawill contain a list of media items and
mediaIdcan be used in media databindings to display the media content.
Session sync modes for data and media can be set on the remote session object or the local session object. The remote sync modes are the default sync modes for all devices, while the local sync modes can be used to override the remote sync modes for a particular device.
Remote sync modes are set on the session object stored in the server database, so remote sync modes are more permanent and global than local sync modes. Every user or device that hasn't set a local sync mode (i.e. has the default local sync modes of
inherit) will automatically use the remote sync mode.
The remote sync modes can be set in script using
skylight.session.setSessionSyncModeand can be accessed in
session.sync.mode. The local sync modes can be set using
skylight.session.setLocalSessionSyncModeand are accessible in
session.local.sync.mode. For more details on using these methods and properties from the scripting API, see Scripting API Reference.
The local sync mode only applies to the device that runs the script that updates the local sync mode and is more ephemeral in nature as it is only stored on the local device database and not the server database. Local sync modes are persisted between application exits and opens, unlike local data. However, signing out will reset the local sync modes.
Local sync modes for both data and media default to the
inheritvalue, which mean that the remote sync modes are used. If the local sync modes are updated to be non-
inherit, setting them back to
inheritwill restore this default behavior of using the remote sync mode.
The current sync status for a session can be determined by using the value of
session.local.sync.status. This can be one of two string values:
- This will be set to the string
in-progressif data or media for that session is still being synchronized for that device.
- This will be set to the string
completedif all data and media for that session have completed synchronizing.
This value signifies the syncing status of the session specifically for the device running the script that queries for it. The same session can have different sync statuses for two different devices. This value can be used in databindings that use the session as a context to indicate to the user the current synchronization status of a session (or multiple sessions).
Sessions can be queried by using
skylight.getSessions(see Scripting API Reference for details) to retrieve basic session information for any sessions that are visible to the user that match the query criteria. This is useful for retrieving information about sessions that may be otherwise inaccessible, such as those that are not synced (ie, data sync mode set to
none) or those that are closed.
The sessions returned from
getSessionsonly contain basic information about the session (e.g. session name, creator, time created, properties) and will not include session data or session media even if the session is currently synchronized to the device.
The result of
getSessionsis a snapshot of the matching sessions as they appeared at the time of query. As such, any updates to those sessions (e.g. adding a new property or changing the name of the session) will not be reflected in the session object returned in the list from
getSessions. This is notably different from the sessions in
skylight.sessions, which are the sessions that are explicitly synchronized and will be kept updated with changes.
The ability to query sessions and set explicit sync status modes leads to a lot of control for the developer to specify exactly what data is synchronized with the device and when. This is an example implementation to illustrate one possible way that these features can be used.
In order to prevent the session from being synchronized to devices by default, the remote session sync status can be set to
nonefor both data and media after creating it. If the user who created the session requires the session to be synchronized to perform further work on it, the local session sync mode should then be set to
allfor both data and media, which will then synchronize the session data and media for the user.
When the user is finished using the session locally, the session can be unsynchronized by setting the local sync mode to
inheritfor both data and media. Or, the session will be unset the next time the user signs out.
Regardless of whether a particular session is synchronized for the user, all sessions that are accessible to the user (as either a participant in the session or by having permission to view all sessions) can be queried. This is useful in situations like:
- showing all sessions that have a specific custom value set in session properties
- showing all sessions that have been created by the user that are open
- showing all sessions that have a particular name
To do this, the sessions are queried using
getSessions. The returned list is then stored in
skylight.local.saveData. The property used to store this can be databound, which will then automatically update when the value is set to the returned array.
This query can be triggered for example by a user card selection action or by a view open action. In the latter, the flow would look like:
- 1.User opens a view that has a card databound to
- 2.View open script performs a
- 3.The result of the query is stored into
- 4.The card that is databound to that local data property will automatically show one card per session with each session as the context
getSessionscall as described above, a list of cards can be shown, each having a session returned from
getSessionsas a context. By using the select action for the card to update the local sync mode, we can sync the appropriate session when the user selects the card.
Some example use cases for this include:
- a manager viewing a list of submitted sessions, selecting a specific session to view its details
- an inspector viewing a list of their previous inspections (sessions), selecting a specific inspection to to review or continue
- a worker seeing a list of work orders to perform, selecting a specific one to then perform work on
To do this, the select action for the card should set the local data sync mode to
allfor both data and media. Then, the session data and media will begin to sync. At this point, the session can be set using
skylight.session.setand a view/card bound to the session can be shown to the user which will begin to populate with the information being synchronized for the session.