Skylight Docs
Search
⌃K
Comment on page

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.

Session Sync Mode: Data

The following sync modes can be specified for data:
  • none
    • Specifying none will prevent the session data and media from syncing. The session will not appear in skylight.sessions
  • basic
    • Specifying basic will 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.
  • all
    • Specifying all will allow all session information and session data for the session to sync. The session will appear in skylight.sessions with session data.

Session Sync Mode: Media

The following sync modes can be specified for media:
  • none
    • Specifying none will prevent all media metadata and content from syncing for the session. session.media will be undefined or an empty list.
  • metadata
    • Specifying metadata will allow media metadata to sync for the session, but will prevent media content from syncing. session.media will contain a list of media items with metadata populated for each item. While mediaId will be available, binding to or otherwise trying to access the media content will fail.
  • all
    • Specifying all will allow media metadata and content to sync for the session. session.media will contain a list of media items and mediaId can be used in media databindings to display the media content.
​

Local vs Remote Sync Modes

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.setSessionSyncMode and can be accessed in session.sync.mode. The local sync modes can be set using skylight.session.setLocalSessionSyncMode and 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 inherit value, which mean that the remote sync modes are used. If the local sync modes are updated to be non-inherit, setting them back to inherit will restore this default behavior of using the remote sync mode.

Sync Status

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-progress if data or media for that session is still being synchronized for that device.
  • This will be set to the string completed if 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).

Querying 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 getSessions only 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 getSessions is 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.

High-level Example Use

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.

Sync mode set to none on session creation

In order to prevent the session from being synchronized to devices by default, the remote session sync status can be set to none for 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 all for 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 inherit for both data and media. Or, the session will be unset the next time the user signs out.

Query for relevant sessions to display as a list to the user

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 inskylight.local.data using 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. 1.
    User opens a view that has a card databound to skylight.local.data.queriedSessions
  2. 2.
    View open script performs a getSessions query
  3. 3.
    The result of the query is stored into skylight.local.data.queriedSessions using skylight.local.saveData
  4. 4.
    The card that is databound to that local data property will automatically show one card per session with each session as the context

Synchronize selected session

Using the getSessions call as described above, a list of cards can be shown, each having a session returned from getSessions as 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 all for 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.set and 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.
​
​
​
Previous
Work Sessions
Next
Card Sizing
Last modified 2yr ago