Module: ConfigClient

This client provides run-time access to Finsemble's configuration. The Config Client functions similar to a global store created with the Distributed Store Client and offers many of the same methods. Values modified at runtime are not persisted.

See the Configuration tutorial for a configuration overview.

Type Aliases

FieldAndValueParam

Ƭ FieldAndValueParam: Object

Type declaration

Name	Type
`field`	`string`
`value`	`any`

FieldAndValueParams

Ƭ FieldAndValueParams: FieldAndValueParam[] | string[]

FieldOnlyParam

Ƭ FieldOnlyParam: Object

LEGACY Types

Type declaration

Name	Type
`field`	`string`

FieldPathArray

Ƭ FieldPathArray: Object

Type declaration

Name	Type
`field`	`PathArray`

FieldPathArrayAndValue

Ƭ FieldPathArrayAndValue: FieldPathArray & { value: any }

ListenerFunction

Ƭ ListenerFunction<T>: (err: StandardError, response: { field: string ; value: T }) => void

Type parameters

Name	Type
`T`	`any`

Type declaration

▸ (err, response): void

Parameters

Name	Type
`err`	`StandardError`
`response`	`Object`
`response.field`	`string`
`response.value`	`T`

Returns

void

ListenerParam

Ƭ ListenerParam: Object

Type declaration

Name	Type
`field`	`string`
`listener`	`ListenerFunction`

PathArray

Ƭ PathArray: string[]

Represents a json path in array format eg: finsemble.appd[my.App].manifest = ["finsemble", "appd", "my.App", "manifest"]

PathArrayListenerParam

Ƭ PathArrayListenerParam: Object

Type declaration

Name	Type
`field`	`PathArray`
`listener`	`ListenerFunction`

ProcessAndSetCallback

Ƭ ProcessAndSetCallback: StandardErrorCallback<QueryResponse<Manifest>>

RemoveListenersType

Ƭ RemoveListenersType: ListenerParam | ListenerParam[] | PathArrayListenerParam | PathArrayListenerParam[]

Functions

addListener

▸ addListener<T>(params, fn, cb?): Promise<void>

Add a listener to the config at either the root config level or field level. If no field is given, the root config level is used. You can also listen for changes to config fields any number of levels deep -- finsemble.configitem.deeperconfigitem.evendeeperconfigitem

const myFunction = function (err, data) {};

FSBL.Clients.ConfigClient.addListener({ field: "field1" }, myFunction, cb);
FSBL.Clients.ConfigClient.addListener(["field1", "property1"], myFunction, cb); // field1.property1

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`params`	`PathArray` \| { `field`: `null` \| `string` }	-
`fn`	`ListenerFunction`<`T`>	The function to be called when the observed piece of config is modified.
`cb?`	() => `void`	Callback to be invoked after the listener is added.

Returns

Promise<void>

addListeners

▸ addListeners<T>(params, fn, cb?): undefined | Promise<void>

Add an array of listeners as objects, strings or path arrays. If using strings, you must provide a function callback as the second parameter.

const myFunction = function (err, data) {};
FSBL.Clients.ConfigClient.addListeners(
  [
    { field: "field1", listener: myFunction },
    { field: "field2", listener: myFunction },
  ],
  null,
  cb,
);

FSBL.Clients.ConfigClient.addListeners(
  [{ field: "field1" }, { field: "field2", listener: myFunction }],
  myFunction,
  cb,
);

FSBL.Clients.ConfigClient.addListeners(["field1", "field2"], myFunction, cb);

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`params`	`string`[] \| `ListenerParam`[] \| `PathArrayListenerParam`[]	-
`fn`	`ListenerFunction`<`T`>	The function to be called when the observed piece of config is modified.
`cb?`	() => `void`	Callback to be invoked after the listeners are added.

Returns

undefined | Promise<void>

get

▸ get<T>(path, cb?): StandardPromise<T>

Get a value from the config.

If a field does not exists in the configuration, data will be undefined and err will be null.

If you pass path as null or an empty path the entire config is returned.

FSBL.Clients.ConfigClient.get(
  ["field1", "property1"], // field1.property1
  function (err, value) {},
);

const { err, data } = await FSBL.Clients.ConfigClient.get(
  ["field1", "property1"], // field1.property1
);

note

In Java, this method is named getValue.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`path`	`null` \| `PathArray`	-
`cb?`	`StandardErrorCallback`<`T`>	Will return the value if found.

Returns

StandardPromise<T>

getManifest

▸ getManifest(cb?): StandardPromise<Manifest>

