Manifest settings

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

The OpenFin Runtime requires each application or platform 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 tool and OpenFin RVM use a manifest file to launch applications as well as to make use of other configuration data.

Starting with RVM version 15, the OpenFin RVM retrieves the application manifest over a secure connection (HTTPS with a valid server certificate).
This approach reduces the odds of a malicious actor substituting a modified manifest file.
If the secure fetch fails, the RVM logs the failure and the reason.
If security settings are not explicitly defined (see Enable HTTPS security), then RVM retries fetching the manifest file with the default settings.

Many of the properties that can be used in a manifest are defined as types in the OpenFin API. Follow links to the API reference for complete details.

📘

Note

The application manifest is read by the RVM when an application starts up and so it needs to be available in order for settings to take effect. If the manifest cannot be read, the RVM uses default settings where applicable, including those that affect reporting about application errors. The RVM can cache manifest settings and use the cached values if the actual manifest fails to load (for example, if the file server containing it is unavailable). In such a circumstance, the last cached version of the manifest is used.

Sections in this document

📘

Note

Required properties: Properties marked with a plus-sign (+) are required to be defined for their enclosing object.


Top-level properties
The following properties can be declared at the top level of a manifest file. Complex properties in this table link to later sections that detail their members.

PropertyTypeDescriptionDefault 
appAssetsarray of objectsDefines assets that can be used by the application, as described in appAssets properties.[]
autoShowbooleanWhether to automatically show the application's window or windows on launch.true
dialogSettingsobjectObject containing properties to customize the appearance of the RVM progress dialog, described in dialogSettings properties.null
deleteRemovedAssetsbooleanIf 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
devtools_portintegerNot available in v25; available in <=v24 and >=v26. A port number to use to access the Chromium development tools by navigating to the selected port.9223
extensions (v38.126.83.73+)array of objectsDefinitions of Chrome extensions; refer to Microsoft Single Sign On extension support.[]
licenseKeystringA licensing identifier for each customer contract. The license indicates which OpenFin features and support level a customer is covered by. If you are interested in a license, please contact us for one. If you're launching your app via the .NET Adapter, specify the license key in RuntimeOptions.LicenseKey. If you're using the Java Adapter, specify the license key in RuntimeConfiguration.setLicenseKey.""
offlineAccessbooleanWhether the application can be run without a network connection. Applies to Workspace and Notification Center as well as non-Workspace applications.false
overrideConfigUrlstringAn override for the location of your application manifest. The RVM renames the location of the manifest and uses the new one.""
platformobjectDefines properties for an OpenFin platform, described in Platform properties.null
runtimeobjectConfigures the OpenFin Runtime that should be used with this application. Refer to Runtime properties.null
shortcutobjectDefines a desktop shortcut for the application; refer to Shortcut propertiesnull
servicesarray of objectsDefines services that are available to this application. Each service object must have a name property and may have a manifestUrl property. Refer to Services for more information.[]
snapshotobjectDefines a snapshot that can be loaded in a platform. It has one member, "windows", which is an array of unnamed window options objectsnull
splashScreenForceDownloadbooleanWhether the RVM re-downloads the splash screen on every launch.false
splashScreenImagestringFile path or URL for an image to show while the application is starting up.""
startup_appobjectDefines properties for a "classic" (standalone) app, described in startup_app propertiesnull
supportInformation objectDefines properties to customize error messages, described supportInformation propertiesnull

Example top-level properties

{
    "splashScreenImage": "http://SERVER/IMAGE_FILE.png",
    "offlineAccess": true,
    "licenseKey": "LICENSE_KEY",
    "runtime": {
        "version": "XX.xx.xx.xx"
    },
    "startup_app": {
        "name": "APP_NAME",
        "uuid": "APP_UUID",
        "url": "APP_SERVER_NAME/START_PAGE.html",
        "autoShow": true,
        "defaultWidth": 500,
        "defaultHeight": 500
    }
}


appAssets properties

PropertyTypeDescriptionDefault
aliasstringName of the asset. The name is used in launchExternalProcess() to launch the asset.""
argsstringThe default command line arguments for the target.""
mandatory booleanWhen set to true, the app fails to load if the asset cannot be downloaded. When set to false, the app continues to load if the asset cannot be downloaded.true
srcstringURL to a zip file containing the package files (executables, DLLs, etc).""
targetstringSpecifies default executable to launch. This option can be overridden in launchExternalProcess.""
versionstringVersion of the package. To force new updates, increment the version.""

