Class System

Provides access to the OpenFin representation of the current code context (usually a document such as a View or Window), as well as to the current Interop context.

Useful for debugging in the devtools console, where this will intelligently type itself based on the context in which the devtools panel was opened.

Adds a listener to the end of the listeners array for the specified event.

Clears cached data containing application resource files (images, HTML, JavaScript files), cookies, and items stored in the Local Storage.

Remarks

For more information on the accepted options, see the following pages:

• cache: browsing data cache for html files and images (caching)
• cookies: browser cookies
• localStorage: browser data that can be used across sessions (local storage)
• appcache: html5 application cache

Example

const clearCacheOptions = {
    appcache: true,
    cache: true,
    cookies: true,
    localStorage: true
};
fin.System.clearCache(clearCacheOptions).then(() => console.log('Cache cleared')).catch(err => console.log(err));
Copy

Clears all cached data when OpenFin Runtime exits.

Example

fin.System.deleteCacheOnExit().then(() => console.log('Deleted Cache')).catch(err => console.log(err));
Copy

Downloads the given application asset.

Note: This method is restricted by default and must be enabled via API security settings.

Example

async function downloadAsset() {
    const appAsset = {
        src: `${ location.origin }/assets.zip`,
        alias: 'dirApp',
        version: '1.23.24',
        target: 'assets/run.bat'
    };

    return fin.System.downloadAsset(appAsset, (progress => {
    //Print progress as we download the asset.
        const downloadedPercent = Math.floor((progress.downloadedBytes / progress.totalBytes) * 100);
        console.log(`Downloaded ${downloadedPercent}%`);
    }));
}

downloadAsset()
.then(() => console.log('Success'))
.catch(err => console.error(err));

Copy

Download preload scripts from given URLs

Example

const scripts = [
    { url: 'http://.../preload.js' },
    { url: 'http://.../preload2.js' }
];

fin.System.downloadPreloadScripts(scripts).then(results => {
    results.forEach(({url, success, error}) => {
        console.log(`URL: ${url}`);
        console.log(`Success: ${success}`);
        if (error) {
            console.log(`Error: ${error}`);
        }
    });
});
Copy

Downloads a version of the runtime.

Remarks

Only supported in an OpenFin Render process.

Example

var downloadOptions = {
    //Specific version number required, if given a release channel the call will produce an error.
    version: '9.61.30.1'
};

function onProgress(progress) {
    console.log(`${Math.floor((progress.downloadedBytes / progress.totalBytes) * 100)}%`);
}

fin.System.downloadRuntime(downloadOptions, onProgress).then(() => {
    console.log('Download complete');
}).catch(err =>    {
    console.log(`Download Failed, we could retry: ${err.message}`);
    console.log(err);
});
Copy

Exits the Runtime.

Example

fin.System.exit().then(() => console.log('exit')).catch(err => console.log(err));
Copy

Fetches a JSON manifest using the browser process and returns a Javascript object.

Example

const manifest = await fin.System.fetchManifest('https://www.path-to-manifest.com');
console.log(manifest);
Copy

Writes any unwritten cookies data to disk.

Example

fin.System.flushCookieStore()
    .then(() => console.log('success'))
    .catch(err => console.error(err));
Copy

Retrieves an array of data for all applications.

Example

fin.System.getAllApplications().then(apps => console.log(apps)).catch(err => console.log(err));
Copy

Retrieves an array of data (name, ids, bounds) for all application windows.

Example

fin.System.getAllExternalApplications()
.then(externalApps => console.log('Total external apps: ' + externalApps.length))
.catch(err => console.log(err));
Copy

Retrieves all process information.

Remarks

This includes the browser process and every process associated to all entities (windows and views).

Example

const allProcessInfo = await fin.System.getAllProcessInfo();
Copy

Retrieves an array of data (name, ids, bounds) for all application windows.

Example

fin.System.getAllWindows().then(wins => console.log(wins)).catch(err => console.log(err));
Copy

Retrieves app asset information.

Example

