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 DesktopOwnerSettings 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"


Property refresh

Starting in RVM version 7.0, the RVM also reads the registry key and the settings file whenever it launches an application. It updates the values of settings where:

  • The setting can be refreshed.
  • The value is different from the last time it was read.

This feature enables desktop owners to update settings for newly-launched applications without terminating the RVM and other running applications, possibly by pointing to a completely different settings file. For already-running applications, the settings values remain as they were at the time that the application was launched.

📘

Note

In the following tables, properties that can be refreshed are marked with the ↺ character.


Top-level properties

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

PropertyDescriptionType
contactInfo(RVM v11+) Info about who to contact about support issues for this system.Object
contactInfo.email(RVM v11+) Email address of a support contact. Required when using runtimeControls settings; if omitted, the Runtime version controls are not enforced.String
customProtocols(RVM v12+, Runtime v34+) Contains up to two members, which are arrays of strings. allowList is protocol schemes that are allowed; denyList is protocol schemes that are denied. Refer to Custom protocols in URLs.Object
desktopSettingsGeneral settings.Object
applicationSettingsSettings to block or allow applications' use of secured APIs. Refer to API security for details of these settings.Object
whitelistRules 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.

PropertyDescriptionTypeDefault value
applicationLoggingControls applications' use of log files, through the following settings.Object
applicationLogging. maxAppLogFileSizeMBMaximum size in megabytes for an application-specific log file.integerInfinity (i.e., unlimited)
applicationLogging. maxAppLogFilesMaximum number of log files per application.integerInfinity (i.e., unlimited)
assetsUrlURL for downloading OpenFin assets, including Runtime and RVM.string"https://cdn.openfin.co/ release"
cleanUnusedRuntimesWhether the RVM cleans up runtime and runtime cache folders that are no longer referenced by any installed application.booleantrue
crashReporterUrlThe URL endpoint to which the RVM sends crash reportsstring"https://dl.openfin.co/ services/crash-report-v2"
deploymentAn object containing settings that control aspects of deploying OpenFin. Refer to the Deployment section below.Objectnone
disableErrorReporting(RVM v10+) Whether to hide the Report Error button in the RVM error reporting dialogs. If set to true, the button is not shown.booleanfalse
disableShortcutCreationWhether to prevent applications installed via RVM from creating their own shortcuts. By default, applications can create shortcuts.booleanfalse
enableDesktopShortcutGlobally determines whether applications have desktop shortcuts.booleantrue
enableInstallation DetectionWhether to allow the RVM to install a font on the system, so that web pages can detect if OpenFin is installed.booleantrue in RVM 12+; false in earlier releases
enableRuntimeDiagnosticsWhether the RVM sends API diagnostics to OpenFin. Refer to OpenFin API diagnostics for details.booleantrue
enableServicesWhether use of services is allowed.booleantrue
enableStartMenuShortcutGlobally determines whether applications have Start menu shortcuts.booleantrue
enableStartupShortcutGlobally determines whether OpenFin applications have startup shortcuts.booleantrue
lrsUrlLicense relay server URL, to which the RVM sends licensing information, for all applications.string"https://dl.openfin.co/ services"
networkContains settings related network operations (for RVM only).Object
network.connectTimeoutTime in ms to wait for a connection to be made before canceling the connection request.integer0
network.receiveTimeoutTime in ms to wait to receive a response, before canceling the request.integer0
network.readTimeoutTime in ms to wait while reading a response, before canceling the request.integer0
network.sendTimeoutTime in ms to while while sending a request, before canceling the request.integer0
reportErrorUrl(RVM v10+) The URL of a server to send error reports to, for all OpenFin applications on the system. For information on hosting a custom error report service, contact [email protected]string"https://dl.openfin.co"
securedAPIDefault PermissionDefault permission for secured APIs whose permission is not otherwise defined. Refer to API security for details.string: one of "allow", "deny", "prompt"."prompt"
startMenuRootFolderRoot folder for applications' Start menu shortcuts.stringstandard Start menu directory
systemAppsDefines custom settings for system applications. Refer to Workspace settings for an example. Note: Prior to RVM version 6.4.1.1, this setting was named openfinSystemApplications.Object{}
trackBetaAutoUpdatesWhether the RVM tracks the beta channel for automatic updates.booleanfalse
unusedRuntimeExpiration InMinutesAmount of time (in minutes) after which the RVM deletes a downloaded runtime and corresponding runtime cache folder(s).integer43,200 (i.e., 30 days)
useLocalAPILanguageWhether to use strings hardcoded in the RVM binary to describe secured APIs in the Review Security Permissions dialog box. If false, the strings are retrieved from https://cdn.openfin.co/release/rvm/ApiLanguage; retrieving the strings requires internet access.booleanfalse


