Work Sessions

Work Sessions (or sessions for short) are the lifeblood of Skylight applications and contain the data that is presented to the user, as well as the data that is gathered from the user. Events that occur in a session are saved to and modify the session data. These events become part of an immutable timeline of events that have taken place in the session that can be used for real-time and post-processing tasks like auditing, report generation, visualizations of the procedure, and ROI computations.

Sessions should generally represent discrete real-world procedures, like:

  • An inspection

  • A pick and pack flow

  • An assembly process

Sessions have two components – the session itself and the session data.

Session

The session itself has a name, description, participants, and properties. The name is required when creating a session; the other fields are optional.

Participants

Participants is a list of participant objects that each have type and id. type is either user or group, specifying whether the id is a skylight group’s id or a skylight user’s id.

When creating a session using the client-side scripting logic, the user that calls that script will automatically be added as a user-type participant to that session. While participants are not visible to client-side scripts, client-side scripts can add participants to a session by either:

  • passing them into the initial session.create call (which will then append the user that called the script as well) or

  • setting that session as the active session in a client-side script then calling addParticipant. See Scripting API Reference for details.

Participants can be removed from a session by setting the session as the active session in a client-side script and then calling removeParticipant.

Properties

Properties is a dictionary of string keys and string values that can be set by the developer. In client-side scripts, properties can be specified when creating sessions and can also be updated by using the skylight.session.update method. See Scripting API Reference for details.

When using the update method, all properties will be replaced by the new properties.

Session Data

Sessions also have session data, which is a dictionary of string keys and primitive, object, or array values. Session data is not directly accessible on the session object but is accessible through other means. Session data is accessible in client-side scripts by setting the relevant session and calling skylight.session.data. See Scripting API Reference for details.

When patching session data either through the client-slide logic or the API/SDK, a session data event is created. This means that there is an immutable history of changes to session data.

See the section below on Session Updates for more information about patching session data.

Session Lifecycle

The lifecycle of a session consists of:

  1. Creating a session

  2. Updating a session and its session data

  3. Closing a session

Session Creation

Sessions can be created at any time, either through client-side scripting (e.g. a user creates a session to mark the start of working on a copy of an existing inspection workflow) or by calling the Skylight REST APIs or using the SDK (e.g. in the case of creating sessions based off of a list of inspections that need to be completed).

When creating a session, the name must be specified. Description and properties are optional. If creating the session client-side, the user creating the session will automatically be added as a participant.

Session Updates

Once a session has been created, the name, description, properties, and participants of a session can be updated.

Updating the name and description are fairly straightforward. Participants can be added in client-side scripts using skylight.session.addParticipant once the session has been set, or by using the Skylight API/SDK.

Updating the properties of a session is done client-side by passing the new properties object into skylight.session.update once the session has been set. In the Skylight API/SDK, the properties object can similarly be passed into the session update method.

When using the update method, all properties will be replaced by the new properties.

To bind data to a view from the session, update a session, save data to a session, read data from a session or its data, or close a session, that session must be first set using the skylight.session.set method in an event script.

Session Data Patches

Once a session has been created, the session data can be patched. Session data is patched by using the Skylight REST API/SDK, or in client-side scripts by setting the relevant session and then calling skylight.session.saveData. These methods will act as a patch for the session data, only updating the specified fields and not overwriting the rest of the session data. There is currently no way to delete a session data key, though they can have null values.

These individual patches to the session data are saved in Skylight as a session event stream. This means that while the session data itself is mutable, the events that have already occurred and are part of the event stream are immutable. This means that it is possible to track all of the events that shaped the session data, increasing clarity and auditability.

Session Close

Sessions can be closed using the client-side script’s skylight.session.close once the session has been set, or by using the API/SDK. Once a session has been closed, all updates to the session and the session data will be restricted.