Configuration

Finsemble is a configuration-driven platform. Configuration is your way to manage a large system logically: you can assemble your config from multiple pieces. Additionally, Finsemble’s config is dynamic, so your smart desktop can adapt to entitlements, environments, and preferences.

Finsemble's configuration is pulled from JSON files on start-up and made available to all components and services for reference. Configuration can be partitioned into two main categories: Finsemble's core configuration and Finsemble's application-level configuration. Typically, when developing Finsemble smart desktops, a developer uses the application-level configuration, contained in ../configs/application/config.json.

This tutorial describes the underlying structure of how Finsemble uses configuration.

For a complete reference, you can take a look at the config reference tree here.

Start-up

Finsemble starts as directed by the manifest file located in your repo at ../configs/application/manifest-local.json. Immediately after start-up, Finsemble spawns the Config Service to dynamically assemble the full Finsemble configuration. The Config Service is started early so it is always available to other components and services through the Config Client API. The Config Service follows these steps:

Step 1: Pull in the Finsemble properties that are defined within the manifest file (you can see the finsemble property at the bottom of the manifest file). This provides enough Finsemble configuration to bootstrap the rest of Finsemble and assemble the complete configuration.
Step 2: Pull in the Finsemble core configuration from internal JSON files. These files are stored either on a server or within a development build directory (e.g., "dist") under ../configs/core.
Step 3: Pull in the application-level config, stored in your repository under ../configs/application/config.json.
Step 4: Apply Dynamic Configuration. This is optional, but can be used to distribute different entitlements to different users.
Step 5: Retrieve the user preference configuration from storage.

Each successive "wave" of configuration overlays the previous ones.

After the Finsemble configuration has been assembled by these steps, the Finsemble start-up sequence continues by launching services and components.

Using the Config Client to retrieve Finsemble's configuration

After start-up, the Config Service is available to respond to configuration queries from any service or component. Generally, no service or components should ever read config settings directly from JSON files. Instead, config settings should be retrieved using the Config Client, which interfaces with the Config Service.

The Config Client can return a copy of all or part of the finsemble object. The field value passed through is standard JSON notation. Below are some examples using the Config Client to retrieve configuration data.

Getting the entire Finsemble configuration:

FSBL.Clients.ConfigClient.getValue({ field: "finsemble" }, function (err, finsembleConfig) {
	console.log(finsembleConfig);
});

Getting a list of all the configured components:

FSBL.Clients.ConfigClient.getValue({ field: "finsemble.components" }, function (err, components) {
	console.log(components);
});

Checking config to determine whether a specific beta feature is enabled:

FSBL.Clients.ConfigClient.getValue({ field: "finsemble.betaFeatures.docking.enabled" }, function (err, dockingEnabled) {
	console.log(dockingEnabled);
});

If you use a period "." in any of your names or custom properties, you will need to encapsulate the name as an index per the JSON spec:

FSBL.Clients.ConfigClient.getValue({ field: 'finsemble.components.["My.Custom.Component"].permissions' }, function (
	err,
	components
) {
	console.log(components);
});

Manifest Macros

Macros such as $applicationRoot or $moduleRoot are automatically defined, or may be explicitly set in the manifest, and can be used as substitutions throughout config. You may also create your own custom macros.

See Manifest Macros in the deployment tutorial for information on creating and using macros.

Partitioning Finsemble's configuration using import files

Finsemble's configuration starts in the manifest file. However, Finsemble was designed to easily support multiple configuration files, providing a much better organization for config settings. Because JSON doesn't have any kind of "import" or "include" capabilities, Finsemble defines two special import properties into JSON that can be used by the developer to dynamically import other config files. This importing is part of the start-up "assembling" done by the Config Service. The two properties and their functions are as follows:

"importConfig" defines an array of JSON URLs to be imported into the top-level finsemble object. Note that this will overwrite any existing config settings, with two exceptions:
1. New services defined under finsemble.services will be added to the list of existing services (as opposed to replacing the existing list of services).
2. New components defined under finsemble.components will be added to the list of existing components (as opposed to replacing the list of existing components).
Regardless of the two exceptions above, a new service or component with the same name as an existing one will replace the existing definition.
"importThirdPartyConfig" defines an array of JSON URLs to be imported into the top-level finsemble object. This import is essentially the same as importConfig with one notable difference: the imported configuration settings cannot overwrite any existing settings. In this case, the settings for any potential overwrite will be discarded with a warning message written to the Config Service's log.

