[[TOC]]

= BOINC Notification System =

As the number of projects increase it becomes increasingly difficult for volunteers to keep track of any relevant news a project publishes.  Volunteers may only check project websites once in a blue moon.  A system is needed to keep the volunteers engaged with a project.

When we talk about volunteers in regards to this feature we are actually talking about three different types of volunteers:
 * A volunteer who attaches to a project but doesn’t participate in the forums.
 * A volunteer who attaches to a project and participates in the forums.
 * A volunteer who attaches to a project and becomes involved enough with the project that they begin to help the project with support issues.

The volunteer should be in control of how much information is going to be exposed to them by way of the notification system.

The rest of this document will describe how the notification system will work.

== Notifications Supported ==
Clients that support the BOINC Notification System should include the following flag in the scheduler request:
{{{
<notifications_supported />
}}}

When the BOINC Server scheduler sees this flag it’ll include extra information in the scheduler reply that is to be included in the BOINC Client Feed stream and a list of feeds the client should be monitoring.

== BOINC Action Feed ==
The BOINC Action feed stream is a special in memory RSS feed the BOINC Client software maintains for informing the volunteer about various conditions.

Events that would be added to the stream would be low disk space issues, low memory issues, missing resources like GPUs, and anything else that cannot automatically be taken care of.

Items in the feed can be generated by the BOINC Server Scheduler or the BOINC Client itself.

== Feeds ==

