File Coverage

blib/lib/Elive.pm

Criterion	Covered	Total	%
statement	26	40	65.0
branch	0	6	0.0
condition	0	6	0.0
subroutine	9	14	64.2
pod	6	6	100.0
total	41	72	56.9

package Elive;
use warnings; use strict;

=head1 NAME

Elive - Elluminate Live! Manager (ELM) Command Toolkit bindings

=head1 VERSION

Version 1.33

=cut

our $VERSION = '1.33';

use 5.008003;

use parent qw{Class::Data::Inheritable};
use Scalar::Util;

use YAML::Syck;
use Carp;
use Elive::Entity;

=head1 EXAMPLE

The following (somewhat contrived) example sets up a meeting of selected
participants:

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

    my $meeting_name = 'Meeting of the Smiths';

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

    my $users = Elive::Entity::User->list(filter => "(lastName = 'Smith')");
    die "smithless" unless @$users;

    my $start = time() + 15 * 60; # starts in 15 minutes
    my $end   = $start + 30 * 60; # runs for half an hour

    my $whiteboard_preload = Elive::Entity::Preload->upload('welcome.wbd');

    my $session = Elive::Entity::Session->insert({
	 name           => $meeting_name,
	 start          => $start . '000',
	 end            => $end   . '000',
         restricted     => 1,
         participants   => $users,
         add_preload    => $whiteboard_preload,
	 });

    print "Session address: ".$session->web_url;

    Elive->disconnect;

=head1 DESCRIPTION

Elive is a set of Perl bindings and entity definitions for quick and easy
integration with the Elluminate I Manager (ELM) application. It can
be used to automate a range of tasks including setting up meetings and
participants, as well as managing users and user groups.

=head1 BACKGROUND

Elluminate I is software for virtual online classrooms. It is suitable
for meetings, demonstrations, web conferences, seminars, training and support.

Most management functions that can be performed via the web interface can
also be achieved via SOAP web services. This is known as the
I and is detailed in chapter 4 of the Elluminate I
Software Developers Kit (SDK).

Users, Meetings and other resources are stored in the Elluminate I
Manager (ELM) database. These can be entered, accessed and manipulated via
the Entity Commands in the Command Toolkit.

=cut

=head1 METHODS

=head2 connect

     Elive->connect('https://myServer.com/test', some_user => 'some_pass');
     my $connection = Elive->connection;

Connects to an Elluminate server instance. Dies if the connection could not
be established. If, for example, the SOAP connection or user login failed.

The login user must either be an Elluminate I system administrator
account, or a user that has been configured to access the Command Toolkit
via web services.

See also: the Elive C file, L.

=cut

sub connect {
    my $class = shift;
    return Elive::Entity->connect(@_);
}

=head2 connection

     $e1 = Elive->connection
         or warn 'no elive connection active';

Returns the current L connection.

=cut

sub connection {
    my $class = shift;
    return Elive::Entity->connection(@_);
}

=head2 login

Returns the login user for the default connection.

    my $login = Elive->login;
    say "logged in as: ".$login->loginName;

See L.

=cut

sub login {
    my ($class, %opt) = @_;

    my $connection = $opt{connection} || $class->connection;

    die "not connected"
	unless $connection;

    return $connection->login;
}

=head2 server_details

Returns the server details for the current connection. See L.

    my $server = Elive->server_details;
    printf("server %s is running Elluminate Live! version %s\n", $server->name, $server->version);

There can potentially be multiple servers:

    my @servers = Elive->server_details;
    foreach my $server (@servers) {
        printf("server %s is running Elluminate Live! version %s\n", $server->name, $server->version);
    }

=cut

sub server_details {
    my ($class, %opt) = @_;

    my $connection = $opt{connection} || $class->connection
	or die "not connected";

    my @server_details = $connection->server_details;
    return wantarray ? @server_details : $server_details[0]
}

=head2 disconnect

Disconnects the default Elluminate connection. It is recommended that you
do this prior to exiting your program.

    Elive->disconnect;
    exit(0);

=cut

sub disconnect {
    my $self = shift;
    return Elive::Entity->disconnect;
}

=head2 debug

    Elive->debug(1)

Sets or gets the debug level.

=over 4

=item 0 = no debugging

