Proposals/Notification Feeds

Mahara will expose user notifications through Atom feeds.

Contents

Each feed will be specific to a single user and will expose notifications for all activity types defined in the activity_type table:

• maharamessage: system messages sent by Mahara (usually in response to a user action)
• usermessage: private message sent by another Mahara user
• watchlist: one of the pages you watch has changed
• viewaccess: you have been added to the access list for a page
• contactus: someone sent a message via the contact us feature (admins only)
• objectionable: someone reported a page as objectionable (admins only)
• virusrepeat: someone has repeatedly uploaded infected files (admins only)
• virusrelease: currently unused
• institutionmessage: institution-related messages such as invitations or requests to join
• groupmessage: system messages sent to the members of a group (usually in response to a user or admin action)
• feedback: someone left feedback on one of your pages
• newpost: a new forum post was made

The Atom feed will follow the Activity Streams 1.0 specification as much as possible (not all of the necessary information may be available in Mahara).

Authentication

Authentication is handled through a shared secret between Mahara and the consuming application. There are two types of tokens:

• user token: only gives access to a single user's notifications (meant to be used by that user only)
• system token: gives access to the notifications of any user on the Mahara site (to be used by trusted third-parties)

Both types of tokens can be invalidated and re-generated by individual users (in the case of a user token) or admins (for system tokens).

There is only one user token per user account, but there can be as many system tokens as needed.

User interface

System Feeds

System feeds can be added by site administrators using a new tab in the Site administration area: Configure Site | System Feeds

That page will consist of a list of existing tokens as well as a form to add a new token.

The listing will be sorted by audience and contain these columns:

• audience
• token
• last used
• delete link

The form will contain a single field:

• audience: mandatory text description of the consumer that will use this token

since Mahara will take care of generating a random 64-character token.

User Feeds

Users can find the current URL (including the token as a query string parameter) to their notifications feed on their own Notifications page (/account/activity/preferences/) in a new section at the bottom of this page.

They can click a button to generate a new URL (which deletes the existing token and re-generates a new random one).

Users have at most one user feed and they cannot remove it.

The initial token is generated the first time that the notifications page is displayed for that user.

Web API

Consumers of this API will issue a GET command to a new page at /api/atom/user_notifications.php which requires the following query string parameters:

• token: a secret shared between Mahara and the consumer which authorizes the consumer to get access to a user's notifications
• user: only needed when using a system token where a consumer needs to specify the user for whom notifications are requested
• types: an optional comma-separated list of the activity types that should be in the feed (empty or missing parameter means "all of them")

The response will be:

• application/atom+xml: Atom feed in the normal case (HTTP 200)
• text/plain: text-based error message in the case of errors (HTTP 403 - for bad tokens, 404 - for non-existent user IDs)

Response headers will instruct clients to cache the data for an hour.

DB schema

A new table will be created, notification_feed, and it will contain the following columns:

• id: unique numerical identifier (primary key)
• usr: the user to which this token belongs (or NULL for a system-wide token)
• token: a UNIQUE string of 64 characters (e.g. pwgen -s 64)
• audience: an optional text comment (max 255 characters) describing the audience of this token
• atime: the datetime when this token was last used (incremented every time a feed is accessed)

Security

Given that tokens can trivially be sniffed from passing requests, running over HTTPS is strongly recommended.

A warning will be shown in the admin homepage if any system tokens are defined on an HTTP site.