NAME

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

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;
    use Elive::Entity::Session;
    use Elive::Entity::Preload;

    Elive->connect('https://someEllumServer.com/my_instance',
                   'some_user', 'some_pass');

    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

Returns a list of properties that have unsaved changes.

     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.
     #

Destroying an object with unsaved changes will cause a warning. To avoid this, you will either need to call update on the object to save the changes, or revert to discard the changes.

revert

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

Reverts unsaved updates.

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 as an array 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 guest object. 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 residing 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 => 'whiteboard',
                     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 => 'whiteboard',
                     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, giving either a userName, userId, or displayName.

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

There's a slightly different format for guests:

    my $guest_jnlp = $session->buildJNLP(
                          displayName => $guest_display_name,
                          sessionRole => ${Elive::Entity::Role::MODERATOR} # 2
                     );

Unlike registered users, guests do not need to be registered as a session participant. They will be given a default role of ${Elive::Entity::Role::PARTICIPANT} (3).

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

adapter `(Str)`

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

allModerators `(Bool)`

All participants can moderate.

boundaryMinutes `(Int)`

Session boundary time (minutes).

costCenter `(Str)`

User defined cost center.

deleted `(Bool)`

True if the session has been deleted.

enableTelephony `(Bool)`

Telephony is enabled

end `(HiResDate)`

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

facilitatorId `(Str)`

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

followModerator `(Bool)`

Whiteboard slides are locked to moderator view.

fullPermissions `(Bool)`

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

id `(Int)`

The sessionId (meetingId).

inSessionInvitation `(Bool)`

Whether moderators can invite other individuals from within the online session

maxTalkers `(Int)`

The maximum number of simultaneous talkers.

moderatorNotes `(Str)`

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

moderatorTelephonyAddress `(Str)`

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

moderatorTelephonyPIN `(Str)`

PIN for moderator telephony

name `(Str)`

Session name.

participantTelephonyAddress `(Str)`

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

participantTelephonyPIN `(Str)`

PIN for participants telephony.

participants `(Array)`

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

password `(Str)`

A password for the session.

privateMeeting `(Str)`

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

profile `(Str)`

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

raiseHandOnEnter `(Bool)`

Raise hands automatically when users join the session.

recordingObfuscation `(Bool)`

recordingResolution `(Str)`

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

recordingStatus `(Str)`

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

redirectURL `(Str)`

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

restrictedMeeting `(Bool)`

Restrict session to only invited participants.

seats `(Int)`

Specify the number of seats to reserve on the server.

serverTelephonyAddress `(Str)`

Either a PHONE number or SIP address for the server.

serverTelephonyPIN `(Str)`

PIN for the server.

start `(HiResDate)`

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

supervised `(Bool)`

Whether the moderator can see private messages.

telephonyType `(Str)`

This can be either SIP or PHONE.

userNotes `(Str)`

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

videoWindow `(Int)`

The maximum number of cameras.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

METHODS

insert

update

retrieve

list

delete

is_changed

revert

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

until (HiResDate)

repeatEvery (Int)

repeatSessionInterval (Int)

repeatSessionMonthlyInterval (Int)

repeatSessionMonthlyDay (Int)

sundaySessionIndicator ... saturdaySessionIndicator (Bool)

timeZone (Str)

Recurring Sessions - Example

Session Property Reference

adapter (Str)

allModerators (Bool)

boundaryMinutes (Int)

costCenter (Str)

deleted (Bool)

enableTelephony (Bool)

end (HiResDate)

facilitatorId (Str)

followModerator (Bool)

fullPermissions (Bool)

id (Int)

inSessionInvitation (Bool)

maxTalkers (Int)

moderatorNotes (Str)

moderatorTelephonyAddress (Str)

moderatorTelephonyPIN (Str)

name (Str)

participantTelephonyAddress (Str)

participantTelephonyPIN (Str)

participants (Array)

password (Str)

privateMeeting (Str)

profile (Str)

raiseHandOnEnter (Bool)

recordingObfuscation (Bool)

recordingResolution (Str)

recordingStatus (Str)

redirectURL (Str)

restrictedMeeting (Bool)

seats (Int)

serverTelephonyAddress (Str)

serverTelephonyPIN (Str)

start (HiResDate)

supervised (Bool)

telephonyType (Str)

userNotes (Str)

videoWindow (Int)