When a volunteer attaches to a project, one or more notification feeds become available to them.  These feeds are published using the [http://www.rssboard.org/rss-2-0 RSS 2.00 specification].

Example feeds a project may wish to expose are:
 * Project news ({{{http://<project_url>/rss_main.php}}})
 * Project personalization feed (welcome message, useful links, milestones)
 * Scientist blogs
 * Administrator blogs
 * Private Messages
 * Forum threads that a volunteer is monitoring
 * A whole forum to answer questions or to deal with problems as they arise.

=== Request ===

Example:
{{{
http://www.example.com/rss_main.php
http://www.example.com/forum_pm_rss.php?auth=4ebd3e5fd8a88f48ed708f04f81fefb7
http://www.example.com/forum_pm_rss.php?auth=4ebd3e5fd8a88f48ed708f04f81fefb7&guid=blah&action=read
}}}

Parameter table:
|| Parameter || Default Value || Meaning ||
|| auth || <null> || Authenticator of the volunteer requesting the feed data. NOTE: For private feeds no information should be provided without the full authenticator. Weak authenticators should be treated as though no authenticator has been provided.||
|| last_guid || <null> || The last guid received by the client.||
|| guid || <null> || The GUID in which an action should be preformed on. ||
|| action || <null> || Which action should be recorded. (Read, Deleted) ||

=== Response ===

Example:
{{{
<channel>
    <item>
        <description>I need more disk space</description>
        <pubDate>Mon, 30 Sep 2002 01:56:02 GMT</pubDate>
        <guid>http://www.example.com/1</guid>
    </item>
    <item>
        <description>I need more memory ({1})</description>
        <pubDate>Sun, 29 Sep 2002 19:59:01 GMT</pubDate>
        <guid>http://www.example.com/2</guid>
        <param_1>64</param_1>
    </item>
</channel>
}}}

Property table:
|| Attribute || Default value || Meaning ||
|| description || <null> || An xml encoded message that the volunteer needs to act on ||
|| pubDate || <scheduler reply time> || RFC 822 representation of the scheduler reply time ||
|| guid || <null> || Unique message ID prefixed with the master URL of the project ||
|| param_1 || <null> || Optional parameter for the item description ||
|| param_2 || <null> || Optional parameter for the item description ||
|| param_3 || <null> || Optional parameter for the item description ||
|| param_4 || <null> || Optional parameter for the item description ||
|| param_5 || <null> || Optional parameter for the item description ||

'''NOTE''': While on face value the inclusion of the GUID to the client software might seem overkill, it serves two important purposes.
 * It can be used to prevent duplication messages from the same project from appearing in the user interface across multiple scheduler requests.
 * Provides a mechanism to display localizable server messages within the user interface.

== Feed List ==

The feed list is published to the client software as part of the client parse-able project preferences.

When the client software connects to the server scheduler it’ll receive an updated list of feeds the client should download as well as any special properties about the feed (private feed for example).

Example:
{{{
<notification_feeds>
    <feed>
        <url>http://www.example.com/rss_main.php</url>
        <name>Project News</name>
        <update>86400</update>
    </feed>
    <feed>
        <url>http://www.example.com/forum_pm_rss.php</url>
        <name>Private Messages</name>
        <update>86400</update>
        <private />
    </feed>
</notification_feeds>
}}}

Property table:
|| Attribute || Default Value || Meaning ||
|| url || <null> || The URL to access the feed ||
|| name || <null> || Volunteer friendly name for the feed ||
|| update || 86400 || Number of seconds in between updates ||
|| private || false || Should the authenticator be provided to the feed ||
|| disabled || false || Feed is disabled and the client should not request updates ||
|| disabled_date || <null> || Epoch time in which the feed was disabled.  A month past the date and both the server and client software should delete any relevant information about the feed. ||
|| application_only || false || Feed is used by an application and should not be shown in BOINC Manager or the BOINC Screen saver. ||

== BOINC Server Scheduler ==
The server scheduler is responsible for aggregating the various pieces of information about feeds and pushes the result to the client as part of the scheduler reply.  A similar process is used for the GUI URLs.

General workflow:
 * Issue query to determine of the volunteer has customized their feeds.
 * Read feeds.xml for feed baseline.
 * Merge the results of feeds.xml and the results of the query, with preference given to the volunteer’s selections.

If an empty result set is returned by the database, then pass the contents of feeds.xml unmodified.

=== Scheduler Reply ===
User messages generally contain information the volunteer needs to know such as there isn’t enough disk space allocated to the project to run a task instance, or they weren’t assigned any work because they ran out of quota.

Messages like a project being out of work should not be included in the notification stream.

Where possible, notification messages should contain information on how to correct the problem.

Example:
{{{
<scheduler_reply>
    <notification_feeds>
        ...
    </notification_feeds>
    <channel>
        ...
    <channel>
</scheduler_reply>
}}}

=== Localizing Server Messages ===
Messages being passed to the client by way of the server will now be identified by a message identifier.  

Message identifier rules:
 * Message identifiers start at 1.
 * Message identifiers should not be removed from the message list and cannot be removed if no longer used.
 * Messages should be enclosed in the _("Test Message") macro syntax.
 * Message parameters are enclosed in ‘{}’ braces with an index to the position in which the parameter should replace the marker.

When new messages are added poEdit or some other string extraction tool should be used to update the BOINC-Server-Messages.pot template file.  After the localization process has been completed the resulting BOINC-Server-Messages.mo file should be shipped with the client software.

A string in need of localization would look like this:
{{{
_("This client needs {1} of additional memory. {2} detected in total.")
}}}

After translation it could look like this:
{{{
_("Your computer has {2} of total detected memory, but the client needs an additional {1} in order to be assigned work.")
}}}

The client software should replace the positional markers with the optional parameter values specified for the message.

== BOINC Project Website ==
A project’s website is the main focal point for adding and removing notification feeds.

Each forum and each thread should have a ‘notify me’ button that’ll add an entry to the notification list in the project preferences for the volunteer.

A new entry in the Preferences section of the Your Account area will be created to manage all the feeds a volunteer is currently subscribed to.

This new section should allow the volunteer to change the refresh rate for any feed they want to be notified about.  It should also allow them to disable any feed.

== BOINC Core Client ==

=== GUI RPCs ===

==== get_feeds() ====
Enumerates all the feeds for a given project as well as provides the properties for a given feed.

Parameters:
|| Parameter || Type || Meaning ||
|| project_url || string || Specify which project should the feed metadata be returned for. ||

'''Notes''':
 * This RPC should not require authentication.
 * If project_url is empty an error should be returned.


==== get_feed() ====
Enumerates all the feed items for a given feed as well as provides the properties for a given feed item.

Parameters:
|| Parameter || Type || Meaning ||
|| project_url || string || Specify which project should the feed metadata be returned for. ||
|| feed_url || string || Specify which feed should the feed items be returned for. ||

'''Notes''':
 * If both project_url and feed_url are empty, the BOINC Action Feed stream is returned.
 * Requests for private feeds should return an error.
 * This RPC should not require authentication.


==== get_private_feed() ====
Enumerates all the feed items for a given feed as well as provides the properties for a given feed item.

Parameters:
|| Parameter || Type || Meaning ||
|| project_url || string || Specify which project should the feed metadata be returned for. ||
|| feed_url || string || Specify which feed should the feed items be returned for. ||

'''Notes''':
 * This RPC requires authentication.


==== set_feed_item_option() ====
Sets a given property for a specific feed item.

Parameters:
|| Parameter || Type || Meaning ||
|| project_url || string || Specify which project should the feed metadata be returned for. ||
|| feed_url || string || Specify which feed should the feed items be returned for. ||
|| guid || string || Specify which feed item should be changed. ||
|| read || bool || Item has been read. ||
|| deleted || bool || Item has been deleted. ||

'''Notes''':
 * This RPC requires authentication.

== BOINC Manager ==

== BOINC Screensaver ==