MatchMakerUtilities.js

/*!
GPII Matchmaker Framework - Utilities

Copyright 2012 OCAD University
Copyright 2012 Antranig Basman
Copyright 2014 Raising the Floor - international

Licensed under the New BSD license. You may not use this file except in
compliance with this License.

The research leading to these results has received funding from the European Union's
Seventh Framework Programme (FP7/2007-2013) under grant agreement no. 289016.

You may obtain a copy of the License at
https://github.com/GPII/universal/blob/master/LICENSE.txt
*/

/* eslint-env browser */
/* eslint strict: ["error", "function"] */

var fluid = fluid || require("infusion"),
    gpii = fluid.registerNamespace("gpii");

(function () {

    "use strict";
    fluid.registerNamespace("gpii.matchMakerFramework.utils");
    fluid.registerNamespace("gpii.matchMakerFramework");

    /*
     * APP_SETTING_PRIORITY: the priority that an application is given if the user has application
     *    specific settings in their preference set for that application, but has no explicit priority for
     *    that application. * MIN_USER_PRIORITY: If an explicit priority is set by the user for an application, this is
     *    the minimum value it should have, to avoid conflicting with system generated priorities.
     */

    gpii.matchMakerFramework.APP_SETTING_PRIORITY = 512;
    gpii.matchMakerFramework.MIN_USER_PRIORITY = 1024;

    /**
     * responsible for building the input payload to the matchmaker, via a bunch of helper functions
     *
     * @param {Object} initialPayload - The initial payload sent to the matchmaking framework. It should as a
     *   minimum contain: gpiiKey, preferences, deviceContext, solutionsRegistryEntries.
     *   The values from this object will become part of the new matchmaker input object returned from this function,
     * @return {Object} The matchmaker input.
     */
    gpii.matchMakerFramework.utils.preProcess = function (initialPayload) {
        var matchMakerInput = fluid.extend({
            specialPreferences: gpii.matchMakerFramework.utils.findSpecialPreferences(initialPayload.preferences)
        }, fluid.copy(initialPayload));
        gpii.matchMakerFramework.utils.addCapabilitiesInformation(matchMakerInput);
        // remove full solutions registry from the payload, now that we've used it
        // to avoid sending a too large payload to the matchmaker (see GPII-1880)
        delete matchMakerInput.fullSolutionsRegistry;

        return matchMakerInput;
    };

    /*
     * extracts the capabilities from a settingshandler block based on the `capabilities` entry
     * and the inputPaths of the capabilitiesTransformations block
     */
    gpii.matchMakerFramework.utils.extractCapabilities = function (settingsHandler) {
        return fluid.model.transform.collectInputPaths(settingsHandler.capabilitiesTransformations || {});
    };

    /**
     * Takes an array of paths as input and returns them in the ontology provided via the transform spec.
     * The result will be an array list of el-paths in the ontology transformed to.
     *
     * @param {Array} paths - An array of supported capabilities by a solution (as returned by the
     *     gpii.matchMakerFramework.utils.computeCapabilitiesFromSolution function).
     * @param {Object} transformSpec - Transformation rules to transform the input paths from the solution
     *    registry format into the format desired in the output array. If if one would like the result
     *    as a list of ISO24751 el-paths and the solutionsregistry transformations are given in
     *    the flat format, a transformation rules for 'flat' to ISO24751 should be given.
     * @return {Array} An array of el-paths to all the input paths of the given capabilities in the
     *    ontology produced by the transformSpec.
     */
    gpii.matchMakerFramework.utils.transformCapabilitiesToOntologizedLeaves = function (paths, transformSpec) {
        // Input paths are flat so need to be transformed into hierarchical
        var skel = gpii.matchMakerFramework.utils.pathsToSkeleton(paths, true);
        var hskeleton = fluid.model.transformWithRules(skel, transformSpec);

        return gpii.matchMakerFramework.utils.computeLeaves(hskeleton);
    };

    /**
     * Given a solution entry, all the capabilities of that solution will be calculated based on
     * input paths in the transformations (specified in the capabilitiesTransformations block) and
     * on the list in the capabilities block of that solution
     *
     * @param {Object} solution - A single solution entry, as can be found in the solutions registry.
     * @return {Array} An array capabilities supported by the given solution.
    */
    gpii.matchMakerFramework.utils.computeCapabilitiesFromSolution = function (solution) {
        var paths = [];
        fluid.each(solution.settingsHandlers, function (handlerBlock) {
            paths = paths.concat(gpii.matchMakerFramework.utils.extractCapabilities(handlerBlock));
        });
        // grab the capabilities block from the solution if present:
        if (solution.capabilities) {
            paths = paths.concat(solution.capabilities);
        }
        return paths;
    };

    /*
     * Helper function for gpii.matchMakerFramework.utils.computeLeaves - see description there
     */
    var computeLeavesImpl = function (model, path, paths) {
        fluid.each(model, function (value, key) {
            var newPath = fluid.pathUtil.composePath(path, key.toString());
            if (fluid.isPrimitive(value)) {
                paths.push(newPath);
            }
            else {
                computeLeavesImpl(value, newPath, paths);
            }
        });
    };

    /**
     * Function to extract all leaves (i.e. primitive end points) from an object. More specifically,
     * it takes a object (eg. prefs set) and finds all leaves - for each leaf found the path is
     * to an array as an el-path, one path for each leaf.
     *
     * @param {Object} model - The object from which to subtract leaves.
     * @return {Array} An array of el-paths, one entry for each leaf found in the object.
     */
    gpii.matchMakerFramework.utils.computeLeaves = function (model) {
        var paths = [];
        computeLeavesImpl(model, "", paths);
        return paths;
    };

    /**
     * Given a array of el-paths, this function creates an object with a structure that includes
     * all the el-paths in the array. Each of the entries will have the value passed as parameter or
     * defaulting to {} (i.e. the empty object);
     *
     * @param {Array} paths - An array of el-paths that should be present in the resulting object.
     * @param {Any} value - The value that should be assigned to each of the keys given in the el-path array,
     *      if no @value is given, this defaults to the empty object ({}).
     * @return {Object} An object with a structure containing all the el-paths, where each path has
     *     the value given in the parameter.
     */
    gpii.matchMakerFramework.utils.pathsToSkeleton = function (paths, value) {
        var togo = {};
        for (var i = 0; i < paths.length; ++i) {
            var path = paths[i];
            var existing = fluid.get(togo, path, fluid.model.escapedGetConfig);
            if (!existing) {
                fluid.set(togo, path, value || {}, fluid.model.escapedSetConfig);
            }
        }
        return togo;
    };

    /**
     * Given a list of solutions and capabilities, ontologize the capabilities and generate a skeleton based on those.
     *
     * @param {Object} solutions - List of solution entries in the same format as the solutions registry\.
     * @param {Object} capabilities - (array)listings of solution capabilities, keyed by solution ID.
     * @param {Object} transformSpec - Transformation rules to translate from the format the input paths are
     *     given in in the solutions entries' capabilitiesTransformations block, to the ontology
     *     that the skeleton should be in.
     * @return {Object} An object listing the same solutions as the input payload, but where each
     *     solution block instead contains three keys: 'solution' which contains the original solution
     *     entry. 'skeleton' which contains the capabilities of the solution. 'index' which contains
     *     the solution id.
     */
    gpii.matchMakerFramework.utils.expandSolutions = function (solutions, capabilities, transformSpec) {
        return fluid.transform(solutions, function (solution, solutionId) {
            var solutionIdObj = {};
            solutionIdObj["http://registry.gpii.net/applications/" + solutionId] = {};
            var transformedId = fluid.model.transformWithRules(solutionIdObj, transformSpec);

            var paths = gpii.matchMakerFramework.utils.transformCapabilitiesToOntologizedLeaves(capabilities[solutionId], transformSpec);
            var skeleton = fluid.extend(true, {}, gpii.matchMakerFramework.utils.pathsToSkeleton(paths), transformedId);

            return {
                solution: solution,
                skeleton: skeleton,
                index: solutionId
            };
        });
    };

    // TODO: While investigating GPII-4468, it was found that this function is only invoked in the pathway between gpii.lifecycleManager.applyExistingPrefs
    // invoked as part of the "update" cycle - probably reflecting the historical fact that the PSP (now abolished) was the only source of changes.
    // This implies that this linkage between "/enabled" and "active" is only ever computed at this point rather than at any login (that is, at LifecycleManager
    // "start") as it should be.
    // Instead, the dominant route for this linkage is in fact gpii.transformer.transformOneLaunchHandler in Transformer.js - it may well be that this business
    // of "active" can be axed in favour of the "running" special setting
    /**
     * Based on the /enabled terms from a user's preference set and the /enabled capabilities from the solution,
     * this function returns what the 'active' value of the solution should be.
     *
     * @param {Object} specialPreferences - The specialPreferences value of the relevant prefsSet (from the value of the same name in the MatchMaker input payload).
     * @param {Array} specialCapabilities - The solutions specialCapabilities (from the value of the same name in the MatchMaker input payload).
     * @param {Object} solution - The solution registry entry of the solution for which to decide the 'active' value.
     * @param {String} solutionId - The solution id.
     * @return {Boolean} The value of the 'active' flag of the solution.
     **/
    gpii.matchMakerFramework.utils.getActiveValueFromEnabledTerms = function (specialPreferences, specialCapabilities, solution, solutionId) {
        var active;

        // see if solution has any enabled flags:
        fluid.each(specialCapabilities, function (term) {
            // if we have an /enabled term and this is not just a settings transformation:
            if (term.endsWith("/enabled") && solution.capabilities && solution.capabilities.includes(term)) {
                // set the active flag based on the user's preference value (from solution specific pref or general pref)
                var applicationBlockKey = gpii.matchMakerFramework.utils.makeApplicationTerm(solutionId);
                active = fluid.get(specialPreferences[applicationBlockKey], term, fluid.model.escapedGetConfig);
                if (active === undefined) {
                    active = fluid.get(specialPreferences, term, fluid.model.escapedGetConfig);
                }
            }
        });

        return active;
    };

    // Function to hack GPII-4468 so that an application which only has an /enabled application-specific term will still get selected
    gpii.matchMakerFramework.utils.flattenEnabled = function (preferences, segs) {
        var togo = {};
        fluid.each(preferences, function (value, key) {
            if (typeof(key) === "string" && key.endsWith("/enabled") && segs.includes("applications")) {
                key = key.substring(0, key.length - "/enabled".length);
            }
            if (fluid.isPrimitive(value)) {
                togo[key] = value;
            } else {
                segs.push(key);
                togo[key] = gpii.matchMakerFramework.utils.flattenEnabled(value, segs);
                segs.pop();
            }
        });
        return togo;
    };

    /**
     * Function that takes a MM payload set as input that *includes* an entry of
     * preferences in a hierarchical format, as well as a strategy for selecting solutions
     * and a set of transformations rules between ontologies.
     *
     * @param {Object} data - A MatchMaker input payload that includes a translation of the
     *     preferences in an hierarchical ontology, keyed by 'hierarchicalPrefs'.
     * @param {Function} strategy - The strategy to use to select which solutions should be configured and
     *     and launched on the system.
     * @param {Object} transformSpec - Transformation rules FROM the format used in the input paths of the
     *     solutions registry capability transformations TO the format in which the
     *     settings of hierarchicalPrefs in the data argument are given.
     * @return {Object} An object keyed by prefsSets and where the values are arrays of solutions
     *     to launch given that set of preferences.
     */
    gpii.matchMakerFramework.utils.disposeSolutions = function (data, strategy, transformSpec) {
        var solrecs = gpii.matchMakerFramework.utils.expandSolutions(data.solutionsRegistryEntries, data.solutionCapabilities, transformSpec);
        var togo = {};
        // calculate match for each of the preferences sets
        fluid.each(data.hierarchicalPrefs.contexts, function (prefsSet, prefsSetId) {
            var tmpSolrecs = fluid.copy(solrecs);
            // add implicit priorities based on which applications the user has application
            // specific settings for
            gpii.matchMakerFramework.utils.addPriorityFromApplicationSettings(prefsSet.preferences, tmpSolrecs);

            // add users explicit application priorities to the solrecs object
            gpii.matchMakerFramework.utils.parsePriorities(prefsSet, tmpSolrecs);

            var preferences = gpii.matchMakerFramework.utils.flattenEnabled(prefsSet.preferences, []);
            var leaves = gpii.matchMakerFramework.utils.computeLeaves(preferences);
            var disposed = strategy(leaves, tmpSolrecs, data.solutionTypeMapping);

            togo[prefsSetId] = {};
            fluid.each(disposed, function (solrec, solid) {
                if (solrec.disposition === "accept") { // only output accepted solutions
                    togo[prefsSetId][solid] = solrec.active; // true if it should be running
                }
            });
        });
        return togo;
    };

    /**
     * Scans the metadata block for application priorities, and for each found, the priority is added
     * to the solrecs object.
     *
     * Given a set of preferences from the "contexts:" block, the function will search its metadata section for
     * application priorities. If this is found, the entry for that solution in the solrec object
     * will be modified by the addition of a `priority` key with the value of the user priority.
     *
     * NOTE: this function will modify the solrecs object
     *
     * @param {Object} prefsSet - The specific set of preferences within a "contexts:" block - i.e. the
     *     part of the preference set that is keyed by a prefsSet name.
     * @param {Object} solrecs - A map of solution information, keyed by solution ids. This object should
     *     have a format identical to the output of the `gpii.matchMakerFramework.utils.expandSolutions`
     *     function. For each solution for which the user has an application priority, this solutions'
     *     entry in solrecs will be modified by the addition of a priority`key.
     */
    gpii.matchMakerFramework.utils.parsePriorities = function (prefsSet, solrecs) {
        // for each entry in the metadata block:
        fluid.each(prefsSet.metadata, function (metadata) {
            if (metadata.type === "priority") {
                fluid.each(metadata.scope, function (applicationId) {
                    // set the priority of the application if it's part of our solrecs list:
                    var solrec = solrecs[gpii.matchMakerFramework.utils.applicationIdFromTerm(applicationId)];
                    if (solrec) {
                        solrec.priority = metadata.value;
                    }
                });
            }
        });
    };

    gpii.matchMakerFramework.utils.addPriorityFromApplicationSettings = function (preferences, solrecs) {
        fluid.each(preferences.applications, function (value, applicationId) {
            var sol = solrecs[applicationId];
            // If solution is available on the system, and doesn't already have higher priority
            if (sol && (!sol.priority || sol.priority < gpii.matchMakerFramework.APP_SETTING_PRIORITY)) {
                sol.priority = gpii.matchMakerFramework.APP_SETTING_PRIORITY;
            }
        });
    };

    /*
     * Filters preferences to contain only common terms and application specific settings for the solutionId
     */
    gpii.matchMakerFramework.utils.filterPreferencesForSolution = function (solutionId, allPreferences, solutionEntry) {
        var filtered = fluid.copy(allPreferences);

        var applicationString = "http://registry.gpii.net/applications/" + solutionId;

        // find supported common terms:
        var supportedCommonArr = gpii.matchMakerFramework.utils.computeCapabilitiesFromSolution(solutionEntry);
        var supportedCommon = {}; // create object of keys that are unescaped common term URIs and values of true
        fluid.each(supportedCommonArr, function (common) {
            fluid.set(supportedCommon, common, true, fluid.model.escapedSetConfig);
        });

        // move any common terms from the application block to the outer level:
        if (filtered[applicationString]) { // application block for this solution
            fluid.each(filtered[applicationString], function (value, preference) {
                // move all common terms outside application block:
                if (gpii.matchMakerFramework.utils.isCommonTerm(preference)) {
                    filtered[preference] = value;
                    delete filtered[applicationString][preference];
                }
            });
        }

        // top level: filter everything that is not the application block and supported common terms
        return fluid.remove_if(filtered, function (value, preference) {
            // Keep preference if it is a supported common term
            if (gpii.matchMakerFramework.utils.isCommonTerm(preference) && supportedCommon[preference] === true) {
                return false;
            }
            // Also leave the applicaiton specific block
            if (preference.startsWith(applicationString) === true) {
                return false;
            }

            return true;
        });
    };

    /**
     * Function to build the payload required to be the output from the matchmaker framework
     *
     * @param {Object} fullModel - The full input sent to the MM.
     * @param {Object} disposed - Object with keys of prefsSet-ids. Each value should be an array listing
     *     the disposed solutions.
     * @return {Object} The data arranged to be compatible with the required MM format.
     */
    gpii.matchMakerFramework.utils.buildReturnPayload = function (fullModel, disposed) {
        var togo = {
            inferredConfiguration: {}
        };
        fluid.each(disposed, function (solArray, prefsSetId) {
            togo.inferredConfiguration[prefsSetId] = {
                applications: {}
            };
            var appBlock = togo.inferredConfiguration[prefsSetId].applications;
            fluid.each(solArray, function (active, solutionId) {
                var filteredSettings = gpii.matchMakerFramework.utils.filterPreferencesForSolution(solutionId, fullModel.preferences.contexts[prefsSetId].preferences, fullModel.solutionsRegistryEntries[solutionId]);
                appBlock[solutionId] = {
                    active: active,
                    settings: filteredSettings
                };
                // TODO: add metadata sections
            });
        });
        return togo;
    };

    /**
     * Simple function that takes a list of capabilities and extract all 'special' capabilities.
     * This is currently all terms ending with /enabled
     *
     * @param {Array} capabilities - An array of term/capabilities.
     * @return {Array} An array of all capabilities that are special (i.e. ends with /enabled).
     */
    gpii.matchMakerFramework.utils.extractSpecialCapabilities = function (capabilities) {
        return fluid.remove_if(fluid.copy(capabilities), function (term) {
            return !term.endsWith("/enabled");
        });
    };

    /**
     * Adds information about the supported capabilities for each solution (in the flat format) and special capabilities.
     * Two things will be added to the payload:
     * (1) A list of inputPaths from the capabilitiesTransformations of the settingshandlers as well as the content of the solutions "capabiliites" entry.
     * (2) A list of special capabilities, meaning the (1) list run through the extractSpecialCapabilities function
     *
     * NOTE: This will modify the supplied payload
     *
     * @param {Object} payload - An object with the format of a standard matchmaker input payload. At a very
     *     minimum this payload should have a `solutionsRegistryEntries` key with a hashmap of
     *     (solutionID => solution registry entry) pairs. Note that this object will be modified by
     *     addition of two toplevel keys: `solutionTypes` and `solutionTypeMapping.
     */
    gpii.matchMakerFramework.utils.addCapabilitiesInformation = function (payload) {
        fluid.each(payload.solutionsRegistryEntries, function (solution, solutionId) {
            var capabilities = gpii.matchMakerFramework.utils.computeCapabilitiesFromSolution(solution);
            fluid.set(payload, [ "solutionCapabilities", solutionId ], capabilities);
            fluid.set(payload, [ "specialCapabilities", solutionId ], gpii.matchMakerFramework.utils.extractSpecialCapabilities(capabilities));
        });
    };

    /**
     * Adds information about the solutions types to the payload parameter, which should be in the
     * format of an input payload for matchmakers.
     *
     * Two keys are added to the given payload:
     * `solutionTypes` is a hash of solutionId->list of the solution types it is
     * `solutionTypeMapping` is a hash of solutionType->array of solutionIds of that type
     *
     * NOTE: this function will modify the supplied `payload`
     *
     * @param {Object} payload - An object with the format of a standard matchmaker input payload. At a very
     *     minimum this payload should have a `solutionsRegistryEntries` key with the solution entries as well
     *     as a 'solutionCapabilities' key, which contains information about a solutions capabilities (i.e. via
     *     the addCapabilitiesInformation function).
     * @param {Object} transformSpec - ontology transform spec translating from common terms into
     *     a solution type ontology.
     */
    gpii.matchMakerFramework.utils.addSolutionTypeInformation = function (payload, transformSpec) {
        fluid.each(payload.solutionCapabilities, function (capabilities, solutionId) {
            // first get an array of what solution types the current entry is:
            var solutionTypes = gpii.matchMakerFramework.utils.transformCapabilitiesToOntologizedLeaves(capabilities, transformSpec);
            fluid.set(payload, [ "solutionTypes", solutionId], solutionTypes);
            // now add solution ID to the return array in the appropriate places:
            for (var i in solutionTypes) {
                // add solution ID to the solution type
                fluid.set(payload, ["solutionTypeMapping", solutionTypes[i], solutionId], true);
            }
        });
    };

    gpii.matchMakerFramework.utils.isApplicationTerm = function (term) {
        return term.startsWith("http://registry.gpii.net/applications/");
    };

    gpii.matchMakerFramework.utils.isCommonTerm = function (term) {
        return term.startsWith("http://registry.gpii.net/common/");
    };

    gpii.matchMakerFramework.utils.applicationIdFromTerm = function (term) {
        return term.substring("http://registry.gpii.net/applications/".length);
    };

    gpii.matchMakerFramework.utils.makeApplicationTerm = function (applicationId) {
        return "http://registry.gpii.net/applications/" + applicationId;
    };

    /**
     * Given a preference set, return a nested structure of context->appliactionBlock->special setting->value
     * and context->special setting->value.
     *
     * This function will walk an preference set and look for any /enabled terms. Anything that is not an /enabled
     * term will not be kept. A structure is returned containing the contexts on the outer level. Each prefsSet
     * will have any non application specific /enabled terms, as well as any application block with its contained
     * /enabled terms.
     *
     * @param {Object} preferences - A preference set
     * @return {Object} The preference set with only prefsSet names and /enabled terms
    */
    gpii.matchMakerFramework.utils.findSpecialPreferences = function (preferences) {
        return fluid.transform(fluid.copy(preferences.contexts), function (prefsSet) {
            var togo = {};
            fluid.each(prefsSet.preferences, function (prefsBlock, prefsId) {
                if (prefsId.endsWith("/enabled")) {
                    togo[prefsId] = prefsBlock;
                } else if (gpii.matchMakerFramework.utils.isApplicationTerm(prefsId)) {
                    var applicationId = gpii.matchMakerFramework.utils.applicationIdFromTerm(prefsId);
                    fluid.each(prefsBlock, function (appPrefVal, appPrefId) {
                        if (appPrefId.endsWith("/enabled")) {
                            fluid.set(togo, [ applicationId, appPrefId ], appPrefVal);
                        }
                    });
                }
            });
            return togo;
        });
    };

    gpii.matchMakerFramework.utils.updateSingleInferredConfiguration = function (inferredConfiguration, prefsSet, pref, value, solutionId, upperLevelApplicationTerm) {
        if (solutionId) {
            var path = gpii.matchMakerFramework.utils.isCommonTerm(pref) ?
                [ prefsSet, "applications", solutionId, "settings", pref ] :
                [ prefsSet, "applications", solutionId, "settings", upperLevelApplicationTerm, pref ];
            if (fluid.get(inferredConfiguration, path) !== undefined) {
                fluid.set(inferredConfiguration, path, value);
            }
        } else {
            // if solutionId is not provided, loop through all solutions and update the preference value
            // (if the preference is already set in the solution)
            fluid.each(inferredConfiguration[prefsSet].applications, function (sol) {
                if (sol.settings[pref] !== undefined) {
                    sol.settings[pref] = value;
                }
            });
        }
    };

    /*
     * Takes a set of preferences and runs through the inferredConfiguration, updating all instances
     * matching preferences/settings within the application with the new values from the preferences
     * set.
     *
     * This feature is required by the PSP to allow updating e.g. a top-level common term and
     * ensuring that the relevant applications are affected by it
     */
    // TODO: This utility is mysteriously only called from gpii.lifecycleManager.applyExistingPrefs and so this linkage between /enabled preferences and solution.active
    // is only applied during "update"
    gpii.matchMakerFramework.utils.updateInferredConfiguration = function (preferences, inferredConfiguration, solutionsRegistryEntries) {
        var inferred = fluid.copy(inferredConfiguration);
        fluid.each(preferences.contexts, function (prefsSet, prefsSetName) {
            fluid.each(prefsSet.preferences, function (val, pref) {
                if (gpii.matchMakerFramework.utils.isCommonTerm(pref)) {
                    gpii.matchMakerFramework.utils.updateSingleInferredConfiguration(inferred, prefsSetName, pref, val);
                } else if (gpii.matchMakerFramework.utils.isApplicationTerm(pref)) {
                    var solutionId = gpii.matchMakerFramework.utils.applicationIdFromTerm(pref);
                    fluid.each(val, function (solPrefVal, solPref) {
                        gpii.matchMakerFramework.utils.updateSingleInferredConfiguration(inferred, prefsSetName, solPref, solPrefVal, solutionId, pref);
                    });
                }
            });
            // get active value from */enabled preferences:
            fluid.each(inferred[prefsSetName].applications, function (solutionBlock, solutionId) {
                var solutionCapabilities = fluid.get(solutionsRegistryEntries, [ solutionId, "capabilities" ]) || {};
                var active = gpii.matchMakerFramework.utils.getActiveValueFromEnabledTerms(prefsSet.preferences, solutionCapabilities,
                        solutionsRegistryEntries[solutionId], solutionId);
                if (active !== undefined) {
                    solutionBlock.active = active;
                }
            });
        });
        return inferred;
    };

    /*
     * Given an inferred configuration this function creates a listing of "allowed" preferences and settings,
     * meaning a list of settings and preferences present in the inferred configuration. Any common term
     * encountered in the inferred configuration is added to the list as top level keys with a value of true. Any application
     * specific term will be added under a top level key of: "http://registry.gpii.net/applications/<app-id>". The
     * resulting "allowed" list will be built based on preferences and settings from all the preferences sets in the
     * inferred configuration (i.e. all the "contexts:" of the preference set)
     */
    gpii.matchMakerFramework.utils.extractAllowedPreferences = function (inferredConfiguration) {
        var allowed = {};
        fluid.each(inferredConfiguration, function (prefsSet) {
            fluid.each(prefsSet.applications, function (app, appId) {
                allowed["http://registry.gpii.net/applications/" + appId] = {}; // mark the solution in allowed
                fluid.each(app.settings, function (val, term) {
                    if (term.startsWith("http://registry.gpii.net/applications/")) {
                        allowed[term] = val; // copy all application specific values to a flat application block key
                        return;
                    }
                    allowed[term] = true;
                });
            });
        });
        return allowed;
    };

    /*
     * Filter a preference set based on the preferences available in the inferred configuration. This is used to
     * ensure that no preferences are passed in the preference set that are not already given via the inferred configuration,
     * which is useful for the something like the untrusted flowmanager model.
     */
    gpii.matchMakerFramework.utils.filterPreferencesFromInferredConfig = function (preferences, inferredConfiguration) {
        // Get the list of allowed terms
        var allowed = gpii.matchMakerFramework.utils.extractAllowedPreferences(inferredConfiguration);

        var togo = fluid.censorKeys(preferences, ["contexts"]);
        togo.contexts = fluid.transform(fluid.copy(preferences).contexts, function (prefsSet) {
            prefsSet.preferences = fluid.remove_if(prefsSet.preferences, function (val, term) {
                // if it's an application block
                if (term.startsWith("http://registry.gpii.net/applications/")) {
                    if (allowed[term] === undefined) { // if the application is not in the allowed terms, remove it
                        return true;
                    }

                    fluid.remove_if(val, function (appVal, appTerm) {
                        // remove if not found as top level common term and it's not in the application specific allowed
                        // terms block
                        return (allowed[appTerm] !== true && (fluid.get(allowed, [ term, appTerm ]) === undefined));
                    });
                } else {
                    return allowed[term] !== true;
                }
            });
            return prefsSet;
        });
        return togo;
    };

    gpii.matchMakerFramework.utils.livenessOrdering = [
        "OSRestart",
        "manualRestart",
        "liveRestart",
        "live"
    ];

    /**
     * Given one or more solutions registry entries and optionally a term, this function will walk each
     * solution (and its settingshandlers) and find the lowest liveness for any of the solutions. If a term is
     * given, the liveliness reported is the lowest of those settingshandlers which supports that term
     * (decided via its capabilities and/or capabilitiesTransformations). The lowest or least
     * liveness is dictated by gpii.matchMakerFramework.utils.livenessOrdering, where a lower
     * index means less/lower liveness.
     *
     * @param {Array<Object>} solutions - A list of the solutions that should be search for support of the term.
     * @param {String} [term] - [optional] The term to find the liveness for.
     * @return {String} Returns the lowest/least liveness found by any solution provided that supports the term.
     */
    gpii.matchMakerFramework.utils.getLeastLiveness = function (solutions, term) {
        var leastLiveness;
        fluid.each(solutions, function (solution) {
            fluid.each(solution.settingsHandlers, function (handler) {
                if (term !== undefined) {
                    // if term is defined, only check liveness of block if the term is within the capabilities
                    // of the block. If not, simply skip to next block
                    var capabilities = gpii.matchMakerFramework.utils.extractCapabilities(handler);
                    if (capabilities && capabilities.indexOf(fluid.pathUtil.composeSegments(term)) === -1) {
                        return;
                    }
                }

                // if the liveness of term in current solution is lower than any previously checked solutions
                var livenessOrder = gpii.matchMakerFramework.utils.livenessOrdering.indexOf(handler.liveness);
                if (leastLiveness === undefined || livenessOrder < leastLiveness) {
                    leastLiveness = livenessOrder;
                }
            });
        });
        return gpii.matchMakerFramework.utils.livenessOrdering[leastLiveness];
    };
})();