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.

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.

Advanced properties
Use these properties only under specialized circumstances.

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.

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

📘

Correction

The allowed.name field in the whitelist was incorrectly documented as a single string for the application name. The correct field name is allowed.appNames and is an array of strings to store an array of names for an application.