NAME

Bb::Collaborate::Ultra::Connection - manage a server connection

DESCRIPTION

This class is used to maintain connections to Blackboard Ultra virtual classroom servers.

        require Bb::Collaborate::Ultra::Connection;
        my %params = (
            issuer => 'my-client-key',
            secret => 'sssh!',
            host => 'https://xx-csa.bbcollab.com',
        );
        my $connection = Bb::Collaborate::Ultra::Connection->new(\%params);

METHODS

auth

Holds the authorization token, obtained from the Collaborate server.

The connect method mast be invoked to obtain an auth token. The renew_lease method may be later used to extend the session, obtaining an new auth token.

debug

    $connection->debug(1);  # enable debugging

When set, a trace is enabled of requests and responses to and from the Collaborate server

connect

This method should be called once, with a newly created Bb::Collaborate::Ultra::Connection object to contact the server and authorize the credentials.

        my %credentials = (
          issuer => 'OUUK-REST-API12340ABCD',
          secret => 'ABCDEF0123456789AA',
          host => 'https://xx-csa.bbcollab.com',
        );

        # connect to server
        my $connection = Bb::Collaborate::Ultra::Connection->new(\%credentials);
        $connection->connect;

client

Returns the underlying client connection of type REST::Client.

renew_lease

    if ($connection->auth->expires_in < time() + 60) {
        # connection is about to expire; keep it alive.
        $connection->renew_lease;
    }

A authorization token typically remains valid for several minutes. This method can be used to extend the lease, whilst keeping the current connection.

POST

Low level method. Posts JSON data formatted data, along with appropriate authorization headers.

    my $response = $connection->POST('sessions', '{"startTime":"2016-09-27T05:10:04Z","endTime":"2016-09-27T05:25:04Z","name":"Test Session"}');
    my $session = Bb::Collaborate::Ultra::Session->construct($response, connection => $connection);

Generally, you should be using higher level class-specific `post` methods:

    my $session = Bb::Collaborate::Ultra::Session->post({startTime => time(), endTime => time() + 900, name => 'Test Session'});

PATCH

Low level method. Put JSON data formatted data.

    my $session_id = $session->id;
    my $response = $connection->PATCH('sessions/'.$session_id, '{"name":"Test Session - Updated"}');

GET

Low level method. Get by path

    my $session_id = $session->id;
    my $response = $connection->GET('sessions/'.$session_id);
    $session = Bb::Collaborate::Ultra::Session->construct($response, connection => $connection);

DELETE

Low level method. Delete by path

    my $session_id = $session->id;
    my $response = $connection->DELETE('sessions/'.$session_id);

cpanm Bb::Collaborate::Ultra

perl -MCPAN -e shell
install Bb::Collaborate::Ultra