Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

Desktop owner settings

Desktop owner settings are global settings that control aspects of the OpenFin environment on an individual computer or device.

The global desktop settings that can be defined include the following:

  • Allowed applications
  • Custom URLs (e.g., OpenFin assets, license server)
  • Global settings for applications, such as whether and where they can have shortcuts

While these settings can be defined directly in the Windows registry, doing so is inconvenient and not very scalable. A more common, convenient, and scalable approach is to define settings in a JSON file, typically residing on the customer's network, and to set only a single registry key containing the location of the desktop owner settings file. This file can therefore be easily updated; it's also possible to define multiple desktop owner settings files, depending on the category of user.

When the OpenFin RVM launches, it does the following:

  1. It reads the registry key to find the location of the desktop owner settings file.
  2. It parses the file and overrides any equivalent registry settings, such as assetsUrl or lrsUrl, with the settings specified in the file. RVM versions 5.3 and up cache the settings in the RVM installation directory.

The following registry key is used to specify the desktop owner file:
Key: HKEY_CURRENT_USER\Software\OpenFin\RVM\Settings\DesktopOwnerSettings
Data type: String
Example value: "https://example.com/company/files/end-user-desktop-owner-settings.json"


Top-level properties
The following top-level properties contain settings for various aspects of the OpenFin environment.

Property

Description

Type

desktopSettings

General settings.

Object

applicationSettings

Settings to block or allow applications' use of secured APIs. Refer to API security for details of these settings.

Object

whitelist

Rules defining which applications can be launched and which are blocked. Refer to the Allowed applications section.

Object

[services]

Deprecated Definitions of custom services

Array of objects


General settings
The following settings can be defined as members of the desktopSettings object. Some of theses settings can also be set in the Windows Registry; in the table, those settings are linked to their corresponding Registry key documentation.

Property

Description

Type

Default value

applicationLogging

Controls applications' use of log files, through the following settings.

Object

applicationLogging. maxAppLogFileSizeMB

Maximum size in megabytes for an application-specific log file.

integer

Infinity (i.e., unlimited)

applicationLogging. maxAppLogFiles

Maximum number of log files per application.

integer

Infinity (i.e., unlimited)

assetsUrl

URL for downloading OpenFin assets, including Runtime and RVM.

string

"https://cdn.openfin.co/release"

cleanUnusedRuntimes

Whether the RVM cleans up runtime and runtime cache folders that are no longer referenced by any installed application.

boolean

true

crashReporterUrl

The URL endpoint to which the RVM sends crash reports

string

"https://dl.openfin.co/services/crash-report-v2"

deployment

Contains the following settings, which control aspects of deploying OpenFin.

Object

deployment.runtimeCache

Location for runtimes to write cache data. Overrides application manifest settings.

string

"%rvmInstallDirectory%/cache"

deployment.runtimeDirectory

Location for runtime binary files.

string

"%rvmInstallDirectory%/runtime"

deployment.rvmInstallDirectory

Location for RVM binary files. The RVM copies itself here.

string

"%localappdata%/OpenFin"

deployment. shortcutPointsToOriginalInstall

Whether the RVM installs itself every time it runs. A true value is typically used in environments such as Citrix that wipe %localappdata%.

boolean

false

disableShortcutCreation

Whether to prevent applications installed via RVM from creating their own shortcuts. By default, applications can create shortcuts.

boolean

false

enableDesktopShortcut

Globally determines whether applications have desktop shortcuts.

boolean

true

enableInstallationDetection

Whether to allow the RVM to install a font on the system, so that web pages can detect if OpenFin is installed.

boolean

false

enableRuntimeDiagnostics

Whether the RVM sends API diagnostics to OpenFin. Refer to OpenFin API diagnostics for details.

boolean

true

enableServices

Whether use of services is allowed.

boolean

true

enableStartMenuShortcut

Globally determines whether applications have Start menu shortcuts.