=item 1 = dump object and class information

=item 2 = also enable SOAP::Lite tracing

=item 3 = very detailed

=back

=cut

sub debug {
    my $class = shift;
    Elive::DAO::_Base->debug(@_);
}

=head1 ERROR MESSAGES

Elluminate Services Errors:

=over 4

=item   "Unable to determine a command for the key : Xxxx"

This may indicate that the particular command is is not available for your
site instance. Please follow the instructions in the README file for
detecting and repairing missing adapters.

=item   "User [], not permitted to access the command {]"

Please ensure that the user is a system administrator account and/or the
user has been configured to access commands via web services. See also the
L file.

=back

=cut

=head1 SCRIPTS

=head2 elive_query - simple query shell

elive_query is a script for issuing basic sql-like queries on entities. It serves as a simple demonstration script, and can be used to confirm connectivity and operation of Elive.

    % perl elive_query https://myserver.com/test -user sdk_user
    Password: connecting to https://myserver.com/test...ok
    Elive query 1.xx - type 'help' for help

    elive> select address,version from serverDetails
    address     |version
    ------------|-------
    myserver.com|10.0.1
    elive> ^D

It serves a secondary function of querying entity metadata. For example,
to show the C entity:

    % elive_query
    Elive query 1.xx  - type 'help' for help

    elive> show
    usage: show group|meeting|...|serverParameters|session|users

    elive> show meeting
    meeting: Elive::Entity::Meeting:
      meetingId          : pkey Int
      adapter            : Str       -- adapter used to create the meeting
      allModerators      : Bool      -- all participants can moderate
      deleted            : Bool
      end                : HiResDate -- meeting end time
      facilitatorId      : Str       -- userId of facilitator
      name               : Str       -- meeting name
      password           : Str       -- meeting password
      privateMeeting     : Bool      -- don't display meeting in public schedule
      restrictedMeeting  : Bool      -- Restricted meeting
      start              : HiResDate -- meeting start time

for more information, please see L, or  or type the command: C

=head2 elive_raise_meeting - meeting creation

This is a demonstration script for creating meetings. This includes the setting
of meeting options, assigning participants and uploading of preloads (whiteboard, plan and media files).

For more information, see L or type the command: C

=head2 elive_lint_config - configuration file checker

A utility script that checks your Elluminate server configuration. This
is more likely to be of use for Elluminate I prior to 10.0. Please
see the README file.

=head1 SEE ALSO

=head2 Modules in the Elive distribution

=over 4

=item L - Sessions (or meetings)

=item L - Groups of Users

=item L - Preload Content (whiteboard, multimedia and plans)

=item L - Session Recordings

=item L - Management Reports

=item L - Users/Logins

=item L - Elluminate SOAP connections

=back

=head2 Scripts in the Elive Distribution

=over 4

=item L - simple interactive queries on Elive entities

=item L - command-line meeting creation

=item L - Elluminate Live! configuration checker

=back

=head2 Related CPAN Modules

L - this module implements the alternate Elluminate I Standard Bridge API (v3).

=head2 Elluminate Documentation

This following documents were used in the construction of this module:

=over 4

=item ELM2.5_SDK.pdf

General Description of SDK development for Elluminate I. In particular
see section 4 - the SOAP Command Toolkit. This module concentrates on
implementing the Entity Commands described in section 4.1.8.

=item Undocumented ELM 3.x SDK Calls.pdf

This describes the C and C commands, as
implemented by the L C and C
methods.

=item DatabaseSchema.pdf

Elluminate Database Schema Documentation.

=back

=head1 AUTHOR

David Warring, C<<  >>

=head1 BUGS AND LIMITATIONS

=over 4

=item * Elive does not support hosted (SAS) systems

The Elive distribution only supports the ELM (Elluminate I Manager) SDK.
The SAS (Session Administration System) is not supported.

=back

=head1 SUPPORT

Please report any bugs or feature requests to C,
or through the web interface at L.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc Elive

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back

=head1 ACKNOWLEDGEMENTS

Thanks to Lex Lucas and Simon Haidley for their ongoing support and
assistance with the development of this module.

=head1 COPYRIGHT & LICENSE

Copyright 2009-2012 David Warring, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

1; # End of Elive