Skylight Docs
Search
K

Scripting API Reference

API reference for developing scripts in Skylight Application Builder.
Parameters in this page denoted with an asterisk (*) are required.

Common Terms

Promise

Many functions run asynchronously, such as the creation of a session. These asynchronous functions return a promise, which means that the function can be awaited (see here for more details) in order to pause execution of the code until that function has completed its operation.

Configuration Object

Instead of passing in multiple arguments into a function, a dictionary with the parameters as keys and the arguments as values is used instead for functions with two or more parameters. This dictionary is called the configuration object. This paradigm allows us to create code that is both resilient in changes to method signatures as well as provide and/or remove optional arguments more easily.

Global

The other objects (e.g. Session, Application) on this page are accessed through the skylight object (i.e. skylight.session.create()). The global object exists at the root level as its own object.
The global object can be written to and read from all scripts. This enables the ability for scripts to share functions and objects.
One typical use case for this is to define shared constants and functions in the Application Open script, which will then be accessible by all other scripts.

Session

session.create()

(method) skylight.session.create({ name: string, description: string, properties: object, participants: [Participant] }: NewSession): Promise<any>
Creates a new application session and automatically makes the creator a participant. You can also pass this an object of properties that match the session data model to set things like “title” and “status”.
Parameters
Return Value
Usage
Parameters
Type
Description
name*
string
A human-friendly name for the session.
description
string
A short description of the new session.
properties
object
Custom indexable and filterable properties.
participants
array
Users and groups participating in the session.
Promise.<object> Session object
// Create a session with name and description:
await skylight.session.create({
name: 'Hello',
description: 'World',
properties: {
propertyA: "valueA",
propertyB: "valueB",
propertyC: "valueC" } })
// Create a session and assign it to another user:
await skylight.session.create({
name: 'Bob',
participants: [{
type: 'user',
id: 'af24d58b-0e91-4777-80bc-3218acde50a7'}]

session.set()

(method) skylight.session.set(sessionId: string): Promise<any>
Sets the current session. All session properties such as name, data, participants, media, etc are updated to match those in the specified session.
Parameters
Return Value
Parameters
Type
Description
sessionID*
string
A valid UUID representing an active Session.
Promise.<object> Session object

session.unset()

(method) skylight.session.unset(sessionId: string): Promise<void>
Unsets the current session (set by session.set).
Parameters
Return Value
Parameters
Type
Description
None

session.close()

(method) skylight.session.close(): Promise<void>
Locks the current session so it no longer receive new events or changes.
Parameters
Return Value
None
None

sessions

(property) skylight.sessions: [Session]
Returns an array of “open” session objects according to this user’s permission.
Parameters
Return Value
None
array Session objects

session.update()

(method) skylight.session.update({ name: string, description: string, properties: object, participants: [Participant] }: UpdateSession): Promise<void>
Updates current session properties.
Parameters
Return Value
Parameters
Type
Description
name
string
Session name
description
string
Session description
properties
object
Custom indexable and filterable properties
participant
array
Users and groups participating in the session
None

session.data.<dataprops>

(property) skylight.session.data: object
Returns the current snapshot of data for the session as known by this local state of the session.
Parameters
Return Value
None
object Session data

session.name

(property) skylight.session.name: string
Returns the session name.
Parameters
Return Value
None
string Session name

session.description

(property) skylight.session.description: string
Returns the session description.
Parameters
Return Value
None
string Session description

session.sync.mode

(method) skylight.session.setSessionSyncMode({ mode: object, sessionId: string }): Promise<void>
Returns the remote sync modes for the session. Does not take into account local sync mode settings.
Parameters
Return Value
None
object The session's remote sync modes, e.g.: { data: 'none', media: 'none' }

session.local.sync.mode

(method) skylight.session.local.sync.mode: object
Returns the local sync modes for the session.
Parameters
Return Value
None
object The session's sync modes, e.g.: { data: 'inherit', media: 'inherit' }

session.local.sync.status

(method) skylight.session.local.sync.status: string
Returns whether any data or media is currently syncing for the session, or if the session has completed all syncing.
Parameters
Return Value
None
string Sync status of the session, either in-progress or completed

session.participants

(property) skylight.session.participants: [Participant]
Returns the session participants.
Parameters
Return Value
None
array Participants

session.properties

(property) skylight.session.properties: any
Returns any custom properties set on the session.
Parameters
Return Value
None
object Session properties

session.status

(property) skylight.session.status: SessionStatus
Returns the session status.
Parameters
Return Value
None
string Session status (open|closed)

session.sessionId

(property) skylight.session.sessionId: string
Returns a valid UUID representing an active Session.
Parameters
Return Value
None
string UUID for the active session

session.saveData()

(method) skylight.session.saveData(data: object): Promise<void>
Queues a patch to the new portion of the session data. Also, creates an event of type session_data_updated. If offline this data change will reflect on the local client session data structure.
Parameters
Return Value
Usage
Parameters
Type
Description
data
object
An object representing an atomic data change
None
//Create a new session
let newSession = await skylight.session.create({
name: skylight.application.data.processName })
//Set the session
await skylight.session.set(newSession.sessionId)
let newData = {
"stepStatus": {
"1": "incomplete",
"2": "incomplete",
"3": "incomplete"
}
}
//Save data to the sessioin
await skylight.session.saveData(newData)

session.createEvent()

(method) skylight.session.createEvent({ eventType: string, data: object, properties: Properties }: SessionEvent): Promise<void>
Creates a custom event for this session.
Parameters
Return Value
Parameters
Type
Description
eventType
string
Custom name for the event, e.g. product_selected
data
object
Custom event data object
properties
object
Custom indexable and filterable properties
None

session.media

(property) skylight.session.media: [MediaItem]
Returns an array of all media captured during the session.
Parameters
Return Value
None
array <media Object>

session.addParticipant()

(method) skylight.session.addParticipant({ id: string, type: ParticipantType }: Participant): Promise<void>
Adds a participant to the session.
Parameters
Return Value
Parameters
Type
Description
id*
string
user or group id
type*
string
user or group
None

session.setSessionSyncMode()

(method) skylight.session.setSessionSyncMode(mode: object, sessionId: string): Promise<void>
This sets the remote sync modes for the session, which clients will use by default. For example, passing in {data:'none', media:'none'} will tell clients to not sync the session, even if they are a participant/admin.
As noted in the parameters list, the full modes object must be specified with both data and media. The current modes can be accessed under skylight.session.sync.mode
These sync modes can be overridden using the setLocalSessionSyncMode method.
Parameters
Parameters
Type
Description
mode*
object
An object with the new data and media sync modes:
  • data*: set data sync mode to
    • none - session will not be synced to the client by default
    • basic - base session fields and properties will be synced; session data will not be synced
    • all - all session fields, properties, and session data will be synced
  • media*: set media sync mode to
    • none - no media information will be synced
    • metadata - list of session media metadata will be synced; media content will not be synced
    • all - list of session media metadata and all media content will be synced
sessionId
string
a string id of the session that should update its sync mode. If unspecified, this method will attempt to perform this update on the currently set session if it exists. When possible, it is recommended to pass in the session id explicitly.

session.setLocalSessionSyncMode()

(method) skylight.session.setLocalSessionSyncMode(mode: object, sessionId: string): Promise<void>
This overrides the remote session sync modes for the session. This override only applies locally to the client on which this method is called.
As noted in the parameters list, the full modes object must be specified with both data and media. The current modes can be accessed under skylight.session.local.sync.mode
Parameters
Parameters
Type
Description
mode*
object
An object with the new data and media sync modes:
  • data*: set data sync mode to
    • inherit - use the remote data sync mode to determine behavior
    • none - session will not be synced to the client by default
    • basic - base session fields and properties will be synced; session data will not be synced
    • all - all session fields, properties, and session data will be synced
  • media*: set media sync mode to
    • inherit - use the remote media sync mode to determine behavior
    • none - no media information will be synced
    • metadata - list of session media metadata will be synced; media content will not be synced
    • all - list of session media metadata and all media content will be synced
sessionId
string
a string id of the session that should update its sync mode. If unspecified, this method will attempt to perform this update on the currently set session if it exists. When possible, it is recommended to pass in the session id explicitly.

session.removeParticipant()

(method) skylight.session.removeParticipant({ id: string }: Participant): Promise<void>
Removes participant from the session.
Parameters
Return Value
Parameters
Type
Description
id*
string
user or group id
None

Application

application.applicationId

(property) skylight.application.applicationId: string
Returns the application's unique id.
Parameters
Return Value
None
string applicationId

application.comment

(property) skylight.application.comment: string
Returns the application comment.
Parameters
Return Value
None
string Application comment

application.compatibilityVersion

(property) skylight.application.compatibilityVersion: number
Returns the application's compatibility version number.
Parameters
Return Value
None
integer Application's compatibility version number

application.configuration

(property) skylight.application.compatibilityVersion: number
Returns the application compatibility version.
Parameters
Return Value
None
number Application compatibility version

application.data.<dataprops>

(property) skylight.application.data: object
Returns the application data object. This is read only data that is built and downloaded at app install time.
Parameters
Return Value
None
object Application data

application.description

(property) skylight.application.description: string
Returns the application description.
Parameters
Return Value
None
string Application description

application.name

(property) skylight.application.name: string
Returns the application name.
Parameters
Return Value
None
string Application name

application.participants

(property) skylight.application.participants: [ParticipantFull]
Returns an array participants visible to the user as defined by the role:read:self or role:read:any permission. The participant object includes user/group metadata.
If a user is given a role in the application as part of a group (and not explicitly as a user), they will not appear in the participants list as a user. See application.users below for a full list of user participants.
If the participant is of type user, then the participant will have a field named status which will have a string value of either active or away. If the participant's status is active, it means that they have recently been active on a Skylight Client or within the Skylight Web Portal.
Parameters
Return Value
None
array Participant object

application.stage

(property) skylight.application.stage: ApplciationStage
Returns the application stage: draft or published.
Parameters
Return Value
None
string Application stage (draft or published)

application.users

(property) skylight.application.users: [User]
Returns a list of users that have a role in this application, including those who are explicitly assigned a role, as well as those who are given a role through a group role assignment.
These user objects will also include a status field which will have a string value of either active or away. If the user's status is active, it means that they have recently been active on a Skylight Client or within the Skylight Web Portal.
Parameters
Return Value
None
[User] Application users

application.version

(property) skylight.application.version: number
Returns the application version number.
Parameters
Return Value
None
number Application version

User

user.firstName

(property) skylight.user.firstName: string
Returns the user's first name.
Parameters
Return Value
None
string User's first name

user.lastName

(property) skylight.user.lastName: string
Returns the user's last name.
Parameters
Return Value
None
string User's last name

user.id

(property) skylight.user.id: string
Returns the user's unique identifier.
Parameters
Return Value
None
string User's unique identifier

user.locale

(property) skylight.user.locale: string
Returns the user's preferred language.
Parameters
Return Value
None
string Language code

user.permissions

(property) skylight.user.permissions: [string]
Returns an array of permission names for the user for the application that is currently open..
Parameters
Return Value
None
array Permission names

user.roles

(property) skylight.user.roles: [string]
Returns an array of role names for this user for the application that is currently open.
Parameters
Return Value
None
array Role names

getUsers()

(method) skylight.getUsers(): Promise<[UserProfile]>
Returns a promise for a list of users.
This list of users does not contain information about users' presences (i.e., the status field that is available on user-type participants in the application.participants list).
Parameters
Return Value
None
Promise.<array> User objects

Network

network.connected

(property) skylight.network.connected: boolean
Indicates if device is connected to the network.
Parameters
Return Value
None
boolean True if connected.

Environment

environment.application

(property) skylight.environment.application: EnvironmentApplication
Returns an object for the current application.
Parameters
Return Value
None
object Application

environment.application.compatibilityVersion

(property) skylight.environment.application.compatibilityVersion: number
Returns the compatibility version number of the Skylight client installed on the device.
Parameters
Return Value
None
number Skylight client compatibility version

environment.device

(property) skylight.environment.device: Device
Returns on object with device information.
Parameters
Return Value
None
object Device
For example:
{
"name": "Chrome",
"version": "90.0.4430.93",
"identifier": "388492022294",
"type": "web" // other values include 'mobile' and 'wearable' for the mobile and HUD clients
}

environment.deviceId

(property) skylight.environment.deviceId: string
Returns the device's unique id.
Parameters
Return Value
None
string deviceId

environment.os

property) skylight.environment.os: string
Returns the operating system for the current device.
Parameters
Return Value
None
string Device operating system

Local

local.data.<dataprops>

(property) skylight.local.data: object
Returns the local data object. Local data is an ephemeral data store that you can use to track data across a single use of your application. It’s helpful for storing temporary information and application state that doesn’t need to make it to the back end and doesn’t need to survive for longer than a single use of the application.
Parameters
Return Value
None
object Local data

local.saveData()

(method) skylight.local.saveData(newData: any): void
Save new portion of the local data and refreshes the view.
Parameters
Return Value
Parameters
Type
Description
data
object
An object representing an atomic data change
None

Client Interfaces

openView()

(method) skylight.openView({ viewId: string, cardId: string, root: boolean, routeParam: string }: OpenViewOptions): Promise<void>
Open a new view on the client.
Parameters
Return Value
Parameters
Type
Description
viewId*
string
Identifier for the view to open
cardId
string
Optional identifier for the card to be focused upon opening the view
root
boolean
Optional flag for whether the view to be opened should be set as the root view
routeParam
string
Optional string that acts as a secondary identifier for the view. If routeParam is different from the current view’s routeParam, a new view will be opened and put on the view stack, even if the viewId is the same.
None

closeView()

(method) skylight.closeView(): any
Closes the current view to reveal the next view in the activity stack. If the current view is the application's root view then the user will be navigated to the applications list.
Parameters
Return Value
None
None

showDialog()

(method) skylight.showDialog({ title: string, body: string, icon: object, backgroundColor: string, buttons: object[] }: NotificationOptions): Promise<string>
Show an interruptive modal with scrollable content and optional buttons. If buttons are included, a user must select an button in order to dismiss the modal.
Parameters
Return Value
Usage
Parameters
Type
Description
title
string
Optional heading text for the dialog
body*
string
The text content in the dialog
icon
object
Optional icon object:
  • name: Unicode name for the icon
  • color: Must be a non-alpha Hex string color (#RRGGBB)
  • visible: Whether or not this icon should be shown
backgroundColor
string
Color of the modal's background. Must be a non-alpha Hex string color (#RRGGBB)
buttons
object[]
Array of objects with button label and id. More than 2 buttons can be specified, but buttons beyond the first two will be ignored.
  • label: (string) - Text displayed on the button
  • id: (string) - If button is pressed, the Promise returned from showDialog resolves to this id
  • If there are no buttons AND dialog is dismissed, then the Promise resolves to null
  • If there are one or more buttons, then the Promise resolves to the id of the pressed button
  • If dismissDialog is called, then the Promise resolves to null
const exIcon = {'name': '226', 'visible': true}
let submissionConfirmation = { title: 'Submit Form?', body: 'Submit the form when you are done with the report.', icon: exIcon, backgroundColor: '#eeff00', buttons: [{ label: 'Submit', id: '123' }, { label: 'Cancel', id: '456'}]}
const clickedId = await skylight.showDialog(submissionConfirmation)
console.log("you clicked on button with id: ", clickedId)

showNotification()

(method) skylight.showNotification({ body: string, icon: object, backgroundColor: string, duration: number, buttons: object[] }: NotificationOptions): Promise<string>
Show a non blocking notification.
Parameters
Return Value
Usage
Parameters
Type
Description
body*
string
The text content for the notification.
icon
object
Optional icon object:
  • uri: Must be a resource:// named icon
  • color: Must be a non-alpha Hex string color (#RRGGBB)
  • visible: Whether or not this icon should be shown
backgroundColor
string
Non-alpha Hex string color (#RRGGBB)
duration
number
The amount of time in milliseconds to show the notification. If unspecified, the notification will not auto-dismiss.
buttons
object[]
Array of objects with button label and id. More than one button can be specified, but buttons beyond the first one will be ignored.
  • label: (string) - Text displayed on the button
  • id: (string) - If button is pressed, the Promise returned from showNotification resolves to this id
  • If there are no buttons AND the snackbar is dismissed, then the Promise resolves to null
  • If there is a button, then the Promise resolves to the id of the pressed button
  • If dismissNotification is called, then the Promise resolves to null
const exIcon = {'name': 'e90b', 'color': '#27be89', 'visible': false}
let notification = {'body': "Beep boop, I'm a message!", 'icon': exIcon, 'backgroundColor': '#ff0000', 'duration': 3000, 'buttons': [{ 'id':'hello', 'label':'goodbye' }]}
const clickedId = await skylight.showNotification(notification)
console.log("you clicked on button with id: ", clickedId)

startMediaViewer()

(method) skylight.startMediaViewer({ mediaIds: [string], readonly: boolean }: MediaViewerOptions): any
Starts a media viewer activity
Parameters
Return Value