Elive::Entity::Session - Session insert/update via ELM 3.x (TRIAL)

Elive::Entity::Session is under construction as a likely successor to Elive::View::Session. It implements the createSession and updateSession commands, introduced with Elluminate 3.0.

Creates a new session on an Elluminate server, using the createSession command.

    use Elive::Entity::Session;
    use Elive::Entity::Preload;

    my $session_start = time();
    my $session_end = $session_start + 900;

    $session_start .= '000';
    $session_end .= '000';

    my $preload = Elive::Entity::Preload->upload('c:\\Documents\intro.wbd');

    my %session_data = (
	name => 'An example session',
	facilitatorId => Elive->login->userId,
	password => 'secret',
	start =>  $session_start,
	end => $session_end,
	privateMeeting => 1,
	recordingStatus => 'remote',
	raiseHandOnEnter => 1,
	maxTalkers => 2,
	boundaryMinutes => 15,
	fullPermissions => 1,
	supervised => 1,
	seats => 10,
        participants => [
            -moderators => [qw(alice bob)],
            -others => '*staff_group'
         ],
        add_preload => $preload,
    );

    my $session = Elive::Entity::Session->insert( \%session_data );

     my $session = Elive::Entity::Session->retrieve( $session_id);
     #
     # ..then later on
     #
     $session->seats( $session->seats + 5);
     @changed = $session->is_changed;
     #
     # @changed will contained 'seats', plus any other unsaved updates.
     #

Returns a list of properties that have unsaved changes. To avoid warnings, you will either need to call update on the object to save the changes, or revert to discard the changes.

    $session->revert('seats'); # revert just the 'seats' property
    $session->revert();        # revert everything

Reverts unsaved updates.

    $session->update({ boundaryTime => 15});

    # ...or...

    $session->boundaryTime(15);
    $session->update;

Updates session properties

Retrieves a session for the given session id.

    Elive::Entity::Session->retrieve( $session_id );

List all sessions that match a given criteria:

    my $sessions = Elive::Entity::Session->list( filter => "(name like '*Sample*')" );

Deletes a completed or unwanted session from the Elluminate server.

    my $session = Elive::Entity::Session->retrieve( $session_id );
    $session->delete;

A simple input list of participants might look like:

    @participants = (qw{alice bob, *perl_prog_tut_1});

By default, all users/groups/guest in the list are added as unprivileged regular participants.

The list can be interspersed with -moderators and -others markers to indicate moderators and regular users.

    @participants = (-moderators => qw(alice bob),
                     -others => '*perl_prog_tut_1');

Each participant in the list can be one of several things:

* A user-id string, in the format '<userId>'

* A pre-fetched user object of type Elive::Entity::User

* A group-id string, in the format '*<groupId>'

* A pre-fetched group object of type Elive::Entity::Group

* An invited guest, in the format 'Display Name(loginName)'

Unless you're using LDAP, you're likely to have to look-up users and groups to resolve login names and group names:

    my $alice = Elive::Entity::User->get_by_loginName('alice');
    my $bob = Elive::Entity::User->get_by_loginName('bob');
    my $tut_group = Elive::Entity::Group->list(filter => "groupName = 'Perl Tutorial Group 1'");

    my @participants = (-moderators => [$alice, $bob],
                        -others => [@$tut_group],
                       );

Then, you just need to pass the list in when you create or update the session:

     Elive::Entity::Session->create({
                     # ... other options
                     participants => \@participants
                    });

You can also fully construct the participant list.

    use Elive::Entity::Participants;
    my $participants_obj = Elive::Entity::Participants->new(\@participants);

     Elive::Entity::Session->create({
                     # ... other options
                     participants => $participants_obj,
                    });

Participant lists are returned an arrays of elements of type Elive::Entity::Participant. Each participant contains one of:

type 0 (Elive::Entity::User)

type 1 (Elive::Entity::Group), or

type 2 (Elive::Entity::Invited::Guest)

These are dereferenced via the user, group or guest methods.For example, to print the list of participants for a session:

    my $session = Elive::Entity::Session->retrieve($session_id);
    my $participants = $session->participants;

    foreach (@$participants) {
	my $type = $_->type;
	my $str;

	if (! $type)  {
	    my $user = $_->user;
	    my $loginName = $user->loginName;
	    my $email = $user->email;

            print 'user: '.$loginName;
	    print ' <'.$email.'>'
		if $email;
	}
	elsif ($type == 1) {
	    my $group = $_->group;
	    my $id = $group->groupId;
	    my $name = $group->name;

	    print 'group: *'.$id;
	    print ' <'.$name.'>'
		if $name;
	}
	elsif ($type == 2) {
	    my $guest = $_->guest;
	    my $loginName = $guest->loginName;
	    my $displayName = $guest->displayName;

	    print 'guest: '.$displayName;
	    print ' ('.$loginName.')'
		if $loginName;
	}
	else {
	    die "unknown participant type $type"; # elm 4.x? ;-)
	}
        print "\n";
    }

You may modify this list in any way, then update the session it belongs to:

    $participants->add( -moderators => 'trev');  # add 'trev' as a moderator

    $session->update({participants => $participants});

