OpenFin

Configuring Your Application

Suggest Edits

The OpenFin Runtime requires each application to provide a JSON formatted configuration file. This configuration file defines the visual properties of the app, its dependencies, and other deployment settings. The developer is in control of the app development process and how this file is hosted and configured. Both the openfin-cli and OpenFin RVM will use a configuration file to launch applications as well as make use of other configuration data.

{
    "licenseKey": "contract_identifier",
    "runtime": {
        "version": "14.78.46.23"
    },
    "startup_app": {
        "name": "MyApp",
        "uuid": "33aa9062-9eb0-4875-b819-c90f38ef03ea",
        "url": "http://localhost:8000/index.html",
        "autoShow": true,
        "defaultWidth": 500,
        "defaultHeight": 500
    }
}

Top-level properties

Asterisk means properties are mandatory

Properties with an * are mandatory

Property Type Description Default Runtime RVM
startup_app object Contains app-specific properties described below -- 6+ 3+
devtools_port integer You can access the Chromium development tools by navigating to the selected port, i.e.: http://localhost:9090. -- 6+ 3+

startup_app object properties

Property Type Description Default Runtime RVM
name* string The name for the window which must be unique within the context of the invoking Application. -- 6+ 3+
url* string The URL of the window -- 6+ 3+
uuid* string The UUID of the application, unique within the set of all other Applications running in OpenFin Runtime. -- 6+ 3+
alwaysOnTop bool A flag to always position the window at the top of the window stack. false 6+ 3+
applicationIcon string A URL for the icon to be shown in the window title bar.
Note: only .ico files are allowed.
autoShow bool A flag to automatically show the Window when it is created. false 6+ 3+
backgroundColor string The window's backfill color as a hexadecimal value, not to be confused with the content background color. This color briefly fills a window's (a) content area before its content is loaded as well as (b) newly exposed areas when growing a window. Setting this value to the anticipated content background color can help improve user experience. #000 6+ 3+
childWindowAutoAuth bool Allow non API created child windows, such as window.open, to authenticate true 6+ 3+
clearChildSubscriptionsOnReload bool Clear InterApplication subscriptions of all child windows when main window is reloaded true 6+ 3+
contextMenu bool A flag to show the context menu when right-clicking on a window. Gives access to the Developer Console for the Window. true 6+ 3+
contentNavigation object Defines where content can be obtained from null 6+ 3+
cornerRounding.height integer This defines and applies rounded corners for the window. 6+ 3+
cornerRounding.width integer This defines and applies rounded corners for the window. 6+ 3+
customWindowAlert bool Application level event for handling window alerts. To enable an application listen on that application for the event "window-alert-requested" false 6+ 3+
defaultCentered bool Specifies that the window will be positioned in the center of the primary monitor when loaded for the first time on a machine. When the window corresponding to that id is loaded again, the position from before the window was closed is used. false 6+ 3+
defaultHeight integer The default height of the window. Specifies the height of the window when loaded for the first time on a machine. When the window corresponding to that id is loaded again, the height is taken to be the last height of the window before it was closed. 500 6+ 3+
defaultLeft integer The default left position of the window. Specifies the position of the left of the window when loaded for the first time on a machine. When the window corresponding to that id is loaded again, the value of left is taken to be the last value before the window was closed. 10 6+ 3+
defaultTop integer The default top position of the window. Specifies the position of the top of the window when loaded for the first time on a machine. When the window corresponding to that id is loaded again, the value of top is taken to be the last value before the window was closed. 10 6+ 3+
defaultWidth integer The default width of the window. Specifies the width of the window when loaded for the first time on a machine. When the window corresponding to that id is loaded again, the width is taken to be the last width of the window before it was closed. 800 6+ 3+
description string The name for the window which must be unique within the context of the invoking application.
fdc3 boolean Specifies whether to include the FDC3 in your application. --- 15.80.50.*+ 5.6+
frame bool A flag to show the frame. true 6+ 3+
icon string A URL for the icon to be shown in the window title bar OpenFin's icon. 6+ 3+
loadErrorMessage string An error message to display when the application fails to load. A dialog box launches with the error message just before the runtime exits. Load fails such as failed DNS resolutions or aborted connections as well as cancellations, e.g., window.stop(), trigger this dialog. Client response codes such as '404 Not Found' are not treated as fails as they are valid server responses. There was an error loading the application. 6+ 3+
enableAppLogging bool If true, console.log, info, warning, and error messages for the app will be written to the app.log folder false 8.56.29.*+ 4.0.1.1+
logManagement object Object that contains properties for remote log management 8.56.29.*+ 4.4.0.13+
logManagement.enabled bool If true, enables remote app log management false 8.56.29.*+ 4.4.0.13+
logManagement.encryptionKey string If present and logManagement is enabled, will use this key to encrypt an zipped log files before sending them to the specified remote server. Format is a base64 public RSA key. 8.56.29.*+ 4.4.0.13+
logManagement.url string If log management is enabled, this is the url where zipped logs will be sent. https://log-manager.openfin.co 8.56.29.*+ 4.4.0.13+
maxHeight integer The maximum height of a window. Will default to the OS defined value if set to -1. -1 6+ 3+
maximizable bool A flag that lets the window be maximized. true 6+ 3+
maxWidth integer The maximum width of a window. Will default to the OS defined value if set to -1. 0 6+ 3+
minHeight integer The minimum height of a window. 0 6+ 3+
minimizable bool A flag that lets the window be minimized. true 6+ 3+
minimumRVMVersion string Minimum RVM version required to run this app. The RVM will show an error if it attempts to run this app, and its version is less than the specified minimumRVMVersion -- 6+ 4.4.0.13+
minWidth integer The minimum width of a window. 6+ 3+
nonPersistent bool A flag to configure the application as non-persistent. Runtime exits when there are no persistent apps running. false 6+ 3+
opacity float A flag that specifies how transparent the window will be. This value is clamped between 0.0 and 1.0. 1 6+ 3+
permissions object Config object to enable restricted API endpoints for your application. false 12+ 3+
permissions.ExternalWindow object Config object to enable restricted ExternalWindow APIs. false 12+ 3+
permissions.ExternalWindowWrap bool Config object to enable restricted ExternlWindow APIs. false 12+ 3+
permissions.ExternalWindow.System object Config object to enable restricted System APIs. false 12+ 3+
permissions.ExternalWindow.System.downloadAsset bool Enables System.downloadAsset false 12+ 3+
permissions.ExternalWindow.getAllExternalWindows bool Enables getAllExternalWindows false 12+ 3+
permissions.ExternalWindow.launchExternalProcess bool Enables launchExternalProcess false 12+ 3+
permissions.ExternalWindow.readRegistryValue bool Enables readRegistryValue false 12+ 3+
permisExternalWindow.terminateExternalProcess bool Enables terminateExternalProcess false 12+ 3+
plugins bool A flag to enable Flash Player. false 7+ 3+
preloadScripts array An array of objects containing a path to a preload script (e.g., { url: "http://path.to/your/preload_script.js" }). An optional mandatory flag can be specified within each object which, if set to false, will run subsequent scripts if the current one fails to load. For local files (which are retrieved but not cached), use the file:// protocol (e.g., "file:///path/to/your/preload_script.js"). 6+ 3+
resizable bool A flag to drop to allow the user to resize the window. true 6+ 3+
resizeRegion.size integer Defines a region in pixels that will respond to user mouse interaction for resizing a frameless window. 2 6+ 3+
resizeRegion.bottomRightCorner integer Defines a region in pixels of an additional square at the bottom right corner of a frameless window. 4 6+ 3+
saveWindowState bool A flag to cache the location of the window or not. true 6+ 3+
shadow bool A flag to display a shadow on your application windows. Shadow and rounded corners are mutually exclusive. On Win7, aero theme is required. Not updatable via window.updateOptions. false 6+ 3+
showTaskbarIcon bool A flag to show the Window's icon in the taskbar. true 6+ 3+
state string A string that sets the window to be "minimized", "maximized", or "normal" on creation. "normal" 6+ 3+
taskbarIcon string The URL of an icon to be shown on the desktop. Support formats: Portable Network Graphic (PNG); Size: 256 x 256. the parent application's icon 6+ 3+
waitForPageLoad bool When set to false, the page will render before the "load" event is fired on the window. Caution, when false you will see an initial empty white window. true 6+ 3+ 
"startup_app": {
    "name": "YourApp",
    "icon": "http://cdn.openfin.co/YourApp/favicon.ico",
    "description": "YourApp",
    "url": "http://cdn.openfin.co/YourApp/",
    "uuid": "OpenfinPOC",
    "backgroundColor": "#fffff",
    "contextMenu": true,
    "contentNavigation": {
        "whitelist": ["https://openfin.co/*"]
    },
    "autoShow": true,
    "defaultWidth": 480,
    "maxWidth": 480,
    "minWidth": 480,
    "maxHeight": 50,
    "defaultHeight": 50,
    "minHeight": 50,
    "defaultTop": 50,
    "defaultLeft": 10,
    "resizable": false,
    "maximizable": false,
    "frame": false,
    "cornerRounding": {
        "width": 5,
        "height": 5,
    },
    "taskbarIconGroup": "myApp",
    "loadErrorMessage": "There was an error loading the application."
}

