Article feedback/Public Policy Pilot/Technical

Page Load
This is the process that occurs when a user goes to a page initially.


 * 1) Page request is received.
 * 2) If pageID is within the pilot's purview, we continue:
 * 3) After full page load, the AA javascript fires.
 * 4) * If the browser has a cookie value amounting to "has ever given a rating" or the user is logged in, the javascript-fired request needs to try to get previous rating values for this user.
 * 5) The server catches this request and returns the correct data:
 * 6) * The values for the current aggregates for all four questions, as well as the number of ratings received.
 * 7) * If there are individual ratings to be returned (user-level):
 * 8) ** The value given by the user for each question
 * 9) ** Whether or not the values are "stale"
 * 10) ** The number of revisions that have passed since the user gave these ratings.
 * 11) Upon receipt of the data from the server, the client-side javascript assembles the visuals as needed and injects the data into the page.

Rating Submission
This is the process that occurs when a user submits ratings. It is effectively the same process whether they are fresh, stale, or re-rating the same revision)


 * 1) User selects values for the questions.
 * 2) * User is not required to submit values for all four ratings.
 * 3) User clicks the submit button.
 * 4) If this is a new rating for the user on this revision, a new row will be inserted into the database. If it is a "re-rating" for the revision, an update will be made (so this is basically an upsert on the userid/pageid/revisionid key)
 * 5) It is at this point that the aggregate rating values are calculated.
 * 6) Data is returned to the client in the same format as it is on page load, and the components are updated (not reloaded)
 * 7) A "this user has given a rating to something" cookie is set on the client.

API
The following API calls will be used with

getCumulativeResults
invoked by  where pageid is the page ID and revid is the revision ID of the desired page

This will return a cached result in an object nested like so  Where 1-4 are the indicies for the dimensions of the review, avg is the average for that dimension, and total is the total number of reviews

setUserVals
invoked by where reviewcookie is the unique identifier for this user in the review system, authcookie is a cookie to match against the server to avoid CXRF, pageid is the page ID, revid is the revision ID of the desired page, and djsonRevObj is a review object in JSON of the following: where val are the values the user has assigned

Database
The data stored will be in the following tables:

article_assessment
Will hold 1 entry per user per revision, namely: Where m1...mn are the dimensions we're measuring (completeness, npov, etc)


 * Known Issue/Open Question: We are assuming that optimal performance may be achieved by using one column per "question".  However, it may be that we wish to have one row per answer (so each submit click results in four rows instead of one).  This is something of lesser concern for the pilot but will be of great concern if/when this feature is rolled out on a higher profile basis.

article_assessment_pages
Will hold 1 entry per page revision per dimension we're measuring, namely: Where dimension refers to the dimension that's being measured (1 = completeness, etc)

Assumptions

 * previous user ratings will be stored in a cookie on the user's browser. All that needs to be stored is [pgid, revid, dimension, rating] but only for the last revision that has been given
 * the page's pageid and current revid need to be visible to JS as variables
 * Historical information will be retained per user per article. That is:  if a user rates a given article 5 times on 5 different revisions, all 5 ratings will be stored to facilitate "over time" statistical analysis.
 * Note that if the user re-rates the same revision, the data will be an update and not an insert. So if the user rates a given article 6 times on 5 revisions, only 5 entries will be stored.

Limitations

 * Any user who uses a different browser or clears their cookies will be seen by the system as having a different browser
 * After the user hits the maximum number of reviewable pages, they won't be able to see their ratings for the first reviewed page
 * We need to limit the MWHooks to 1 call so that code only gets injected when it is a page that has AA enabled for it, and this comparison only needs to be made once

Open Issues

 * Cache invalidating - On every new rating, the cached version of this page will have to be invalidated.
 * We mark pages as invalid after an edit, short-term solution is to do this
 * Long-term solution is to get the ratings info from an API call that has cache-able resources


 * Only to appear on select pages
 * Short-term solution is to have a configurable list of page titles or IDs that this extension will be visible on, and optimize to exit out if the page is not among these
 * Long-term solution not necessary as this will be on all pages long-term