OpenFin

Runtime Version Manager

Overview

The OpenFin Runtime Version Manager (RVM) is a lightweight background process that runs alongside the OpenFin Runtime to manage updates, lifecycle, and security for all OpenFin applications on a given desktop. It is recommended to use the RVM as it provides several beneficial support features to fortify the Runtime.

The RVM ensures critical bugs are fixed, security patches are instantly distributed, and Runtime performance remains at its peak. It also enables a number of features that make it easier for Desktop Owners to update and improve applications to enrich user experience.

With the RVM, Desktop Owners can:

  • Manage Runtime and asset versions/updates including background downloads of new Runtimes and deletion of duplicate downloads
  • Employ OS level features such as auto-launch on startup, branded shortcuts, splash screens, dialogs, support emails, and download progress bar
  • Load OpenFin Desktop Services from the app directory before app startup
  • Seamlessly track licensing information and retrieve application logs
  • Create custom protocol handlers that invoke app launch or pass context to a specific location

The RVM is evergreen, which means it will always remain functional throughout any instance of update or change to itself or to the Runtime. Before the release of a new RVM version, OpenFin conducts beta and full end-to-end integration testing. These tests are completed to ensure compatibility between the RVM and multiple Runtime versions, including older Runtime versions. The RVM also has a built-in rollback feature in the event of app incompatibility after a new version rollout.

RVM Configuration

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

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

There is only one RVM running on a desktop at a time. If a new RVM starts because an app is launched, it will detect if there are other RVMs. If there's another RVM with an equal or higher version running, the newly launched RVM will delegate itself to that one.

Installation

OpenFin Installer

The OpenFin Installer generates an RVM installer to streamline the process of installing and updating the Runtime. The installer is pre-baked with the application’s config URL and is delivered as a .zip file containing an installer executable that can be hosted on a web server.

MSI Generator

The MSI Generator bundles Runtime version with the RVM into an MSI for offline installation. Users can then install and uninstall the MSI interactively or silently.

Command line options

The following command line options are available for the RVM:

Command Description
--config URI/URL for the Application Configuration file.
--do-not-launch Perform all of the startup sequence steps but do not launch the app (ideal for silent installs). This can be set per app.
--no-ui Suppress all of the visuals for the app being loaded in the RVM. This includes progress dialog, error report dialog, and message boxes.
--only-self-install If rvmInstallDirectory is set along with this argument, the RVM will perform the copy and terminate immediately after. (RVM 2.8+)

RVM Functionality

App launch

The RVM is responsible for the launch of OpenFin applications. When an app is launched, the RVM reads the application manifest file and downloads the specified Runtime from the OpenFin CDN to launch the app.

Learn more about configuring the app manifest file here.

Runtime and app asset download and update

By default, the RVM resolves release channels, downloads runtimes and newer RVMs from OpenFin’s servers. The RVM can optionally be configured through the desktop owner settings file or registry to pull these assets from your own servers. This can be achieved by specifying an “assetsUrl” within your configuration.

Learn more about hosting Runtimes, RVMs, and app assets here.

Services

If a "services" array of objects is placed in the app manifest file, the RVM will load the services from the app directory before app startup. For example, if Layouts is configured, the app manifest file will contain the following code snippet:

"services": [
    {
        "name": "layouts"
    }
]

Learn more about Services here.

Branded shortcuts and splash screens

The RVM can be configured to include customized, branded shortcuts and splash screens by placing the shortcut object property or splashScreenImage string in your app manifest file. If shortcuts and/or splash screens are configured, the app manifest file will contain the following code snippets:

"shortcut": {
    "company": "OpenFin",
    "description": "Hyperblotter",
    "icon": "http://cdn.openfin.co/hyperblotter/favicon.ico",
    "name": "Hyperblotter",
    "target": ["desktop", "start-menu"],
    "startMenuRootFolder": "foo/bar"
}
{
    "splashScreenImage": "http://SERVER/image.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 here.

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

Deep linking

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

In order to leverage the deep linking feature in your application, you must use the “args” object in fin.desktop.main for processing added parameters on launch and the “args” object on the run-requested application event if your application is already running.

Example Deep Link:
fins://mydomain.com/path-to-manifest/app.json?$$parameter1=value1&$$paramater2=value2

Example Code:

// On application launch parameters are passed through fin.desktop.main(function(args) { 
//args parameter contains deep link context console.log(args.parameter1); }) // If app is already running parameters are passed through the “run- requested” event app.addEventListener("run-requested", function (event) { 
if(event.userAppConfigArgs){ 
//args parameter contains deep link context console.log(event.userAppConfigArgs.parameter1); } } 

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

Error reporting

When an error occurs prior to app launch, the RVM will show 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.

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

Have questions? Get in touch with us at support@openfin.co.

Analytics

As of version 5.0.0.5, the RVM relays analytical information to OpenFin. Analytical information retrieved 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. OpenFin does not consume personally identifiable information from machines using applications built on OpenFin. Information relayed to OpenFin is only accessible to OpenFin and the developer upon request.

For questions related to RVM analytics, contact support@openfin.co.

Runtime Version Manager


Suggested Edits are limited on API Reference Pages

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