Changes between Version 64 and Version 65 of Notifications


Ignore:
Timestamp:
Dec 13, 2009, 9:54:50 PM (14 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Notifications

    v64 v65  
    11[[TOC]]
    22
    3 = BOINC Notification System =
    4 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.
     3= GUI notices =
    54
    6 When we talk about volunteers in regards to this feature we are actually talking about three different types of volunteers:
    7  * A volunteer who attaches to a project but doesn’t participate in the forums.
    8  * A volunteer who attaches to a project and participates in the forums.
    9  * A volunteer who attaches to a project and becomes involved enough with the project that they begin to help the project with support issues.
     5== Goals ==
    106
    11 The volunteer should be in control of how much information is going to be exposed to them by way of the notification system.
     7The goal is to create a way to notify users of events
     8that either requiring their attention or are likely to interest them.
     9Examples include:
     10 * Conditions in the core client requiring user attention
     11   (messages with mode MSG_USER_ERROR)
     12 * New client version available
     13 * High-priority messages from the scheduler
     14   (e.g., no jobs because too little disk allocated, wrong driver version, etc.)
     15 * Web notifications such as friend request or confirm, private message,
     16   posting to subscribed thread, etc.
     17 * Project news (scientific, credit milestones, etc.)
     18 * An RSS feed specified by the project or the user.
    1219
    13 The rest of this document will describe how the notification system will work.
     20== User interface ==
    1421
    15 == Notifications Supported ==
    16 Clients that support the BOINC Notification System should include the following flag in the scheduler request:
    17 {{{
    18 <notifications_supported />
    19 }}}
     22The Messages tab will be renamed the "Event Log".
     23It will be available via a menu item rather than a tab.
    2024
    21 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 Server Action Feed, defined later, and a list of feeds the client should be monitoring.
     25Notices will be shown in a new Notices tab.
     26They will be displayed in HTML.
     27The 10 most recent notices will be displayed,
     28with a button to show all notices in the last month.
     29Like messages, each will have a timestamp and a project.
     30Buttons will let users filter by project and select notices.
    2231
    23 == Feeds ==
    24 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].
     32When there is a new notice, a balloon appears over the system tray icon for 10 seconds.
     33It will show the type of the notice.
     34Clicking on the balloon will open the Manager in the Notices tab.
    2535
    26 Example feeds a project may wish to expose are:
    27  * Project Notifications
    28  * Scientist blogs
    29  * Administrator blogs
     36The default BOINC screensaver will display new notices.
     37Notices are classified as "private" and "public";
     38e.g., private messages and friend requests are private.
     39The screensaver will show only public messages.
    3040
    31 === Request ===
    32 Example:
    33 {{{
    34 http://www.example.com/notify_rss.php
    35 http://www.example.com/notify_rss.php?auth=4ebd3e5fd8a88f48ed708f04f81fefb7
    36 }}}
     41== Message architecture ==
    3742
    38 Parameter table:
    39 || Parameter || Default Value || Meaning ||
    40 || 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.||
    41 || last_guid || <null> || The last guid received by the client.||
     43Notices are conveyed as time-ordered RSS feeds.
    4244
    43 === Response ===
    44 Example:
    45 {{{
    46 <channel>
    47     <item>
    48         <description>I need more disk space</description>
    49         <pubDate>Mon, 30 Sep 2002 01:56:02 GMT</pubDate>
    50         <guid>http://www.example.com/1</guid>
    51     </item>
    52     <item>
    53         <description>I need more memory ({1})</description>
    54         <pubDate>Sun, 29 Sep 2002 19:59:01 GMT</pubDate>
    55         <guid>http://www.example.com/2</guid>
    56         <boinc_param_1>64</boinc_param_1>
    57     </item>
    58 </channel>
    59 }}}
     45Scheduler replies include a list of URLs to poll for notices.
     46The client polls these URLs and saves the results in files.
     47The client saves scheduler messages and its own messages in files.
    6048
    61 Property table:
    62 || Attribute || Default value || Meaning ||
    63 || description || <null> || An xml encoded message that the volunteer needs to act on ||
    64 || pubDate || <scheduler reply time> || RFC 822 representation of the scheduler reply time ||
    65 || guid || <null> || Unique message ID prefixed with the master URL of the project ||
    66 || boinc_project || <project_friendly_name> || The volunteer friendly name for the project ||
    67 || boinc_param_1 ... boinc_param_x || <null> || Optional parameter(s) for the item description ||
     49Some of the URLs may contain the user's authenticator.
     50In response to a scheduler RPC with a weak authenticator,
     51the scheduler supplies only URLs for public notices,
     52and passes the weak authenticator.
    6853
    69 '''NOTE''': While on face value the inclusion of the GUID to the client software might seem overkill, it serves two important purposes.
    70  * It can be used to prevent duplication messages from the same project from appearing in the user interface across multiple scheduler requests.
    71  * Provides a mechanism to display localizable server messages within the user interface.
     54GUIs (Manager and screensaver) periodically polls the client for new messages
     55via GUI RPC.
     56
     57
     58== Implementation ==
     59
    7260
    7361=== Localization ===
    74 Items being passed to the manager by way of the server scheduler or core client will now be identified by a item identifier.  The item identifier will be appended to the of the project's master url and we used as the item's GUID.
    7562
    76 Item identifier rules:
    77  * Item identifiers start at 1.
    78  * Item identifiers should not be removed from the item list and cannot be removed if no longer used.
    79  * Items should be enclosed in the _("Test Message") macro syntax.
    80  * Item parameters are enclosed in ‘{}’ braces with an index to the position in which the parameter should replace the marker.
     63Strings of the form _(...) in message body are localizable.
    8164
    82 When new items 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.
    8365
    84 A string in need of localization would look like this:
    85 {{{
    86 _("This client needs {1} of additional memory. {2} detected in total.")
    87 }}}
     66=== Feed List ===
    8867
    89 After translation it could look like this:
    90 {{{
    91 _("Your computer has {2} of total detected memory, but the client needs an additional {1} in order to be assigned work.")
    92 }}}
    93 
    94 The client software should replace the positional markers with the optional parameter values specified for the message.
    95 
    96 == Feed List ==
    97 The feed list is published to the client software as part of the client parse-able project preferences.
    98 
    99 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 (application only for example).
    100 
     68Scheduler replies can include a feed list.
    10169Example:
    10270{{{
    … …  
    11684
    11785Property table:
    118 || Attribute || Default Value || Meaning ||
    119 || url || <null> || The URL to access the feed ||
    120 || name || <null> || Volunteer friendly name for the feed ||
    121 || update || 86400 || Number of seconds in between updates ||
    122 || last_update || 0 || The epoch time of the last successful update ||
    123 || application_only || false || Feed is used by the project application and should not be shown in BOINC Manager or the BOINC Screen saver. The contents of the feed should be written to the init_data.xml file in the slot directory before the application is launched.||
     86 update:: Number of seconds in between updates
     87 application_only:: Feed is used by the project application and should not be shown in BOINC Manager or the BOINC Screen saver.
     88   The contents of the feed should be written to the init_data.xml file in the slot directory before the application is launched.
    12489
    125 == Initial Feeds ==
    12690BOINC has several built-in community defining features and feedback mechinisms. The notification system should attempt to reuse as much of it as possible.
    12791
    128 === Project Notifications ===
    129 Project notifications is an umbrella feed which covers several different pieces of information including:
     92=== Default project feed ===
     93
     94This feed generates
     95
    13096 * Project Messages
    13197 * Project News
    … …  
    136102 * Forum Threads
    137103
    138 This functionality is currently implemented using the following link:
     104Other useful messages might be milestones and anniversaries.
     105Either could contain a link to a certificate generated on demand that the volunteer could print out.
     106
     107The URL is:
    139108{{{
    140109http://<project_url>/notify_rss.php
    141110}}}
    142111
    143 The following changes should be made:
    144112
    145  * Each item should belong to one or more categories the client software can use to filter on.
     113=== Categories ===
    146114
    147 '''NOTE:''' This whole feature area should be audited.  I would be surprised if 1% of the volunteer population even uses it, after this whole feature is completed 100% of the active host population will be using it.
    148 
    149 Database queries should be batched and referenced tables should be converted from MyISAM to InnoDB, whole table locks will cause both BOINC clients and the website to stall depending on which operation(s) are in play.
    150 
    151 Preliminary investigation reveals this could be a problem area for us, one query is issued to return all the notifications, and then a new query is issued for each notification to get the details.
    152 
    153 A better strategy, using the same schema, is to issue a feeler query that’ll return hints as to which batch queries to issue.  Each positive hint will cause a new query to be issued that uses a join to merge all notification records of a certain type with the details of that type.
    154 
    155 For instance if a volunteer has 50 private messages the current scheme would result in a minimum of 51 queries issued against the database, the proposed scheme should result in 2 queries against the database. Things get progressively worse the more engaged the volunteer is, 50 private messages and 10 threads being watched would result in 61 queries issued in the current scheme, while only 3 queries would be issued in the proposed scheme.
    156 
    157 It is also important to note that the effect of the numbers increase in proportion to the number of machines attached to the project.
    158 
    159 ==== Project Messages ====
    160 Project messages are messages the project would like to see and should be personalized in some way.
    161 
    162 Ideally when a volunteer attaches to a project they would receive a welcome message as well as a few links to useful information about the project.
    163 
    164 Other useful messages might be milestones and anniversaries. Either could contain a link to a certificate generated on demand that the volunteer could print out.
    165 
    166 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    167 || category || Message ||
    168 
    169 ==== Project News ====
    170 Project news is determined by the news items found in project_news.inc.
    171 
    172 Only the 5 most recent items newer than a month old should be added to the Project Notifications feed.
    173 
    174 || guid || {{{http://<project_url>/news/<datestamp>}}} ||
    175 || category || News ||
    176 
    177 ==== Private Messages ====
    178 Private messages are not displayed in the screensaver or a project’s graphics application.
    179 
    180 A link should be provided that takes the volunteer to the message by way of a web browser.
    181 
    182 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    183 || category || Private Message ||
    184 
    185 ==== Friend Requests ====
    186 Friend Requests are not displayed in the screensaver or a project’s graphics application.
    187 
    188 A link should be provided that takes the volunteer to the notification by way of a web browser.
    189 
    190 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    191 || category || Friend Request ||
    192 
    193 ==== Friend Confirmations ====
    194 Friend Confirmations are not displayed in the screensaver or a project’s graphics application.
    195 
    196 A link should be provided that takes the volunteer to the notification by way of a web browser.
    197 
    198 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    199 || category || Friend Confirmation ||
    200 
    201 ==== Forums ====
    202 A link should be provided that takes the volunteer to the notification by way of a web browser.
    203 
    204 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    205 || category || Forum Update ||
    206 ==== Forum Threads ====
    207 A link should be provided that takes the volunteer to the notification by way of a web browser.
    208 
    209 || guid || {{{http://<project_url>/notify/<notifyid>}}} ||
    210 || category || Thread Update ||
    211 
    212 === BOINC Action Feed ===
    213 The BOINC Action feed stream is a special in memory RSS feed the BOINC Client software maintains for informing the volunteer about various conditions.
    214 
    215 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.  Network connectivity issues should only be displayed if the automatically connect and automatically disconnect preferences are not set.
    216 
    217 Items in the feed can be generated by the BOINC Server Scheduler or the BOINC Client itself.
    218 
    219 == BOINC Server Scheduler ==
    220 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.
    221 
    222 General workflow:
    223  * Issue query to determine of the volunteer has customized their feeds.
    224  * Read feeds.xml for feed baseline.
    225  * Merge the results of feeds.xml and the results of the query, with preference given to the volunteer’s selections.
    226 
    227 If an empty result set is returned by the database, then pass the contents of feeds.xml unmodified.
     115 * Project news
     116 * Private message
     117 * Friend request
     118 * Friend confirmation
     119 * Forum update
     120 * Thread update
     121 * Scheduler notice
     122 * Client notice
    228123
    229124=== Scheduler Reply ===
    230 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.
    231 
    232 Messages like a project being out of work should not be included in the notification stream.
    233 
    234 Where possible, notification messages should contain information on how to correct the problem.
    235125
    236126Example:
    … …  
    247137
    248138== BOINC Project Website ==
    249 A project’s website is the main focal point for adding and removing notification feeds.
    250 
    251 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.
    252139
    253140A 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.
    254141
    255 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.
     142This new section should allow the volunteer to change the refresh rate for any feed they want to be notified about.
     143 It should also allow them to disable any feed.
    256144
    257145== BOINC Core Client ==
    258146
    259 === Feed List ===
    260 Feeds will be added and removed from the feed list at the end of a scheduler operation.
    261 
    262 New items are items in which there is not already an entry in the existing list.
    263 
    264 Old items are items that are in the existing list and do not have an entry in the scheduler response.
    265 
    266 === Feeds ===
    267 Periodically the client will loop through the feed list and download a feed update.  The feed update will be stored in a temporary file and any new items will be added to and old items will be deleted from the existing feed list.
    268 
    269 Feed updates are required when the current_time > (last_update + update).
    270 
    271 New items are items in which there is not already a matching guid in the existing list.
    272 
    273 Old items are items that are marked deleted in the existing list and do not have an entry in the feed update.
    274147
    275148=== Feed Storage ===
    … …  
    283156=== GUI RPCs ===
    284157
    285 ==== get_feeds() ====
    286 Enumerates all the feeds for a given project as well as provides the properties for a given feed.
     158==== get_feed() ====
     159Enumerates all the feed items for a given feed as well as provides the properties for a given feed item.
    287160
    288161Parameters:
    … …  
    291164
    292165'''Notes''':
    293  * This RPC should not require authentication.
    294  * If project_url is empty an error should be returned.
    295 
    296 
    297 ==== get_feed() ====
    298 Enumerates all the feed items for a given feed as well as provides the properties for a given feed item.
    299 
    300 Parameters:
    301 || Parameter || Type || Meaning ||
    302 || project_url || string || Specify which project should the feed metadata be returned for. ||
    303 || feed_url || string || Specify which feed should the feed items be returned for. ||
    304 
    305 '''Notes''':
    306166 * If both project_url and feed_url are empty, the BOINC Action Feed stream is returned.
    307167 * Requests for private feeds should return an error.
    308168 * This RPC should not require authentication.
    309 
    310169
    311170==== get_private_feed() ====
    … …  
    315174|| Parameter || Type || Meaning ||
    316175|| project_url || string || Specify which project should the feed metadata be returned for. ||
    317 || feed_url || string || Specify which feed should the feed items be returned for. ||
    318176
    319177'''Notes''':
    … …  
    321179
    322180
    323 ==== set_feed_item_option() ====
    324 Sets a given property for a specific feed item.
    325 
    326 Parameters:
    327 || Parameter || Type || Meaning ||
    328 || project_url || string || Specify which project should the feed metadata be returned for. ||
    329 || feed_url || string || Specify which feed should the feed items be returned for. ||
    330 || guid || string || Specify which feed item should be changed. ||
    331 || read || bool || Item has been read. ||
    332 || deleted || bool || Item has been deleted. ||
    333 
    334 '''Notes''':
    335  * This RPC requires authentication.
    336 
    337181== BOINC Manager ==
    338182
    339183=== Options Dialog ===
    340 [[Image(optionsdialog.jpg)]]
    341184
    342 The network reminder interval option will be renamed to action notification reminder interval.
    343 A new notification reminder interval will be added for dealing with non-action related notifications and it will be called notification reminder interval.
    344 
    345  '''NOTE:''' We will need to present a better mechanism than the slider for determining the reminder interval, at present we cap it at two hours.  I would like to set the high water mark at 1 week for the notification reminder interval.  Maybe a drop-down combo box will work better in that we can scale the selection.
    346185
    347186=== Taskbar Notifications ===
    348187[[Image(taskbarnotification.jpg)]]
    349 
    350 Once every notification reminder interval the current list of feeds is checked for any new or unread feed items and if any are detected it should tell the volunteer by way of a balloon.
    351188
    352189=== Advanced View ===
    … …  
    358195== BOINC Screensaver ==
    359196
    360 The default BOINC screensaver should only display the BOINC Action feed if there is anything to display.  If the BOINC Action feed is empty then it should display at random different feed items from the various project news feeds. A new item should be chosen at random every minute.
    361 
    362 Projects are encouraged to consume their own feeds and display them in whatever manor fits with their graphics application.
    363 
    364 At no time should a screensaver or graphics application attempt to display feeds that have been marked private.