Example appAssets object properties

"appAssets": [{
    "src": "http://SERVER_NAME/PATH/APP_NAME.zip",
    "alias": "APP_ALIAS",
    "version": "3.2.50.71",
    "target": "APP_NAME.exe",
    "args": "--flag=3",
    "mandatory": true
    }, 
    {
    "src": "http://SERVER_NAME/PATH/ANOTHER_APP.zip",
    "alias": "ANOTHER_APP_ALIAS",
    "version": "0.0.0.72"
}]


dialogSettings properties

PropertyTypeDescriptionDefault
bgColorintegerThe 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
logostringThe logo or image in the progress dialog. The logo must be a semi-transparent PNG, 100×25 pixels.OpenFin
progressBarBgColorintegerThe background color of the area where the progress bar is displayed.4278190080
progressBarFillColorintegerThe color of the progress bar.4281513430
progressBarBorderColorintegerThe border color of the progress bar.4282137660
textColorintegerThe color of the text displayed above the progress bar location.4293980400

Example dialogSettings object properties

"dialogSettings": {
    "logo": "http://SERVER_NAME/LOGO_FILE.png",
    "bgColor": 4163183909,
    "textColor": 4293980400,
    "progressBarBgColor": 4278190080,
    "progressBarFillColor": 4281513430,
    "progressBarBorderColor": 4282137660
}


domainSettings properties

A domainSettings object may be a property of either a platform object or a startup_app object. It contains a rules array and (starting in version 37), a default object that defines default values for certain properties. The rules property is an array of match pattern strings, and option definitions for rules that apply to domains that match the match patterns.

Refer to Domain-based permission for details.

In Runtime v34 and earlier, the domainSettings object, and the corresponding DomainSettings and DomainSettingsRule interfaces, were known as defaultDomainSettings, DefaultDomainSettings, and DefaultDomainSettingsRule, respectively.


Platform properties

PropertyTypeDescriptionDefault
allowLaunchIntoPlatformBooleanWhether launching content manifests into the platform is allowed(v36 & v37) true; (v38+) false
defaultWindowOptionsobjectOptions that apply by default to all platform windows. These can include any window options, plus stylesheetUrl, a string containing the path of a custom CSS file to be injected into all windows that use default options.null
defaultViewOptionsobjectView options that apply by default to all views created by the platform.null
disableErrorReportingBoolean(RVM v10+) Whether to show the Report Error button in RVM error reporting dialogs for the application.

This property can also be set in Desktop owner settings, which takes precedence over application manifest settings.
false
domainSettingsobjectContains a rules property that controls access to file downloads and OpenFin APIs, based on match rules for domains; described in domainSettings properties. (Was defaultDomainSettings in v34 and earlier)null
reportErrorUrlstring(RVM 10+) The URL of a server to send error reports to.

For information on hosting a custom error reporting service, contact [email protected].
"https://dl.openfin.co/services/report-error"
securityPermissions MoreInfoUrlstringURL to a page containing information about API security permissions, used in the Review Security Permissions dialog box. (RVM v6.9+)"https://developers.openfin.co/ of-docs/page/review-security-permissions"
viewProcessAffinityStrategystringPossible values are "same" and "different", indicating whether windows and views (with a given origin) should be created in the same process or different ones."same"

A platform object inherits, and therefore can accept, properties from the following:

The following Application options are usually specified for a platform:

PropertyTypeDescriptionDefault
uuid+stringRequired The unique universal identifier of the application; it must be unique within the set of all applications running in OpenFin Runtime.""
namestringThe name of the application. This name is used in error messages, API security dialog boxes and in the directory name in %localappdata%/OpenFin/apps/<name><hash>.""
urlstringThe URL of the application's main window."about-blank"

A platform object can also contain a permissions object, which declares the secured APIs used by the application. Refer to Declaring APIs in an application manifest for details.


Runtime properties

PropertyTypeDescriptionDefault
version+stringSpecifies the 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+)""
futureVersionstringThe RVM preloads this newer OpenFin version to prepare for an upgrade. The download occurs silently and does not interrupt the startup of your app in the current version. (RVM 3.3+)

The desktop is checked to make sure an upgrade to the specified version can succeed. The results are reported to the application owner by calling the getInstalledRuntimes method,

In RVM v10 and later, the string is validated and sent to the OpenFin licensing server so that OpenFin deployment support can track upgrade progress.
""
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 or --user-gesture-required (to prevent media autoplay). For more information, refer to Current Chromium Switches. ""
forceLatestbooleanIf using runtime channels, setting this to true forces the RVM to always get the latest version before launching the application (prevents background installs).false
enableCacheMigration booleanIf 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

