Elive::Entity::Session - Session insert/update via ELM 3.x commands
Elive::Entity::Session creates and modifies meetings via the createSession and updateSession commands, introduced with Elluminate Live! Manager 3.0.
createSession
updateSession
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 );
$session->update({ boundaryTime => 15}); # ...or... $session->boundaryTime(15); $session->update;
Updates session properties, using the updateSession command.
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;
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.
deleted
So to check for a deleted session:
my $session = Elive::Entity::Session->retrieve( $session_id ); my $session_is_deleted = !$session || $session->deleted;
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.
update
revert
$session->revert('seats'); # revert just the 'seats' property $session->revert(); # revert everything
Reverts unsaved updates.
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.
-moderators
-others
@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>
<userId>
A pre-fetched user object of type Elive::Entity::User
A group-id string, in the format: *<groupId>
*<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)
Display Name (loginName)
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, });
Participant lists are returned as an array of elements of type Elive::Entity::Participant. Each participant contains one of:
Each participant will contain either an user, group or guest object. For example, to print the list of participants for a session:
user
group
guest
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});
There are three types of preloads:
whiteboard: file extension *.wbd, *.wbp
whiteboard
*.wbd
*.wbp
plan (Elluminate Plan!): file extensions: *.elp, *.elpx
plan
*.elp
*.elpx
media (Multimedia): anything else
media
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:
mimeType
$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:
import_from_server
$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.
fileName
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.
check_preload
$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.
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.
userName
userId
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.
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.
Recordings
For more information, please see Elive::Entity::Recording.
The create command has a number of additional parameters for setting up blocks of recurring meetings:
create
(HiResDate)
Repeat session until this date.
(Int)
Repeat session type:
repeatSessionInterval
sundaySessionIndicator
saturdaySessionIndicator
Repeat the session every X days|days depending of repeatEvery value.
Week of the month session should be scheduled in.
Day of the week the monthly session should be scheduled in.
(Bool)
For repeatEvery value = 2, which days sessions should be scheduled.
repeatEvery
(Str)
An optional alternate time-zone name to use for for the scheduling calculations (E.g. Australia/Melbourne).
Australia/Melbourne
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);
Here's an alphabetical list of all available session properties
This property is read-only. It should always have the value default for sessions created via Elive::Entity::Session.
default
All participants can moderate.
Session boundary time (minutes).
(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.
(milliseconds)
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.
(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".
A password for the session.
Whether to hide the session (meeting) from the public schedule.
Which user profiles are displayed on mouse-over: none, mod (moderators only) or all.
none
mod
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
CG
CC
MG
MC
FG
FC
Recording status; on, off or remote (start/stopped by moderator)
on
off
remote
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.
SIP
PHONE
General notes for users. These are not uploaded to the live session).
The maximum number of cameras.
Meeting telephony is not yet supported
list() method caveats
list()
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:
list
You can only filter on core meeting properties (name, start, end, password, deleted, faciltatorId, privateMeeting, allModerators, restrictedMeeting and adapter).
name
start
end
password
faciltatorId
privateMeeting
allModerators
restrictedMeeting
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.
Elive::View::Session - provides an identical interface, but implements insert and update using ELM 2.x compatible commands.
insert
To install Elive, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Elive
CPAN shell
perl -MCPAN -e shell install Elive
For more information on module installation, please visit the detailed CPAN module installation guide.