Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

Configuring your application

Use a JSON-formatted manifest file to configure an application for the OpenFin environment.

The OpenFin Runtime requires each application to provide a JSON formatted manifest file with configuration information. This manifest 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 use a manifest file to launch applications as well as make use of other configuration data.

❗️

Important

Properties with an asterisk (*) are mandatory.


Top-level properties

PropertyTypeDescriptionDefault 
startup_appobjectContains app-specific properties described in startup_app object properties--
devtools_portintegerYou can access the Chromium development tools by navigating to the selected port, e.g. http://localhost:9090.--
{
    "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
    }
}


startup_app object properties

PropertyTypeDescriptionDefault
name*stringThe name for the window, which must be unique within the context of the invoking Application. --
url*stringThe URL of the window--
uuid*stringThe UUID of the application, unique within the set of all other applications running in OpenFin Runtime. --
alwaysOnTop boolA flag to always position the window at the top of the window stack. false
applicationIconstringA URL for the icon to be shown in the window title bar.
Note: only .ico files are allowed.
autoShow boolA flag to automatically show the window when it is created. false
backgroundColor stringThe 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
childWindowAutoAuth boolAllow non-API-created child windows, such as window.open, to authenticate true
clearChildSubscriptionsOnReload boolClear InterApplication subscriptions of all child windows when main window is reloadedtrue
contextMenu boolA flag to show the context menu when right-clicking on a window. Gives access to the Developer Console for the window. true
contentNavigationobjectDefines where content can be obtained from null
cornerRounding.heightintegerHeight of rounded corners for the window.
cornerRounding.widthintegerWidth of rounded corners for the window.
customWindowAlertboolApplication-level event for handling window alerts. To enable an application, listen on that application for the event "window-alert-requested" false
defaultCenteredboolSpecifies that the window is to 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
defaultHeightintegerThe 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
defaultLeftintegerThe default left position of the window. Specifies the position of the left side 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
defaultTopintegerThe 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
defaultWidthintegerThe 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
descriptionstringThe name for the window, which must be unique within the context of the invoking application.---
fdc3booleanSpecifies whether to include FDC3 in your application.---
frameboolA flag to show the frame of the window.true
iconstringA URL for the icon to be shown in the window title barOpenFin's icon
loadErrorMessagestringAn error message to display when the application fails to load. A dialog box launches with the error message just before the runtime exits. Load failures 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 failures as they are valid server responses. There was an error loading the application.
enableAppLoggingboolIf true, console.log, info, warning, and error messages for the app are written to the app.log folderfalse
logManagementobjectObject that contains properties for remote log management
logManagement.enabledboolIf true, enables remote app log managementfalse
logManagement.encryptionKeystring If present and logManagement is enabled, OpenFin uses this key to encrypt zipped log files before sending them to the specified remote server. Format is a base64 public RSA key.
logManagement.urlstringIf log management is enabled, this is the URL where zipped logs are sent.https://log-manager.openfin.co
maxHeightintegerThe maximum height of a window. Defaults to the OS defined value if set to -1. -1
maximizableboolA flag that lets the window be maximized.true
maxWidthintegerThe maximum width of a window. Defaults to the OS defined value if set to -1.0
 minHeight integerThe minimum height of a window.0
minimizableboolA flag that lets the window be minimized.true
minimumRVMVersionstringMinimum RVM version required to run this app. The RVM shows an error if it attempts to run this app, and its version is less than the specified version--
minWidth integerThe minimum width of a window.
nonPersistent boolA flag to configure the application as non-persistent. The runtime exits when there are no persistent apps running. false
opacityfloatA flag that specifies how transparent the window is. This value is clamped between 0.0 and 1.0.1
permissionsobjectConfig object to declare secured API endpoints for your application, described in permissions object propertiesfalse
pluginsboolA flag to enable Flash Player.false
preloadScripts arrayAn 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, runs 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").
resizableboolA flag to allow the user to resize the window.true
resizeRegion.size integerDefines a region in pixels that responds to user mouse interaction for resizing a frameless window.2
resizeRegion.bottomRightCornerintegerDefines a region in pixels of an additional square at the bottom right corner of a frameless window.4
saveWindowStateboolA flag to cache the location of the window. true
shadowboolA flag to display a shadow on the application's windows. Shadow and rounded corners are mutually exclusive. On Win7, aero theme is required. Not updatable via window.updateOptions. false
showTaskbarIconboolA flag to show the window's icon in the taskbar.true
statestringA string that sets the window to be "minimized", "maximized", or "normal" on creation."normal"
taskbarIcon stringThe URL of an icon to be shown on the desktop. Supported formats: Portable Network Graphic (PNG); Size: 256 x 256. the parent application's icon
waitForPageLoadboolWhen set to false, the page renders before the "load" event is fired on the window. Caution: when false, an initial empty white window appears.true
"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."
}


permissions object properties

For more information about the use of permissions options, refer to API security.

