The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Bb-Collaborate-V3-0.10
River stage zero No dependents
++
/ Bb::Collaborate::V3::Session

NAME

Bb::Collaborate::V3::Session - Collaborate session instance class

DESCRIPTION

This is the main entity class for sessions.

PROPERTIES

sessionId (Int)

Identifier of the session.

accessType (Int)

Session access type:

1. Private - Only the SAS Owner may join the session. Note: this type does not apply to ELM. If you set this to 1, the API will change it to 2.
2. Restricted - only users specified in the chair or non-chair lists (or guests invited with the email links) may join.
3. Public - All users within your login group may join.

Notes:

  • SAS Use of this parameter should be avoided as this controls SAS Native Mode session and recording access. The default value for this parameter is 2 (Restricted) and is appropriate for API use.

  • ELM If you don't specify a value, the default is taken from the Restrict Session Access setting in the Default Session Preferences, These preferences are available through the ELM user interface. For more information, see the online help available from the Collaborate Manager user interface.

allowInSessionInvites (Bool)

This flag value controls whether or not the chair of this session can send invitations to join the session from within the session.

If you don't specify a value, the default is taken from the Allow in-Session invites setting in the Meeting Defaults.

boundaryTime (Int)

Boundary time. (Defined as the period before the start of a session in which users can join the session. Used by chairs to preload content and by non-chairs who have never joined a Collabroate session before to download any files and configure their audio.)

Specified in minutes, to a maximum value of 1440 minutes (24 hours). If you don't specify a value, the default is taken from the Boudary Time setting in the Meeting Defaults.

chairList (Str)

Array of user identifiers from your system that specifies which users may join the Collaborate session as chairpersons.

Each user identifier in the list may be 1 - 64 characters in length, and each identifier is case sensitive and can include UTF-8 characters.

A userId may not appear in both the chair and non-chair lists.

Note: See also the register_atttendee method, which can be used to add a user to the chair or non-chair list when joining.

chairNotes (Str)

Text field that can be used to store notes specific to users with chair role. 1 to 2147483647 characters in length.

creatorId (Str)

Identifier of the session creator as specified by you in your system. Case sensitive. 1 - 32 characters in length. Can include UTF-8 characters.

endTime (HiResDate)

End date and time of the session in milliseconds.

groupingList (Str)

Array of unique course identifiers from your system with which to associate this Collaborate session.

Each course identifier may be 1 - 32 characters in length, each identifier is case sensitive and can include UTF-8 characters.

sessionName (Str)

The session name. This name will appear in the Collaborate session title bar. Case insensitive. 1 - 255 characters in length. Must begin with a letter or digit and may not contain <, &, '"', #, or %.

hideParticipantNames (Bool)

This flag value controls whether or not the session participant names are hidden in any session recording that may be made.

If you don't specify a value, the default is taken from the Hide Names in Recordings setting in the Meeting Defaults.

maxCameras (Int)

Maximum number of simultaneous video cameras to be configured in the Collaborate session at session launch time.

For single server configurations, this value must be between 1 and maxAvailableCameras (as returned from the Bb::Collaborate::V3::Server::Configuration get() method).

For multiple server configurations, this must be between 1 and versionMaxFilmersLimit for the version you are using (as returned from the Bb::Collaborate::V3::Server::Version list() method).

If you don't specify a value, the default is taken from the Max Cameras setting in the Meeting Defaults.

maxTalkers (Int)

Maximum number of simultaneous talkers to be configured in the Collaborate session at session launch time.

For single server configurations, this value must be between 1 and maxAvailableTalkers property (as returned from the Bb::Collaborate::V3::Server::Configuration get() method).

For multiple server configurations, this must be between 1 and versionMaxTalkersLimit for the version you are using (as returned from the Bb::Collaborate::V3::Server::Version get() method).

If you don't specify a value, the default is taken from the Max Talkers setting in the Meeting Defaults.

mustBeSupervised (Bool)

Permits chairpersons to view all private chat messages in the Collaborate session.

If you don't specify a value, the default is taken from the Session is supervised setting in the Meeting Defaults.

