Runs an executable or batch file. If an unused UUID is provided in options, it will be used. If no UUID is provided, OpenFin will assign one.

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);
});

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
}

Example specifying a lifetime for an external process

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.

example specifying a cwd for an external process

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.logerror;
});

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.logerror;
});

Certificate Validation

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.logerror;
});

Example launching a file downloaded by the user

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.logerror;
        });
    }
});