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:
A pick and pack flow
An assembly process
Sessions have two components – the session itself and the session data.
The session itself has a
properties. The name is required when creating a session; the other fields are optional.
Participants is a list of participant objects that each have
type is either
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
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.
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.
The lifecycle of a session consists of:
Creating a session
Updating a session and its session data
Closing a session
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.
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.
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.
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.