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.

{
    "licenseKey": "contract_identifier",
    "runtime": {
        "version": "9.61.36.36"
    },
    "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

Properties with a * 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+
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 (document.body.style.backgroundColor). 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+
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 folder which is currently <rvmInstallDirectory>/<apps>/<appHash>/app.log 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+
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+
plugins bool A flag to enable Flash Player. false 7+ 3+
preloadScripts array An array of objects containing a path to a preload script and optional mandatory flag (e.g., { url: "http://path.to/your/preload_script.js" }), which are retrieved, cached, and eval'd. 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 application 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+

Example

"startup_app": {
    "name": "Hyperblotter",
    "icon": "http://cdn.openfin.co/hyperblotter/favicon.ico",
    "description": "Hyperblotter",
    "url": "http://cdn.openfin.co/hyperblotter/",
    "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."
}

Additional Runtime properties

Top-level properties

Property Type Description Default Runtime RVM
assetsUrl string If an application specifies a valid "assetsUrl", then that "assetsUrl" will be used as the base portion of the URL instead of the OpenFin default, https://developer.openfin.co/release/. More information on hosting your Runtime or RVM can be found here https://cdn.openfin.co/release/ 6+ 3+
runtime object Contains runtime-specific properties described below 6+ 3+
appAssets array of objects Array containing objects that describe app-assets described below 6+ 3+
shortcut object Contains shortcut-specific properties described below 6+ 3+
dialogSettings object An optional object containing properties to customize the appearance of the RVM progress dialog 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+
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+
offlineAccess bool If true, enables offline application support when no internet access. false 6+ 3.2.0.0
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+
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+
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

Example

{
    "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+
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 toCurrent 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

Example

"runtime": {
    "arguments": "",
    "version": "8.56.24.41",
    "fallbackVersion": "7.53.23.23",
    "futureVersion": "8.56.25.*",
    "forceLatest": true
}

appAssets object properties

Property Type Description Default Runtime RVM
src string URL to a zip file containing the package files (executables, dlls, etc...). 6+ 3+
alias string Name of the asset. The name will be used in launchExternalProcess to launch the asset. 6+ 3+
version string Version of the package. To force new updates, increment the version. 6+ 3+
target string Specifies default executable to launch. This option can be overridden in launchExternalProcess. 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) false 6+ 3+

Example

"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+
icon* string Location for the icon image to be used when installing the application shortcut. 6+ 3+
name string Name of the application to display with the 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 'false'. 6+ 3.6.1.0
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+
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+
startMenuRootFolder string Set this value with a folder path (e.g. foo/bar) and the RVM will create the start menu shortcut under RootFolder/Company/App. 6+ 3+
uninstall-shortcut bool If true, creates an uninstall shorcut for the app true 6+ 3+

Example

"shortcut": {
    "company": "OpenFin",
    "description": "Hyperblotter",
    "icon": "http://cdn.openfin.co/hyperblotter/favicon.ico",
    "name": "Hyperblotter",
    "target": ["desktop", "start-menu"],
    "startMenuRootFolder": "foo/bar"
}

dialogSettings object properties

Property Type Description Default Runtime RVM
logo string Determines the logo or image in the progress dialog. The logo should be a semi-transparent PNG. 100×25 pixels. 6+ 3+
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. 6+ 3+
textColor integer Determines the color of the text displayed above the progress bar location. 6+ 3+
progressBarBgColor integer Determines the background color of the area where the progress bar is displayed. 6+ 3+
progressBarFillColor integer Determines the color of the progress bar. 6+ 3+
progressBarBorderColor integer Determines the border color of the progress bar. 6+ 3

Example

"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+
product* string Displays the product name or application name in 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+
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. 6+ 3+
enableErrorReporting bool To disable the error reporting feature, set this value to false. 6+ 3+

Example

"supportInformation" : {
    "company": "Company Name",
    "product": "Product Name",
    "email": "support@company.com",
    "forwardErrorReports": true
}

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

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.