subscribeSessions and unsubscribeSessions

The following functions allows subscribing and unsubscribing for changes of sessions.

subscribeSessions

The subscribeSessions function allows subscribing for changes of sessions in the systems of interest. Then it calls the provided <callback> with the operation result.

If the <system> is not provided or is null, all the active sessions of all the systems are returned.

The sessions subscription remains active until the unsubscribeSessions function is called.

Syntax

var result = subscribeSessions(<callback>, <system>, <initialSessions>);

Parameters Usage

Parameter

Type

Default

Use

Annotation

callback

Function

-

Mandatory

Object that identifies the callback function invoked to provide the sessions changes.

system

Integer

String

SystemObject

null

Optional

The identifier (ID), name, or SystemObject of the system of interest.

The null default value means all the systems.

initialSessions

Boolean

True

Optional

If True, the callback method is called right after the subscription, with the currently available sessions.

If False, the callback method is called only after a sessions change.

Result

If the subscribe operation is successful, the subscribeSessions function returns a SubscribeSessionsResult object containing the result of the subscription. This result must be used to perform the corresponding unsubscription.

If any errors occurred during the subscribe operation, the error property of the SubscribeSessionsResult indicates the reason why the operation failed.

It is necessary to keep this result in a global variable to use as input parameter for the unsubscribeSessions.

The callback is a function declared as follows, and is called when a session change occurs:

 

function onSessionsChanged(<sessions>)

{

    //... Do callback stuff here ...

}

 

Where < sessions > is a SessionObjects collection.

 

Error Handling

Errors can occur in case:

  • The <callback> is missing, invalid, null, or empty.
  • The specified <system> is not a positive integer, a string, or a SystemObject.
  • The specified <initialSessions> is not a Boolean value.

Examples of Use

 

How to subscribe to session changes for all systems and retrieve the sessions count per system and per station

Note that, since the unsubscribeSessions function is not called, this script remains running until it is manually stopped.

 

var onSessionsChange = function (sessions) {

    console("----- {0} -----\n", new Date().toLocaleString());

    handleSessions(sessions);

}

var subscribeSessionsResult = subscribeSessions(onSessionsChange);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

}

function handleSessions(sessions)

{

    if (sessions === null)

    {

        console("No active sessions");

        return;

    }

    console("- All sessions:\n{0}\n", sessions);

    

    // A map for the systemName =>sessionsCount mappings

    var sessionsPerSystem = {};

    // Loop through the sessions

    for (var i = 0; i < sessions.length; i ++) {

    

        var session = sessions[i];

        

        var systemName = session.system.systemName;

        var currentCount = 0;

        if (sessionsPerSystem[systemName])

        {

            currentCount = sessionsPerSystem[systemName];

        }

        currentCount += sessions[i].count;

        sessionsPerSystem[systemName] = currentCount;

    }

    console("- Sessions count per System:");

    for (systemName in sessionsPerSystem) {

        console(systemName + ": " + sessionsPerSystem[systemName]);

    }

    console("\n");

}

unsubscribeSessions

The unsubscribeSessions method allows terminating any session subscription created by calling the subscribeSessions function. On this purpose, the result of the subscribeSessions invocation must be provided as parameter.

Syntax

var result = unsubscribeSessions(<subscribeSessionsResult>);

 

Parameters Usage

Parameter

Type

Default

Use

Annotation

subscribeSessionsResult

SubscribeSessionsResult

-

Mandatory

The result of a successful subscribeSessions call.

Result

If any errors occurred during the unsubscribe operation, the error property of the UnsubscribeSessionsResult object indicates the reason why the operation failed.

Error Handling

Errors can occur in case:

  • The SubscribeSessionsResult object is missing, invalid, null, or empty.

Examples of Use

 

How to subscribe to sessions changes in System1 and unsubscribe after five notifications

 

var count = 0;

var onSessionsChange = function (sessions) {

    console(sessions);

    count++;

    

    //Unsubscribe after 5 session changes    

    if (count >= 5)

    {

        unsubscribeSessions(subscribeSessionsResult);

    }

}

var subscribeSessionsResult = subscribeSessions(onSessionsChange, null);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

}

 

How to monitor the session changes count for two hours

 

console("{0} - Start monitoring session changes in System2", new Date())

var sessionsChanges = 0;

var subscribeSessionsResult = subscribeSessions(callback, “System2”);

if (subscribeSessionsResult.error != null)

{

    console(subscribeSessionsResult.error);

    terminate();

}

setTimeout(timeoutElapsed, 120 * 60 * 1000);

// Callbacks

function callback(sessions)

{

    sessionsChanges++;

    if (sessions != null)

        console("{0} - {1} active session(s)", new Date(), sessions.length);

    else

        console("{0} - no active sessions");

}

function timeoutElapsed()

{

    unsubscribeSessions(subscribeSessionsResult);

    console("{0} - Stop monitoring session changes", new Date())

    console("Sessions changes notified {0} times.", sessionsChanges);

}

 

getSessionsByType Function

The getSessionsByType function allows retrieving all the active sessions of the specified type, for the systems of interest.

Syntax

var result = getSessionsByType(sessionTypeId, <system>);

Parameters Usage

Parameter

Type

Default

Use

Annotation

sessionTypeId

Integer

-

Mandatory

The id corresponding to the session type of interest:

0 = Primary Desktop

1 = Primary Web

2 = Single Sign-On Web

3 = Web Service Session

system

Integer

String

SystemObject

null

Optional

The identifier (ID), name, or SystemObject of the system of interest.

The null default value means all the systems.

Result

The getSessions function returns:

  • the number of active sessions of the specified <sessionTypeId>.
  • 0, if there are no active sessions of the specified <sessionTypeId> for the requested system, or the specified system is offline or invalid.

Error Handling

Errors can occur in case:

  • The specified <system> is not a positive integer, a string, or a SystemObject.

 

Examples of Use

 

How to get the number of active Primary Desktop sessions of the current system

var system = getCurrentSystem();

var primaryDesktopSessions = getSessionsByType(0, system);

console("System: {0}\n\t- Primary Desktop Sessions: {1}", system.systemName, primaryDesktopSessions);

 

How to get the number of active Primary Desktop sessions in all systems

var primaryDesktopSessions = getSessionsByType(0);

console("All systems:\n\t- Primary Desktop Sessions: {0}", primaryDesktopSessions);