Scripting API Reference
API reference for developing scripts in Skylight Application Builder.
Parameters in this page denoted with an asterisk (*) are required.
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.
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.
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.(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'}]
(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(method) skylight.session.unset(sessionId: string): Promise<void>
Unsets the current session (set by
session.set
).Parameters
Return Value
Parameters | Type | Description |
| | |
None
(method) skylight.session.close(): Promise<void>
Locks the current session so it no longer receive new events or changes.
Parameters
Return Value
None
None
(property) skylight.sessions: [Session]
Returns an array of “open” session objects according to this user’s permission.
Parameters
Return Value
None
array
Session objects(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
(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(property) skylight.session.name: string
Returns the session name.
Parameters
Return Value
None
string
Session name(property) skylight.session.description: string
Returns the session description.
Parameters
Return Value
None
string
Session description(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' }
(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' }
(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
(property) skylight.session.participants: [Participant]
Returns the session participants.
Parameters
Return Value
None
array
Participants(property) skylight.session.properties: any
Returns any custom properties set on the session.
Parameters
Return Value
None
object
Session properties(property) skylight.session.status: SessionStatus
Returns the session status.
Parameters
Return Value
None
string
Session status (open|closed)(property) skylight.session.sessionId: string
Returns a valid UUID representing an active Session.
Parameters
Return Value
None
string
UUID for the active session(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)
(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
(property) skylight.session.media: [MediaItem]
Returns an array of all media captured during the session.
Parameters
Return Value
None
array
<media Object>(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
(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:
|
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. |
(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:
|
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. |
(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
(property) skylight.application.applicationId: string
Returns the application's unique id.
Parameters
Return Value
None
string
applicationId(property) skylight.application.comment: string
Returns the application comment.
Parameters
Return Value
None
string
Application comment(property) skylight.application.compatibilityVersion: number
Returns the application's compatibility version number.
Parameters
Return Value
None
integer
Application's compatibility version number(property) skylight.application.compatibilityVersion: number
Returns the application compatibility version.
Parameters
Return Value
None
number
Application compatibility version(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(property) skylight.application.description: string
Returns the application description.
Parameters
Return Value
None
string
Application description(property) skylight.application.name: string
Returns the application name.
Parameters
Return Value
None
string
Application name(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(property) skylight.application.stage: ApplciationStage
Returns the application stage: draft or published.
Parameters
Return Value
None
string
Application stage (draft
or published
)(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(property) skylight.application.version: number
Returns the application version number.
Parameters
Return Value
None
number
Application version(property) skylight.user.firstName: string
Returns the user's first name.
Parameters
Return Value
None
string
User's first name(property) skylight.user.lastName: string
Returns the user's last name.
Parameters
Return Value
None
string
User's last name(property) skylight.user.id: string
Returns the user's unique identifier.
Parameters
Return Value
None
string
User's unique identifier(property) skylight.user.locale: string
Returns the user's preferred language.
Parameters
Return Value
None
string
Language code(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(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(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(property) skylight.network.connected: boolean
Indicates if device is connected to the network.
Parameters
Return Value
None
boolean
True if connected.(property) skylight.environment.application: EnvironmentApplication
Returns an object for the current application.
Parameters
Return Value
None
object
Application(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(property) skylight.environment.device: Device
Returns on object with device information.
Parameters
Return Value
None
object
DeviceFor example:
{
"name": "Chrome",
"version": "90.0.4430.93",
"identifier": "388492022294",
"type": "web" // other values include 'mobile' and 'wearable' for the mobile and HUD clients
}
(property) skylight.environment.deviceId: string
Returns the device's unique id.
Parameters
Return Value
None
string
deviceIdproperty) skylight.environment.os: string
Returns the operating system for the current device.
Parameters
Return Value
None
string
Device operating system(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(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
(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
(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
(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:
|
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.
|
- 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 tonull
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)
(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:
|
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.
|
- 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 tonull
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)
(method) skylight.startMediaViewer({ mediaIds: [string], readonly: boolean }: MediaViewerOptions): any
Starts a media viewer activity
Parameters
Return Value