Retrieves the entire manifest

FSBL.Clients.ConfigClient.getManifest(function (err, value) {});
const { err, data } = await FSBL.Clients.ConfigClient.getManifest();

Parameters

Name	Type
`cb?`	`StandardErrorCallback`<`Manifest`>

Returns

StandardPromise<Manifest>

getMultiple

▸ getMultiple<T>(paths, cb?): StandardPromise<T>

Get multiple values from the config.

If a field does not exists in the configuration, data will be undefined and err will be null.

FSBL.Clients.ConfigClient.getMultiple(
  [
    // field1.property1.subproperty1
    ["field1", "property1", "subproperty1"],

    // field1.property2
    ["field1", "property2"],
  ],
  (err, values) => {
    if (!err) {
      console.log("Values: ", values);
    }
  },
);

const { err, data } = await FSBL.Clients.ConfigClient.getMultiple([
  // field1.property1.subproperty1
  ["field1", "property1", "subproperty1"],

  // field1.property2
  ["field1", "property2"], // field1.property2
]);
if (!err) {
  console.log("Values: ", data);
}

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`paths`	`PathArray`[]	-
`cb?`	`StandardErrorCallback`<`T`>	Will return the value if found.

Returns

StandardPromise<T>

getPreferences

▸ getPreferences(cb?): StandardPromise<null | Record<string, any>>

Retrieves all of the preferences set for the application.

FSBL.Clients.ConfigClient.getPreferences((err, preferences) => {
  if (!err) {
    console.log(preferences); // an object containing the entire user preferences.
  }
});
const { err, data } = await FSBL.Clients.ConfigClient.getPreferences();

Parameters

Name	Type
`cb?`	`StandardErrorCallback`<`null` \| `Record`<`string`, `any`>>

Returns

StandardPromise<null | Record<string, any>>

getValue

▸ getValue<T>(params, cb?): StandardPromise<T>

deprecated - Use FSBL.Clients.ConfigClient.get() instead.

Get a value from the config.

FSBL.Clients.ConfigClient.getValue(
  { field: "field1" },
  function (err, value) {},
);
FSBL.Clients.ConfigClient.getValue("field1", function (err, value) {});
const { err, data } = await FSBL.Clients.ConfigClient.getValue({
  field: "field1",
});
const { err, data } = await FSBL.Clients.ConfigClient.getValue("field1");

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`params`	`string` \| `FieldOnlyParam`	-
`cb?`	`StandardErrorCallback`<`T`>	Will return the value if found.

Returns

StandardPromise<T>

getValues

▸ getValues<T>(fields?, cb?): StandardPromise<Record<string, T>>

deprecated - Use FSBL.Clients.ConfigClient.getMultiple() instead.

Get multiple values from the config.

caution

Deprecated functionality: If there are no fields provided, the complete configuration manifest is returned (use getManifest()).

FSBL.Clients.ConfigClient.getValues(
  ["field1", "field2"],
  function (err, values) {},
);
FSBL.Clients.ConfigClient.getValues(null, callback); // returns the complete manifest containing the finsemble property
const { err, data } = await FSBL.Clients.ConfigClient.getValues([
  "field1",
  "field2",
]);

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`fields?`	`null` \| `string`[] \| `FieldOnlyParam`[]	An array of objects containing a field property or an array of string field names.
`cb?`	`StandardErrorCallback`<`Record`<`string`, `T`>>	Will return the value if found.

Returns

StandardPromise<Record<string, T>>

processAndSet

▸ processAndSet(params, cb?): StandardPromise<Manifest>

