Google Calendar Contrib Tool
The Sakai Google Calendar Contrib tool allows instructors to add automatically create a google calendar that's shared with all users of a Sakai course site. This requires that an institution leverages Google Apps For Education for their collaboration, enterprise environment (e.g. email and calendar). For more information, see http://www.google.com/enterprise/index.html
If the sakai user has a google account (corresponding to their email address), they will be able to view this google calendar directly from https://www.google.com/calendar . Otherwise they can only view events from within Sakai. Eventually, we will be integrating this tool with Assignments, and possibly other tools.
Creating a new event:
Sakai Google Calendar Week View:
Sakai Google Calendar Month View:
Google Calendar View:
- Source Code https://source.sakaiproject.org/contrib/umich/google/gcalendar/
- Tech Details: README.txt
- Google Service Accounts Console
- Google OAuth Documentation: https://developers.google.com/accounts/docs/OAuth2ServiceAccount#libraries
Google Authorization Configuration
- Service Account Creation:
- Create a Google account for Sakai admin
- Go to Services in Google Console (https://code.google.com/apis/console), and enable Calendar API
- Create Service Account in Google Console for Sakai admin user, by going to API Access
- Click "Create another client ID", select "Service account", click "Create client ID"
- Download the private key and save it in a secure place.
- Configure Google Apps for education to trust the Service account created above, and define the scope of access. Related documentation is at http://support.google.com/a/bin/answer.py?hl=en&answer=162106. This will give the service account the power to become any user of Google Apps for education domain, without user's input.
Google Calendar creation and adding users and their permissions is done through java calls to the Google Calendar API.
Every Google Calendar request requires authorization before it is completed. We are using OAuth 2.0 to authorize our requests. Two fields in the sakai.properties file must be set to get the proper OAuth token:
The private key currently resides in the fully qualified filename defined by the google.private.key property (e.g. /usr/local/tomcat/sakai/google.p12).. This authorization token is passed as part of the calls to the Google Calendar API. See the section in the README.txt files on Service Account Creation for more information on creating or obtaining the private key.
Sakai permissions, gcal.*, control whether the user can just see the events or whether they can add, modify or create events. Sakai permissions are mapped to Google Calendar permissions in the following way:
- gcal.view - view as free or busy and cannot create events
- gcal.view.all - view details and cannot create events
- gcal.edit - can edit, create, delete events
- realm.edit - administrator access (can share calendar implicitly by updating realm membership)
Sakai admin users and users without google accounts have gcal.view access by default, but only within the Sakai gcalendar tool.
The Permission button is available for users with the site.upd.site.mbrshp role. When this button is pressed, the permission matrix for the GCalendar tool is displayed.
Sakai permissions are stored as a user preference (in the sakai database). Each time the user signs on, the current gcal permission for their role is checked against the permissions in the database. If the permissions is different, the permissions in Google are updated. This is accomplished by using the Google Calendar API to set the access control list (acl) for the user in the Google Calendar.
Flow for creating a new Calendar: When you add the GCalendar tool, the Google Calendar is created and the “owner” is set to the person creating the calendar. This is all server side processing. Users are NOT added to the access control list (acl) for the calendar (based on Sakai permissions) at this time. Permissions for a user are added when the user first accesses the GCalendar tool in a site..
Flow for setting permissions for a user: When the user accesses the GCalendar tool, their current permissions are compared to their previous GCalendar permissions. If they do not have any GCalendar permissions in Sakai, then their role-based permissions are stored as Sakai user preferences, and sent to Google. If their GCalendar permissions are the same, then they continue processing. If their GCalendar permissions are different, then the Sakai user preferences and Google are updated with the new permissions. It is intentional that there is no way to remove a user from a Google calendar from the Sakai GCalendar tool. Once they have been added to the Google calendar, the administrator of the calendar will need to remove (unshare) them from the Google Calendar Settings user interface.
Flow for displaying a Google Calendar : When a user, with edit permissions, selects an event they are taken to a Google Calendar event dialog where they can edit or delete the selected event. They can press the return button and go into the regular calendar view and edit or remove other events. If a user has View Details permissions, they are taken to the Google Calendar event dialog that only allows the user to see the details of the event, but are not allowed to change the event. If the user has only View permissions, then the user can only see the events on a calendar as “busy” and they can not add or update an event.
- Google calendar API documentation: https://developers.google.com/google-apps/calendar/
- FullCalendar documentation: http://arshaw.com/fullcalendar/
This implementation of a Google Calendar integration uses the philosophy, except for the dialog for creating and event, to use the existing Google Calendar dialog boxes when available. This reduces the complexity of the dialog boxes within Sakai.
When a user selects an event from within Sakai and is taken to the Google Calendar, if the corresponding calendar is not open in Google, the user can not delete the event. The delete button looks like it is being pressed, but nothing happens. The user can select the “Back to Calendar” button, open the calendar and delete the event from there. If the Google calendar is open in Google, the event will be deleted.
Within the Google Calendar Settings user interface, the “Share this calendar with others” check-boxes and associated permissions override the “Share with specific people” permissions at setting the users minimum permissions. For instance, when the “Share this calendar with others” permissions for the domain are set to “See all events”, each user in the “Share with specific people” will have this permission level as a MINIMUM and will see all events even though their permission setting is “See only free/busy (hide details)”.
When a GCalendar is deleted from within Sakai, the corresponding Google Calendar is not deleted. The administrator must do it manually from with Google. This is intentional by design.
The gcal.view permission is required for the GCalendar Tool to be displayed within Sakai. Other permissions may be set, but gcal.view controls whether or not the GCalendar tool is available for a particular calendar. It is a good idea to set gcal.view in the templates so that when sites are created, the Google Calendar tool is enabled.
The GCalendar tool explicitly sets the summary, description, and location fields for each event to “busy” if the user only has gcal.view permission. There is no event information returned by the Google API for these fields when the effective Google permission is set to “See only free/busy (hide details)”.
Google Calendars are created for the google account of the site owner. If the site owner does not have a valid google account, then the calendar cannot be created.
When Sakai-based GCalendar permissions are changed, the users will retain their original permissions in Google until they select the corresponding GCalendar from within Sakai. Their new Google permissions will then be updated.
If a user is logged into another Google account within the same browser session, the dialog boxes for Google will use the other accounts credentials and therefore its permissions for accessing the Google Calendar.
Changes to the Google calendar permissions through Sakai will not immediately be reflected in the Google calendar. If the user already has an active session in the Google calendar when the change is made, the permission changes will not become active until the user logs out of the Google calendar and then logs back in.
If a Google Calendar is removed through the Google UI, the following steps must be taken in order to add it back to the Sakai Course/Project Site:
- Delete tool from site
- Using the Admin Sites tool, remove the 'gcalid' property
- Add tool back as you would normally, and the google calendar will be re-created and re-associated with the Sakai Course/Project site.
If the owner of the Google Calendar "unsubscribes" from the calendar within the Google UI, the calendar will still exist, in an odd invisible state. Other users can view/edit, and the original creator can view/edit within Sakai, but not within Google. The resolution requires another user (with google edit/share permission) to remove and add back in the original owner of the calendar.
If a user adds the Google calendar to a site and immediately goes to the Assignments tool to "Add due date to schedule", the event will not be added to the Google calendar as the calendar will not yet be created. The calendar is only created in Google when the user accesses the Google calendar tool for the first time.