Preloads may be both uploaded from the client or server:

    # 1. upload a local file
    my $preload1 = Elive::Entity::Preload->upload('c:\\Documents\slide1.wbd');

    # 2. stream it ourselves
    open ( my $fh, '<', 'c:\\Documents\slide2.wbd')
	or die "unable to open preload file $!";
    my $content = do {local $/; $fh->binmode; <$fh>};
    close $fh;

    my $preload2 = Elive::Entity::Preload->upload(
                     name => 'slide2.wbd',
                     data => $content,
                   );

    # 3. import a file on the Elluminate Live! server
    my $preload3 = Elive::Entity::Preload
         ->import_from_server('/home/uploads/slide3.wbd');

These can then be added to sessions in a number of ways:

    # 1. at session creation
    my $session = Elive::Entity->Session->create({
                           # ...
                           add_preload => $preload1,
                        });

    # 2. when updating a session
    $session->update({add_preload => $preload2});

    # 3. via the add_preload() method
    $session->add_preload( $preload3 );

A single preload can be shared between sessions:

    $session1->add_preload( $preload );
    $session2->add_preload( $preload );

Attempt to add the same preload to a session more than once is considered an error. The check_preload method might help here>

    $session->add_preload( $preload )
        unless $session->check_preload( $preload );

Preloads are not automatically deleted when you delete session, if you want to delete them, you can do this yourself:

    my $preloads = $session->list_preloads;
    $session->delete;
    $_->delete for (@$preloads);

But you'd only want to delete the preload if it's not being shared with other active sessions!

Please see also Elive::Entity::Preload.

If a user has been registered as a meeting participant, either by being directly assigned as a participant or by being a member of a group, you can then create a JNLP for access to the meeting.

    my $user_jnlp = $session->buildJNLP(user => $username);

There's a slightly different format for guests:

    my $guest_jnlp = $session->buildJNLP(userName => $guest_username,
                                         displayName => $guest_display_name);

Unlike registered users, guests do not need to be registered as a session participant for you to add them as a guest.

For more information, please see Elive::Entity::Meeting.

A session can be associated with multiple recording segments. A segment is created each time recording is stopped an restarted, or when all participants entirely vacate the session. This can happen multiple times for long running sessions.

The recordings seem to generally become available within a few minutes, without any need to close or exit the session.

my $recordings = $session->list_records;

if (@$recordings) { # provide access to the first recording my $recording_jnlp = $recordings[0]->buildJNLP(userId => $username); }

Also note that recordings are not deleted, when you delete sessions. If you want to delete associated recordings when you delete sessions:

   my $recordings = $session->recordings;
    $session->delete;
    $_->delete for (@$recordings);

However it is often customary to keep recordings for an extended period of time - they will remain accessable from the Recordings web page on your Elluminate Live! web server.

For more information, please see Elive::Entity::Recording.

Here's an alphabetical list of all available session properties:

This is a read only property. This property is read-only and should always have the value default for sessions created via Elive::Entity::Session.

All participants can moderate.

Session boundary time (minutes).

User defined cost center.

True if the session has been deleted.

Telephony is enabled

The session end time (milliseconds). This can be constructed by appending '000' to a unix ten digit epoch date.

The userId of the facilitator who created the session. They will always have moderator access.

Whiteboard slides are locked to moderator view.

Whether participants can perform activities (e.g. use the whiteboard) before the supervisor arrives.

The sessionId (meetingId).

Whether moderators can invite other individuals from within the online session

The maximum number of simultaneous talkers.

General notes for moderators. These are not uploaded to the live session).

Either a PHONE number or SIP address for the moderator for telephone.

PIN for moderator telephony

Session name.

Either a PHONE number or SIP address for the participants for telephone.

PIN for participants telephony.

A list of users, groups and invited guest that are attending the session, along with their access levels (moderators or participants). See Working with Participants.

A password for the session (see Working with Participants).

Whether to hide the session (meeting) from the public schedule.

Which user profiles are displayed on mouse-over: none, mod (moderators only) or all.

Raise hands automatically when users join the session.

Resolution of session recording. Options are: CG:course gray, CC:course color, MG:medium gray, MC:medium color, FG:fine gray, or FC:fine color

Recording status; on, off or remote (start/stopped by moderator)

URL to redirect users to after the online session is over.

Restrict session to only invited participants.

Specify the number of seats to reserve on the server.

Either a PHONE number or SIP address for the server.

PIN for the server.

Session start time. This can be constructed by appending '000' to a unix ten digit epoch date.

Whether the moderator can see private messages.

This can be either SIP or PHONE.

General notes for users. These are not uploaded to the live session).

The maximum number of cameras.

Maintaining the Elive::Entity::Session abstraction may involve fetches from several entities. This is mostly transparent, but does have some implications for the list method:

* You can only filter on core meeting properties (name, start, end, password, deleted, faciltatorId, privateMeeting, allModerators, restrictedMeeting and adapter).

* Access to other properties requires a secondary fetch. This is done lazily on a per record basis and may be considerably slower. This includes access to attributes of meeting parameters, server parameter and participant list.

* recurring meetings are not yet implemented

* meeting telephony is not yet tested or supported

Please see Elive::View::Session. This provides an identical interface, but implements insert and update using ELM 2.x compatible commands.