Dynamic configuration

At its heart, Finsemble is a config-driven framework. This was a purposeful design decision to allow for easy integration of third-party componentry and to support a user-configurable interface.

The most basic Finsemble implementations are driven by a static configuration, which we describe in the Configuration tutorial. However, many production implementations demand a dynamic configuration. That is, they require that configurations are determined at runtime, either by the application itself or by a remote server. For example, you might want to have Finsemble’s available components or default workspaces vary depending on [user entitlements](/docs/7.x/enterprise/authentication/Authentication. In this scenario, Finsemble could prompt the user for authentication, relay the user’s credentials to a server, and then receive back a configuration for that user.

Only trusted components, i.e., components on the same domain as the the Finsemble services can make changes to the config. Note that changes to the config made at run time do not persist.

Listen for changes to component config

Components can add listeners to listen for changes to their own config and make necessary adjustments. To add a listener:

function configChanged(err, newConfig) {
    // Do what you need to do here with newConfig
}

// Get component type of current component
var componentType = FSBL.Clients.WindowClient.options.customData.component.type;

// Add listener
FSBL.Clients.ConfigClient.addListener({ field: "finsemble.components." + componentType }, configChanged);

In fact, you can use the listener to listen for changes to any config item at any level. So if you only wanted to listen to a change for a property called defaultChartType, you could do this:

FSBL.Clients.ConfigClient.addListener(
    { field: "finsemble.components." + componentType + ".defaultChartType" },
    function (err, defaultChartType) {
        setChartType(defaultChartType);
    }
);

---

Dynamically load components based on authentication

Using dynamic config, you can have a specific Finsemble installation only have certain components accessible based on the user that is authenticated. To do this, you need to modify our sample Authentication component to fetch the components after authentication. You can then either replace the entire finsemble.components config item or add to it by setting finsemble.components.componentType for each component type that you wish to add.

caution

During dynamic configuration, Finsemble can overwrite components already in the configuration when ConfigClient.processAndSet is called. To prevent this from happening, set manifest.component.category = "system" in the config of the component. This setting is used, for example, to prevent system UI components from being dropped out of the config.

---

Example

We also provide an in-depth example of using dynamic configuration.

See also

Read the API documentation about the Config Client for additional information.

Reading the Distributed Store Client documentation can provide deeper context.

Check out Storing Data to learn about how Finsemble stores and retrieves application data.