Skip to content

Spec: Activity Stream Notifications

Jump to bottom
seanh edited this page Oct 22, 2012 · 7 revisions

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
  • 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.

Add a notifications_outbox database table and model class.

Add a notification mailer job that consumes rows from this table and emails them.

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.

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).

Don't send one mail per activity, instead send multiple activities in one mail, max e.g. one mail per day. This should be configurable. Grouping of notifications should be handled by the mailer job.

In the web UI there needs to be a checkbox where people can turn off email notifications. The emails themselves should have a link to this page.
Maybe also a way for sysadmins to enable/disable emails for people.

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

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
  • group: a string field used for grouping emails

The group field is used for grouping emails. For example when the mailer job runs, e.g. once per day, it will send all notifications with the same user and group in one email. So we can have activity stream notifications always get sent together in digest emails, but other types of notifications sent in separate emails.

Does grouping overlap with grouping activities in the web UI?
Seems like two different things.

The 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.

Clone this wiki locally