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"

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.

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
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 servicesArray 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"
deploymentContains the following settings, which control aspects of deploying OpenFin.Object
deployment.runtimeCacheLocation for runtimes to write cache data. Overrides application manifest settings.string"%rvmInstall Directory%/cache"
deployment. runtimeDirectory Location for runtime binary files.string"%rvmInstall Directory%/runtime"
deployment. rvmInstallDirectoryLocation for RVM binary files. The RVM copies itself here.string"%local appdata%/OpenFin"
deployment.shortcutPoints ToOriginalInstallWhether the RVM installs itself every time it runs. A true value is typically used in environments such as Citrix that wipe %localappdata%.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.booleanfalse
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
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)


Advanced properties
Use these properties only under specialized circumstances.

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


Example

{

    "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": 30000,
            "sendTimeout": 30000,
            "receiveTimeout": 30000,
            "connectTimeout": 30000
        },

        "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]",
        "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"
                ]
           }
        ]
    }
}