Actions

Proposals/MNet replacement/Connection manager

From Mahara Wiki

< Proposals‎ | MNet replacement
Revision as of 12:43, 4 November 2014 by Piersharding (talk | contribs)

Web Services Client Connection Manager

Summary

This specification describes the new functionality for managing client connections (Mahara is the client) for web service interactions, and the utility functions/classes that abstract away the complexities of making web services calls for Plugin developers.

Target Release

Mahara 15.04

Owner

TBD


References

Inspiration for the implementation pattern was source from Developer_Area/Core_Subsystems/Artefact_Plugins_//_Artefact_Types, and the Web Services plugin .


Motivation

The idea behind this requirement is to abstract away the management of connection details from individual components of Mahara (eg. a plugin), so that each component does not need to maintain a set of configuration, and the management of that configuration is consistent in behaviour, look and feel.

Once there is a consistent management of Web Service client connections, it is also possible to abstract away the code in helper classes and functions for executing Web Service calls, which should streamline and component development, and ensure that components use a common code base for Web Service interaction.


Use Cases(Stories)

Plugin Developer

Description

As a plugin developer, I want to be able to have a logical reference to a list of connections that refer to 1 or more web service end points that I can pass attributes to for web service call execution.

Preconditions

  • Developing a plugin is dependent on inheriting from class 'Plugin' .

Steps

  1. With each plugin developed, specify a list of connection 'handles' that represent client connections that my plugin will interact with.
  2. When I wish to execute a remote web service call, I can call a function that returns a list of prefabricated client connections. These client connections are an abstraction from the complexity of dealing with different web services protocols, authentication, and encoding schemas, so that I can concentrate on formulating the data packet, and interpreting the results.

Postconditions

Metadata for the Plugin related client connections has been defined.


Mahara administrator

Description

As a Mahara administrator I want an interface that enables me to configure a logical reference to a a list of web service connections.

Preconditions

  • Plugin developers have defined the client connection related metadata.

Steps

  1. Login as an Administrator, and go to Institution specific configuration.
  2. Add, amend, delete or reorder priority of client connection instances.
  3. Drill into a client connection and specify name, version. protocol, authentication, and end point configuration.
  4. enable/disable client connection instance.
  5. enable/disable all client connections.

Postconditions

  • A list of client connection instances are maintained for each Institution.
  • The web service client connection instances must adequately describe the supported protocols of SOAP, XML-RPC, and REST using the payload encodings of SOAP, XML, URL, and JSON where appropriate. The connections must also support the configuration of authentication options of token, user+password, OAuth1.x and WSSE where appropriate.

Specification

Description

The changes required fall into two broad categories:

  • interactive configuration components for maintaining the connection metadata
  • Plugin framework class modifications to support web service client abstractions

Client Connection Manager

A plugin or component that needs WS client connection :

 * needs a reference handle
 * put in settings file - auto discovered
 * multiple connections to various targets
 * only ever called from an event handler ?
 * fields: M  name/handle (from settings - class level attr)
           O enable/disable whole connection object
           M priority of instance
           O instance name - not necessarily unique but could be used by plugin to determine a different payload requirement
           O instance interface version - similar to above
           O institution ? (do interfaces run per institution or for site as a whole?)
           O enable/disable individual instance
           O is fatal - if error, what do we do ?
           M type (SOAP, XML-RPC, REST)
           M payload encoding (SOAP-SOAP, XML-RPC - XML, REST-URL,XML,JSON)
           M auth (SOAP- token, user+pass, wsse; XML-RPC- cert, token, user+pass; REST -  token, user+pass, OAuth1.x)
           M WS endpoint
           O user/consumerkey      }
           O pass/consumersecret   } -   one of these must be set
           O token                 }
           O cert                  }
           O additional parameter/values to pass ? <---- could be just put on endpoint ?
           O params POST body/GET ?^^ - defaults to GET if any parameters set


Plugin Abstraction Layer

Return a list of connection classes defined for this plugin. These will be used to determine what connection classes are available for configuration in the connection manager. Empty if none.

class Plugin implments IPlugin {
...
function define_webservice_connections() {
    return array();
}
...

class AuthPlugin extends Plugin {
...


class MyAuthPlugin extends PluginAuth {
...
function define_webservice_connections() {
    return array(array('id' => 'my_connection', 'name' => 'My Plugin WebService Connection'), ...);
}
...


 foreach ($plugin->get_webservice_connections() as $connection) {
    try {
        $results = $connection->call(array('field' => 'username', 'values' => array($dbuser->username)));
    } catch (Exception $e) {
         ...
    }   
 }


Assumptions

Issues

Process Flow

UX

This should contain discussion of the UX implications of the change. If the UX discussion already has a design proposal, a link should be inserted here. If the discussion is ongoing it can take place in the whiteboard area.

Wireframes, & Mockups

Connection Manager

The connection manager is an extension of the exiting Institution configuration page - navigate Adminstration -> Institutions -> 'Edit' Institution.

Mahara-Connection-Manager.png

Connection Manager Master Switch

The master switch for disabling/enabling all client connections is located on the main Web Services configuration page.

Mahara-Connection-Manager-Master-Switch.png

Classes, Utilities

Database Tables

Security

Modifications to Other code

Testing

Brief instruction for reviewers to exercise the changes, including expected results where non-obvious.

Dependencies

Is this functionality already supported in other services? List the appropriate API calls and if they are extensions or base API functionality.

This should describe any cross project dependencies. This should include:

 * changes to Mahara services
 * changes in external projects

Links to particular patches should be included in the whiteboard area.


Doc Impact

This should describe any changes to Mahara documentation that will be required. This could include:

 * settings file changes that will be required
 * changes to default behaviours
 * any deprecation or obsolescence notices


Milestones

How the work can be broken up