Click the link below for additional runtime properties:

Top-level properties

Property Type Description Default Runtime RVM
appAssets array of objects Array containing objects that describe app-assets described below 6+ 3+
dialogSettings object An optional object containing properties to customize the appearance of the RVM progress dialog described below -- 6+ 3+
licenseKey string A string used as a licensing identifier for each customer/contract. The license indicates which OpenFin features and support level a customer is covered by. If interested in a Community or Enterprise license, please contact us for one here. If you're launching your app via our .NET or Java Adapters, you'll also need to add your licenseKey as follows: NET Adapter: Please include the licenseKey in RuntimeOptions.LicenseKey.Java Adapter: Please include the licenseKey in RuntimeConfiguration.setLicenseKey. -- 6+ 3+
offlineAccess bool If true, enables offline application support when no internet access. false 6+ 3.2.0.0
overrideConfigUrl string A string that enables you to update the location of your application manifest to a new location. The RVM will rename the location of the config and use the new one. Example: overrideConfigUrl: "NEW_CONFIG_LOCATION" -- 6+ 3+
runtime object Contains runtime-specific properties described below -- 6+ 3+
services array of objects An array of objects containing services to be launched with the application. More details here. -- 9+ 4.5+
shortcut object Contains shortcut-specific properties described below
Note that shortcuts must use an .ico file.		 -- 6+ 3+
splashScreenForceDownload bool If specified, the rvm will re-download the splash screen on every launch -- 6+ 3+
splashScreenImage string You can specify an image to display while the runtime is loading. It takes any image file (including semi-transparent PNGs) -- 6+ 3+
supportInformation object An optional object to with properties to customize error messages, described below -- 6+ 3+ 
{
    "splashScreenImage": "http://SERVER/image.png",
    "offlineAccess": true,
    "licenseKey": "8f5ac730-b6a4-4b11-a71c-500427190fda",
}

