Elluminate Live! (c) is software for virtual online classrooms. It is suitable
for meetings, demonstrations web conferences, seminars, general training and
support.

Elive is a set of Perl bindings and entity definitions for the entity commands
in the Command Toolkit. You can, for example, use it to manage users, groups
meetings and meeting participants.

Some manual configuration may be required on your Elluminate Live! server to
enable access to SOAP web services. Please see the server configuration section.

COMPATIBILITY

    The Elive distribution only supports only self hosted Elluminate Live!
    servers.

    - works best with ELM (Elluminate Live Manager) version 3.0 - 3.3.5 and
      Elluminate Live! version 9.5 - 10.0.1

    - does not support access to externally hosted servers deployed with SAS
      (Session Administration System).

INSTALLATION

    To install this module, run the following commands:

        perl Makefile.PL
        make
        make test
        make install

CONFIGURING SDK ACCESS

    By default, only Elluminate Live! administrator users (Role 0) are
    granted access to the SDK.

    If you wish to to grant access to non-administrator users and/or
    revoke administrator access, you'll need to manually change this
    in your site instance configuration.

    To do this, firstly stop the site using the Elluminate Live Instance
    Manager (http://yourserver/elmcontrol).

    Then you'll need to edit the configuration.xml for the site instance.

      (*) Under Linux, the web application root is:

          /opt/ElluminateLive/manager/tomcat/webapps

      (*) or under Windows, it's:

         C:/Program Files/ElluminateLive/manager/tomcat/webapps

      (*) The actual configuration for the root instance is the sub-path:

         ROOT/WEB-INF/resources/configuration.xml

      (*) or for any additional sites built with the instance manager:

                 mysite/WEB-INF/resources/configuration.xml

    Edit the file and add an entry for the SDK user to the security section:

            <elm>
                ...
               <proxymanager enable="true">
                 <proxy name="web" ..>
                  ...
                  <security adapter-name="default">
                    <permissions>
                      <role id="0">
                        <allow command="*" />
                      </role>

                      <!-- ++ ADD THIS -->
                      <user name="some_user">
                         <allow command="*" />
                      </user>
                      <!-- -- ADD THIS -->
                    </permissions>
                    ...

ADDITIONAL TESTING

    There are additional live tests in t/soap-*.t and t/script-*t. By default,
    these are either skipped or run offline.

    These may be run against a live server by setting up the environment
    variables, and running tests, as shown below:

        perl Makefile.PL
        make
        export ELIVE_TEST_URL=http://sdk_user@some_server.com/some_instance
        export ELIVE_TEST_PASS=some_password
        make test

    There's also some additional envirnoment variables that may be set
    to further extend the range of tests:

    ELIVE_TEST_PRELOAD_SERVER_PATH - absolute path of an existing preload
               file on the server. Set this to enable testing of the
               Elive::Entity::Preload::import_from_server() method.

    ELIVE_TEST_USER_UPDATES - set this to true to enable insert and update
               of user accounts on a live site (t/soap-user.t). 

    ELIVE_TEST_GROUP_UPDATES - set this to true to enable insert and update
               of groups on a live site (t/soap-group.t).

    The User and Group update tests can only be run on sites that have not
    been configured for LDAP.

    WARNING: These tests will both create and delete various entities
    instances. For this reason you should be wary of running the live
    tests on production sites.

    Consider restricting live testing to designated development and test
    sites, or newly created site instances!

POST INSTALLATION

    The elive_query script can be used to check basic operation of Elive
    and access to your Elluminate server(s).

        % elive_query --user admin_user http://myserver/mysite

    Where admin_user is an Elluminate system administrator account.

    You will need to enter a password. You should then get:

        connecting to http://myserver/mysite...done
        Elive query 1.xx (Elluminate Live 10.y.z) - type 'help' for help
        elive>

    You can then try a simple query:

        elive> select * from users

    See also elive_raise_meeting. This is a utility script that creates
    Elluminate meetings.

        % elive_raise_meeting --user admin_user http://myserver/mysite -name 'Test'

TROUBLESHOOTING

    'User [<username>], not permitted to access the command {<command>]'
    --------------------------------------------------------------------
    You are connected to the SOAP services with an account that has not
    been setup for full SDK access. Please see the Server Configuration
    section above.
    
    'Unable to determine a command for the key Xxxxx'
    -------------------------------------------------
    This may indicate that some of the adapters are missing from
    your Elluminate configuration. This can be prone to likely to
    happen with an Elluminate instance that has been through several
    Elluminate upgrades.

    You can use the installed script elive_lint_config to check for
    missing adapters.

        % cd /opt/ElluminateLive/manager/tomcat/webapps
        % elive_lint_config WEB-INF/resources/configuration.xml
        missing adapter command: getUser
        missing adapter command: deletePreload
        missing adapter command: listPreloads

    The adapters can be added to your configuration file.

    For example, if elive_lint_config returned the error:

        "missing adapter command: getUser"

    You'll need to first stop Elluminate services.

    Save a backup copy of configuration.xml Then you can add an adapter
    entry can be added to the list of adapters.

    E.g., to add the getUser adapter:

        <elm>
            ...
            <adapters>
               <adapter name="default" class="com.elluminate.adapter.CommandAdapter" adapterType="ELM">
                  <commands>
                    ...
                    <!-- ++ ADD COMMANDS HERE -->
                    <command name="getUser" class="com.elluminate.adapter.command.GetUserCommand" />
                    <!-- -- ADD COMMANDS HERE -->

LDAP AUTHENTICATION

    Elluminate Live! can also be configured to use an LDAP repository for
    user authentication.  Users and groups can  be retrieved or listed, but
    cannot be updated.

    * You can map both of the user's userId and loginName to the
      LDAP uid attribute.

    * Updates and deletes are not supported by the LDAP DAO adapter.

SUPPORT AND DOCUMENTATION

    See the Elluminate Live documentation. In particular, this package
    follows the entities and relationships described in DatabaseSchema.pdf.

    You will find a copy on the installation disk; or if you have access to the
    server, you will will typically find this in /opt/Elluminate/documentation. 

    After installing, you can find documentation for this module with the
    perldoc command.

        perldoc Elive

    You can also look for information at:

        RT, CPAN's request tracker
            http://rt.cpan.org/NoAuth/Bugs.html?Dist=Elive

        AnnoCPAN, Annotated CPAN documentation
            http://annocpan.org/dist/Elive

        CPAN Ratings
            http://cpanratings.perl.org/d/Elive

        Search CPAN
            http://search.cpan.org/dist/Elive/


COPYRIGHT AND LICENCE

Copyright (C) 2009-2011 David Warring

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

