Proposals/MNet replacement/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

Client connection objects will be inherently tied to a plugin. This enables existing functionality for automatic lookup and discovery of plugin features to be used and also restricts the context of web service client execution to:

1. a single plugin
2. the contextual institution of the logged-in user
3. the access control rights of the logged in user

In order to support this 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 a Web Service client connection:

• requires a reference 'name' put in plugin 'lib.php' class definition file - refer to Mahara 'events' get_event_subscriptions() as an example
• multiple connections to various targets - this could be multiple remote web service function calls, or multiple external systems to be integrated with simultaneously for the same API

Metadata

Client Connection Instance
Mandatory	Element	Type	Default
M	name/handle (from settings - class level attr)	String	None
M	enable/disable individual instance	Boolean/Checkbox	Disabled
M	priority of instance	Integer/Ordinal	1
O	instance name - not necessarily unique but could be used by plugin to determine a different payload requirement	String	None
O	instance interface version - remote version supported for this instance	String	None
M	is fatal - if error, what do we do ?	Boolean/Checkbox	False
M	type (SOAP, XML-RPC, REST)	String	REST
M	payload encoding (SOAP-SOAP, XML-RPC - XML, REST-URL,XML,JSON)	String	URL Encoded
M	auth (SOAP- token, user+pass, wsse; XML-RPC- cert, token, user+pass; REST - token, user+pass, OAuth1.x)	String	None
M	Web Service endpoint	String	None
O	user/consumer key	String	None
O	password/consumer secret	String	None
O	token	String	None
O	X509 Certificate for XML-RPC	String	None
O	Additional parameter/values to pass	String	None
O	Additional parameters POST body/GET	String	GET

Note:

• one of user/consumer key + password/consumer secret, or token, or X509 certificate must be specified.
• if additional parameters are specified, then POST/GET must be specified

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();
}

function get_web_service_connections() {
  # query connection manager tables for list of connections
  # build and return a list of connection objects based on each client connection instance specification
...
}

...

class AuthPlugin extends Plugin {
...


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

In the plugin developers code, get_webservice_connections() is called and returns a list of client connection objects, that can be called to execute the relevant web services call.

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

The connection objects returned by get_webservice_connections() provide introspection capabilities so that the Plugin developer can know:

• what client ID this is - this should equate to the logical definition of an interface
• version
• protocol
• encoding
• authentication details
• parameters
• end point
• error handling (is fatal)

get_webservice_connections() only returns the enabled connections, so if all are disabled including with the master switch, then none are returned.

Assumptions

• Plugins that use client connections must deal with no connection objects passed by get_webservice_connections(), gracefully.
• it is the Plugin developers responsibility to deal with errors thrown by the connection object. The 'is fatal' flag is essentially a hint that is passed in to help the Plugin developer decide whether or not they wish to intervene on an error being thrown.

Process Flow

Wireframes, & Mockups

Connection Manager

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

Connection Manager Master Switch

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

Classes, Utilities

Modifications as describes above to class Plugin

Database Tables

New table required keyed by institution, connection ID, and client connection instance ID for the connection instance details (see table above).

Connection ID should be prefixed with '<Plugin Name>_' to ensure uniqueness.

Security

Client connection manager requires administration access for the given institution.

The global enable/disable switch for all connections requires global administrator access.

Modifications to Other code

See Client Connection Master switch above.

Testing

As a testing strategy, it should be possible to create a local plugin that can perform web services calls to either another Mahara instance, or a Moodle 2.7 (or above) instance.

Dependencies

This functionality depends on the final implementation of the Web Services plugin into core. The dependency is for:

• Mahara to Mahara testing
• master switch panel
• for the client connection object framework that this plugin provides.

Documentation Impact

Documentation is required for:

• the general client connection configuration process
• how plugin developers use the client connection features

Milestones

1. Client connection master switch
2. DML changes - new table
3. class Plugin client connection abstraction support
4. client connection manager configuration screens
5. reference implementation and test plugin