Skylight Docs
Search
⌃K

Integration SDK Reference

API reference for utilizing the Skylight Integration SDK.

Object Definition

Application

The application object includes the following properties:
Property
Type
Description
Application Id
string
The id of the application
Name
string
The name of the application
Description
string
The description of the role
Draft Version
number
The latest draft’s version, or -1 if there is no draft for this application
Published Version
number
The latest published version, or -1 if this application has not been published
Created By
string
The id of the user that created this application
Created At
date/time
The date and time the application was created

Participant

The participant object includes the following properties:
Property
Type
Description
Id
string
The id of the user or group
Type
string enum
The type of participant; either user or group

Role

The role object includes the following properties:
Property
Type
Description
Name
string
The name of the role
Description
string
The description of the role
Permissions
string[]
The permissions associated with this role
Participants
​Participant[]
The Participants (users and groups) that have this role.
Created By
string
The id of the user that created this role – empty if the role is one of the default roles that are created upon application creation
Created At
date/time
The date and time the role was created – set to a non-meaningful value if the role is one of the default roles that are created upon application creation, in which case the creation time of the application can be used instead
Modified By
string
The id of the user that last modified this role
Modified At
date/time
The date and time the role was last modified

Session

The session object includes the following properties:
Property
Type
Description
Application Id
string
The id of the application
Session Id
string
The id of the session
Status
string enum
The status of the session; either open or closed
IsDraft
bool
Whether or not this session was created in a draft version of the application
Version
number
The version for this session
Name
string
The name of the application
Description
string
The description of the application
Participants
​Participant[]
The Participants (users and groups) of this session.
Created By
string
The id of the user that created this application
Created At
date/time
The date and time the application was created
Modified By
string
The id of the user that last modified this session
Modified At
date/time
The date and time the session was last modified
Properties
dictionary
Developer-writable and readable dictionary with string keys and string values to store filterable information about the session

Application Methods

GetApplication()

Returns the object for a specified application.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application to retrieve
​Application object

GetApplications()

Returns a list of all applications for which the user has the application:read permission.
Parameters
Return Value
None
List of Application objects

GetApplicationRoles()

Returns a list of roles for a specified application.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for which the roles should be retrieved
List of Role objects

Session Methods

GetSession()

Returns information for a specified session.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application to retrieve
Session Id
string
The id of the session
​Session object

GetSessions()

Returns a list of open sessions that the user has permission to view for a specified application.
A user has access to a session if they are either:
  • A participant of the session and are in an application role that has the session:read:participant permission
  • Or if the user is in an application role that has the session:read:any permission
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for which the sessions should be retrieved
List of Session objects

CreateSession()

Creates a new session. Note: The integration code user will automatically be added to the session’s list of participants.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Name
string
The name of the session
Description
(optional)
string
The name of the session – defaults to an empty string
Properties
(optional)
dictionary
Developer-writable and readable dictionary with string keys and string values for this session that can be used to store filterable information about the session – defaults to an empty dictionary
Session Version
(optional)
number
Developer-assigned version number for this session – defaults to the application’s latest published version or the application’s latest draft version if application has not been published
​Session object

PatchSession()

Patches the specified session's fields. Any unspecified field will not be updated.
Note: If specified, the properties will be overwritten with the new dictionary, so make sure to include all existing properties fields.
While this method is available for use, there are other methods available in the SDK for updating individual fields of the session. It is recommended to use those methods instead of this one unless there is a need to specifically update multiple fields at once.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Patch
object
An object that contains the information for the fields that should be patched.
None

UpdateSessionProperties()

Updates the specified session's properties, which is a field of the session that is used to store developer-specified key-value pairs.
The properties will be overwritten with the new dictionary, so make sure to include all existing properties fields. Values must be strings.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Properties
dictionary
Developer-writable and readable dictionary with string keys and string values for this session that can be used to store filterable information about the session – defaults to an empty dictionary
None

UpdateSessionName()

Updates the specified session's name.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Name
string
The new name of the session
None

UpdateSessionDescription()

Updates the specified session's description.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Description
string
The new description of the session – defaults to an empty string
None

PatchSessionData()