Runtime object properties

Property Type Description Default Runtime RVM
version* string Specifies what version of the runtime the app should use. The value can be a version or a release channel. For the available values, see the versions page. -- 6+ 3+
fallbackVersion string The RVM will fallback to this version if it fails to retrieve the desired Runtime version, assuming this version is already installed. (RVM 2.8+) -- 6+ 3+
futureVersion string The RVM preloads this newer OpenFin version in preparation of an upgrade. The download occurs silently and does not interrupt the startup of your app in the current version. (RVM 3.3+) -- 6+ 3.3.0.0
arguments string Command line arguments to set when launching the runtime. The OpenFin Runtime supports Chromium command line switches e.g.: "-- --disable-accelerated-compositing -- --enable-threaded-compositing" for a complete list of values please refer to Current Chromium Switches. -- 6+ 3+
forceLatest bool If true, forces the runtime to always get the latest runtime version before launching (prevents background installs). false 6+ 3+
enableCacheMigration bool If true, then when the RVM detects that an app has upgraded its runtime version (e.g. from v8.1.0.0 -> 8.2.0.0), it will migrate Local Storage, IndexedDB, and winposCache data to the cache of the new version true 6+ 3.8.1.0 
"runtime": {
    "arguments": "",
    "version": "15.80.48.12",
    "fallbackVersion": "14.78.48.16",
    "futureVersion": "16.83.53.26",
    "forceLatest": true
}

appAssets object properties