PropertyTypeDescriptionDefault
ExternalWindowobjectObject to declare secured ExternalWindow APIs.--
wrapboolAs a member of the ExternalWindow object, declares use of ExternalWindow.wrap() method.false
SystemobjectObject to declare secured System APIs.--
downloadAssetboolAs a member of the System object, declares use of System.downloadAsset()false
getAllExternalWindowsboolAs a member of the System object, declares use of getAllExternalWindows()false
launchExternalProcessboolAs a member of the System object, declares use of System.launchExternalProcess()false
readRegistryValueboolAs a member of the System object, declares use of System.readRegistryValue()false
terminateExternalProcessboolAs a member of the System object, declares use of System.terminateExternalProcess()false
webAPIsarray of stringsDeclares use of secured Web APIs. Possible values include: audio, clipboard-read, clipboard-write, fullscreen, geolocation, midiSysex, notifications, pointerLock, video[]

Runtime properties
Click the link below for additional runtime properties:


Top-level properties

PropertyTypeDescriptionDefault 
appAssets array of objectsArray containing objects that describe app-assets described in appAssets object properties
deletedRemovedAssetsboolIf true: If an asset was declared in a previous version of an application manifest, but is now no longer present in the version about to be launched, then the asset is presumed unused and is removed.false
dialogSettingsobjectAn optional object containing properties to customize the appearance of the RVM progress dialog described in dialogSettings object properties--
licenseKey stringA 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.--
offlineAccessboolIf true, enables offline application support when no internet access. false
overrideConfigUrlstringA 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"--
runtimeobjectContains runtime-specific properties described in runtime object properties--
 servicesarray of objectsAn array of objects containing services to be launched with the application. --
shortcutobjectContains shortcut-specific properties described in shortcut object properties
Note: Shortcuts must use an .ico file.
--
splashScreenForceDownloadboolIf specified, the rvm will re-download the splash screen on every launch--
splashScreenImage stringYou can specify an image to display while the runtime is loading. It takes any image file (including semi-transparent PNGs)--
supportInformation objectAn optional object to with properties to customize error messages, described supportInformation object properties--
{
    "splashScreenImage": "http://SERVER/image.png",
    "offlineAccess": true,
    "licenseKey": "8f5ac730-b6a4-4b11-a71c-500427190fda",
}


Runtime object properties

PropertyTypeDescriptionDefault 
version*stringSpecifies 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.--
fallbackVersionstringThe RVM will fallback to this version if it fails to retrieve the desired Runtime version, assuming this version is already installed. (RVM 2.8+)--
futureVersion stringThe 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+)--
argumentsstringCommand 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. --
forceLatestboolIf true, forces the runtime to always get the latest runtime version before launching (prevents background installs).false
enableCacheMigration boolIf 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 versiontrue
"runtime": {
    "arguments": "",
    "version": "15.80.48.12",
    "fallbackVersion": "14.78.48.16",
    "futureVersion": "16.83.53.26",
    "forceLatest": true
}


appAssets object properties

PropertyTypeDescriptionDefault
aliasstringName of the asset. The name will be used in launchExternalProcess to launch the asset.--
argsstringThe default command line arguments for the aforementioned target.--
mandatory boolWhen 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
srcstringURL to a zip file containing the package files (executables, DLLs, etc).--
target stringSpecifies default executable to launch. This option can be overridden in launchExternalProcess.--
versionstringVersion of the package. To force new updates, increment the version.--
"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

PropertyTypeDescriptionDefault 
company*stringCompany name for the application shortcut.--
description stringA short description of the application shortcut. Will be shown when hovering over the shortcut icon.--
diagnostics-shortcutboolCreates 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.*--
forceboolIf 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
icon*stringLocation for the icon image to be used when installing the application shortcut.
Note: This property must point to an .ico file.
--
namestringName of the application to display with the shortcut.--
startMenuRootFolderstringSet this value with a folder path (e.g. foo) and the RVM will create the start menu shortcut under foo/Company/App.--
targetstringLocations 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"]
uninstall-shortcutboolIf true, creates an uninstall shortcut for the apptrue
"shortcut": {
    "company": "OpenFin",
    "description": "YourApp",
    "icon": "http://cdn.openfin.co/YOurApp/favicon.ico",
    "name": "YourApp",
    "target": ["desktop", "start-menu"],
    "startMenuRootFolder": "foo"
}


dialogSettings object properties

PropertyTypeDescriptionDefault
bgColorintegerDetermines 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
logostringDetermines the logo or image in the progress dialog. The logo should be a semi-transparent PNG. 100×25 pixels.OpenFin
progressBarBgColor integerDetermines the background color of the area where the progress bar is displayed.4278190080
progressBarFillColorintegerDetermines the color of the progress bar.4281513430
progressBarBorderColor integerDetermines the border color of the progress bar.4282137660
textColor integerDetermines the color of the text displayed above the progress bar location.4293980400
"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

PropertyTypeDescriptionDefault 
company*stringDisplays the company name in the title bar for the support error dialog that appears when an application fails to load.--
email* stringDisplays the email to contact in the support error dialog that appears when an application fails to load.--
enableErrorReportingboolTo disable the error reporting feature, set this value to false.true
forwardErrorReportsboolWhen 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
product*stringDisplays the product name or application name in the support error dialog that appears when an application fails to load.--
"supportInformation" : {
    "company": "Company Name",
    "product": "Product Name",
    "email": "[email protected]",
    "forwardErrorReports": true
}

Have questions? Get in touch with us at [email protected].

Updated 27 days ago


Related topics

License Configuration

Configuring your application


Use a JSON-formatted manifest file to configure an application for the OpenFin environment.

Suggested Edits are limited on API Reference Pages

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