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
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.