Storing Data

The Finsemble Storage Client interfaces with the Storage Service to provide a central location for persistent storage and retrieval of application data across multiple component windows and services.

The Storage Client API supports a key-value store. However, there's nothing preventing you from attaching your own virtual store that bridges to another database model.

The Storage Client delivers one form of cross-origin resource sharing (CORS), specifically cross-origin storage. If you don't care about cross-origin storage (or the other storage features the Storage Client provides), you have the option to bypass the Storage Client and directly access HTML5's localStorage from your component window. However, by using our Storage Client, different data stores can be transparently used, multiple users can be supported, and future storage enhancements can be inherited (e.g., storage backup, migration, permissions).

The high-level storage architecture looks something like this:

Using the Storage Client API

The Storage Client comes with three Finsemble enhancements:

  1. All storage is by username, which is specified by the Authentication Service invoking the StorageClient.setUser method during startup—because the username is always set automatically, you never need to do it. If authentication is disabled, the underlying Authentication Service still sets the username to "defaultUser." This implies that changing the username (i.e., logging on through the Authentication Service with a different username) will change the storage being accessed. A new username always starts with empty storage.
  2. All storage is also partitioned by topic, which is akin to a namespace to prevent key conflicts. All of Finsemble's core storage uses "finsemble" as the topic. Application developers can use any topic they choose, which might be a application name or a company name.
  3. Storage's underlying data store can be selected by topic using the StorageClient.setStore method. This allows a specific component's storage to be redirected to it's own data store (e.g., Redis, Data Bridge) independent from Finsemble's default data store.


The Storage Service can utilize "topics," allowing developers to determine where their data is saved. This allows developers to save some data locally and other data to the network.

Finsemble uses three storage topics.

  • Finsemble.workspace is storage for the workspace and is only accessed when workspaces are initialized or explicitly saved by the user.
  • Finsemble.workspace.cache is temporary storage for high-frequency updates (e.g., window moves, resizes, opens, closes). Typically this should be assigned to LocalStorageAdapter.
  • Finsemble is general topic than contains everything outside of the workspace. This has low frequency usage—very little falls under this topic currently.

You can (and should) define your own topics for storage. The topics you define can be mapped to any adapter by inserting a corresponding entry under topicToDataStoreAdapters: the property name (e.g., Finsemble.workspace) must be the topic and the property value (e.g., LocalStorageAdapter) must be the adapter.

Custom Data Storage

The Storage Client uses an adapter to save and retrieve data from a data store. Because we wanted Finsemble to use localStorage, we built the Local Storage Adapter. Check out the adapter on Github. A prototype data store built on Redis is also available on request. If you want to utilize a data store besides localStorage—such as a remote database, Oracle's relational database, or MongoDB—you simply need to build an adapter that interfaces the Storage Client API with that data store.

Our adapter is provided as an example: feel free to modify, add to, and customize it for your purposes.

Similar to our example, your adapter must extend our base storage model and override all the required methods in the model (listed below). You can specify different storage adapters by topic at runtime using the setStore method in the Storage Client API. Remember, all storage is partitioned by topic, which is akin to a namespace to prevent key conflicts. All of Finsemble's core storage uses "finsemble" as the topic. You can use any topic you choose, for example your application or a company's name.

If you are using our seed build process, you can add your files to be built in the webpack.files.entries.json file in a similar method to the Local Storage Adapter.

Required methods for your adapter

When building an adapter, remember that Finsemble supports only the key-value store by topic. When you build you adapter, it needs to have the following required methods:

  • Save: Saves a key value pair for a specific topic.
  • Get: Gets a key value pair for a specific topic.
  • Delete: Deletes a key value pair for a specific topic.
  • Empty: Deletes everything in the storage.
  • Keys: Gets a list of all keys for a specific topic.


In your Finsemble config, you can specify storage adapters in the storage setting:

"storage": {
    "topicToDataStoreAdapters" : {
    "Finsemble" : "LocalStorageAdapter",
    "Finsemble.workspace" : "LocalStorageAdapter",
    "Finsemble.workspace.cache" : "LocalStorageAdapter"
    "dataStoreAdapters" : {
      "LocalStorageAdapter": "$applicationRoot/adapters/LocalStorageAdapter.js"

You can specify the default adapter using the defaultStorage setting:

"defaultStorage": "LocalStorageAdapter"

Storage config is processed during the initialization of the storage services, so all related config settings will take place before any storage clients are initialized. If a topic doesn't have a storage adapter in the config, it defaults to the "defaultStorage" value. If no "defaultStorage" value exists, it then defaults to localStorage.

check   The Storage Client API supports a key-value store, but you are encouraged to attach your own virtual store that bridges to another database model.

Further reading

Advanced information about storing data can be found in the Storage Client documentation.

Read the Router tutorial to better understand how Finsemble sends and receives messages.