Skylight Docs
Search…
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
1
// Create a session with name and description:
2
await skylight.session.create({
3
name: 'Hello',
4
description: 'World',
5
properties: {
6
propertyA: "valueA",
7
propertyB: "valueB",
8
propertyC: "valueC" } })
Copied!
1
// Create a session and assign it to another user:
2
await skylight.session.create({
3
name: 'Bob',
4
participants: [{
5
type: 'user',
6
id: 'af24d58b-0e91-4777-80bc-3218acde50a7'}]
Copied!

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
1
//Create a new session
2
let newSession = await skylight.session.create({
3
name: skylight.application.data.processName })
4
5
//Set the session
6
await skylight.session.set(newSession.sessionId)
7
8
let newData = {
9
"stepStatus": {
10
"1": "incomplete",
11
"2": "incomplete",
12
"3": "incomplete"
13
}
14
}
15
16
//Save data to the sessioin
17
await skylight.session.saveData(newData)
Copied!

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.getSessions()

(method) skylight.session.getSessions(query: object): Promise<Session[]>
Queries the API and returns up to 200 sessions that match the criteria
Parameters
Return Value
Parameters
Type
Description
query*
object
An object with the query filter:
      status: filter by session status:
        open - default, show only open sessions
        closed - show only closed sessions
      sync: filter by session sync status:
        undefined - default, get all sessions
        true - get only sessions that are synced by default
        false - get only sessions that are NOT synced by default
      participants: filter by session participants. An array of user or group ids
        undefined - default no filter
        example: ['70546521-1181-4dca-9e26-8f3b11534bbe']
      name: session prefix to filter by. Returns session, which names start with this param.
        undefined - default, no filter
        example: report - would return report1, reportApollo, will NOT return bugreport
      prop.*: filter by a specific custom string property.
        example: prop.department: ‘HR’
Session[] up to 200 sessions that match the criteria

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:
1
{
2
"name": "Chrome",
3
"version": "90.0.4430.93",
4
"identifier": "388492022294",
5
"type": "web" // other values include 'mobile' and 'wearable' for the mobile and HUD clients
6
}
Copied!

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
1
const exIcon = {'name': '226', 'visible': true}
2
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'}]}
3
const clickedId = await skylight.showDialog(submissionConfirmation)
4
console.log("you clicked on button with id: ", clickedId)
Copied!

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
1
const exIcon = {'name': 'e90b', 'color': '#27be89', 'visible': false}
2
let notification = {'body': "Beep boop, I'm a message!", 'icon': exIcon, 'backgroundColor': '#ff0000', 'duration': 3000, 'buttons': [{ 'id':'hello', 'label':'goodbye' }]}
3
const clickedId = await skylight.showNotification(notification)
4
console.log("you clicked on button with id: ", clickedId)
Copied!

startMediaViewer()

(method) skylight.startMediaViewer({ mediaIds: [string], readonly: boolean }: MediaViewerOptions): any
Starts a media viewer activity
Parameters
Return Value
Parameters
Type
Description
mediaIds
array
An array of Media ids to view
readonly
boolean
Optional parameter that if set to true, will open the media viewer with image deletion and annotation creation/editing/deletion controls hidden. Annotations will still be visible.
None

startTextInput()

(method) skylight.startTextInput({ type: string, icon: object, label: string, suffix: string, helpText: string, input: string, header: string, placeholder: string, maxChar: number, characterConfig: object, preferSpeech: boolean, onSubmit: function }: StartTextInputOptions): Promise
Displays an activity for inputting text and returns a promise with the text that was input.
Parameters
Return Value
Usage
Parameters
Type
Description
type
string
Type of keyboard to show (generic or numeric)
icon
object
The configuration object defining an optional icon
    name: The glyph value (unicode) of the icon you wish to display
    visible: Whether or not this icon should be shown
label
string
Optional label for the text field
suffix
string
Optional short text field that should be used to denote the units of measure for the data entered, or something similar, eg "lbs"
helpText
string
Optional field for helper message that is displayed below the field
input
string
Existing input, if applicable
header
string
Optional field that provides additional context to the input. Placed above the input box where a view's title is normally displayed.
placeholder
string
Optional text that will be displayed in the field before text is entered
maxChar
number
Optional limit for the maximum allowed characters to be input
characterConfig
object
Optional configuration object for the text input field:
    string characters: A string that defines which characters can be input into the text input field. These characters will be displayed on the Skylight character picker on smart glasses.
    boolean backspace: Shows the backspace button on the Skylight character picker on smart glasses
    boolean cancel: Shows the cancel button on the Skylight character picker on smart glasses
    boolean confirm: Shows the confirm button on the Skylight character picker on smart glasses
preferSpeech
boolean
Optional flag to indicate that speech-to-text is the preferred method of input if supported on a wearable device. On Glass EE2 and RealWear HMT-1 the speech-to-text activity will be presented in place of the Skylight character picker.
onSubmit
function
An optional function that accepts an object (herein referred to as lastInput), used to react to a user submitting input
    NOTE: await-able onSubmit instances are not supported. You will be able to perform any other skylight API call, but you cannot await a result.
    NOTE: preferSpeech will completely bypass this callback.
    onSubmit will only be triggered when the user submits their inputted data, not each time they change the input value
    onSubmit should accept/expect lastInput to be of the following schema:
lastInput = { get value (){}, // this returns a String setError: (errorText) => {}, // will set error text and state once set. Text is REQUIRED.
}
    If lastInput.setError is called with an error string, an error message will be shown within the text input activity. Note that if this is specified, onSubmit should not return a value (or it should return a null/undefined value) so that the text input activity remains.
    If onSubmit returns a String value, it will resolve the await call with the returned value which will close the text input activity
    (see example)
      It is possible to change the value returned; however, unless used for sanitization or normalization purposes, we do not recommend manipulating the user’s input for the best user experience.
    If onSubmit returns a null/undefined value, no data will be committed and the text input activity will remain.
Promise.<string> Inputted text
1
const exIcon = {
2
'name': '226',
3
'visible': true}
4
5
const charConf = {
6
characters: '1123456abc',
7
backspace: true,
8
cancel: false,
9
confirm: true}
10
11
const resultString = await skylight.startTextInput({
12
type: 'generic',
13
icon: exIcon,
14
label: 'Confirm the quantity of effort in these examples',
15
helpText: 'No help',
16
placeholder: "1",
17
maxChar: 100,
18
preferSpeech: false,
19
charConf})
20
21
console.log("You inputted: ", resultString)
Copied!

startScanner()

(method) skylight.startScanner({ timeout: number, scanMode: ScanMode, onScan: function }: StartScannerOptions): Promise<string>
Launches an activity for scanning barcodes and returns a promise with the value of the barcode that was scanned.
Parameters
Return Value
Usage
Parameters
Type
Description
timeout
number
The amount of time in milliseconds that the notification should be shown.
    Default value: 3000
    If timeout is greater than 0, the scanner will dismiss itself after the specified time, on a successful scan, or when dismissed by the user.
    If timeout is 0, the scanner will not dismiss itself automatically. The scanner will dismiss itself on a successful scan, or when dismissed by the user.
    If timeout is -1, the scanner will not dismiss itself automatically, and the user cannot dismiss it. The scanner will only dismiss itself on a successful scan.
    timeout cannot be null
    If timeout is undefined/missing, it will be set to the default value stated above.
scanMode
object
Type of scan to perform. Possible values:
    skylight.SCAN_TYPE.PRODUCT_MODE
      UPC/EAN/ “barcodes”
    skylight.SCAN_TYPE.ONE_D_MODE
      One-dimension code types
    skylight.SCAN_TYPE.QR_CODE_MODE
      QR Codes only
    skylight.SCAN_TYPE.AZTEC_MODE
      Aztec symbology
    skylight.SCAN_TYPE.PDF_417_MODE
      PDF417 symbology
    skylight.SCAN_TYPE.DEFAULT_MODE
      Everything that the device supports in its default scanning mode
      EE2/HMT
    skylight.SCAN_TYPE.CODABAR
    skylight.SCAN_TYPE.CODE_39
    skylight.SCAN_TYPE.CODE_93
    skylight.SCAN_TYPE.CODE_128
    skylight.SCAN_TYPE.DATA_MATRIX
    skylight.SCAN_TYPE.EAN_8
    skylight.SCAN_TYPE.EAN_13
    skylight.SCAN_TYPE.ITF
    skylight.SCAN_TYPE.MAXICODE
    skylight.SCAN_TYPE.PDF_417
    skylight.SCAN_TYPE.QR_CODE
    skylight.SCAN_TYPE.RSS_14
    skylight.SCAN_TYPE.RSS_EXPANDED
    skylight.SCAN_TYPE.UPC_A
    skylight.SCAN_TYPE.UPC_E
    skylight.SCAN_TYPE.UPC_EAN_EXTENSION
onScan
function
A function that accepts a String, used to react to a user submitting input. It should return a String? value.
    NOTE: await-able onScan instances are not supported. You will be able to perform any other skylight API call, but you cannot await a result.
    If onScan is defined and returns a defined string value, it will resolve the await call with the returned value (see example) and close the scanner as in a successful scan
      It is possible to change the value returned; however, unless used for sanitization or normalization purposes, we do not recommend manipulating the user’s input for the best user experience.
    If onScan is defined and returns a null/undefined value, the scanner experience will not be dismissed and the await will not be resolved
    If onScan is not defined, the timeout will be the governing factor in when/how the scanning experience is dismissed and all scans will be considered successful
Promise.<string> Scanned value
1
const foo = await skylight.startScanner({
2
3000,
3
skylight.SCAN_TYPE.DEFAULT_MODE})
4
​</