nonChairList

Comma-separated list of user identifiers from your system that specifies which users may join the Collaborate session as non-chair participants. (That is assuming that openChair is set to false. If openChair is set to true, then all users will be chairpersons.)

Each user identifier in the list may be 1 - 64 characters in length, and each identifier is case sensitive and can include UTF-8 characters.

A userId may not appear in both the chair and non-chair lists.

Note: See also the register_atttendee method, which can be used to add a user to the chair or non-chair list when joining.

nonChairNotes (Str)

Text field that can be used to store notes specific to non-chair participants. 1 to 2147483647 characters in length.

startTime (HiResDate)

Start date and time of the session in milliseconds.

This can be constructed by appending 000 to a standard unix epoch date.

openChair (Bool)

All users will join the session as a chairperson in the Collaborate session.

If you don't specify a value, the default is taken from the Permissions granted on enter setting in the Meeting Defaults.

permissionsOn (Bool)

All users who join the session as non-chairpersons are granted full permissions to session resources such as audio, whiteboard, etc.

If you don't specify a value, the default is taken from the Permissions granted on enter setting in the Meeting Defaults.

raiseHandOnEnter (Bool)

When users join the Collaborate session, they will automatically raise their hand (this is accompanied by an audible notification).

If you don't specify a value, the default is taken from the Raise hand on enter setting in the Meeting Defaults.

recordingModeType (Int)

The mode of recording in the Collaborate session:

1. (Manual) - A chairperson must start the recording.
2. (Automatic) - The recording starts automatically when the session first starts.
3. (Disabled) - Recording is disabled.

If you don't specify a value, the default is taken from the Mode setting in the Meeting Defaults.

reserveSeats (Int)

Number of seats reserved for this session.

If Must reserve seats is enabled for your login group, this number will be removed from your purchased license limit for the duration of this session.

In addition, this number acts as a cap to the number of users that may join this session, regardless of the number of users in the user lists, or guests invited through the email facility.

If Must reserve seats is disabled, then this parameter is ignored. Generally, this parameter is not used.

secureSignOn (Bool)

The parameter used to indicate that a session created through the API should use the extended authentication provided by the secure sign-on functionality.

recordings (Bool)

Whether the session has any recordings.

versionId (Int)

The version of Blackboard Collaborate to use for this session. Valid values are retrieved from the Bb::Collaborate::V3::Server::Versions get() or list() methods. If this parameter is not supplied the session will use the 'default' version.

METHODS

insert

    use Bb::Collaborate::V3;
    use Bb::Collaborate::V3::Session;
    use Elive::Util;

    my $connection = Bb::Collaborate::V3->connect(
                                'http://myserver/mysite',
                                'some_user' => 'some_pass' );

    # Sessions must start and end on the quarter hour.

    my $session_start = Elive::Util::next_quarter_hour();
    my $session_end = Elive::Util::next_quarter_hour( $session_start );

    my %session_data = (
        sessionName   => 'My Demo Session',
        creatorId     => $connection->user,
        startTime     => $session_start . '000',
        endTime       => $session_end . '000',
        openChair     => 1,
        mustBeSupervised => 0,
        permissionsOn => 1,
        nonChairList  => [qw(alice bob)],
        groupingList  => [qw(mechanics sewing)],
    );

    my $session = Bb::Collaborate::V3::Session->insert(\%session_data);

    my $url = $session->session_url( userId => 'bob', displayName => 'Robert');
    print "bob's session link is: $url\n";

register_attendee calls the UpdateSessionAttendees request. This ensures that the user is registered on either the chairList or nonChairList and returns a url for joining the session.

    my %late_comer = (userId => 'fred', displayName => 'Fred Nurk', isChair => 1);
    my $url2 = $session->register_attendee( \%late_comer );

A series of sessions can be created using the recurrenceCount and recurrenceDays parameters.

    #
    # create three weekly sessions
    #
    my @sessions = Bb::Collaborate::V3::Session->insert({
                            ...,
                            recurrenceCount => 3,
                            recurrenceDays  => 7,
                        });

