Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Community hub - technical specification

From MoodleDocs

Moodle 2.0


Implementation

The community hub project is implemented in core (site related code), and as two external plugins.

Moodle core

In Moodle core we added:

  • a new registration form
  • a community block (search course, import and restore course)
  • some course publication operations

Hub server

A hub server is a plugin in /local/hub/. Note that in Moodle core, there is a little hack that detect the plugin, and display a specific hub front page.

The plugin can be found into Contrib CVS.

Hub directory

A hub directory is a plugin in /local/hubdirectory.

The plugin is not released.

Hub directory

Data structure

on the hub directory we have a table named hub_directory containg all registered hubs :

Name Type Description
id int Standard autoincrement
name varchar Name of the hub
description text Description of the hub
url varchar The full URL to the hub front page
token varchar The token used to call the hub
trusted int Is the hub trusted?
language varchar What is the primary language of this hub? (blank for multilanguage)
timeregistered int Time that the hub was first registered
timemodified int Time that the hub was last modified
contactname varchar Name of the contact person
contactemail varchar Email of the contact person
imageurl varchar hub logo url
visible int is hub visible (i.e. enable field)
prioritise int is this hub prioritised
courses int Number of courses on this hub
sites int Number of sites on this site
privacy varchar "public"/"private"

on the hub directory we have a table named hub_global_course_directory containg all public published courses into all public hub:

Name Type Description
id int Standard autoincrement
hubid int Hub ID from the table hub_directory
sitename varchar Site name - can be blank
siteurl varchar Site URL- can be blank
fullname varchar Fullname of the course
description text Description of the course
courseurl varchar The full URL to the course
contributornames varchar Contributor names
coverage varchar Coverage
language varchar What is the language of this hub?
timemodified int Time that the course was last published
creatorname varchar Name of the creator
publishername varchar Name of the publisher
format varchar url or Zip
shortname varchar course short name
licenseshortname varchar license shortname
subject varchar subject
audience varchar
educationallevel varchar
coursemapid varchar
creatornotes varchar
creatornotesformat varchar
privacy varchar
downloadurl varchar
originaldownloadurl varchar
demourl varchar
trusted int
enrollable int
screenshotsids varchar
enrolcost int
enrolcostcurrency varchar
downloadcost int
downloadcostcurrency varchar

communication with hub

Communications between hub and hub directory are two ways, they can call each other by web service. For any hub/hub directory communication, we record the remote entity (i.e. hub directory/hub) in a table named hub_communication or hub_directory_communication. This is mainly used to remember the token used by the remote entity and the name of the remote entity. It's also used as a flag to know if a registration attempt has been confirmed.

Name Type Description
id int Standard autoincrement
localtype varchar Is our Moodle site a: Site, Hub or Hub directory
token text the token used for this communication
localws varchar What kind of entity is our site in this communication. Are we server or client?
remotetype varchar Is the remote Moodle site a: Site, Hub or Hub directory
remotename varchar Full name of the remote site
remoteurl varchar URL of the remote entity
confirmed int Is this confirmation confirmed (in case the registration/update failed)


registration process

  1. the hub admin goes on hub settings page => settings are saved with set_config
  2. the hub admin presses register and is redirected to the hub directory registration page. This redirection has the token used by the hub directory.
  3. the hub admin enters a recaptcha on the hub directory registration page. It is mandatory to avoid people to write script automatically registering.
  4. the hub directory redirect the hub admin to his own site on a confirmation page. The redirection has the token used by the hub.

update process

  1. the hub admin changes the settings.
  2. the hub admin presses update registration.
  3. the hub calls by web service the update info function on the hub directory.

security design

  • because there is a recaptcha, only human being can register.
  • all other communications are protected by Moodle ws security design
  • In order to use web service we automatically create Users/Services/Roles/Functions. All created users, web services functions, web services and web service tokens are visible in the admin user interface. Hub admin should not to delete them, neither create some with the same names. Hub admin can only modify the roles in order to restrict the capabilities to use some of the functions. To know about automatically created Users/Services/Roles, see their respective sections in this same page.

Hub server

Data structure

Primarily this hub_site_directory table will store information about the sites that have registered course information on that Hub. On hub.moodle.org this information will also be used for general statistics and the listing of registered sites:

Name Type Description
id int Standard autoincrement
name varchar Name of the site
description text Description of the site
url varchar The full URL to the site front page
secret varchar The site secret used to confirm the registration and to not register a site twice.
trusted int Is the site trusted?
language varchar What is the primary language of this site? (blank for multilanguage)
timeregistered int Time that the site was first registered
timemodified int Time that the site was last modified
contactname varchar Name of the contact person
contactemail varchar Email of the contact person
contactphone varchar Phone of the contact person
contactable int can we contact the person
imageurl varchar site logo url
visible int is site visible (i.e. enable field)
prioritise int is this site prioritised
countrycode varchar country code ISO 3166 (AU, FR etc) lang/XX_utf8/countries.php
regioncode varchar region code ISO 3166-2 ISO 3166-2 (XX-XXX) (alphanumeric codes) (TODO: MDL-24020)
street varchar street
geolocation varchar lattitude and longitute (like in googlemap/twitter)
moodleversion varchar Moodle version
moodlerelease varchar Moodle releasel
ip varchar last IP of this site
courses int Number of courses on this site
users int Number of users on this site
enrolments int Number of enrolments on this site
resources int Number of resources on this site
questions int Number of questions on this site
modulenumberaverage int Module number average on this site
participantnumberaverage int Participant number average on this site
emailalert int Do we send email notification - Subscribed to securityalerts@lists.moodle.org
privacy varchar "public"/"private"
posts int Number of posts on this site
timevalidationfailed int The time the last time the site was not reach
deleted int is the site deleted
publicationmax int how many publication are allowed on the hub every day

On the hub server, the hub_course_directory table stores registered courses, one record per course. Some courses will be "downloadable", some will be enrollable, so different fields can be used. Note that from these data you can build the exact Dublin Core Metadata Element Set, Version 1.1:

Name Type Description
id int Standard autoincrement
siteid int Site ID from the table hub_site_directory
fullname varchar Fullname of the course
description text Description of the course
courseurl varchar The full URL to the course
contributornames varchar Contributor names
coverage varchar Coverage
language varchar What is the language of this hub?
timemodified int Time that the course was last published
creatorname varchar Name of the creator
publishername varchar Name of the publisher
format varchar url or Zip
shortname varchar course short name
licenseshortname varchar license shortname
subject varchar subject
audience varchar Students | Admin
educationallevel varchar Secondary | Primary | Government | Corporate | Association | Other
coursemapid varchar Is a course map supplied? (Simple XML description of course structure, could be rendered graphically later CompendiumLD )
creatornotes varchar Creator notes (describes how to use the course, where it came from, context, more description etc)
creatornotesformat varchar Creator notes format (HTML etc)
privacy varchar Availability (public/private)
downloadurl varchar Download URL (usually a local cached zip but could be anything else, including empty for non-downloadable)
originaldownloadurl varchar Original Download URL (usually a download script on the original Moodle site, used by Hub to get cache)
demourl varchar Demo URL (a URL, if any, where the course can be seen in action)
trusted int Is the course trusted? (all downloadable courses from non-trusted sites start as "no", then this gets changed by someone who checks it)
enrollable int Is the course enrollable anyone with an account?
screenshots varchar Number of supplied screenshots
enrolcost int Enrol Cost (and currency) ISO 4217
enrolcostcurrency varchar
downloadcost int Download Cost (and currency) ISO 4217
downloadcostcurrency varchar
Dublin Core Metadata Element Set, Version 1.1
    1. Contributor - course manager names or whoever the publisher nominates
    2. Coverage - User tags
    3. Creator - main teacher name or copyright holder or whoever the publisher nominates
    4. Date - date this was last published/updated
    5. Description - course description
    6. Format - zip / url
    7. Identifier - course shortname (unique on the original site)
    8. Language - based on lang.php
    9. Publisher - the name of the person who caused this record to be entered here
    10. Relation - the site id that it came from
    11. Rights - one of a standard set of open source, creative commons and other licenses
    12. Source - original URL of the course
    13. Subject - The best-matching item from (Standard Classification of Educational Fields)
    14. Title - Course fullname
    15. Type - "course" (later there might other types such as activities or SCORM packages etc)

TODO:

    1. Is guest access allowed?


Course feedback

  • id
  • course id
  • type (bug / comment)
  • text
  • rating (probably a rating ID => futur rating API)