fin.System.getAppAssetInfo({alias:'procexp'}).then(assetInfo => console.log(assetInfo)).catch(err => console.log(err));
Copy

Retrieves the command line argument string that started OpenFin Runtime.

Example

fin.System.getCommandLineArguments().then(args => console.log(args)).catch(err => console.log(err));
Copy

Get additional info of cookies.

Example

fin.System.getCookies({name: 'myCookie'}).then(cookies => console.log(cookies)).catch(err => console.log(err));
Copy

Get the current state of the crash reporter.

Example

fin.System.getCrashReporterState().then(state => console.log(state)).catch(err => console.log(err));
Copy

Returns domain settings for the current application. Initial settings are configured with the defaultDomainSettings application option via manifest. Domain settings can be overwritten during runtime with System.setDomainSettings.

Example

const domainSettings = await fin.System.getDomainSettings();
// {
//     "rules": [
//         {
//             "match": [
//                 "https://openfin.co"
//             ],
//             "options": {
//                 "downloadSettings": {
//                     "rules": [
//                         {
//                             "match": [
//                                 "<all_urls>"
//                             ],
//                             "behavior": "prompt"
//                         }
//                     ]
//                 }
//             }
//         }
//     ]
// }
Copy

Retrieves a frame info object for the uuid and name passed in

Remarks

The possible types are 'window', 'iframe', 'external connection' or 'unknown'.

Example

const entityUuid = 'OpenfinPOC';
const entityName = '40c74b5d-ed98-40f7-853f-e3d3c2699175';
fin.System.getEntityInfo(entityUuid, entityName).then(info => console.log(info)).catch(err => console.log(err));

// example info shape
{
    "uuid": "OpenfinPOC",
    "name": "40c74b5d-ed98-40f7-853f-e3d3c2699175",
    "parent": {
        "uuid": "OpenfinPOC",
        "name": "OpenfinPOC"
    },
    "entityType": "iframe"
}
Copy

Gets the value of a given environment variable on the computer on which the runtime is installed

Example

fin.System.getEnvironmentVariable('HOME').then(env => console.log(env)).catch(err => console.log(err));
Copy

Get current focused window.

Example

fin.System.getFocusedWindow().then(winInfo => console.log(winInfo)).catch(err => console.log(err));
Copy

Retrieves system information.

Example

fin.System.getHostSpecs().then(specs => console.log(specs)).catch(err => console.log(err));
Copy

Returns an array of all the installed runtime versions in an object.

Example

fin.System.getInstalledRuntimes().then(runtimes => console.log(runtimes)).catch(err => console.log(err));
Copy

Retrieves the contents of the log with the specified filename.

Example

async function getLog() {
    const logs = await fin.System.getLogList();
    return await fin.System.getLog(logs[0]);
}

getLog().then(log => console.log(log)).catch(err => console.log(err));
Copy

Retrieves an array containing information for each log file.

Example

fin.System.getLogList().then(logList => console.log(logList)).catch(err => console.log(err));
Copy

Returns a unique identifier (UUID) provided by the machine.

Example

fin.System.getMachineId().then(id => console.log(id)).catch(err => console.log(err));
Copy

Returns the minimum (inclusive) logging level that is currently being written to the log.

Example

fin.System.getMinLogLevel().then(level => console.log(level)).catch(err => console.log(err));
Copy

Retrieves an object that contains data about the monitor setup of the computer that the runtime is running on.

Example

fin.System.getMonitorInfo().then(monitorInfo => console.log(monitorInfo)).catch(err => console.log(err));
Copy

Returns the mouse in virtual screen coordinates (left, top).

Example

fin.System.getMousePosition().then(mousePosition => console.log(mousePosition)).catch(err => console.log(err));
Copy

Returns an array with all printers of the caller and not all the printers on the desktop.

Example

fin.System.getPrinters()
    .then((printers) => {
        printers.forEach((printer) => {
            if (printer.isDefault) {
                console.log(printer);
            }
        });
    })
    .catch((err) => {
        console.log(err);
    });
Copy

Retrieves an array of all of the runtime processes that are currently running. Each element in the array is an object containing the uuid and the name of the application to which the process belongs.

