Google Collaborative Activity Technical Specification
Overview/approach/rationale
The Google collaborative activity is to be a Moodle module that enables collaboration
between groups of students on a shared document. All of the user interactions with
the document take place within Google Apps; the key purpose of this activity module
is to initiate the creation and sharing of the document with the correct users.
This module would provide very similar functionality to a wiki; however, unlike a wiki,
Google collaborative activities are not recommended for assessment purposes as
individual contribution cannot be determined.
The activity has the following features:
 Administration – activity setup and document template select
 Sharing – create document(s) and share with users
 View – show user the collaborative document
The key feature of the activity is the sharing of a document with a group of students
and the administration of that document by tutors and staff. This functionality is not
currently possible using Google Apps alone as only tutor student allocation (TSA)
groups are being added to the system and functional multi-user accounts are not
possible (due to single-sign-on).
This functionality is possible due to the support of API access to documents in a
Google Apps domain. Therefore, this activity will only be able available to users that
have a Google account within an (OU) Google Apps domain, personal Google
accounts cannot be supported. Providing a Google Docs API key gives access to all
documents in the domain; for security purposes this key will be stored in a
configuration setting not in code and as such will not be available to developers (for
development and testing purposes an API key for the sandbox domain should be
used).
Using the Google Docs API at a domain level requires authentication through the use
of the OAuth protocol. This is only supported in the latest version (3) of the Google
Docs API which is currently in beta (‘Labs’). It is not expected that this area of the
API will change, however this will need to be monitored closely. There is not a client
library available for this version of the API; as such a large part of the development of
this module will encompass the creation of a code library to connect to the Google
Docs API utilising OAuth.
At present it is unclear if staff (including tutors) will be able to be added to the OU
Google Apps domain (or even if they are if this will be widespread). Therefore this
activity will attempt to overcome this issue by:
1. Providing a view of the collaborative documents to staff (who have a tutor or
administrative role within the course). This could also be used to show a view
of the documents to students who have not signed-up for a Google account
(take-up is not compulsory).
2. Providing administrative functions for the Google documents associated with
the activity e.g. deleting or sharing with a specified individual (at present only
sharing within the domain is permitted).
Structure
This activity should be in the form of a Moodle module and as such will not need to
customise any core code. The module identifier should be ‘googlecollab’, the folder
and all appropriate areas of code should use this name.
All functions that interact with the Google API directly should reside in a separate
library that can be easily re-used by other plugins. Suggest that this sits in its own
local plugin (called googleappslib).
Config/DB/Capabilities
Expected config settings for googleappslib plugin:
 API consumer key (local_googleappslib_consumerkey)
 API consumer secret (local_googleappslib_secret)
 Gapps domain name (local_googleappslib_domain)
 GApps domain admin user name (local_googleappslib_domainadmin)
 GApps user name (local_googleappslib_userfield; username (default) or
email) – user either Moodle user name @ Gapps domain or Moodle user
email.
Expected settings for the collaborative activity:
 Global document owner (full account name inc domain) (googlecollab_owner)
Capabilities for the module are:
 View activity document(s) (mod/googlecollab:viewdoc). Enables the read-only
view of a document if user does not have access via Goggle. Everyone
should have this.
 Moderate activity (mod/googlecollab:moderate). Tutors should have this
capability.
 View separate groups (mod/googlecollab:viewall). Show groups as visible
even when separate group mode used. Staff (and possibly tutors) should
have this capability.
 Administer documents (mod/googlecollab:manage). Enables control over
documents stored in Google. Staff should have this capability.
The following information will need to be stored in the database:
 Module instance and associated settings.
 Records of the documents created by the module in Google Docs.
Table: googlecollab
Field name
Data type
Id [PKEY]
bigserial
Course [FKEY] bigint
name
Charvar (255)
intro
text
introformat
smallint
timecreated
bigint
timemodified
bigint
templates
text
Description
ID of the module instance
Course ID of the course the instance sits in
Name of the module instance
Description text
The type of text used in description (html/plain)
Unix timestamp
Unix timestamp
Template files used in this activity and groups
they relate to – Need to work out how to store
this: serialised array?
Table: googlecollab_docs
Field name
Id [PKEY]
Actid [FKEY]
Data type
bigserial
bigserial
docid
Group [FKEY]
text
bigserial
timecreated
bigint
Description
Primary key
ID of the module instance the doc
belongs to
The document id in Google Apps
ID of the group that the document
belongs to – or 0 if none.
Unix timestamp
Functionality
Administration
Standard Moodle module settings will be available including a description for the
module instance that will be displayed in the main view page.
Module specific settings are:
 Template document (file) – Upload a Word document to be used for the
