Enhanced Data Model for NOVA

From wiki.gpii
Jump to: navigation, search

This page documents the enhanced data model for the final NOVA deployment. The content is for discussion and reviews.

Data Model

The enhanced data model adds 3 fields in 2 document types. These new fields are marked with light-red background.

GPII data model NOVA.png

Example of a New Client Credentials document

    "_id": "clientCredential-1",
    "type": "clientCredential",
    "schemaVersion": "0.1",
    "clientId": "gpiiAppInstallationClient-1",
    "oauth2ClientId": "oauth2ClientId-for-NOVA",
    "oauth2ClientSecret": "oauth2ClientSecret-for-NOVA",
    "allowedIPBlocks": [
        "",          // IPv4 block
        "2001:cdba::3257:9652",    // IPv6 block
        ""              // IP string
    "allowedPrefsToWrite": [
        // common registry preferences
        // application specific preferences
    "isCreateGpiiKeyAllowed": true,
    "isCreatePrefsSafeAllowed": true,
    "revoked": false,
    "revokedReason": null,
    "timestampCreated": "2017-11-21T18:11:22.101Z",
    "timestampRevoked": null


1. A npm module for ip range check: https://www.npmjs.com/package/ip-range-check

2. Based on discussion on May 17, 2019, for now, GPII Cloud will only support cases when "isCreateGpiiKeyAllowed" and "isCreatePrefsSafeAllowed" have the same value (true or false). When these flags have different values, the request will be rejected and an error will be returned. Having two flags rather than one is to reduce the data model migration burden. It's much easier to modify the code logic than writing migration scripts and updating hundred and thousands records in the database.


1. The new field "gpiiAppInstallationAuthorization.assignedIP" is to record the IP assigned to a particular access token. This IP must be the same with the IP that /settings GET (or PUT) requests using this access token are sent from. This is to ensure it is the same computer that requests the access token and uses this access token. Is this second verification to ensure it's the same computer using this access token necessary?

Answer: From discussion on May 8, 2019, it's decided:

(1) The extra verification on /settings GET/PUT handlers is unnecessary;

(2) There should be a flag to allow the creation of prefs safe.

These decisions result in 2 changes on the data model: (1) remove "assignedIP" field from "GpiiAppInstallationAuthorization" document type; (2) Add a new field "isCreatePrefsSafeAllowed" in "ClientCredential" document type.

2. The point i) in the GPII-3719 JIRA says: "That the new OAuth grant type should be in effect for sessions secured by access tokens granted to clients presenting a matching machine secret/client credentials". Seems to me no data model change is required for this point. It would be helpful to discuss about this at reviewing this document.

Answer: From the same discussion on May 8, 2019, we will explore another option that is, rather than adding a special OAuth grant type for NOVA, the existing grant type could be reused to accommodate both NOVA use case and current use case for libraries and AJCs by either checking the existence of new fields ("allowedIPBlocks", "allowedPrefsToWrite", "isCreatePrefsSafeAllowed") or the boolean value of "isCreatePrefsSafeAllowed === true". These fields will only exist for NOVA and with "isCreatePrefsSafeAllowed === true".

3. Discuss the timing of making the actual code work with the data model versus adding schema validation. Who is doing what, and when? Do we need schemas for the current data model? For how long?

Answer: The same author of the code who requires the validation should learn and write the schema validation part.

4. Sync up the use of "settings" and "preferences" keywords. Tony's JIRA comment refers to "prefsSafe.preferences" field as "prefsSafe.settings".


Helps to distinguish "prefsSafe.preferences" with another "preferences" path down in its own structure. An example of a typical prefsSafe document that has 2 "preferences" paths:

    "_id": "prefsSafe-GPII-270-rbmm-demo",
    "type": "prefsSafe",
    "schemaVersion": "0.1",
    "prefsSafeType": "snapset",
    "name": "GPII-270-rbmm-demo",
    "email": null,
    "preferences": {
        "flat": {
            "contexts": {
                "gpii-default": {
                    "name": "Default preferences",
                    "preferences": {
                        "http://registry.gpii.net/common/matchMakerType": "ruleBased",
                        "http://registry.gpii.net/common/fontSize": 24,
                        "http://registry.gpii.net/common/foregroundColor": "white",
                        "http://registry.gpii.net/common/backgroundColor": "black",
                        "http://registry.gpii.net/common/fontFaceFontName": [
                            "Comic Sans"
                        "http://registry.gpii.net/common/fontFaceGenericFontFace": "sans serif",
                        "http://registry.gpii.net/common/magnification": 2,
                        "http://registry.gpii.net/common/tracking": "mouse",
                        "http://registry.gpii.net/common/speechRate": 42,
                        "http://registry.gpii.net/common/trackingTTS": "mouse",
                        "http://registry.gpii.net/common/speakTutorialMessages": true,
                        "http://registry.gpii.net/common/keyEcho": true,
                        "http://registry.gpii.net/common/wordEcho": true,
                        "http://registry.gpii.net/common/announceCapitals": false,
                        "http://registry.gpii.net/common/screenReaderBrailleOutput": false,
                        "http://registry.gpii.net/common/punctuationVerbosity": "some",
                        "http://registry.gpii.net/common/readingUnit": "word",
                        "http://registry.gpii.net/common/auditoryOutLanguage": "GR",
                        "http://registry.gpii.net/common/screenReaderTTS/enabled": true,
                        "http://registry.gpii.net/common/pitch": 0.4,
                        "http://registry.gpii.net/common/volumeTTS": 0.5,
                        "http://registry.gpii.net/applications/com.microsoft.windows.highContrast": {
                            "HighContrastOn": {
                                "path": "pvParam.dwFlags.HCF_HIGHCONTRASTON",
                                "value": true
    "timestampCreated": "2019-03-15T13:58:06.037Z",
    "timestampUpdated": null


Just to my understanding (I'm not sure if it's correct), "preferences" is used for generic common or application specific terms such as:

    "http://registry.gpii.net/common/matchMakerType": "ruleBased",
    "http://registry.gpii.net/common/fontSize": 24,
    "http://registry.gpii.net/common/foregroundColor": "white",
    "http://registry.gpii.net/common/backgroundColor": "black"

"settings" is after preferences go thru the matchmaking process and are converted into actual application settings that will be applied to computers. An example of a setting is to set the screen reader speech rate to 200 words per minute.