boolean

true

enableStartupShortcut

Globally determines whether OpenFin applications have startup shortcuts.

boolean

true

lrsUrl

License relay server URL, to which the RVM sends licensing information, for all applications.

string

"https://dl.openfin.co/services"

secureAPIDefaultPermission

Default permission for secured APIs whose permission is not otherwise defined. Refer to API security for details.

string: one of "allow", "deny", or "prompt".

"prompt"

startMenuRootFolder

Root folder for applications' Start menu shortcuts.

string

standard Start menu directory

systemApps

Defines custom settings for system applications. Refer to Workspace options for an example. Note: Prior to RVM version 6.4.1.1, this setting was named openfinSystemApplications.

Object

{}

trackBetaAutoUpdates

Whether the RVM tracks the beta channel for automatic updates.

boolean

false

unusedRuntimeExpirationInMinutes

Amount of time (in minutes) after which the RVM deletes a downloaded runtime and corresponding runtime cache folder(s).

integer

43,200 (i.e., 30 days)


Advanced properties
Use these properties only under specialized circumstances.

Property

Description

Type

Default

protocolHandlerLocation

Location where fin and fins links launch the RVM from. (RVM 6.6+)
Note: Takes precedence over deployment.rvmInstallDirectory. Use only in situations where this location needs to be explicitly set, such as when the default location in a virtual environment is periodically emptied.

string

"%localappdata%/OpenFin"


Allowed applications
One important use of the desktop owner settings file is to allow applications listed in the whitelist object.

The members of the whitelist object are the following:

  • distributionEmail: An email alias that end-users can contact to request permission for a denied application. It is displayed in a dialog box that is shown to the end-user when an application tries and fails to launch because it is not allowed.
  • allowedRVMVersions: An array of RVM version strings for RVM versions that are allowed to be used by applications.
  • allowed: An array of objects specifying applications that are allowed to run.

An application can be allowed by listing its Client ID (same as the licenseKey in its application manifest) as well an App UUID or App Config Domain. If it is listed, the application launches.

{

    "desktopSettings": {
        "assetsUrl": "http://localhost:8000/",
        "lrsUrl": "http://localhost:8000/services",
        "cleanUnusedRuntimes": true,
        "unusedRuntimeExpirationInMinutes": "43200",
        "enableDesktopShortcut": true,
        "enableStartMenuShortcut": true,
        "enableStartupShortcut": true,
        "disableShortcutCreation": false,
        "startMenuRootFolder": "CompanyName",

        "network": {
            "readTimeout": 10,
            "sendTimeout": 10,
            "receiveTimeout": 10,
            "connectTimeout": 10
        },

        "deployment": {
            "runtimeCache": "C:\\custom\\runtime\\cache\\dir",
            "runtimeDirectory": "C:\\custom\runtime\\dir",
            "rvmInstallDirectory": "C:\\custom\\dir"
        },

        "applicationLogging": {
            "maxAppLogFileSizeMB": 10000,
            "maxAppLogFiles": 10
        }
    },
    "whitelist": {
        "distributionEmail": "[email protected]",
        "allowedRVMVersions": ["4.4.0.13"],
        "allowed": [{
                "name": "company_name",
                "clientId": "company_name_client_id"
            },
            {
                "name": "company_name",
                "clientId": "OpenFin_special_assigned_id",
                "appUuids": [
                    "app_1",
                    "app_2",
                    "app_3"
                ]
            },
            {
                "name": "company_name",
                "clientId": "company_name_special_assigned_id",
                "appUuids": [
                    "app_1"
                ],
                "appRuntimes": [
                    "1.2.3.4", "5.6.7.8"
                ],
                "appConfigDomains": [
                    "www.company1.com", "www.company2.com"
                ]
           }
        ]
    }
}

Updated about 2 hours ago


Desktop owner settings


Suggested Edits are limited on API Reference Pages

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