document template. Need to try and support individual documents for each
group or grouping (if enabled).
The module will also need to work with standard Moodle settings such as Groups,
Conditional access and completion tracking as well as standard Moodle features
such as backup and restore.
It is not expected that this module will need to work with Gradebook.
These feature compatibilities will need to be set using the ‘supports’ function in the
module lib.
Groups
The module should support the use of groups and grouping.
Mode
No groups
Separate groups
Visible groups
Grouping
Action
One document is used for all users. A single template document
is supported.
A document is used for each group. A single template document
can be used for all groups or an individual template for each
group (these would need to be defined). Users can only see the
document for the group they belong to. (mod/googlecollab:viewall
will allow for the read-only view of other group documents as per
Visible groups mode)
A document is used for each group. A single template document
can be used for all groups or an individual template for each
group (these would need to be defined). Users can see all the
other documents (view-only). This is via a drop-down select menu
that lists all of the groups.
Effectively merges all of the groups listed in the grouping and
treats them as one group with one document.
Student view
On entering the main page for the module (view.php) checks should be made against
the role the user has on the course and the group mode set. If the user has no role
on the course then they should not be able to see the activity contents.
No group mode set:
1. Check is made against database for document record.
2. If no record exists the document is created (from template if set). If an error
occurs then the process is halted. Give user option to try again.
3. An attempt is then made to add the current user to the document’s sharing list
as a writer. (Assumption that user can be added again if already on list)
4. If the sharing is seen as being successful (assumption this can be tested
easily) then the Google doc will be shown to the student within an iFrame.
5. If sharing fails then access the sharing list and see if the user’s email address
is on the list, if so go to 4. (Only need to do this if external access to Google
domain is enabled, otherwise unnecessary)
6. If there has been a problem then show a standard message with link on how
to obtain a Google Apps account. Show the document (dependent on
mod/googlecollab:viewdoc) in view-only format e.g. a download of the text
shown on the screen.
Group mode set:
1. Work out what group id the user belongs. If this cannot be determined then
they should not see any document (unless they have capability
mod/googlecollab:viewdoc and either visible group mode is enabled or they
have capability: mod/googlecollab:viewall).
2. Follow No group mode steps as above, but for document specific to group (or
grouping).
As long as the process to add a student to the document sharing list is undertaken on
every access then there should be no issues around giving students access to a
particular document e.g. if they are yet to get a Google account, or have been
recently added to a group.
Tutor view
A tutor will have the mod/googlecollab:moderate capability, this determines whether
the functionality of this view is enabled.
Checks against which document to access are made as in the student view. If no
Google document exists yet for the activity then this should be flagged.
The tutor view differs from the student view in that:
1. Tutors are not added to the sharing list of the document automatically –
therefore actions around this are not required.
2. Tutors see the view-only document by default and should be able to see all
documents in group mode (if mod/googlecollab:viewall capability enabled).
3. Tutors have the option to add themselves to the document sharing list (as
writer role). This will be via a button on the view page. This could be
automated, but by being user-initiated give greater flexibility as tutors can
then view other group activities and can still access the activity if they do not
have (or do not understand how to use) a Google account. The inclusion and
functionality of this feature is dependant on whether tutors will be added to
the Google domain or whether external account sharing is enabled.
4. Tutors will be able to access the Google document via a link on the view
page. This could be two options – direct hyperlink to open in a new window or
link to display within activity in an iFrame.
Staff view
Checks against which document to access are made as in the student view. If no
Google document exists yet for the activity then this should be flagged.
Staff view works the same as student view except:
1. Staff should not be in any of the groups, therefore they will only see the viewonly version of the document(s) if they have the right capabilities.
2. They will see an extra option (possibly tab?) that gives access to the
document management screen if they have the capability
mod/googlecollab:manage. This screen allows the user to delete the activity
documents (individually or collectively - resetting the activity) and to manually
add a user to a document’s sharing list.
Flow diagram showing an overview of view process
Document management
Management of the documents stored in Google Docs occurs:
1. When students access the activity and a document record does not yet exist document creation.
2. When using the document management screen to reset the activity document deletion.
3. When deleting the activity (backup and restore should not deal with Google
documents) – document deletion.
References to the Google documents used in each activity are stored in the
googlecollab_docs table - recording the unique document id for each document.
Documents should be stored in a single account, the user of which is determined
from the googlecollab_owner config setting. In the case of the OU Google Apps
domain, due to single-sign-on, this account would not be accessible via the Google
Apps interface, only via the API. Students as document ‘writers’ will be able to see
the ‘owner’ of the document and as such, to avoid confusion, the account should
have a name that is recognisable as being related to a collaborative activity e.g.
Google-activity@my.open.ac.uk. If possible, this account could have mail forwarding
enabled to allow for any direct communication from students to be intercepted – this
would need to be investigated as a shared-mailbox or similar would be required.
During development and testing the account can be defined as that of an individual
user e.g. developer’s account in the Google domain sandbox.
As the account cannot be accessed directly there is no need to organise the created
documents in any way. However, documents should be named according to the
activity title and module short name so that users can identify the documents easily
once shared with them e.g. .B201-11J – Activity 3.1.
Users with the mod/googlecollab:manage capability will have access to a document
management screen. This screen will list all of the Google documents associated
with the activity. This information is obtained from the googlecollab_docs table, so
only documents that have been created for the activity will be shown. For documents
in this list user will be able to:
 View information for the group the document belongs to (if activity settings
use a group mode).
 Delete a document from Google Docs – this will ‘reset’ the document, useful if
