View source for Community hub - technical specification

{{Template:WillNotMigrate}}

{{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 :
{| class="wikitable"
|-
! 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:

{| class="wikitable"
|-
! 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.
{| class="wikitable"
|-
! 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 ===
# the hub admin goes on hub settings page => settings are saved with set_config
# the hub admin presses register and is redirected to the hub directory registration page. This redirection has the token used by the hub directory. 
# the hub admin enters a recaptcha on the hub directory registration page. It is mandatory to avoid people to write script automatically registering.
# 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 ===
# the hub admin changes the settings.
# the hub admin presses update registration.
# 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 [http://moodle.org/stats general statistics] and the listing of [http://moodle.org/sites registered sites]:
{| class="wikitable"
|-
! 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) [http://cvs.moodle.org/moodle/lang/en_utf8/countries.php?view=markup lang/XX_utf8/countries.php]
|-
|regioncode
|varchar
|region code ISO 3166-2  [http://www.commondatahub.com/live/geography/state_province_region/iso_3166_2_state_codes 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:

{| class="wikitable"
|-
! 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
|Audience:  Educators | Students | Admin
|-
|educationallevel
|varchar
|Educational level being discussed (for educators audience only):  Tertiary | Secondary | Primary | Government | Corporate | Association | Other
|-
|coursemapid
|varchar
|Is a course map supplied?   (Simple XML description of course structure, could be rendered graphically later [http://kn.open.ac.uk/public/workspace.cfm?wpid=8690 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) [http://en.wikipedia.org/wiki/ISO_4217 ISO 4217]
|-
|enrolcostcurrency
|varchar
|
|-
|downloadcost
|int
|Download Cost (and currency) [http://en.wikipedia.org/wiki/ISO_4217 ISO 4217]
|-
|downloadcostcurrency
|varchar
|
|}

 Dublin Core Metadata Element Set, Version 1.1
*# Contributor - course manager names or whoever the publisher nominates
*# Coverage - User tags
*# Creator - main teacher name or copyright holder or whoever the publisher nominates
*# Date - date this was last published/updated
*# Description - course description
*# Format - zip / url
*# Identifier - course shortname (unique on the original site)
*# Language - based on lang.php
*# Publisher - the name of the person who caused this record to be entered here
*# Relation - the site id that it came from
*# Rights - one of a standard set of open source, creative commons and other licenses
*# Source - original URL of the course
*# Subject - The best-matching item from ([[Standard Classification of Educational Fields]])
*# Title - Course fullname
*# Type - "course" (later there might other types such as activities or SCORM packages etc)

TODO:
*# 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 ==
[[Image:Hubdirectory_moodleorg2hubserver_moodle.org.png|900x950px]]

== Moodle site and Moodle.org Hub directory ==
[[Image:Moodlesite2moodleorg.png|900x950px]]

= 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 ==
#The hub creates a specific ws user, a specific ws role, a specific ws service and a specific token. 
#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==
* [https://docs.moodle.org/en/Community_hub Community hub]
* [https://docs.moodle.org/en/Development:Community_hub Development: community hub project specification]

[[Category:Hub]]