Deprecated

Please use our new set of process APIs: Window.getProcessInfo View.getProcessInfo Application.getProcessInfo System.getAllProcessInfo

Example

fin.System.getProcessList().then(ProcessList => console.log(ProcessList)).catch(err => console.log(err));
Copy

Retrieves the Proxy settings.

Example

fin.System.getProxySettings().then(ProxySetting => console.log(ProxySetting)).catch(err => console.log(err));

//This response has the following shape:
{
    config: {
        proxyAddress: "proxyAddress", //the configured Proxy Address
        proxyPort: 0, //the configured Proxy port
        type: "system" //Proxy Type
    },
    system: {
        autoConfigUrl: "",
        bypass: "",
        enabled: false,
        proxy: ""
    }
}
Copy

Returns information about the running Runtime in an object.

Example

fin.System.getRuntimeInfo().then(RuntimeInfo => console.log(RuntimeInfo)).catch(err => console.log(err));
Copy

Returns information about the running RVM in an object.

Example

fin.System.getRvmInfo().then(RvmInfo => console.log(RvmInfo)).catch(err => console.log(err));
Copy

Returns the json blob found in the desktop owner settings for the specified service.

Remarks

More information about desktop services can be found here. This call will reject if the desktop owner settings file is not present, not correctly formatted, or if the service requested is not configured or configured incorrectly.

Example

// Here we are using the [layouts](https://github.com/HadoukenIO/layouts-service) service.
fin.System.getServiceConfiguration({name:'layouts'}).then(console.log).catch(console.error);
Copy

Returns a hex encoded hash of the machine id and the currently logged in user name. This is the recommended way to uniquely identify a user / machine combination.

Remarks

For Windows systems this is a sha256 hash of the machine ID set in the registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid and USERNAME.

For OSX systems, a native-level call is used to get the machine ID.

Example

fin.System.getUniqueUserId().then(id => console.log(id)).catch(err => console.log(err));
Copy

Returns the version of the runtime. The version contains the major, minor, build and revision numbers.

Example

fin.System.getVersion().then(v => console.log(v)).catch(err => console.log(err));
Copy

Returns information about the given app's certification status

Example

const manifestUrl = "http://localhost:1234/app.json"
try {
    const certificationInfo = await fin.System.isAppCertified(manifestUrl);
} catch(err) {
    console.error(err)
}
Copy

Runs an executable or batch file. A path to the file must be included in options.
A uuid may be optionally provided. If not provided, OpenFin will create a uuid for the new process.
Note: This method is restricted by default and must be enabled via API security settings. Also, this api has an enhanced permission set to make it less dangerous. So application owners can only allow to launch the assets owned by the application, the enabled downloaded files or the restricted executables.

Remarks

If an unused UUID is provided in options, it will be used. If no UUID is provided, OpenFin will assign one. This api has an enhanced permission set to make it less dangerous. So application owners can only allow to launch the assets owned by the application, the enabled downloaded files or the restricted executables.

Note: Since appAssets relies on the RVM, which is missing on MAC_OS, 'alias' is not available. Instead provide the full path e.g. /Applications/Calculator.app/Contents/MacOS/Calculator.

Example

Basic Example:

