Flow Manager

From wiki.gpii
Jump to: navigation, search
See Also

Flow Manager API

Relevant pages

Overview

The Flow Manager is a Kettle app responsible for the overall orchestration of the various subcomponents which comprise the GPII personalization architecture. The Flow Manager is the event-driven, asynchronous component. It is implemented as a very small web server and is responsible for bringing together the various components in the system and invoking them at the appropriate points in the process. The Flow manager can be deployed either on the user's local device or in the cloud.

Local Deployment

When deployed locally, the Flow Manager

  • logs users in and out by responding to requests from User Listeners,
  • queries the Preferences Server and Device Reporter,
  • communicates with the Matchmaker to determine a set of the solutions and settings to be applied, and
  • passes the list of solutions and their settings to the Lifecycle Manager.

Cloud-Based Deployment

When deployed in the cloud, the Flow Manager

  • responds to requests from a web-based solution (such as a web app)
    • the request includes information that would normally be provided by a login request (such as the user token) or fetched from the Device Reporter (such as the app information)
  • queries the Preferences Server,
  • communicates with the Matchmaker to determine the settings to be applied, and
  • returns those settings to web-based solution.

Requests

The Flow Manager coordinates responses several requests, as described below. For more information on the request handling, see the page for the particular request handler.

Login (local only)

Request type GET
Request format <url to flow manager>/user/<user token>/login
Handled by User Login Request Handler
Note Only in a local deployment (see below for more information)

Logout (local only)

Request type GET
Request format <url to flow manager>/user/<user token>/logout
Handled by User Logout Request Handler
Note Only in a local deployment (see below for more information)

Save (sockets only)

Request type POST
Request format <url to flow manager>/save/<user token>?
Handled by User Save Request Handler
Note Only when socket support has been configured (see below for more information)

Update (sockets only)

Request type POST
Request format <url to flow manager>/udpate
Handled by User Update Request Handler
Note Only when socket support has been configured (see below for more information)

Settings (cloud-based only)

Request type GET
Request format <url to flow manager>/<user token>/settings/<device info>
Handled by Settings Request Handler
Note Only in a cloud-based deployment (see below for more information)


Socket Support

coming soon...

Developing with the Cloud-Based Flow Manager

Before running the cloud-based Flow Manager, you need to set NODE_ENV to cloudBased.development.all.local.

Then you start the GPII framework by running the following command from <GPII_INSTALL_FOLDER>/node_modules/universal: node gpii.js.

Note: The authoritative instructions are on GitHub.

This will run the system in cloud-based flow manager mode, reading preferences and solutions from the local device.

Now to use the flow manager, you can use the base URL http://127.0.0.1:8081 as you would usually use http://flowmanager.gpii.net.. So for example, typing the URL (without encoding):

 http://127.0.0.1:8081/<USER>/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

would give you the settings for the user <USER> encoded for the application org.gnome.desktop.a11y.magnifier. The browser will automatically URL encode this - so after encoding, it would look like:

 http://127.0.0.1:8081/<USER>/settings/%7B%22OS%22:%7B%22id%22:%22linux%22%7D%2C%22solutions%22:%5B%7B%22id%22:%22org.gnome.desktop.a11y.magnifier%22%7D%5D%7D

For example, to test the setup, try typing

  http://127.0.0.1:8081/sammy/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

in a browser. This should return a payload of preferences, indexed by the gnome magnifier id.


Boneyard

OLD INSTRUCTIONS

[ The information below is based on a thread started on 29 October 2013. ]

Work is in progress for getting an updated config into the master repository, but currently it's slightly akward to launch the cloud based flowmanger in full development mode. The easiest approach is the following:

download the file: https://raw.githubusercontent.com/kaspermarkus/universal/cloudConfig/gpii/configs/cloudBasedFlowManager.json

and place it in the "gpii/configs" folder in universal

Now, to start up the system, go to the universal folder and type:

 set NODE_ENV=cloudBasedFlowManager
 node node_modules/kettle/lib/init.js gpii/configs/

This will run the system in cloud-based flowmanager mode, reading preferences and solutions from the local device.

Now to use the flowmanager, you can use the base URL http://127.0.0.1:8081 as you would usually use http://flowmanager.gpii.net.. So for example, typing the URL (without encoding):

 http://127.0.0.1:8081/<USER>/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

would give you the settings for the user <USER> encoded for the application org.gnome.desktop.a11y.magnifier. The browser will automatically URL encode this - so after encoding, it would look like:

 http://127.0.0.1:8081/<USER>/settings/%7B%22OS%22:%7B%22id%22:%22linux%22%7D%2C%22solutions%22:%5B%7B%22id%22:%22org.gnome.desktop.a11y.magnifier%22%7D%5D%7D

For example, to test the setup, try typing

  http://127.0.0.1:8081/sammy/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

in a browser. This should return a payload of preferences, indexed by the gnome magnifier id.


OLDER INSTRUCTIONS

For development purposes, it is helpful to run an instance of the cloud-based Flow Manager locally. This will allow you to modify the solutions registry locally when testing your transformations, etc.

In one console, type

 set NODE_ENV=cloudBased
 node node_modules/kettle/lib/init.js gpii/node_modules/flowManager/configs/

In another console, type

 node node_modules/kettle/lib/init.js gpii/node_modules/matchMaker/configs/

After doing this, you should be able to "log in" a user by passing the relevant parameters to a URL like the following:

 http://flowmanager.gpii.net/<USER>/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

With encoding, this looks like:

 http://flowmanager.gpii.net/<USER>/settings/%7B%22OS%22:%7B%22id%22:%22linux%22%7D%2C%22solutions%22:%5B%7B%22id%22:%22org.gnome.desktop.a11y.magnifier%22%7D%5D%7D

This should give you the preferences of <USER> for the solution with the id: *"org.gnome.desktop.a11y.magnifier".

However, to use the locally installed Flow Manager, the URL should be (without encoding):

 http://127.0.0.1:8081/<USER>/settings/{"OS":{"id":"linux"},"solutions":[{"id":"org.gnome.desktop.a11y.magnifier"}]}

and after encoding:

 http://127.0.0.1:8081/<USER>/settings/%7B%22OS%22:%7B%22id%22:%22linux%22%7D%2C%22solutions%22:%5B%7B%22id%22:%22org.gnome.desktop.a11y.magnifier%22%7D%5D%7D


Note: If you're running this under Linux or Mac OS, you probably need to use export instead of set when defining the NODE_ENV environment variable.

Note on URL encoding: According to IETF RFC 3986, section 3.3, the characters { and } need to be URL-encoded as %7B and %7D, respectively, " as %22, , as %2C, and [ and ] as %5B and %5D, respectively. You can use the URL Decoder/Encoder at http://meyerweb.com/eric/tools/dencoder/ to ... decode and encode URLs.

Note on the Preferences Server: By default, the local instance of the cloud-based Flow Manager will use the online Preferences Server at http://preferences.gpii.net. If you want to use your own N&P sets for developing purposes, you have to run your own instance of a preferences server. For information on how to run a Preferences Server locally, see Running a Preferences Server Locally.