Property Type Description Default Runtime RVM
alias string Name of the asset. The name will be used in launchExternalProcess to launch the asset. -- 6+ 3+
args string The default command line arguments for the aforementioned target. -- 6+ 3+
mandatory bool When set to true, the app will fail to load if the asset cannot be downloaded. When set to false, the app will continue to load if the asset cannot be downloaded. (Default: true) true 6+ 3+
src string URL to a zip file containing the package files (executables, DLLs, etc). -- 6+ 3+
target string Specifies default executable to launch. This option can be overridden in launchExternalProcess. -- 6+ 3+
version string Version of the package. To force new updates, increment the version. -- 6+ 3+ 
"appAssets": [{
    "src": "http://server/hostedApp.zip",
    "alias": "my-app",
    "version": "3.2.50.71",
    "target": "myapp.exe",
    "args": "--flag=3",
    "mandatory": true
}, {
    "src": "http://server/anotherApp.zip",
    "alias": "foo",
    "version": "0.0.0.72"
}]

shortcut object properties

Property Type Description Default Runtime RVM
company* string Company name for the application shortcut. -- 6+ 3+
description string A short description of the application shortcut. Will be shown when hovering over the shortcut icon. -- 6+ 3+
diagnostics-shortcut bool Creates a shortcut menu-item to run your application in Diagnostics Mode. Diagnostics Mode provides you and your end-users an opportunity to recreate previously reported issues within your application and remotely deliver the runtime debug logs to OpenFin. It can also be manually triggered by adding "--diagnostics" to the command line for your application. Default is 'true' after RVM 5.2.* -- 6+ 3.6.1.0+
force bool If set to true, a desktop icon is always created on application start-up (even when user has deleted it). If set to false, a desktop icon is created on initial application launch but not created on subsequent application launches. false 6+ 3+
icon* string Location for the icon image to be used when installing the application shortcut.
Note that this must point to an .ico file.		 -- 6+ 3+
name string Name of the application to display with the shortcut. -- 6+ 3+
startMenuRootFolder string Set this value with a folder path (e.g. foo) and the RVM will create the start menu shortcut under foo/Company/App. -- 6+ 3+
target string Locations for where the application shortcut is added on the desktop owner's machine. Available options are "desktop", "start-menu" and "automatic-start-up". ["start-menu", "desktop"] 6+ 3+
uninstall-shortcut bool If true, creates an uninstall shortcut for the app true 6+ 3+ 
"shortcut": {
    "company": "OpenFin",
    "description": "YourApp",
    "icon": "http://cdn.openfin.co/YOurApp/favicon.ico",
    "name": "YourApp",
    "target": ["desktop", "start-menu"],
    "startMenuRootFolder": "foo"
}

dialogSettings object properties

Property Type Description Default Runtime RVM
bgColor integer Determines the color of the dialog. Color value is a decimal representation of a 32 bit number (A,R,G,B). For instance : FF00FF00 or 4278255360 is fully opaque green. 4163183909 6+ 3+
logo string Determines the logo or image in the progress dialog. The logo should be a semi-transparent PNG. 100×25 pixels. OpenFin 6+ 3+
progressBarBgColor integer Determines the background color of the area where the progress bar is displayed. 4278190080 6+ 3+
progressBarFillColor integer Determines the color of the progress bar. 4281513430 6+ 3+
progressBarBorderColor integer Determines the border color of the progress bar. 4282137660 6+ 3+
textColor integer Determines the color of the text displayed above the progress bar location. 4293980400 6+ 3+ 
"dialogSettings": {
    "logo": "http://openfin.co/wp-content/uploads/2014/11/logo.png",
    "bgColor": 4163183909,
    "textColor": 4293980400,
    "progressBarBgColor": 4278190080,
    "progressBarFillColor": 4281513430,
    "progressBarBorderColor": 4282137660
}

supportInformation object properties

Property Type Description Default Runtime RVM
company* string Displays the company name in the title bar for the support error dialog that appears when an application fails to load. -- 6+ 3+
email* string Displays the email to contact in the support error dialog that appears when an application fails to load. -- 6+ 3+
enableErrorReporting bool To disable the error reporting feature, set this value to false. true 6+ 3+
forwardErrorReports bool When set to true, prompts end users with a dialog when a deployment error occurs from within the RVM and enables them send along log files from their machine. Error reports are delivered to your email address set in supportInformation. false 6+ 3+
product* string Displays the product name or application name in the support error dialog that appears when an application fails to load. -- 6+ 3+ 
"supportInformation" : {
    "company": "Company Name",
    "product": "Product Name",
    "email": "[email protected]",
    "forwardErrorReports": true
}

Have questions? Get in touch with us at support@openfin.co.

Updated 2 days ago

What's Next

License Configuration

Configuring Your Application

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.