the template or activity title has changed.
 Specify an email address to add to the sharing list – Can add staff etc to
document, they would have to view within Google as view-only document
would always show in activity.
Google Docs connection
All points of connection to the Google Apps Documents List API should take place
within the separate googleappslib local plugin. This code could then be re-used as
required by other modules within Moodle.
There is currently no PHP client library for the latest version of the Google
Documents List API and there is not a Moodle library to connect to Google via OAuth
authentication. Therefore the googleappslib plugin will need to handle all calls and
authentication to the Documents List API.
The plugin will need to support:
 The handling of connection, authorisation and session management.
 Creating a blank document.
 Creating a document from a Word/rtf file.
 Deleting a document.
 Returning contents of document html as string.
 Adding a user to the sharing list.
 Returning a list of users on the document sharing list.
Mobile optimisation
The use of an iFrame to display Google Documents is untested on mobile devices.
Therefore this view, and any other complicated user interfaces, should use a Moodle
custom page layout to display. This could then be overridden by a mobile view theme
to display alternate content if necessary.
Test script
Requirements:
1. User with permission to update a course – to replicate member of OU staff on
a module e.g. have ‘course updater’ role (editing-teacher) on course.
2. Course with two test groups defined (referred to in this test as 1 & 2), residing
within a test grouping.
3. Google collaborative activity and googleappslib configuration settings
correctly set. If these are not already set then this means access to a Google
Apps domain API key/secret and to a Google Apps account in that domain is
required.
4. Test user with student role on course. User should be a member of test group
1. User should also have a Google Apps account in the domain configured in
step 3; this should match either the username (e.g. OUCU) or email specified
for user (depending on configuration in step 3).
5. Test user with tutor (non-editing teacher) role on course. User should be a
member of test group 1. User should also have a Google Apps account in the
domain configured in step 3; this should match either the username (e.g.
OUCU) or email specified for user (depending on configuration in step 3).
6. A Google Collaborative activity added to the test course.
Test standard activity:
1. As the ‘Staff’ user setup the Google Collaborative activity with no group mode
set. Select a Word document to be used as a template for the activity (this
should only contain content known to convert into Google document format;
otherwise information may be lost in the conversion process).
2. Access the activity. You should see a message informing that the document
does not yet exist. You should also see an option to manage the activity
documents. On selecting this option the page should show an empty list of
documents to manage.
3. Access the system as the test tutor user and enter the activity. You should
see a message informing that the document does not yet exist.
4. Access the system as the test student user and enter the activity. You should
see a Google document in an iFrame on the page. It should contain the
contents of the document uploaded as the template.
5. Add content to the document and make sure it has been saved.
6. Access the system as the test tutor user and enter the activity. You should
now see an on-screen representation of the document (with student
contribution).
7. Select the link that adds the tutor to the documents sharing list.
8. Select the link that views the Google document within the activity – you
should then see the activity with the Google document shown within an
iFrame on the page.
9. Access the system as ‘Staff’ user and enter the activity. You should now see
an on-screen representation of the document. Select the option to manage
the activity. You should now see the document within the list on that screen.
10. Select the option to add another user to the document and add the username
of an account on the Google Apps domain. Test the sharing has been
successful. (Only undertake this step if you have access to that account to
verify the sharing)
11. ‘Reset’ the document listed for the activity. On accessing the main activity
page you should be informed that the document is yet to be created.
Test ‘separate groups’ activity:
1. As the ‘Staff’ user setup the Google Collaborative activity with ‘separate’
group mode set. Select a Word document to be used as a template for each
group in the activity (this should only contain content known to convert into
Google document format; otherwise information may be lost in the conversion
process).
2. Access the activity. You should see a message informing that the document
does not yet exist. You should see a drop-down menu listing all of the groups
available to the activity.
You should also see an option to manage the activity documents. On
selecting this option the page should show an empty list of documents to
manage.
3. Access the system as the test tutor user and enter the activity. You should
see a message informing that the document does not yet exist. You should
see a drop-down menu listing all of the groups available to the activity. The
test group the tutor belongs to should be selected.
4. Access the system as the test student user and enter the activity. You should
see a Google document in an iFrame on the page. It should contain the
contents of the document uploaded as the template. You should not be able
to access any other group’s documents.
5. Access the system as the test tutor user and enter the activity. You should
now see an on-screen representation of the document. Selecting to view any
other group’s documents should result in a message being displayed
informing that the document does not exist.
6. Access the system as ‘Staff’ user and enter the activity. You should now see
an on-screen representation of the document (only if the test group is the first
on the list, if not select it to see the document).
7. Select the option to manage the activity. You should now see the document
within the list on that screen, listed against the appropriate group.
Test ‘visible groups’ activity:
1. Follow ‘separate groups’ test but set module settings to ‘separate groups’.
2. All steps should be the same except at step 4 you should be able to access
the other group’s documents as a student (but only view them).