Example runtime object properties

"runtime": {
    "arguments": "",
    "version": "15.80.48.12",
    "fallbackVersion": "14.78.48.16",
    "futureVersion": "16.83.53.26"
}


Shortcut properties

PropertyTypeDescriptionDefault
company+stringCompany name for the application shortcut.""
descriptionstringA short description of the application shortcut. It is shown when hovering over the shortcut icon.""
diagnostics-shortcutbooleanCreates 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.true in RVM v5.2+
forcebooleanIf 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 creates 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-shortcutbooleanIf true, creates an uninstall shortcut for the apptrue

Example shortcut object properties

"shortcut": {
    "company": "COMPANY_NAME",
    "description": "APP_DESCRIPTION",
    "icon": "http://SERVER_NAME/PATH/ICON_FILE.ico",
    "name": "APP_NAME",
    "target": ["desktop", "start-menu","automatic-start-up"],
    "startMenuRootFolder": "FOLDER_NAME"
}


startup_app properties

A startup_app object can accept properties from any of the following:

A startup_app object can also contain:

The following Application options are usually specified for a classic app:

  • uuid+: The unique universal identifier of the application; it must be unique within the set of all applications running in OpenFin Runtime.

  • name: The name of the application. This name is used in error message and permissions dialog boxes and in the directory name in %localappdata%/OpenFin/apps/<name><hash>. If there is a Platform properties section of the manifest, then this value is ignored in favor of the name value provided in the platform section.

  • url: The URL of the application's main window; defaults to "about-blank".

The following option can be specified to customize the dialog box that appears when a user is prompted to allow or deny security permissions to an app:

  • securityPermissionsMoreInfoUrl: A string containing a URL to be linked from "more information" in the dialog box.
    Refer to API security for more information about customizing this dialog box.

Example startup_app options

"startup_app": {
    "name": "APP_NAME",
    "icon": "http://SERVER_NAME/PATH/ICON_FILE.ico",
    "description": "APP_NAME",
    "url": "http://SERVER_NAME/PATH/START_PATH.html",
    "uuid": "UUID",
    "backgroundColor": "#fffff",
    "contextMenu": true,
    "contentNavigation": {
        "whitelist": ["https://ALLOWED_DOMAIN/*"]
    },
    "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": "APP_GROUP",
    "loadErrorMessage": "There was an error loading the application."
}


supportInformation properties

The following properties are used to customize the dialog box that appears when an application fails to load, that is, the app load error dialog. Note that if the application's manifest itself cannot be reached, the app load error dialog uses default values for these settings.

PropertyTypeDescriptionDefault
company+stringDisplays the company name in the title bar for the app load error dialog.""
email+stringThe email address displayed in any RVM error dialogs for the application. If the user clicks Report Error in the dialog and forwardErrorReports is true, this address is sent to the error reporting service along with the error report; OpenFin's default service then sends a copy of the error report to this address. (A custom error reporting service might behave differently.)"[email protected]"
enableErrorReportingbooleanA legacy property to control the possibility for an end user to use the Report Error button in the RVM error dialog. If set to false, in RVM 10 and later, the button is hidden; in RVM 9 and earlier, the button is disabled. The default OpenFin error reporting service can send a copy of the error report to the email address set in the email property. In RVM 10 and later, the preferred way to control this button is with the disableErrorReporting option under the platform or startup_app properties; the new property can also be set in Desktop owner settings and therefore can affect all OpenFin applications on the system.true
forwardErrorReportsbooleanIf set to true, the email address specified in the email property is included in the information sent to the error reporting service. OpenFin's error reporting service sends a copy of the error report to this address. (A custom error reporting service might behave differently.)false
moreInfoUrlstringURL that is linked from "troubleshooting steps" in the RVM error dialog. See the Sample troublshooting guide for example content of such a pageIf no value is specified, the line containing the link is suppressed: "For help, visit troubleshooting steps."
product+stringDisplays the product name or application name in the RVM error dialog.""

Example supportInformation object properties

"supportInformation" : {
    "company": "COMPANY_NAME",
    "product": "PRODUCT_NAME",
    "email": "EMAIL_ADDRESS",
    "forwardErrorReports": true,
    "moreInfoUrl": "TROUBLESHOOTING_INFO_URL"
}

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


Related topics