Advanced properties

Use these properties only under specialized circumstances.

PropertyDescriptionTypeDefault value
protocolHandlerLocationLocation 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\"%local appdata%/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.

  • 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.


Deployment

The deployment member of the desktopSettings object contains several properties that control aspects of OpenFin's operation that are relevant to deployment to end users.

PropertyDescriptionTypeDefault
runtimeCacheLocation for runtimes to write cache data. Overrides application manifest settings.string"%rvmInstall Directory%/cache"
runtimeControls. allowedVersionList(RVM v11+) A list of Runtime versions that are allowed to run.Array of stringsnone
runtimeControls. blockedVersionsList(RVM v11+) A list of Runtime versions that are blocked from running.Array of stringsnone
runtimeControls. enforce(RVM v11+) If "strict", the RVM blocks a disallowed version from running; if "warn", the RVM only warns that the version is disallowed.String: "strict" or "warn""warn"
runtimeControls. maximumAllowedVersion(RVM v11+) The lowest Runtime version number that can be run.Stringnone
runtimeControls. minimumAllowedVersion(RVM v11+) The highest Runtime version number that can be run.Stringnone
runtimeDirectory Location for runtime binary files.string"%rvmInstall Directory%/runtime"
rvmControls. versionPattern(RVM v11+) A pattern for RVM versions that are allowed to be run. A version pattern consists of up to 4 dot-separated levels, where a level is either a concrete number or *; a concrete number must not follow *.Stringnone
rvmInstallDirectoryLocation for RVM binary files. The RVM copies itself here.string"%local appdata%/OpenFin"
shortcutPointsTo OriginalInstallWhether the RVM installs itself every time it runs. A true value is typically used in environments such as Citrix that wipe %localappdata%.booleanfalse

🚧

Warning

If you use any of the runtimeControls settings, you must also define the top-level contactInfo.email option. If you do not specify an email address that users can contact for support in case of problems, then the Runtime version controls are not enforced.


Example

{

    "desktopSettings": {
        "assetsUrl": "http://localhost:8000/",
        "lrsUrl": "http://localhost:8000/services",
        "contactInfo" : {
            "email" : "[email protected]"
        },
        "cleanUnusedRuntimes": true,
        "unusedRuntimeExpirationInMinutes": 43200,
        "enableDesktopShortcut": true,
        "enableStartMenuShortcut": true,
        "enableStartupShortcut": true,
        "disableShortcutCreation": false,
        "startMenuRootFolder": "CompanyName",

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

        "deployment": {
            "runtimeCache": "CUSTOM_RUNTIME_CACHE_DIR",
            "runtimeDirectory": "CUSTOM_RUNTIME_DIR",
            "runtimeControls": {
                "enforce" : "warn",
                "allowedVersionsList" : ["N.0.*.*", "M.0.0.*"],
                "blockedVersionsList" : ["K.106.83.*"],
                "maximumAllowedVersion" : "W.*.*.*",
                "minimumAllowedVersion" : "G.0.0.*"
            },
            "rvmControls" : {
                "versionPattern" : "X.Y.Z.*"
            },
            "rvmInstallDirectory": "CUSTOM_RVM_DIR"
        },

        "applicationLogging": {
            "maxAppLogFileSizeMB": 10000,
            "maxAppLogFiles": 10
        }
    },
    "whitelist": {
        "distributionEmail": "[email protected]",
        "allowed": [
            {
                "appNames": [
                    "COMPANY_NAME"
                ],
                "clientId": "COMPANY_NAME_CLIENT_ID"
            },
            {
                "appNames": [
                    "COMPANY_NAME"
                ],
                "clientId": "OPENFIN_SPECIAL_ASSIGNED_ID",
                "appUuids": [
                    "APP_1",
                    "APP_2",
                    "APP_3"
                ]
            },
            {
                "appNames": [
                    "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"
                ]
            }
        ]
    }
}