RVM functionality

Configuration

RVM functionality is configured through Desktop Owner Settings and Group Policy and Registry Settings. There are a few options, such as shortcuts and splash screens, that can be configured in the application manifest file. These configurations are noted in their individual sections below.

🚧

Note

When the OpenFin RVM launches, it parses the desktop owner settings file and overrides any equivalent registry settings, such as assetsUrl, with the settings specified in the desktop owner settings file.

Installation

The OpenFin RVM is responsible for deploying itself and all your application’s assets, including the OpenFin Runtime.

You can use the OpenFin installer generator to create an executable file that streamlines the process of installing an application and updating the Runtime. The generated installer can be pre-baked with the application's manifest; it is delivered as a zip file containing the executable. See OpenFin installer for details about the installer generator.

RVM update logic

When the RVM starts (either from an installer or by direct execution), it first checks whether an RVM is already available on the system. The RVM might be started with a payload, that is, a configuration file or command-line arguments.

📘

FYI

Only one instance of the RVM can run on a system at any given time.

If OpenFin is not installed, the RVM copies itself to rvmInstallDirectory (defaults to %LOCALAPPDATA%\OpenFin on Windows), and then launches with the specified payload.

If OpenFin is installed and the newly-launched RVM version is older than or the same as the existing RVM version, it terminates itself after it launches the existing RVM with the specified payload.

If OpenFin is installed and the newly-launched RVM version is newer than the existing RVM version, it performs the following process:

  • If the existing RVM is currently running:

    1. Replace the existing RVM with the installer RVM (with payload removed).
    2. Delegate to the running RVM with the specified payload.
  • If the existing RVM is not running:

    1. Replace the existing RVM with the installer RVM (with the payload removed).
    2. Launch with the specified payload.

Application launch

The RVM is responsible for launching OpenFin applications.

To launch an OpenFin-based application, pass the location of the application manifest file to the RVM executable:

Windows

$ openfinRVM.exe --config="SERVER_NAME/APP_MANIFEST_FILE"

In this case SERVER_NAME is the network location, and APP_MANIFEST_FILE is the name of the application manifest file, which is typically in JSON format.

When this command is executed, the RVM reads the application manifest file and downloads the specified Runtime from the download location to launch the app.

Learn more about configuring the app manifest file in the Manifest settings topic.

Download of Runtime and application assets

By default, the RVM resolves release channels, and downloads runtimes and newer RVMs from OpenFin’s servers. The RVM can optionally be configured through the desktop owner settings file or the Windows registry to pull these assets from alternative servers, such as ones on your internal network. Use the assetsUrl property within the configuration.

Learn more about hosting Runtimes, RVMs, and app assets in the Hosting assets topic.

Branded shortcuts and splash screens

You can provide an application with customized, branded shortcuts and splash screens by defining the shortcut object property or splashScreenImage string in the application manifest file, as shown in the following code snippets:

shortcut example

{ ...
  "shortcut": {
      "company": "OpenFin",
      "description": "YourApp",
      "icon": "http://cdn.openfin.co/YourApp/favicon.ico",
      "name": "YourApp",
      "target": ["desktop", "start-menu"],
      "startMenuRootFolder": "foo/bar"
  } ...
}

splashScreenImage example

{...
    "splashScreenImage": "http://SERVER/IMAGE_FILE.png",
    "offlineAccess": true,
    "licenseKey": "8f5ac730-b6a4-4b11-a71c-500427190fda",
}

Semantic versioning for Runtime

The RVM supports semantic versioning for applications tested and verified to run in multiple OpenFin Runtime versions. This feature is especially useful for application providers who need to target OpenFin Runtimes that are hosted within a Desktop Owner’s environment.
Learn more about semantic versioning in the Semantic Versioning topic.

License tracking

The RVM manages sets of information to determine OpenFin usage, including hardware (desktop/machine), and software (app config) data points. Learn more about license tracking in the License usage data topic.

Deep linking

The RVM permits deep linking to an OpenFin application from anywhere that can invoke a “link,” such as a browser, email client, or another OpenFin application. The RVM uses a custom protocol handler to invoke an application, if not already running, and to pass context to a specific location within an OpenFin application via a uniform resource identifier (URI). For more information, see Deep linking.

App logging and encryption

Application logging is invoked by the RVM and allows applications to have their own, separate logs that can be retrieved for later use by the App Provider.

Learn more about log management and encryption in the Log Management topic.

Error reporting

When an error occurs prior to launching an application, the RVM shows an error dialog. This dialog includes an error code and a prompt to send an email to OpenFin support with the corresponding RVM logs. Below is a list of error codes and descriptions used by the RVM.

Error code descriptions

CodeError Description
100Internal error
101No write access
102Invalid arguments
103Failed to initialize RVM config
104Invalid app config URI
200Failed to remove app
300Failed to load app
301Runtime is missing
302Failed to create app install directory
303Failed to read app config
304Failed to resolve Runtime version
305Failed to install Runtime
306Failed to install Runtime assets
307Failed to install app assets
308Failed to launch app

Diagnostics

As of version 5.0.0.5, the RVM relays diagnostic information to OpenFin. This diagnostic information pertains to RVM startup, installation, app delegation, auto-update, exit, and errors.

This information is collected to solely support the development of the RVM and streamlines the error support process.

Command line options

The following options are supported by OpenFinRVM.exe (as of RVM version 8):

OptionArgumentDescription
--configStringThe location of an application manifest to install or start an application
--diagnosticsBooleanEnable diagnostics
--do-not-launch or --dnlBooleanInstall the application without launching it
--enable-ssl-validationnoneRun with HTTPS security enforcement, regardless of security-related registry values
--health-checkStringRun the RVM in health-check mode
--helpnoneDisplay help information about command line options
--nameStringName of an application from the Application Directory to install or start
--no-uiBooleanRun the RVM without progress or error dialogs
--only-self-installBooleanRVM only installs itself, not an application, ignoring any --config argument
--remove-app??Remove an application from the system
--runtime-argumentsStringAdd or replace runtime arguments to launch the application manifest with
--runtime-health-check (RVM 9+)StringRun a health check on the Runtime version specified in the string argument, which must be a specific dotted version number, not a release channel name; the minimum supported version is 29.0.0.0.
--support-emailemail addressCustomize error messages using the specified email address. Default is [email protected]
--versionnoneDisplay the RVM version