fin.System.launchExternalProcess({
    path: 'notepad',
    arguments: '',
    listener: function (result) {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

Promise resolution:

//This response has the following shape:
{
    uuid: "FB3E6E36-0976-4C2B-9A09-FB2E54D2F1BB" // The mapped UUID which identifies the launched process
}
Copy

Listener callback:

//This response has the following shape:
{
    topic: "exited", // Or "released" on a call to releaseExternalProcess
    uuid: "FB3E6E36-0976-4C2B-9A09-FB2E54D2F1BB", // The mapped UUID which identifies the launched process
    exitCode: 0 // Process exit code
}
Copy

By specifying a lifetime, an external process can live as long the window/application that launched it or persist after the application exits. The default value is null, which is equivalent to 'persist', meaning the process lives on after the application exits:

fin.System.launchExternalProcess({
    path: 'notepad',
    arguments: '',
    listener: (result) => {
        console.log('the exit code', result.exitCode);
    },
    lifetime: 'window'
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

Note: A process that exits when the window/application exits cannot be released via fin.desktop.System.releaseExternalProcess.

By specifying a cwd, it will set current working directory when launching an external process:

fin.System.launchExternalProcess({
    path: 'cmd.exe',
    cwd: 'c:\\temp',
    arguments: '',
    listener: (result) => {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

Example using an alias from app.json appAssets property:

"appAssets": [
    {
        "src": "exe.zip",
        "alias": "myApp",
        "version": "4.12.8",
        "target": "myApp.exe",
        "args": "a b c d"
    },
]
Copy

//  When called, if no arguments are passed then the arguments (if any)
//  are taken from the 'app.json' file, from the  'args' parameter
//  of the 'appAssets' Object with the relevant 'alias'.
fin.System.launchExternalProcess({
    //Additionally note that the executable found in the zip file specified in appAssets
    //will default to the one mentioned by appAssets.target
    //If the the path below refers to a specific path it will override this default
    alias: 'myApp',
    listener: (result) => {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

Example using an alias but overriding the arguments:

"appAssets": [
    {
        "src": "exe.zip",
        "alias": "myApp",
        "version": "4.12.8",
        "target": "myApp.exe",
        "args": "a b c d"
    },
]
Copy

//  If 'arguments' is passed as a parameter it takes precedence
//  over any 'args' set in the 'app.json'.
fin.System.launchExternalProcess({
    alias: 'myApp',
    arguments: 'e f g',
    listener: (result) => {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

It is now possible to optionally perform any combination of the following certificate checks against an absolute target via fin.desktop.System.launchExternalProcess():

"certificate": {
    "serial": "3c a5 ...",                        // A hex string with or without spaces
    "subject": "O=OpenFin INC., L=New York, ...", // An internally tokenized and comma delimited string allowing partial or full checks of the subject fields
    "publickey": "3c a5 ...",                     // A hex string with or without spaces
    "thumbprint": "3c a5 ...",                    // A hex string with or without spaces
    "trusted": true                               // A boolean indicating that the certificate is trusted and not revoked
}
Copy

Providing this information as part of the default configurations for assets in an application's manifest will be added in a future RVM update:

fin.System.launchExternalProcess({
    path: 'C:\\Users\\ExampleUser\\AppData\\Local\\OpenFin\\OpenFinRVM.exe',
    arguments: '--version',
    certificate: {
        trusted: true,
        subject: 'O=OpenFin INC., L=New York, S=NY, C=US',
        thumbprint: '‎3c a5 28 19 83 05 fe 69 88 e6 8f 4b 3a af c5 c5 1b 07 80 5b'
    },
    listener: (result) => {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => {
    console.log(processIdentity);
}).catch(error => {
    console.log(error);
});
Copy

It is possible to launch files that have been downloaded by the user by listening to the window file-download-completed event and using the fileUuid provided by the event:

const win = fin.Window.getCurrentSync();
win.addListener('file-download-completed', (evt) => {
    if (evt.state === 'completed') {
        fin.System.launchExternalProcess({
            fileUuid: evt.fileUuid,
            arguments: '',
            listener: (result) => {
                console.log('the exit code', result.exitCode);
            }
        }).then(processIdentity => {
            console.log(processIdentity);
        }).catch(error => {
            console.log(error);
        });
    }
});
Copy

Launching assets specified in the app manifest:

Sample appAssets section in app.json

    "appAssets": [
        {
            "src": "http://filesamples.com/exe.zip",
            "alias": "myApp",
            "version": "4.12.8",
            "target": "myApp.exe",
            "args": "a b c d"
        },
        {
            "src": "http://examples.com/exe.zip",
            "alias": "myApp2",
            "version": "5.12.8",
            "target": "myApp2.exe",
            "args": "a b c"
        }
    ]
Copy

This permission allows for launching of all assets specified in the above appAssets section. ("myApp" and "myApp2"):

    "permissions": {
       "System": {
           "launchExternalProcess": {
                "enabled": true,
                "assets": {
                    "enabled": true
                }
            }
       }
    }
Copy

This permission allows for launching of only the "myApp" asset in the above appAssets section, as defined in srcRules:

    "permissions": {
       "System": {
           "launchExternalProcess": {
                "enabled": true,
                "assets": {
                    "enabled": true
                    "srcRules": [
                        {
                            "match": [
                                "*://filesamples.com/*"
                            ],
                            "behavior": "allow"
                        },
                        {
                            "match": [
                                "<all_urls>"
                            ],
                            "behavior": "block"
                        }
                    ]
                }
            }
       }
    }
Copy

Launching downloaded files:

    "permissions": {
       "System": {
           "launchExternalProcess": {
                "enabled": true,
                "downloads": {
                    "enabled": true
                }
            }
       }
    }
Copy

This permission allows to launch all the executables:

    "permissions": {
       "System": {
           "launchExternalProcess": {
                "enabled": true,
                "executables": {
                    "enabled": true
                }
            }
       }
    }
Copy

This permission only allows launching of executables whose file paths match the corresponding pathRules:

    "permissions": {
       "System": {
           "launchExternalProcess": {
                "enabled": true,
                "executables": {
                    "enabled": true
                    "pathRules": [
                        {
                            "match": [
                                "/Windows/System32/*.exe"
                            ],
                            "behavior": "allow"
                        },
                        {
                            "match": [
                                "*.exe"
                            ],
                            "behavior": "block"
                        }
                    ]
                }
            }
       }
    }
Copy

Launch application using a manifest URL/path. It differs from Application.startFromManifest in that this API can accept a manifest using the fin protocol.

Remarks

Supports protocols http/s and fin/s, and also a local path.

Note: This API is Windows only.

Example

This API can handle most manifest types. Some examples below.

Traditional:

const manifest = await fin.System.launchManifest(
  'https://demoappdirectory.openf.in/desktop/config/apps/OpenFin/HelloOpenFin/app.json');
console.log(manifest);
Copy

Platform:

const manifest = await fin.System.launchManifest('https://openfin.github.io/platform-api-project-seed/public.json');
console.log(manifest);
Copy

Launching traditional manifest into a platform:

const manifest = await fin.System.launchManifest(
  'https://openfin.github.io/platform-api-project-seed/public.json?\
  $$appManifestUrl=https://demoappdirectory.openf.in/desktop/config/\
  apps/OpenFin/HelloOpenFin/app.json');
console.log(manifest);
Copy

Launching with RVM options:

const manifest = await fin.System.launchManifest('https://openfin.github.io/platform-api-project-seed/public.json',
    { noUi: true, userAppConfigArgs: { abc: '123', xyz: '789' } });
console.log(manifest);
Copy

Local Path:

const manifest =  await fin.System.launchManifest('file://c:\\path\\to\\manifest\\file.json');
console.log(manifest);
Copy

Launching with RVM 'subscribe' option:

This option allows users to subscribe to app version resolver events when calling launchManifest with fallbackManifests specified.

fin.System.launchManifest('fins://system-apps/notifications/app.json', { subscribe: (launch) => {
        launch.on('app-version-progress', (progress) => {
            console.log("Trying manifest " + progress.manifest)
        });

        launch.on('runtime-status', (status) => {
            console.log("Runtime status: " + JSON.stringify(status));
        });

        // RVM has successfully found the target runtime version
        launch.on('app-version-complete', (complete) => {
            console.log("Parent app " + complete.srcManifest + " resolved to " + complete.manifest);
            launch.removeAllListeners();
        });

        // RVM failed to find an available runtime version
        launch.on('app-version-error', (error) => {
            console.log("Failed to resolve " + error.srcManifest + " from the fallbackManifests");
            launch.removeAllListeners();
        });
    }
});
Copy

Writes the passed message into both the log file and the console.

Example

fin.System.log("info", "An example log message").then(() => console.log('Log info message')).catch(err => console.log(err));
Copy

Monitors a running process. A pid for the process must be included in options.
A uuid may be optionally provided. If not provided, OpenFin will create a uuid for the new process.

Remarks

If an unused uuid is provided in options, it will be used. If no uuid is provided, OpefinFin will assign a uuid.

Example

fin.System.monitorExternalProcess({
    pid: 10208,
    uuid: 'my-external-process', // optional
    listener: function (result) {
        console.log('the exit code', result.exitCode);
    }
}).then(processIdentity => console.log(processIdentity)).catch(err => console.log(err));
Copy

Adds a listener to the end of the listeners array for the specified event.

Remarks

Event payloads are documented in the Events namespace.

Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed.

Remarks

Event payloads are documented in the Events namespace.

Opens the passed URL in the default web browser.

Remarks

It only supports http(s) and fin(s) protocols by default. In order to use other custom protocols, they have to be enabled via API security settings. File protocol and file path are not supported.

Example

fin.System.openUrlWithBrowser('https://cdn.openfin.co/docs/javascript/stable/tutorial-System.openUrlWithBrowser.html')
.then(() => console.log('Opened URL'))
.catch(err => console.log(err));
Copy

Example of permission definition to enable non-default protocols:

Note: permission definition should be specified in an app manifest file if there is no DOS settings. Otherwise it has to be specified in both DOS and app manifest files.

    "permissions": {
       "System": {
           "openUrlWithBrowser": {
                "enabled": true,
                "protocols": [ "msteams", "slack"]
            }
       }
    }
Copy

Adds a listener to the beginning of the listeners array for the specified event.

Remarks

Event payloads are documented in the Events namespace.

Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed. The listener is added to the beginning of the listeners array.

Remarks

Event payloads are documented in the Events namespace.

Query permission of a secured api in current context.

Example

fin.System.queryPermissionForCurrentContext('System.launchExternalProcess').then(result => console.log(result)).catch(err => console.log(err));

//This response has the following shape:
{
   permission: 'System.launchExternalProcess', // api full name
   state: 'granted', // state of permission
   granted: true
}
Copy

Reads the specifed value from the registry.

Remarks

This method is restricted by default and must be enabled via API security settings.

Example

fin.System.readRegistryValue("HKEY_LOCAL_MACHINE", "HARDWARE\\DESCRIPTION\\System", "BootArchitecture").then(val => console.log(val)).catch(err => console.log(err));
Copy

See here for Window's error code definitions.

Example payloads of different registry types:

See list of types here.

// REG_DWORD
{
    data: 1,
    rootKey: "HKEY_LOCAL_MACHINE",
    subkey: "Foo\Bar",
    type: "REG_DWORD",
    value: "Baz"
}

// REG_QWORD
{
    data: 13108146671334112,
    rootKey: "HKEY_LOCAL_MACHINE",
    subkey: "Foo\Bar",
    type: "REG_QWORD",
    value: "Baz"
}

// REG_SZ
{
    data: "FooBarBaz",
    rootKey: "HKEY_LOCAL_MACHINE",
    subkey: "Foo\Bar",
    type: "REG_SZ",
    value: "Baz"
}

// REG_EXPAND_SZ
{
    data: "C:\User\JohnDoe\AppData\Local",
    rootKey: "HKEY_CURRENT_USER",
    subkey: "Foo\Bar",
    type: "REG_EXPAND_SZ",
    value: "Baz"
}

// REG_MULTI_SZ
{
    data: [
        "Foo",
        "Bar",
        "Baz"
    ],
    rootKey: "HKEY_CURRENT_USER",
    subkey: "Foo\Bar",
    type: "REG_MULTI_SZ",
    value: "Baz"
}

// REG_BINARY
{
    data: {
        data: [
            255,
            255,
            0,
            43,
            55,
            0,
            0,
            255,
            255
        ],
        type: "Buffer"
    },
    rootKey: "HKEY_CURRENT_USER",
    subkey: "Foo\Bar",
    type: "REG_BINARY",
    value: "Baz"
}
Copy

This function call will register a unique id and produce a token. The token can be used to broker an external connection.