TODO: a simple way to alert the publisher of new feedback on a course.

Course content

  • id
  • course id
  • module type (activity / block)
  • module name (forum, resource etc)
  • count

Course outcomes

  • id
  • course id
  • outcome (text)

communication between site and hub

The site registration process is similar to "Hub registration on hub directory", except that the site doesn't create any ws token for the hub. However the site creates a secret key in order to confirm the registration process, the hub sending it back at the end of the process. The communication between site and hub are one way only, site to hub.

Registered site

tables

On the registered sites we have a table named hub_course_published containg all published courses.

communication

Sites send files calling a upload.php script on the hub.

List of communications between the three entities

Following the different communication operations expected between Moodle.org, hub servers and Moodle site.

Moodle site and Hub server

One way communications, site to hub.

Moodle.org Hub directory and (Moodle.org) Hub server

Hubdirectory moodleorg2hubserver moodle.org.png

Moodle site and Moodle.org Hub directory

Moodlesite2moodleorg.png

How does the communication work

We are going to use Moodle web services. We will create a new /hub/webservice.php entry point It will bypass $CFG->enablewebservice and it will consider a choosen protocol as activated.

Registration operations

  1. The hub creates a specific ws user, a specific ws role, a specific ws service and a specific token.
  2. The hub sends by POST the web service token to the site/hub directory.

Unknown caller operations

the webservice.php entry point should by pass token authentication for some public functions.

public function list

  • global search
  • search courses on a hub
  • get hub list from the hub directory

Required roles for community hub web services

Moodle.org Hub list

"Public Directory User" - Role for any sites :

  • moodle/hubs:view (public token for any sites) for searching the global listing

"Directory User" - Role for hub to update the listing:

  • moodle/hubs:updateinfo (private token for any registered hub) for updating hub information (it creates a new private token different from the one used to call this function)

Hub server

Will have one new user per registered site, plus one for Moodle.org hub directory and one for pubic users.

"Public Hub User" - Role for any site (public token)

  • moodle/hub:view for course searches
  • moodle/hub:rate for rating a course
  • moodle/hub:comment for commenting a course
  • moodle/hub:download for downloading a course template

"Registered Hub User" - Role for registered sites (private token -> each site gets a private user)

  • moodle/hub:view for course searches
  • moodle/hub:rate for rating a course
  • moodle/hub:comment for commenting a course
  • moodle/hub:download for downloading a course template
  • moodle/hub:publish for publishing a course template
  • moodle/hub:updateinfo (private token for any registered site) for updating site information (it creates a new private token different from the one used to call this function)

"Moodle.org Hub Directory" - Role for Moodle.org Hub Directory (private token)

  • moodle/hub:viewinfo for getting hub information
  • moodle/hub:view for getting course information
  • moodle/hub:confirmhubregistration confirm the registration

Required community hub web services

We will have one hidden service per role. Following their name:

Moodle.org Hub list

the following service will exist only on Moodle.org Hub directory

"Hub directory public site":

  • global search function

"Hub directory hub server":

  • update info function

Hub server

the following services will exist on any Moodle site (but disabled till a first token is linked to it)

"Public site":

  • course searches function
  • rating a course function
  • commenting a course function
  • downloading a course template function

"Registered site"

  • course searches function
  • rating a course function
  • commenting a course function
  • downloading a course template function
  • publishing a course template function
  • update info function

"Hub directory"

  • getting hub information function
  • getting course information function
  • confirm the hub registration function

Required users for community hub web services

Moodle.org Hub list

A user is be linked to one role only and one service only

"Public sites": they all use the same public_directory_user user.

  • His role is 'Public Directory User'
  • His service is 'Hub directory public site'

"Hub servers": they all have their own $huburl."_directory_hub_user" user.

  • Their role is 'Directory user'
  • Their service is 'Hub directory hub server'

Hub server

"Public sites": they all use the same 'public_hub_user' user.

  • His role is 'Public Hub User'
  • His service is 'Public site'

"Registered sites": they all have their own $siteurl.'_registered_site_user' user.

  • Their role is 'Registered Hub User'.
  • Their service is 'Registered site'.

"Hub directory": they use their own $hubdirectoryurl.'_directory_user' (in case the hub directory change his url)

  • Their role is 'Moodle.org Hub Directory'.
  • Their service is 'Hub directory'.

See also