Spec: Activity Stream Notifications

We want both on-site notification (bubble in top-right of site that tells you how many new activities you have) and email notification of new activities in your dashboard activity stream.

Question: How should email notifications and on-site notifications interact, in terms of which activities are considered seen or unseen?

• If the user has viewed her activity stream on the site then we know that she has seen the activities and it would be annoying if we then sent her a notification email about them.

• But if we have sent an email notification for an activity we do not know if the user has received and read the email so we might not want to mark the activity as seen on the site.

Suggested solution:

• Viewing your activity stream on the site automatically marks all of your activities as "seen" (you do not have to click a "mark as read" button)
• If activities have been marked as seen by viewing them on the site, then email notifications of those activities will not be sent
• But, sending an email notification for an activity does not mark the activity as seen on the site, when the user logs in to the site it will still say that she has unseen activities, she has to view her activity stream to mark them as seen (but the email will contain a link directly to the page with the activity stream, clicking the link will automatically mark the activities as seen)
• If CKAN has sent an email notification for an activity it will not send another notification for the same activity, even if the user has not logged in and looked at her dashboard so the activity is still marked as unseen on the site. The reason is that it might be annoying if CKAN kept sending repeated notifications for the same activities.

This means that behind the scenes we need two separate concepts, seen/unseen activities for the on-site notification and unsent activity notifications for the email notification. Viewing your activity stream on the site marks all of your activities as seen and deletes any unsent activity notifications that were waiting to be sent by email, without sending them. Sending an email notification for some activities deletes them from the unsent notifications queue but does not mark them as seen.

On-Site Notifications

We want to add a "bubble" to the top-right of the site when logged in, that shows the number of "unseen" (or "new") activities you have in your dashboard activity stream.

The main problem with implementing this is that there is currently no concept of "seen" and "unseen" activity streams in the model.

We need to record the seen/unseen status of an activity on a per-user basis, the same activity may be seen by some users and unseen by others, so a simple boolean seen/unseen column on the activity streams table is not an option.

Suggested solution:

• Add a datetime column to the user model, recording the time they last looked at their dashboard activity stream.

• Add a logic/action/get.py function num_unseen_activities(), returns the number of unseen activities in a user's dashboard by looking for activities newer than the time the user last viewed her dashboard.

• Add a logic/action/update.py function that updates the time that the user last viewed her dashboard. When email notifications have been implemented, this function should also delete any unsent notifications.

• Then we just need to add the frontend for it.

Email Notifications

We want to add email notifications of activity stream activities, so that users can receive an email from CKAN when they have new activities in their activity stream, rather than having to login to the site to see this.

There also has to be a user preference that turns the email notifications off. Suggest a simple on/off setting nothing more complicated. This probably requires adding a field to the user model to save the setting. The emails should contain a link to this preferences page.

Add a notifications_outbox database table and model class.

• The create_activity() logic action function and the activity streams session extension need to add rows to the notifications outbox (these are the only two places where new activities are created). Add one row to the table per activity.
• What columns should the unsent_notifications table have? user (id or name of the user to notify), type (the type of notification e.g. activity stream, determines what notification renderer is used to render the email body), content

Add a notification mailer job that consumes rows from the outbox table and emails them:

• After an email is sent successfully, the rows are deleted from the outbox table.
• Implement the mailer job as a paster command, and have a cron job call it.
• The notification mailer can then be reused for sending notifications about other things besides activity streams.
• Don't send one mail per activity, instead send multiple activities in one mail. Each time the mailer job runs it will send at most one email per user. The mailer job will group all rows from the notification table that have the same user into a single email.
• The maximum frequency of emails can be configured by the site admin by setting how often the cron job runs.
• The mailer job should check if the user has email notifications turned off, if she does just delete all her rows from the unsent notifications table without sending anything.

CKAN already has a Mailer class that sends emails e.g. for password resets, organization application emails, see:

• ckan/controllers/user.py
• ckan/tests/lib/test_mailer.py
• ckan/tests/mock_mail_server.py
• ckan/tests/misc/test_mock_mail_server.py
• ckan/tests/functional/test_user.py