update

    $session->maxCameras(5);
    $session->hideParticipantNames(0);
    $session->update;

    #
    # ...or...
    #
    $session->update({maxCameras => 5, hideParticipantNames => 0});

Updates an existing session.

retrieve

    my $session = Bb::Collaborate::V3::Session->retrieve( $session_id );

Retrieves a session.

list

    #
    # perl code snippet to select sessions in group 'perl_tut_1'
    # created from yesterday onwards.
    #
    my $yesterday_dt = DateTime->today->subtract( days => 1 );
    my $yesterday_msec = $yesterday_dt->epoch . '000';

    my $sessions
           = Bb::Collaborate::V3::Session->list(filter => {
                                               groupingId => 'perl_tut_1',
                                               startTime => $yesterday_msec,
                                              });

    foreach my $session (@$sessions) {

        my $session_id = $session->sessionId;
        my $session_name = $session->sessionName;

        print "found id=$session_id, name=$session_name\n"; 

    }

Returns an array of session objects. You may filter on:

userId - Matched against chairList and nonChairList
groupingId - An Element from the groupingList
sessionId - Session identifier
creatorId - Session creator
startTime - Start of the search date/time range in milliseconds.
endTime - End of the search date/time range in milliseconds.
sessionName - The session name

delete

    $session->delete;

Deletes unwanted or completed sessions.

telephony

    my $session_telephony = $session->telephony;
    $session_telephony->update({
        chairPhone => '(03) 5999 1234',
        chairPIN   => '6342',
     });

Returns an Bb::Collaborate::V3::Session::Telephony object for the given session. This can then be used to get or set the session's telephony characterisitics.

set_presentation

    $session->set_presentation($presentation);

Associates a seession with presentation content.

set_multimedia

    $session->set_multimedia([$multimedia_1, $multimedia_2]);

Associates a session with multimedia content.

list_multimedia

    my $multimedia = $meeting_obj->list_multimedia;

Lists all multimedia associated with the session.

See also Bb::Collaborate::V3::Multimedia.

list_presentation

    my $presentation = $meeting_obj->list_presentation;

Lists all presentation associated with the session.

See also Bb::Collaborate::V3::Presentation.

remove_presentation

    my $presentation_list = $session->list_presentation;

    foreach my $presentation_item (@$presentation_list) {
        $session->remove_presentation( $presentation_item );
    }

Disassociate the given presentation item from the session

remove_multimedia

    my $multimedia_list = $session->list_multimedia;

    foreach my $multimedia_item (@$multimedia_list) {
        $session->remove_multimedia( $multimedia_item );
    }

Disassociate the given multimedia item from the session

list_recordings

    my $recordings = $meeting_obj->list_recordings;

Lists all recording associated with the session.

See also Bb::Collaborate::V3::Recording.

session_url

    my $session_url = $session->session_url(userId => 'bob');

Returns a URL for the session. This provides authenthicated access for the given user.

set_api_callback_url

    my $session_url = $session->set_api_callback_url($url);

This method calls the SetApiCallbackUrl command, which is used to specify a callback URL that will be notified every time a room closes.

If a session is launched multiple times, there will be multiple rooms (instances of the session). When each room closes, the callback URL will be called. If the session is only launched once, the URL will be called once.

register_attendee

    my %attendee = (userId => 'fred', displayName => 'Fred Nurk', isChair => 0);
    my $attendee_url = $session->register_attendee( \%attendee );
    # or to call from the class level
    $attendee_url = Bb::Collaborate::V3::Session->register_attendee( \%attendee, sessionId => 123456 );
    print "Please go to: $attendee_url";

Ensures that the user is in the chair or non-chair list for this session and returns a join URL for the session.

The user may be added and/or promoted/demoted between the chairList and nonChairList as required.

attendance

    my $yesterday = DateTime->today->subtract(days => 1);

    my $attendance = $session->attendance( $yesterday->epoch.'000' );

Reports on session attendance for a given day. It returns a reference to an array of Bb::Collaborate::V3::Session::Attendance objects.