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
Parameters

Name

Type

Description

Application Id

string

The id of the application to retrieve

Return Value

Application object

GetApplications()

Returns a list of all applications for which the user has the application:read permission.

Parameters
Return Value
Parameters

None

Return Value

List of Application objects

GetApplicationRoles()

Returns a list of roles for a specified application.

Parameters
Return Value
Parameters

Name

Type

Description

Application Id

string

The id of the application for which the roles should be retrieved

Return Value

List of Role objects

Session Methods

GetSession()

Returns information for a specified session.

Parameters
Return Value
Parameters

Name

Type

Description

Application Id

string

The id of the application to retrieve

Session Id

string

The id of the session

Return Value

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
Parameters

Name

Type

Description

Application Id

string

The id of the application for which the sessions should be retrieved

Return Value

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
Parameters

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

Return Value

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
Parameters

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.

Return Value

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
Parameters

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

Return Value

None

UpdateSessionName()

Updates the specified session's name.

Parameters
Return Value
Parameters

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

Return Value

None

UpdateSessionDescription()

Updates the specified session's description.

Parameters
Return Value
Parameters

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

Return Value

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
Parameters

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

Return Value

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
Parameters

Name

Type

Description

Application Id

string

The id of the application for the session

Session Id

string

The id of the session

Return Value

The current state of the session data for a session.

AddParticipant()

Adds a participant to a session.

Parameters
Return Value
Parameters

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

Return Value

None

CloseSession()

Closes the specified session by patching the status field of the session to closed.

Parameters
Return Value
Parameters

Name

Type

Description

Application Id

string

The id of the application for the session

Session Id

string

The id of the session

Return Value

None

Session Events

SessionCreated

Occurs when a new session is created.

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