First Discovery Server

The First Discovery Server acts as a web server for a First Discovery Editor instance and provides a means for storing preferences to the GPII Preferences Server. The First Discovery Server makes use of the Kettle configuration system for configuration and instantiation, but uses gpii-express rather than Kettle for expressing an HTTP server.

Access to the GPII Preferences Server is mediated by the GPII OAuth2 Security layer. The First Discovery Server communicates with the Security layer via the Client Credentials Grant workflow.

Configuration

The First Discovery Server can be configured via Kettle Configs. A set of these are provided with the server in the config directory. An integrator can choose to make use of the provided configs directly or use them as the basis for creating new configs.

The gpii.firstDiscovery.server.configurator grade defines a default schema which the configuration is validated against. If the validation fails, the application will throw an error.

environment.json

environment.json accepts environment variables for all of the critical configuration options that are needed for running the First Discovery Server and connecting to the OAuth2 security server.

Environment Variable	Description
`FIRST_DISCOVERY_SERVER_TCP_PORT`	The port number that the First Discovery Server is hosted at. Example: "8088" Option Path: `port`
`GPII_OAUTH2_TCP_PORT`	The port number that the GPII OAuth2 server is hosted at. Example: "8081" Option Path: `preferencesConfig.securityServer.port`
`GPII_OAUTH2_HOST_NAME`	The hostname that the GPII OAuth2 server is hosted at. Example: "http://localhost" Option Path: `preferencesConfig.securityServer.hostname`
`GPII_OAUTH2_ACCESS_TOKEN_PATH`	The path to the resource for requesting an access token. Example: "/access_token" Option Path: `preferencesConfig.securityServer.paths.token`
`GPII_OAUTH2_ADD_PREFERENCES_PATH`	The path to the resource for creating a preference set. A query parameter can be added to provide the view/ontology that the preferences are to be stored in. Example: "/add-preferences?view=%view" Option Path: `preferencesConfig.securityServer.paths.preferences`
`GPII_OAUTH2_AUTH_GRANT_TYPE`	The grant type supported by the OAuth2 server. Example: "client_credentials" Option Path: `preferencesConfig.authentication.grant_type`
`GPII_OAUTH2_AUTH_SCOPE`	The level of permissions that are being requested. Example: "add_preferences" Option Path: `preferencesConfig.authentication.scope`
`GPII_OAUTH2_AUTH_CLIENT_ID`	The client ID registered with the OAuth2 server. Should be kept confidentially. Example: "client_id_first_discovery" Option Path: `preferencesConfig.authentication.client_id`
`GPII_OAUTH2_AUTH_CLIENT_SECRET`	The client secret registered with the OAuth2 server. Used to securely identify the client with the OAuth2. Should be kept confidentially. Example: "client_secret_first_discovery" Option Path: `preferencesConfig.authentication.client_secret`

oauth2.json

oauth2.json merges on top of environment.json to replace the authentication related environment variables with concrete values for the Client Credentials Grant workflow.

Option Path	Description	Value
`preferencesConfig.securityServer.paths.token`	The path to the resource for requesting an access token. (see: GPII OAuth 2 Guide: Access Token)	"/access_token"
`preferencesConfig.securityServer.paths.preferences`	The path to the resource for creating a preference set. A query parameter can be added to provide the view/ontology that the preferences are to be stored in. (see: GPII OAuth 2 Guide: User's Preferences)	"/add-preferences?view=%view"
`preferencesConfig.authentication.grant_type`	The grant type supported by the OAuth2 server.	"client_credentials"
`preferencesConfig.authentication.scope`	The level of permissions that are being requested.	"add_preferences"

vagrant.json

vagrant.json merges on top of oauth2.json, replacing the environment variables for connecting to the OAuth2 server with the expect hostname and port when running inside of a Vagrant VM. The configuration assumes that an instance of the OAuth2 server is available through the host machine at port 8081.

A Vagrant VM is provided with the First Discovery Server for quickly creating its own development environment.

(see: vagrant.json)

Option Path	Description	Value
`preferencesConfig.securityServer.port`	The port number that the GPII OAuth2 server is hosted at.	"8081"
`preferencesConfig.securityServer.hostname`	The hostname that the GPII OAuth2 server is hosted at.	"http://10.0.2.2"

Launching

The First Discovery Server can be launched as a Kettle application by making use of Kettle Configs.

There are two typical ways of launching a Kettle app, programmatically and from command line.

(See: Starting a Kettle application)

Programmatically

// require the kettle module
var kettle = require("kettle");

// load the config
kettle.config.loadConfig({
    // path to the config directory
    configPath:"./src/config",

    // name of the config to load, without the file extension
    configName: "vagrant"
});

Command Line

# Call Kettle's init.js script with the
# configPath and configName
# node node_modules/kettle/init.js <configPath> [<configName>]
node node_modules/kettle/init.js ./src/config vagrant

# or using an environment variable to specify
# the configName
# NODE_ENV=<configName> node node_modules/kettle/init.js <configPath>
NODE_ENV=vagrant node node_modules/kettle/init.js ./src/config

REST API

URL Request Description

URL	Request	Description
`/user[?view=:view]`	`POST`	Accepts a set of preferences, in a JSON object, to be stored on the preferences server. For example: `{"gpii_firstDiscovery_language": "en-US"}` On successfully storing the preferences set, a JSON object is returned containing `userToken` and `preferences` properties. The `userToken` is the GPII token, which can be used for retrieving the preferences on a GPII enabled device. The `preferences` are a confirmation of the preferences stored on Preferences server for that GPII token. For example: `{ "userToken": "2288e676-d0bb-4d29-8131-7cff268ba012", "preferences": { "contexts": { "gpii-default": { "name": "Default preferences", "preferences": { "gpii_firstDiscovery_language": "en-US" } } } } }` The optional `view` query parameter is used to specify which ontology the preferences are stored in. (See: Preferences Server)

/user[?view=:view]

POST

Accepts a set of preferences, in a JSON object, to be stored on the preferences server. For example:

{"gpii_firstDiscovery_language": "en-US"}

On successfully storing the preferences set, a JSON object is returned containing userToken and preferences properties. The userToken is the GPII token, which can be used for retrieving the preferences on a GPII enabled device. The preferences are a confirmation of the preferences stored on Preferences server for that GPII token. For example:

{
  "userToken": "2288e676-d0bb-4d29-8131-7cff268ba012",
  "preferences": {
    "contexts": {
      "gpii-default": {
        "name": "Default preferences",
        "preferences": {
          "gpii_firstDiscovery_language": "en-US"
        }
      }
    }
  }
}

The optional view query parameter is used to specify which ontology the preferences are stored in. (See: Preferences Server)

Demos

This demo implements the integration with the GPII Preferences Server to save preferences. http://build.fluidproject.org/first-discovery/demos/prefsServerIntegration

Source code

Edit this Page on GitHub

Documentation for the First Discovery Tool

First Discovery Tool