Patches the specified session's session data.
Data can be any object, so long as it can be turned into a JSON string.
This method acts as a patch to the session data, so keys that aren’t specified in the Data dictionary will remain intact. This is true for nested objects as well.
If a key inside of Data points to an array value, whether nested or not, the existing array at that key (if one exists) will be overwritten.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Data
dictionary
String keys and generic values with which to patch the session data
None

GetSessionData()

Gets information about the specified session's session data.
As the session data structure is designed by the developer, it should also be parsed by the developer.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
The current state of the session data for a session.

AddParticipant()

Adds a participant to a session.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
Id
string
The id of the participant; either a user id or group id
Type
(optional)
string enum
The type of participant; either user or group – if unspecified, this will default to user
None

CloseSession()

Closes the specified session by patching the status field of the session to closed.
Parameters
Return Value
Name
Type
Description
Application Id
string
The id of the application for the session
Session Id
string
The id of the session
None

Session Events

SessionCreated

Occurs when a new session is created.
Parameters
Name
Type
Description
Application Id
string
The id of the application for this event
Session Id
string
The id of the session for this event
Event Id
string
The id of the event
Source
string
The source of the event; currently always set to skylight for this event
User Id
string
The id of the user that created this session
Created At
date/time
The date and time the session was created, as noted by the server
Timestamp
date/time
The date and time the session was created, as noted by the client
Version
number
The version number of the application when this event occurred
Event Type
string
The event type; always set to session_created for this event
Session
​Session​
The object for the session that was just created

SessionPropertiesUpdated

Occurs when a session’s properties field is updated.
The updated session properties should be accessed by using the session’s properties field and not the session event’s properties field. Specifically, the call (while differing in syntax based on language) will look something like sessionEvent.Session.Properties.
Parameters
Name
Type
Description
Application Id
string
The id of the application for this event
Session Id
string
The id of the session for this event
Event Id
string
The id of the event
Source
string
The source of the event; currently always set to skylight for this event
User Id
string
The id of the user that created this session
Created At
date/time
The date and time the session was created, as noted by the server
Timestamp
date/time
The date and time the session was created, as noted by the client
Version
number
The version number of the application when this event occurred
Event Type
string
The event type; always set to session_created for this event
Session
​Session​
The session for which the properties updated – this will only have the following properties:
  • Properties: The updated properties field for the session
  • Version: The version number of the session when the session properties were updated

SessionDataUpdated

Occurs when a session’s data is updated.
The contents of the Data field are specified by the developer and it is up to the developer to parse the contents.
Parameters
Name
Type
Description
Application Id
string
The id of the application for this event
Session Id
string
The id of the session for this event
Event Id
string
The id of the event
Source
string
The source of the event; currently always set to skylight for this event
User Id
string
The id of the user that created this session
Created At
date/time
The date and time the session was created, as noted by the server
Timestamp
date/time
The date and time the session was created, as noted by the client
Version
number
The version number of the application when this event occurred
Event Type
string
The event type; always set to session_created for this event
Data
dictionary
The developer-specified string keys and generic values that were used to patch the session data

SessionEventCreated

Occurs when a custom session event is created.
Parameters
Name
Type
Description
Application Id
string
The id of the application for this event
Session Id
string
The id of the session for this event
Event Id
string
The id of the event
Source
string
The source of the event; currently always set to skylight for this event
User Id
string
The id of the user that created this session
Created At
date/time
The date and time the session was created, as noted by the server
Timestamp
date/time
The date and time the session was created, as noted by the client
Version
number
The version number of the application when this event occurred
Event Type
string
The event type; always set to session_created for this event
Data
dictionary
The developer-specified string keys and generic values that were used to patch the session data

SessionClosed

Occurs when a session is closed.
Parameters
Name
Type
Description
Application Id
string
The id of the application for this event
Session Id
string
The id of the session for this event
Event Id
string
The id of the event
Source
string
The source of the event; currently always set to skylight for this event
User Id
string
The id of the user that created this session
Created At
date/time
The date and time the session was created, as noted by the server
Timestamp
date/time
The date and time the session was created, as noted by the client
Version
number
The version number of the application when this event occurred
Event Type
string
The event type; always set to session_created for this event
Session
​Session​
The session that was closed – this will only have the following properties:
  • Version number : The version of the session when it was closed
  • Status string enum : This will always be set to closed

​