Config Reference

The configuration tree is built from many JSON files which use "$importConfig" as a way to include other JSON files. These JSON files will be found in your seed project's config directory. At runtime, Finsemble assembles this full config tree, which you can access programmatically through the ConfigClient API.

finsemble - The root level config. This will be in the OpenFin manifest.

  • applicationRoot "https://localhost:3375" - Should point to the root of your application. Finsemble will use this to build URLs internally.
  • cssOverridePath "$applicationRoot/assets/css/finsemble-overrides.css" - (Deprecated) For white labeling.
  • debugServiceDelay 0 - (Deprecated) The amount of delay for the service to come online. On Windows 7, the debugger sometimes takes several seconds to appear. You can set this value if you need to debug a service on start-up. This is rarely used.
  • defaultStorage "localStorage" - The default storage model to use when saving and loading data.
  • failedComponentCloseNotification false - Whether to throw a notification when a component fails to close within the time limit specified in finsemble["Window Manager"].componentCloseTimeout
  • isAuthEnabled true - (Deprecated) Turns on authentication. For current methods to enable authentication, click here.
  • moduleRoot "https://localhost:3375/finsemble" - Where you are serving the Finsemble core library from. This is important for resolving URLs internally.
  • shutdownTimeout 10000 - Amount of time (in milliseconds) to give services and components to shutdown before forcibly quitting the application.
  • systemTrayIcon $moduleRoot/assets/img/Finsemble_Taskbar_Icon.png - Sets the location of the system tray icon (lower right corner of the terminal)
  • workspaceTemplates {} - A key-value mapping of workspace templates to be available on application startup.
  • workspaces [] - An array of workspaceDescriptors to be presented to the user the first time they start Finsemble.
  • authentication Configurations related to authentication, including authentication profiles
    • [password profile name] Declare an authentication profile that uses simple password collection or any other type of custom authentication process.
      • adapter "PASSWORD" - Specify that this profile will use the Password adapter.
      • component "defaultAuthorization" - Specify which component to display in order to collect the user's credentials.
    • [OAuth profile name] Declare an authentication profile for an OAuth2 connection to a specific identity provider. This can be used to authenticate against OpenID providers.
      • adapter "OAUTH2" - Specify that this profile will use the OAuth2 adapter.
      • scope "openid" - The "scope" as specified by your IP.
      • client_id "XYZABC" - The client ID provided by your IP.
      • authorization_endpoint "https:/openid.c2id.com/login" - The authorization endpoint for your IP.
      • backchannel_endpoint "https://yoursite/authenticate" - Your backchannel endpoint URL.
      • redirect_url "$applicationRoot/components/authentication/oauthResponse.html" - The component to handle the response from your IP. If you don't provide this, components/authentication/oauthResponse.html will be used.
    • startup When an authentication profile exists with the name "startup" then Finsemble stop booting until the user is authenticated (using any of the available adapter types).
  • betaFeatures Turn on beta features by including them in this section.
    • docking - Docking is when two windows are grouped together by user when they click the "circle" icon.
      • enabled true - Set to true to turn on docking behavior.
    • assimilation - Assimilation of native windows. This only works on Windows operating systems.
      • enabled true - Set to true to turn on Assimilation
      • port 8392 - Assimilation communicates with Finsemble's HTML services via a WebSocket. Set the port here.
      • throttle 15 - Windows sends dozens of events per second when a window is moved. This value tells the application how often to collect those events. You may see performance degradations if you set the throttle below 5.
      • blacklist [] - If onlySpawned is false, this array is a list of applications that assimilation will ignore.
      • whitelist [] - If onlySpawned is false, this array is a list of applications that assimilation will control.
      • onlySpawned true - This Boolean tells assimilation whether it should restrict its scope to external applications spawned by Finsemble. If true, only applications launched from Finsemble will be controlled. If false, it will try to control the movements of all windows on the desktop.
  • components Configurations for components.
    • [component name] The name of the component you are configuring.
      • window Configurations that manage placement of the component on the screen.
      • component Configurations specific to this component. Put any custom configurations for your components in this section.
        • spawnOnStartup false - When true, Finsemble will automatically launch this component when the application starts.
        • spawnOnHotKey ["ctrl","alt","a"] - The component will be launched when this global hotkey combination is activated by the end user.
      • foreign - This section contains configurations that other components and services read when they interact with this component.
        • services - Configurations for services that wish to interact with this component.
          • dockingService - Configurations related to the docking service.
            • isArrangeable true - If false then the docking service will not interfere with the location and size of this component.
          • workspace - Configurations related to the workspace service.
            • persistURL false - When true, the component will automatically persist it's URL through restarts and workspace reloads.
        • components - Configurations specific to other components that wish to interact with this component.
          • App Launcher - App launcher is a drop down menu that launches other components.
            • launchableByUser false - If true, then the App Launcher will include this component in its menu.
          • Toolbar - Configurations related to the global toolbar (at the top of the monitor).
            • iconURL "$applicationRoot/assets/img/Finsemble_Taskbar_Icon.png" - The icon to display when this component is pinned in the toolbar.
            • iconClass "ff-ungrid" - A CSS class character to display when this component is pinned in the toolbar. See "fin-font" or use font-awesome or similar.
          • Window Manager Configurations specific to the component's header bar.
            • alwaysOnTopIcon false - When set to true, the window can be pinned so that it is always on top (like a sticky note).
            • componentCloseTimeout 5000 - Time (in ms) to wait for the component to close successfully. If the component hasn't closed within this limit, it will be force closed.
            • FSBLHeader true - If true then the header will be injected into the component.
            • hackScrollbar true - Unless set to false, a window's scrollbar will be positioned underneath the finsemble window title bar using html{ overflow-y: none} and body{ overflow-y: auto}
            • persistWindowState false - If the component is part of the workspace, this tells Finsemble whether it should persist the position of the window when it moves.
            • showLinker false - Set to true to display the linker drop down in the window header.
            • title string - Set the title for your component. You can also do this programatically through FSBL.Clients.WindowClient.setWindowTitle().
  • preferences
    • workspaceService
      • promptUserOnDirtyWorkspace false - When set to false, the user's workspace automatically saves to the last configuration when switching workspaces or closing Finsemble. When set to true, the user is prompted to save the current workspace configuration.
  • scheduledRestart false - Set Finsemble to automatically restart.
    • These values can be overriden by the user through user preferences.
    • hour 0 - The hour when Finsemble should restart. This is in 24 hour time according to the user's local machine's timezone.
    • minute 0 - The minute when Finsemble should restart.
    • dialogTimeout 10000 - When it is time to restart, the user is presented with a dialog to confirm or cancel. Since resets occur at night while the machine is unattended, most often the dialog will time out and Finsemble will reset. The dialogTimeout specifies how long to wait for a user response in milliseconds.
  • servicesConfigs Configurations for Finsemble's built-in services.
    • dockingService Configs specific to the docking service
      • config
        • ALLOW_GROUPS_TO_SNAP true - Allows groups to snap to one another.
        • BUFFER_SIZE 20 - The zone around a window that will cause it to snap to other windows. This value is in pixels.
        • GROUP_MODE
          • enabled true - Whether to allow windows to group to one another.
          • behavior "explicit" - "Implicit" grouping auto-groups windows that snap to one another. "Explicit" group requires an additional API call (made by our windowHeader) to group windows.
        • MINIMUM_WIDTH 98 - The smallest width to allow a window to shrink on resize.
        • MINIMUM_HEIGHT 28 - The smallest height to allow a window to shrink on resize.
        • RESIZE_EVENT_THROTTLE_PERIOD 0 - Value (in milliseconds) to throttle resize events. If you find that the quantity of resize events is causing poor performance, tweak this value until you are happy with the performance.
        • SNAPPING_OPACITY 0.8 - The opacity windows change to when other windows encroach on their buffer zone.
      • Tabbing
        • enabled true - Whether to allow windows to tab together.
      • Tiling
        • enabled true - Whether to allow windows to tile together.
    • launcher
      • staggerPixels 40 - Set the amount of "stagger" pixels when components are launched on top of another. Staggering is like laying cards out on a table.
    • workspace
      • persistURL false - A Global config for component URL persistence. When true, components automatically save their last URL instead of using the one in the config. The component config will overwrite the global config.
  • splinteringConfig Configuration related to process splintering.
    • enabled true - Whether to enable process splintering. It is highly recommend that you leave this value as true.
    • splinterAgents "[]" - An array of splinterAgents. See the tutorial about process splintering for more.
  • storage Configuration for Storage Adapters
    • dataStoreAdapters - A key-value map of storage adapters that the storage service will load up on application startup.
      • [adapterName] "[adapterPath]" - The keys in this object represent storage adapter names. The values are the paths to the adapters.
    • topicToDataStoreAdapters - This maps storage "topics" to adapters.
      • finsemble "localstorage" - Which storage adapter to use when persisting non-workspace-related information.
      • finsemble.workspace"localstorage" - Which storage adapter to use when persisting workspace information.
      • finsemble.workspace.cache "localstorage" - Which storage adapter to use when persisting data related to the activeWorkspace.
  • Window Manager - Global settings for the window title bar
    • alwaysOnTopIcon true - When set to true, all windows can be pinned so that they are always on top (like a sticky note). You can override this setting for specific components in their config.
    • componentCloseTimeout 5000 - Time (in ms) to wait for a component to close successfully. If the component hasn't closed within this limit, it will be force closed. You can override this setting for specific components in their config.

  • services - Configurations that are available when building services
    • [service name] - The name of the service. i.e., "launcherService", "storageService", etc.
      • visible false - Set to true in order to get a window for the service. Useful for debugging.
      • showDevConsoleOnVisible true - Automatically spawns a dev console when visible is true.
      • active true - Run the service
      • name "workspaceService" - The name of the service
      • html "$servicesRoot/workspace/workspace.html" - The location of the service code

Further reading

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

See LauncherClient.spawn() for more information on configuring components.

For a discussion about dynamic configuration, as opposed to the static configuration described here, check out the Dynamic Configuration tutorial.