Again, the following snippet from the manifest file shows the application-level config is being pulled from another file.

    "finsemble": {
        "applicationRoot": "http://localhost:3375/yourSubDirectory/dist",
        "moduleRoot": "http://localhost:3375/yourSubDirectory/node_modules/@finsemble/finsemble-core/dist",
        "importConfig": [
            "$applicationRoot/configs/application/config.json"
        ]
    }

Below are the seed project's contents for that import file, configs/application/configs.json. Note that four more config files are imported at the bottom.

	"importConfig": [
		"$applicationRoot/configs/application/UIComponents.json",
		"$applicationRoot/configs/application/appd.json",
		"$applicationRoot/configs/application/workspaces.json",
		"$applicationRoot/configs/application/services.json"
	]
	}

The Central Logger is a unified console for viewing messages across all components and services. It can be used to view import errors and debug the configuration process.

More on configuration format and imports

It is important to understand that all configuration properties are always inserted directly under the finsemble object, independent from where the import occurred. In other words, regardless of where the JSON data is pulled from, it is always defined under finsemble.

For example, consider the following import contents contained in the file someConfig.json:

	{
		"myConfigValue": {
			"first": 1,
			"last": 99
		},
		"myOtherConfigValue": 456,
		"services": {
			"aChatService": {
					"visible": false,
					"active": true,
					"name": "aChatService",
					"html": "achat/chat.html",
					"file": "achat/chatService.js"
			}
		},
		"importConfig": [
			"configs/application/myOtherConfig.json"
		]
	}

This references the import file configs/application/myOtherConfig.json with the following contents:

	{
		"myConfigValue": {
			"first": 0,
			"last": 100
		},
		"myNewConfigValue": 0,
	}

After the first pass of processing the data (all data but the imports) in someConfig.json, the equivalent of the following will exist in the finsemble object:

	finsemble.myConfigValue = {"first": 1, "last": 99};
	finsemble.myOtherConfigValue = 456;
	finsemble.services.aChatService = {"visible": false, "active": true, ...};

Then, after configs/application/myOtherConfig.json is imported (from the importConfig), the finsemble object will effectively contain:

	finsemble.myConfigValue = { "first": 0, "last": 100};
	finsemble.myOtherConfigValue = 456;
	finsemble.myNewConfigValue = 0;
	finsemble.services.aChatService = {"visible": false, "active": true, ...};

Note the value of myConfigValue was overwritten by the import. Also, a new value named myNewConfigValue was added.

User preferences

User preferences are developer-defined options that give end users the ability to fine-tune their Finsemble experience. They are set prior to the initialization of the Finsemble services, and are applied to the main configuration, overriding or augmenting it (similar to dynamic configuration) with the user's chosen settings. The user can only modify what you give them access to.

User preferences are the last configuration applied. Thus, they will always overwrite any config that comes before it. This means they are powerful and should be implemented carefully.

The API methods for preferences are FSBL.Clients.ConfigClient.setPreference and FSBL.Clients.ConfigClient.getPreferences.

Our seed project includes an example implementation that allows users to customize the following configs:

Specify a time for Finsemble to automatically restart itself.
Specify which workspace will load on start-up.

Additionally, if you have Finsemble Connect, the user preferences panel allows you to import and export workspaces.

Additional notes

Each URL in a list of imports will be completely assembled before going to the next URL in the list. Given that any imported file can contain other imports, the process of importing operates recursively in a depth-first fashion. This provides a well-defined ordering when imports redefine config settings.
importConfig and importThirdPartyConfig are always processed last in a file, independent from where they are placed in the JSON. For this reason it's a good practice to put imports at the bottom.
Any property directly defined under finsemble that matches the RegEx /comment.*/ will be stripped out at run-time (e.g., finsemble.comment, finsemble.comment1).
Configuration processing, as well as error reporting, can be seen in the Config Service's console output.

Finsemble is a configuration-driven platform. Configuration properties are always inserted directly under the Finsemble object, independent from where the import occurred.