Adds a listener to the end of the listeners array for the specified event.
Optionaloptions: SubscriptionOptionsClears cached data containing application resource files (images, HTML, JavaScript files), cookies, and items stored in the Local Storage.
See below for details.
For more information on the accepted options, see the following pages:
const clearCacheOptions = {
appcache: true,
cache: true,
cookies: true,
localStorage: true
};
fin.System.clearCache(clearCacheOptions).then(() => console.log('Cache cleared')).catch(err => console.log(err));
Downloads the given application asset.
Note: This method is restricted by default and must be enabled via API security settings.
App asset object
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));
Download preload scripts from given URLs
URLs of preload scripts.
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}`);
}
});
});
Downloads a version of the runtime.
Download options.
called as the runtime is downloaded with progress information.
Only supported in an OpenFin Render process.
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);
});
Retrieves an array of data for all applications.
ExperimentalRetrieves all process information.
Retrieves an array of data (name, ids, bounds) for all application windows.
Retrieves app asset information.
Get additional info of cookies.
Get the current state of the crash reporter.
Retrieves the registration state for a given custom protocol.
Note: This method is restricted by default and must be enabled via API security settings. It requires RVM 12 or higher version.
These protocols are reserved and cannot get states for them:
const protocolState = await fin.System.getCustomProtocolState('protocol1'
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.
Retrieves a frame info object for the uuid and name passed in
The UUID of the target.
The name of the target.
The possible types are 'window', 'iframe', 'external connection' or 'unknown'.
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"
}
Gets the currently-installed
Retrieves the contents of the log with the specified filename.
A object that id defined by the GetLogRequestType interface
Retrieves an object that contains data about the monitor setup of the computer that the runtime is running on.
Returns the mouse in virtual screen coordinates (left, top).
Returns an array with all printers of the caller and not all the printers on the desktop.
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.
Please use our new set of process APIs: Window.getProcessInfo View.getProcessInfo Application.getProcessInfo System.getAllProcessInfo
fin.System.getProcessList().then(ProcessList => console.log(ProcessList)).catch(err => console.log(err));
Retrieves the Proxy settings.
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: ""
}
}
Returns information about the running Runtime in an object.
Returns the json blob found in the desktop owner settings for the specified service.
An object containing a name key that identifies the service.
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.
// Here we are using the [layouts](https://github.com/HadoukenIO/layouts-service) service.
fin.System.getServiceConfiguration({name:'layouts'}).then(console.log).catch(console.error);
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.
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.
fin.System.getUniqueUserId().then(id => console.log(id)).catch(err => console.log(err));
Returns information about the given app's certification status
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.
A object that is defined in the ExternalProcessRequestType interface
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.
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);
});
Promise resolution:
//This response has the following shape:
{
uuid: "FB3E6E36-0976-4C2B-9A09-FB2E54D2F1BB" // The mapped UUID which identifies the launched process
}
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
}
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);
});
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);
});
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"
},
]
// 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);
});
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"
},
]
// 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);
});
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
}
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);
});
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);
});
}
});
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"
}
]
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
}
}
}
}
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"
}
]
}
}
}
}
Launching downloaded files:
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"downloads": {
"enabled": true
}
}
}
}
This permission allows to launch all the executables:
"permissions": {
"System": {
"launchExternalProcess": {
"enabled": true,
"executables": {
"enabled": true
}
}
}
}
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"
}
]
}
}
}
}
ExperimentalLaunch application using a manifest URL/path. It differs from Application.startFromManifest in that this API can accept a manifest using the fin protocol.
The manifest's URL or path.
Parameters that the RVM will use.
Supports protocols http/s and fin/s, and also a local path.
Note: This API is Windows only.
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);
Platform:
const manifest = await fin.System.launchManifest('https://openfin.github.io/platform-api-project-seed/public.json');
console.log(manifest);
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);
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);
Local Path:
const manifest = await fin.System.launchManifest('file://c:\\path\\to\\manifest\\file.json');
console.log(manifest);
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();
});
}
});
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.
If an unused uuid is provided in options, it will be used. If no uuid is provided, OpefinFin will assign a uuid.
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));
Adds a listener to the end of the listeners array for the specified event.
Optionaloptions: SubscriptionOptionsEvent payloads are documented in the OpenFin.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.
Optionaloptions: SubscriptionOptionsEvent payloads are documented in the OpenFin.Events namespace.
Opens the passed URL in the default web browser.
The URL to open
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.
fin.System.openUrlWithBrowser('https://cdn.openfin.co/docs/javascript/stable/tutorial-System.openUrlWithBrowser.html')
.then(() => console.log('Opened URL'))
.catch(err => console.log(err));
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"]
}
}
}
Adds a listener to the beginning of the listeners array for the specified event.
Optionaloptions: SubscriptionOptionsEvent payloads are documented in the OpenFin.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.
Optionaloptions: SubscriptionOptionsEvent payloads are documented in the OpenFin.Events namespace.
Query permission of a secured api in current context.
The full name of a secured API.
If a function has a structured permission value, the value of granted will reflect the enabled key
of the call's permissions literal. In this case, permission may still be denied to a call pending arguments or other
runtime state. This is indicated with state: unavailable.
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
}
Reads the specifed value from the registry.
The registry root key.
The registry key.
The registry value name.
This method is restricted by default and must be enabled via API security settings.
fin.System.readRegistryValue("HKEY_LOCAL_MACHINE", "HARDWARE\\DESCRIPTION\\System", "BootArchitecture").then(val => console.log(val)).catch(err => console.log(err));
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"
}
Attempts to install and enable extensions for the security realm. Users may want to call this function in response
to an extensions-install-failed event. Only extensions allowed by every application on the current security realm
will be installed/enabled.
Creates a new registry entry under the HKCU root Windows registry key if the given custom protocol name doesn't exist or overwrites the existing registry entry if the given custom protocol name already exists.
Note: This method is restricted by default and must be enabled via API security settings. It requires RVM 12 or higher version.
These protocols are reserved and cannot be registered:
if a given custom protocol failed to be registered.
if a manifest URL contains the '%1' string.
if a manifest URL contains a query string parameter which name equals to the Protocol Launch Request Parameter Name.
if the full length of the command string that is to be written to the registry exceeds 2048 bytes.
fin.System.registerCustomProtocol({protocolName:'protocol1'}).then(console.log).catch(console.error);
This function call will register a unique id and produce a token. The token can be used to broker an external connection.
A UUID for the remote connection.
ExperimentalRegisters a system shutdown handler so user can do some cleanup before system is shutting down.
system shutdown handler
Once system shutdown starts, you are unable to cancel it.
fin.System.registerShutdownHandler((shutdownEvent) => {
// save state or cleanup
console.log('do some cleanup before shutdown');
// Notify app is ready for termination.
shutdownEvent.proceed();
})
.then(() => console.log('Shutdown handler registered!'))
.catch(err => console.log(err));
(Internal) Register the usage of a component with a platform
Object with data and type
async function registerUsage() {
const app = await fin.System.getCurrent();
return await fin.System.registerUsage({
type: 'workspace-licensing',
// example values for the following data object
data: {
apiVersion: '1.0',
componentName: 'home',
componentVersion: '1.0',
allowed: true,
rejectionCode: ''
}
});
}
registerUsage().then(() => console.log('Successfully registered component application')).catch(err => console.log(err));
Removes all listeners, or those of the specified event.
OptionaleventType: Remove a listener from the listener array for the specified event.
Optionaloptions: SubscriptionOptionsRetrieves the UUID of the computer on which the runtime is installed
The uuid of the running application
Used to serve an asset signed by OpenFin within the given runtime.
Not indended for general use, will be used by the @openfin/workspace-platform package.
Sets the domain settings for the current application.
domain settings object
const domainSettings = await fin.System.getDomainSettings();
// {
// "rules": [
// {
// "match": [
// "https://openfin.co"
// ],
// "options": {
// "downloadSettings": {
// "rules": [
// {
// "match": [
// "<all_urls>"
// ],
// "behavior": "prompt"
// }
// ]
// }
// }
// }
// ]
// }
// Valid rule behaviors are 'prompt' and 'no-prompt'
domainSettings.rules[0].options.downloadSettings.rules[0].behavior = 'no-prompt';
await fin.System.setDomainSettings(domainSettings);
const newDomainSettings = await fin.System.getDomainSettings();
// {
// "rules": [
// {
// "match": [
// "https://openfin.co"
// ],
// "options": {
// "downloadSettings": {
// "rules": [
// {
// "match": [
// "<all_urls>"
// ],
// "behavior": "no-prompt"
// }
// ]
// }
// }
// }
// ]
// }
Set the minimum log level above which logs will be written to the OpenFin log
Shows the Chromium Developer Tools for the specified window
This is a object that is defined by the Identity interface
Start the crash reporter if not already running.
configure crash reporter
You can optionally specify diagnosticsMode to have the logs sent to
OpenFin on runtime close. (NOTE: diagnosticsMode will turn on verbose logging and disable the sandbox
for newly launched renderer processes. See https://developers.openfin.co/of-docs/docs/debugging#diagnostics-mode for
more details.)
fin.System.startCrashReporter({diagnosticsMode: true}).then(reporter => console.log(reporter)).catch(err => console.log(err));
Attempt to close an external process. The process will be terminated if it has not closed after the elapsed timeout in milliseconds.
Note: This method is restricted by default and must be enabled via API security settings.
A object defined in the TerminateExternalRequestType interface
fin.System.launchExternalProcess({
path: "notepad",
listener: function (result) {
console.log("The exit code", result.exitCode);
}
})
.then(identity => fin.System.terminateExternalProcess({uuid: identity.uuid, timeout:2000, killTree: false}))
.then(() => console.log('Terminate the process'))
.catch(err => console.log(err));
Removes the registry entry for a given custom protocol.
Note: This method is restricted by default and must be enabled via API security settings. It requires RVM 12 or higher version.
These protocols are reserved and cannot be unregistered:
if a protocol entry failed to be removed in registry.
await fin.System.unregisterCustomProtocol('protocol1');
Updates Process Logging values: periodic interval and outlier detection entries and interval.
Process Logging updatable options.
When enabling verbose mode, additional process information is logged to the debug.log:
await fin.System.updateProcessLoggingOptions({
interval: 10,
outlierDetection: {
interval: 15,
entries: 200
}
});
Update the OpenFin Runtime Proxy settings.
A config object defined in the ProxyConfig interface
An object representing the core of OpenFin Runtime. Allows the developer to perform system-level actions, such as accessing logs, viewing processes, clearing the cache and exiting the runtime as well as listen to system events.