Dynamically set config values within the Finsemble configuration. You can set new config properties or modify existing ones. Note that configuration changes will not necessarily dynamically modify the components or services that use the corresponding configuration -- it depends if the component or service handles the corresponding change notifications (either though PubSub or the config's DataStore). Also, these changes do not persist in any config files.

Only services and components that reside on the same domain as Finsemble can use proessAndSet. If you want to use it from a domain other than Finsemble, you can't do so directly. Instead, you need to set up a proxy service that is hosted on the same domain as Finsemble. Because this proxy server is on the same domain as Finsemble, it can use processAndSet. Now, you can have an externally hosted service or app communicate with this proxy service.

Here is an example:

Create a proxy app service on the Finsemble domain and make it subscribe to a channel (for example, "customerName.app.config").
The cross domain app publishes the new config on that same channel ("customerName.app.config").
When the proxy app service receives this request, it invokes ConfigClient.processAndSet(...) using the payload from the router message.

note

Any time you set config by using this API, the newConfig along with the updated manifest will by published to the PubSub topic "Config.changeNotification". To get these notifications any component or service you can subscribe to the topic. See an example below.

note

Anytime you set config by using this API, the dataStore underlying configuration 'Finsemble-Configuration-Store' will also be updated. To get these dataStore events, you can set a listener as shown in the example below. However, any config modifications made directly though the DataStore will not result in corresponding PubSub notifications.

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. For example, use this setting to prevent system UI components from being dropped out of the config.

// Examples using processAndSet()
FSBL.Clients.ConfigClient.processAndSet({
  newConfig: { myNewConfigField: 12345 },
  overwrite: false,
});
FSBL.Clients.ConfigClient.processAndSet(
  {
    newConfig: {
      myNewConfigField: 12345,
      myNewConfigObject: {
        A: "this is a test",
        B: "more test",
      },
      importConfig: ["$applicationRoot/configs/application/test.json"],
    },
    overwrite: true,
    replace: false,
  },
  function (err, finsemble) {
    if (err) {
      console.error("ConfigClient.set", err);
    } else {
      console.log("new finsemble config", finsemble);
    }
  },
);

// example subscribing to PubSub to get notifications of dynamic updates
RouterClient.subscribe("Config.changeNotification", function (err, notify) {
  console.log("set notification", notify.data.newConfig, notify.data.finsemble);
});

// example using DataStore to get notifications of dynamic updates
DistributedStoreClient.getStore(
  { store: "Finsemble-Configuration-Store", global: true },
  function (err, configStore) {
    configStore.addListener(
      { field: "finsemble" },
      function (err, newFinsembleConfig) {
        console.log("new manifest.finsemble configuration", newFinsembleConfig);
      },
    );
  },
);

Parameters

Name	Type	Description
`params`	`Object`
`params.newConfig`	`Record`<`string`, `any`>	Provides the configuration properties to add into the existing configuration under manifest.finsemble. This config must match the Finsemble config requirements as described in the Configuration tutorial. It can include importConfig references to dynamically fetch additional configuration files.
`params.overwrite`	`boolean`	If true then overwrite any preexisting config with new config (can only set to true when running from same origin, not cross-domain); if false then newConfig must not match properties of existing config, including service and component configuration.
`params.replace`	`boolean`	True specifies any component, app, or service definitions in the new config will place all existing non-system component and service configuration
`cb?`	`ProcessAndSetCallback`	-

Returns

StandardPromise<Manifest>

remove

▸ remove<T>(path, cb?): StandardPromise<T>

Remove a value (and its key) from the config.

Removing a value will trigger events that you can listen to using addListener().

FSBL.Clients.ConfigClient.remove(
['field1', 'property1'],  // field1.property1
function(err,value){ }
);

const {err, data} = await FSBL.Clients.ConfigClient.remove(
['field1', 'property1']); // field1.property1

note

In Java, this method is named removeValue.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`path`	`PathArray`	-
`cb?`	`StandardErrorCallback`<`T`>	Optional callback.

Returns

StandardPromise<T>

removeListener

▸ removeListener(params, fn, cb?): void

Remove a listener from config. If no field is given, we look for a config root listener

let myFunction = function (err, data) {};

FSBL.Clients.ConfigClient.removeListener(
  { field: "field1" },
  myFunction,
  function (err, bool) {},
);
FSBL.Clients.ConfigClient.removeListener(myFunction, function (err, bool) {});
FSBL.Clients.ConfigClient.removeListener(
  ["field1"],
  myFunction,
  function (err, bool) {},
);

Parameters

Name	Type	Description
`params`	`PathArray` \| { `field`: `null` \| `string` }	-
`fn`	`ListenerFunction`<`any`>	The listener to remove.
`cb?`	`Function`	Returns true if it was successful in removing the listener.

Returns

void

removeListeners

▸ removeListeners(params, fn?, cb?): void

Remove an array of listeners from the config

let myFunction = function (err, data) {};
FSBL.Clients.ConfigClient.removeListeners(
  {
    field: "field1",
  },
  MyFunction,
  function (bool) {},
);

FSBL.Clients.ConfigClient.removeListeners(
  [{ field: "field1", listener: MyFunction }],
  function (bool) {},
);

FSBL.Clients.ConfigClient.removeListeners(
  ["field1"],
  MyFunction,
  function (bool) {},
);

Parameters

Name	Type	Description
`params`	`RemoveListenersType`
`fn?`	`ListenerFunction`<`any`>	The listener to remove
`cb?`	`StandardErrorCallback`<`boolean`>	Returns true if it was successful in removing the listener.

Returns

void

removeMultiple

▸ removeMultiple<T>(paths, cb?): StandardPromise<T>

Remove multiple values (and their keys) from the config.

Removing a value will trigger events that you can listen to using addListener().

// Remove field1.property1 AND field2.property2
FSBL.Clients.ConfigClient.removeMultiple(
  [
    ["field1", "property1"],
    ["field2", "property2"],
  ],
  function (err, value) {},
);

// Remove field1.property1 AND field2.property2
const { err, data } = await FSBL.Clients.ConfigClient.removeMultiple([
  ["field1", "property1"],
  ["field2", "property2"],
]);

note

In Java, this method is named removeValues.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`paths`	`PathArray`[]	-
`cb?`	`StandardErrorCallback`<`T`>	Optional callback.

Returns

StandardPromise<T>

removeValue

▸ removeValue<T>(params, cb?): StandardPromise<T>

deprecated - Use FSBL.Clients.ConfigClient.remove() instead.

Remove a value from the config.

FSBL.Clients.ConfigClient.removeValue({ field: "field1" }, function (err) {});
FSBL.Clients.ConfigClient.removeValue("field1", function (err) {});

const { err } = await FSBL.Clients.ConfigClient.removeValue({
  field: "field1",
});
const { err } = await FSBL.Clients.ConfigClient.removeValue("field1");

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`params`	`string` \| `FieldOnlyParam`	-
`cb?`	`StandardErrorCallback`<`T`>	Returns an error if there is one

Returns

StandardPromise<T>

removeValues

▸ removeValues(fields, cb?): Promise<{ err: undefined | null | string }>

deprecated - Use FSBL.Clients.ConfigClient.removeMultiple() instead.

Removes multiple values from the config.

FSBL.Clients.ConfigClient.removeValues(["field1"], function (err) {});
const { err } = await FSBL.Clients.ConfigClient.removeValues(["field1"]);

Parameters

Name	Type	Description
`fields`	`string`[] \| `FieldOnlyParam`[]	An array of objects containing a field property or an array of string field names.
`cb?`	`StandardErrorCallback`<`void`>	Returns an error if there is one.

Returns

Promise<{ err: undefined | null | string }>

set

▸ set<T>(path, value, cb?): StandardPromise<T>

Sets a value in the config.

Setting a value will trigger events that you can listen to using addListener().

// Set field1.property1 = "foo"
FSBL.Clients.ConfigClient.set(
  ["field1", "property1"],
  "foo",
  function (err, value) {},
);

// Set field1.property1 = "foo"
const { err, data } = await FSBL.Clients.ConfigClient.set(
  ["field1", "property1"],
  "foo",
);

note

In Java, this method is named setValue.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`path`	`PathArray`	-
`value`	`any`	-
`cb?`	`StandardErrorCallback`<`T`>	Optional callback.

Returns

StandardPromise<T>

setMultiple

▸ setMultiple<T>(pathsAndValues, cb?): StandardPromise<T>

Sets multiple values in the config.

Setting a value will trigger events that you can listen to using addListener().

// Set both field1.property1 = "foo" AND field2.property2 = "bar"
FSBL.Clients.ConfigClient.setMultiple(
  [
    { field: ["field1", "property1"], value: "foo" },
    { field: ["field2", "property2"], value: "bar" },
  ],
  function (err, value) {},
);

// Set both field1.property1 = "foo" AND field2.property2 = "bar"
const { err, data } = await FSBL.Clients.ConfigClient.setMultiple([
  { field: ["field1", "property1"], value: "foo" },
  { field: ["field2", "property2"], value: "bar" },
]);

note

In Java, this method is named setValues.

Type parameters

Name	Type
`T`	`any`

Parameters

Name	Type	Description
`pathsAndValues`	`FieldPathArrayAndValue`[]	-
`cb?`	`StandardErrorCallback`<`T`>	Optional callback.

Returns

StandardPromise<T>

setPreference

▸ setPreference(params, cb?): StandardPromise<void>

Sets a value on the configStore and persists that value to storage. On application restart, this value will overwrite any application defaults.

FSBL.Clients.ConfigClient.setPreference(
  {
    field: "finsemble.initialWorkspace",
    value: "Workspace 2",
  },
  (err, response) => {
    // preference has been set
  },
);

const { err, data } = await FSBL.Clients.ConfigClient.setPreference({
  field: "finsemble.initialWorkspace",
  value: "Workspace 2",
});

Parameters

Name	Type
`params`	`FieldAndValueParam`
`cb?`	`StandardErrorCallback`<`void`>

Returns

StandardPromise<void>

setValue

▸ setValue(params, cb?): Promise<{ err: undefined | null | string }>

deprecated - Use FSBL.Clients.ConfigClient.set() instead.

Set a value in the config. Setting a value will trigger events that you can listen to using addListener().

FSBL.Clients.ConfigClient.setValue(
  { field: "field1", value: "new value" },
  function (err) {},
);
const { err } = await FSBL.Clients.ConfigClient.setValue({
  field: "field1",
  value: "new value",
});

Parameters

Name	Type	Description
`params`	`FieldAndValueParam`	-
`cb?`	`StandardErrorCallback`<`void`>	Optional callback

Returns

Promise<{ err: undefined | null | string }>

setValues

▸ setValues(fields, cb?): Promise<{ err: undefined | null | string }>

deprecated - Use FSBL.Clients.ConfigClient.setMultiple() instead.

Set multiple values in the config.

FSBL.Clients.ConfigClient.setValues([{ field: "field1", value: "new value" }]);
const { err } = await FSBL.Clients.ConfigClient.setValues([
  { field: "field1", value: "new value" },
]);

Parameters

Name	Type	Description
`fields`	`FieldAndValueParams`	-
`cb?`	`StandardErrorCallback`<`void`>	Optional callback

Returns

Promise<{ err: undefined | null | string }>

unsetPreference

▸ unsetPreference(params, cb?): StandardPromise<void>

Reset a user preference value to default. On application restart, the application default value will be used instead of the preference.

FSBL.Clients.ConfigClient.unsetPreference(
  {
    field: "finsemble.initialWorkspace",
  },
  (err, response) => {
    //preference has been unset
  },
);
const { err, data } = await FSBL.Clients.ConfigClient.unsetPreference({
  field: "finsemble.initialWorkspace",
});

Parameters

Name	Type	Description
`params`	`FieldOnlyParam`	The preference field to unset.
`cb?`	`StandardErrorCallback`<`void`>	-

Returns

StandardPromise<void>

Module: ConfigClient

Type Aliases​

FieldAndValueParam​

Type declaration​

FieldAndValueParams​

FieldOnlyParam​

Type declaration​

FieldPathArray​

Type declaration​

FieldPathArrayAndValue​

ListenerFunction​

Type parameters​

Type declaration​

Parameters​

Returns​

ListenerParam​

Type declaration​

PathArray​

PathArrayListenerParam​

Type declaration​

ProcessAndSetCallback​

RemoveListenersType​

Functions​

addListener​

Type parameters​

Parameters​

Returns​

addListeners​

Type parameters​

Parameters​

Returns​

get​

Type parameters​

Parameters​

Returns​

getManifest​

Parameters​

Returns​

getMultiple​

Type parameters​

Parameters​

Returns​

getPreferences​

Parameters​

Returns​

getValue​

Type parameters​

Parameters​

Returns​

getValues​

Type parameters​

Parameters​

Returns​

processAndSet​

Parameters​

Returns​

remove​

Type parameters​

Parameters​

Returns​

removeListener​

Parameters​

Returns​

removeListeners​

Parameters​

Returns​

removeMultiple​

Type parameters​

Parameters​

Returns​

removeValue​

Type parameters​

Parameters​

Returns​

removeValues​

Parameters​

Returns​

set​

Type parameters​

Parameters​

Type Aliases

FieldAndValueParam

Type declaration

FieldAndValueParams

FieldOnlyParam

Type declaration

FieldPathArray

Type declaration

FieldPathArrayAndValue

ListenerFunction

Type parameters

Type declaration

Parameters

Returns

ListenerParam

Type declaration

PathArray

PathArrayListenerParam

Type declaration

ProcessAndSetCallback

RemoveListenersType

Functions

addListener

Type parameters

Parameters

Returns

addListeners

Type parameters

Parameters

Returns

get

Type parameters

Parameters

Returns

getManifest

Parameters

Returns

getMultiple

Type parameters

Parameters

Returns

getPreferences

Parameters

Returns

getValue

Type parameters

Parameters

Returns

getValues

Type parameters

Parameters

Returns

processAndSet

Parameters

Returns

remove

Type parameters

Parameters

Returns

removeListener

Parameters

Returns

removeListeners

Parameters

Returns

removeMultiple

Type parameters

Parameters

Returns

removeValue

Type parameters

Parameters

Returns

removeValues

Parameters

Returns

set

Type parameters

Parameters

Returns