NAME
Elive::Entity::Session - Session insert/update via ELM 3.x (TRIAL)
DESCRIPTION
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.
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,
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 );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.
revert
$session->revert('seats'); # revert just the 'seats' property
$session->revert(); # revert everythingReverts unsaved updates.
update
$session->update({ boundaryTime => 15});
# ...or...
$session->boundaryTime(15);
$session->update;Updates session properties
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;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)'
Unless you're using LDAP, you're likely to have to look-up users and groups based on their 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 @guests = qw{'Larry Wall(TimToady)'}; # just in case ;-)
my @participants = (-moderators => [$alice, $bob],
-others => [@$tut_group, @guests],
);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,
});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::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:
push (@$participants, 'trev'); # add a user
$session->update({participants => $participants});Working with Preloads
Preloads may be both uploaded from the client or server:
# upload from a file
my $preload1 = Elive::Entity::Preload->upload('c:\\Documents\slide1.wbd');
# 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,
);
my $preload3 = Elive::Entity::Preload
->import_from_server('/home/uploads/slide3.wbd');These can then be added in a number of ways:
my $session = Elive::Entity->Session->create({
# ...
add_preloads => $preload1,
});
$session->update({add_preloads => $preload2});
$session->add_preload( $preload3 );The one preload can be reused across multiple sessions:
$session1->add_preload( $preload );
$session2->add_preload( $preload );Adding a preload more than once is consider an error. The check_preload method can 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'll need to do this yourself:
my $preloads = $session->preloads;
$session->delete;
$_->delete for (@$preloads);But the preload also become unavailable for any other meetings that are sharing it, which may not be what you want.
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 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 the 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 a not deleted, when you delete sessions. In a similar vain to preloads, if you want to delete associated recordings when you delete sessions:
my $recordings = $session->recordings;
$session->delete;
$_->delete for (@$recordings);For more information, please see Elive::Entity::Recording.
Session Property Reference
Here's an alphabetical list of all available session properties:
adapter (String)
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.
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
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".
password (Str)
A password for the session (see "Working with Participants").
privateMeeting (Str)
Whether to hide the session (meeting) from the public schedule.
profile
Which user profiles are displayed on mouse-over: none, mod (moderators only) or all.
raiseHandOnEnter
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
General notes for users. These are not uploaded to the live session).
videoWindow (Int)
The maximum number of cameras.
BUGS AND LIMITATIONS
Maintaining the Elive::View::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,restrictedMeetingandadapter).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
SEE ALSO
Please see Elive::View::Session. This provides an identical interface, but implements insert and update using ELM 2.x compatible commands.