NAME
DESCRIPTION
METHODS
Working with Participants
- Constructing Participant Lists
- Managing Participant Lists
Working with Preloads
- Creating Preloads
- Associating Preloads with Sessions
Providing access to Sessions (session JNLPs)
Working with recordings (recording JNLPs)
Working with Recurring Sessions
- Recurring Sessions - Parameters
- Recurring Sessions - Example
Session Property Reference
BUGS AND LIMITATIONS
SEE ALSO

NAME

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

DESCRIPTION

Elive::Entity::Session creates and modifies meetings via the createSession and updateSession commands, introduced with Elluminate Live! Manager 3.0.

METHODS

insert

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,
        restricted => 1,
        privateMeeting => 1,
        recordingStatus => 'remote',
        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 );

update

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

    # ...or...

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

Updates session properties, using the updateSession command.

retrieve

Retrieves a session for the given session id.

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

list

List all sessions that match a given criteria:

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

delete

Deletes a completed or unwanted session from the Elluminate server.

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

Note that a session, will have its deleted property immediately set to true, but may remain accessible for a short period of time until garbage collected.

So to check for a deleted session:

    my $session = Elive::Entity::Session->retrieve( $session_id ); 
    my $session_is_deleted = !$session || $session->deleted;

is_changed

     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.

Working with Participants

Constructing Participant Lists

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), e.g. Robert (bob@example.com)

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);

    $participants_obj->add(-other => @latecomers);

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

Managing Participant Lists

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::InvitedGuest)

Each participant will contain either an user, group or guestobject For example, to print the list of participants for a session:

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

    foreach my $participant (@$participants) {

        if (my $user = $participant->user)  {
            my $loginName = $user->loginName;
            my $email = $user->email;

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

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

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

        print " [moderator]"
            if $participant->is_moderator;

        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});

Working with Preloads

There are three types of preloads:

whiteboard: file extension *.wbd, *.wbp
plan (Elluminate Plan!): file extensions: *.elp, *.elpx
media (Multimedia): anything else

Creating Preloads

Preloads may be:

1. uploaded from a local file:

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

2. uploaded from binary content:

    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. imported from a file on the Elluminate Live! server:

    my $preload3 = Elive::Entity::Preload
         ->import_from_server('/home/uploads/slide3.wbd');

The type of the preload can be whiteboard, media or plan. Each preload also has a mimeType property. Both are guessed from the file extension, or you can supply, these details yourself:

    $preload2 =  Elive::Entity::Preload->upload({
                     name => 'slide2.wbd',
                     data => $content,
                     type => 'preload',
                     mimeType => 'application/octet-stream',
                   });

The import_from_server method also has an extended form:

    $preload3 =  Elive::Entity::Preload->import_from_server({
                     fileName =>'/home/uploads/slide3.wbd.tmp123'
                     ownerId => 357147617360,
                     type => 'preload',
                     mimeType => 'application/octet-stream',
                   });

Where fileName is the path to the file to be uploaded.

Associating Preloads with Sessions

Preloads 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 );

Attempting 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 automatically garbage collected by ELM, if they are not associated with any sessions, or the sessions have been deleted.

Please see also Elive::Entity::Preload.

Providing access to Sessions (session JNLPs)

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.

Working with recordings (recording JNLPs)

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_recordings;

    if (@$recordings) {
        # build a JNLP for the first recording
        my $recording_jnlp = $recordings[0]->buildJNLP(userId => $username);
    }

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

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

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

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

Working with Recurring Sessions

Recurring Sessions - Parameters

The create command has a number of additional parameters for setting up blocks of recurring meetings:

until `(HiResDate)`

Repeat session until this date.

repeatEvery `(Int)`

Repeat session type:

0 no repeat,
1 -> repeat every X days (as defined by repeatSessionInterval),
2 -> Repeat every x (as defined by repeatSessionInterval) weeks for each of the select days as defined by sundaySessionIndicator ... saturdaySessionIndicator.
3-5 -> Reserved,
6 -> Monthly session: Repeat on the X'th week on the month of the day of the as defined: 0 -> sunday, 1 -> Monday, etc.

repeatSessionInterval `(Int)`

Repeat the session every X days|days depending of repeatEvery value.

repeatSessionMonthlyInterval `(Int)`

Week of the month session should be scheduled in.

repeatSessionMonthlyDay `(Int)`

Day of the week the monthly session should be scheduled in.

sundaySessionIndicator ... saturdaySessionIndicator `(Bool)`

For repeatEvery value = 2, which days sessions should be scheduled.

timeZone `(Str)`

An optional alternate time-zone name to use for for the scheduling calculations (E.g. Australia/Melbourne).

Recurring Sessions - Example

For example, the following inserts three meetings, of duration 15 minutes, for today (starting in 5 minutes), tomorrow and the following day:

    use DateTime;

    my $start = DateTime->now->add(minutes => 5);
    my $end = $start->clone->add(minutes => 15);
    my $until = $end->clone->add(days => 2);

    my $start_msec = $start->epoch . '000';
    my $end_msec   = $end->epoch   . '000';
    my $until_msec = $until->epoch . '000';
    
    my %insert_data = (
        name              => 'daily scrum meeting',
        facilitatorId     => Elive->login->userId,
        password          => 'sssh!',
        privateMeeting    => 1,
        restricted        => 1,
        participants => '*the_team',
        start =>  $start_msec,
        end   => $end_msec,

        until                 => $until_msec,
        repeatEvery           => 1,
        repeatSessionInterval => 1,
    );

    my @sessions = $class->insert(\%insert_data);

Session Property Reference

Here's an alphabetical list of all available session properties

BUGS AND LIMITATIONS

Meeting telephony is not yet supported
list() method caveats
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 the participant list.

CPAN RT