Email Alerts Design (post-launch)

WARNING: This page is not relevant to launch. See AlertsImplementaiton for launch information.

Launch Requirements

  • Weekly email alerts on categories

Mid-Term Requirements / Design

  • Weekly, Daily or real-time checks on things user is interested in
  • Definitions:
    • Category: Articles will be posted into multiple categories.
    • Author: It is probably interesting to watch specific other users.
    • Group: A collection of authors (or categories?)
  • Interests expressed as:
    • New/changed articles by category/author/group
    • New/changed annotations to an article/category/author/group
  • Alert Specification: (Need to eval yahoo/google features)
    • Keep it simple -- no complex queries
    • 1+ Categories on new and/or changed articles and/or annotations
    • 1+ Authors (a group) on new and/or changed articles and/or annotations
    • 1+ Articles on changes and/or new/changed annotations
  • Configuration
    • Maximum number of alerts per user/email-address
    • Frequency to send email (weekly, daily, hourly, real-time)
    • Max number of items and/or max number of days to keep per-rss
  • Per-alert Preferences
    • html or plain
    • digest option
  • Per-user Preferences
    • digest-all option
  • Per-alert Storage
    • Alert Description (search specification)
    • Alert Preferences
    • List of content already found (but not expired yet)
  • Alerts based on search-term in full-text of article abstracts

Future Requirements

  • Alerts based on search-term in full-text of anything
  • Near Real-time alerts

Existing alert models

Most of these imply real-time alerts, not batched.

Implementation

We will model the trac-timeline view (http://gandalf.topazproject.org/trac/timeline). Thus, there will be a web-service for inserting events into our timeline. These events will be persisted to Fedora and in the web-service's memory (for faster access when generating alerts). The web-service will also store the list of email addresses with their alert preferences (in Fedora and in memory). On a scheduler, alert emails will be generated. The last time the user was alerted will be updated. Events will be purged after N days.

We will also provide an API for searching the timeline in real-time. This will facilitate things like RSS feeds and web UIs like the trac-timeline.

Object Model

  • Alert
    • String emailAddresses[]
    • ContentAction? actions[] empty means all
    • ContentKind? kinds[] empty means all
    • ContentSpec? spec Null means all
    • String specNames[] what are we searching on
    • String fullText for future use - Null means find-all
    • boolean html
    • boolean digest
    • boolean enabled bounces will disable
    • int lastUpdate seconds since epoch
  • Event
    • int timestamp
    • String categories[]
    • String author Is owner author?
    • String groups[]
    • String contentDoi Ties us to specific article if kind=ARTICLE
    • ContentKind? kind
    • ContentAction? action
    • String summary abstract - stuff to full-text index

API

void setAlert(String emailAddresses[], ContentAction actions[], ContentKind kind,
              ContentSpec spec, String SpecNames[], String fullText = Null,
              boolean html = False, boolean digest = True)
    throws NotImplemented
void delAlert(String emailAddresses[], ContentAction actions[], ContentKind kind,
              ContentSpec spec, String kindNames[], String fullText = Null)
    throws DoesntExist
void addEvent(String categories[], String author, String groups[], String contentDoi,
              ContentKind kind, ContentAction action, String summary,
              int timestamp = 0)

Much of this API will throw NotImplemented? if called during launch. In that timeframe, we will only support alerts on new articles into categories in plain-text generated on a weekly basis.

Questions

  • Should owner and groups be strings, ints or some other referential type?
  • Is there a difference between an author and an owner?
    • My supposition is that articles will be ingested by entities other than their owners. In that case, we need to understand how to distinguish for purposes here.

Alert Format

Current PLoS alert emails provide a reasonable template for PLoS One alerts.

  • General email
    • Info on how to get support
    • Link to RSS equivalent (reasonably short URL)
    • Banner with web-like navigation (current PLOS mail has this, HTML only)
    • Footer graphics (HTML only)
    • Links to change alert preferences
  • Per Article
    • Title of article (including sub-title) - may wrap lines
    • Entire list of authors
    • Link to article (must be reasonably short URL for text-based emails)
    • Link to PDF view of article (only in HTML version of an alert)
  • Additional suggestions
    • Though not a mailing-list, should consider having RFC2369 mailing list controls
    • Google alerts on the same content provide a mini-abstract (using some heuristic). We should be able to do better?
    • Simple alert management links:
      • Remove this alert
      • Create another alert
      • Manage your alerts

Attachments