Proxy

The proxy functions can be used to run shell commands or predefined scripts inside a remote network through the automator Proxy.

executeOnProxy

Executes a shell command or a predefined script on the proxy connected to a Proxy account.

const result = executeOnProxy(account, data);

The shape of data depends on the execution mode of the account:

Script mode: { script, parameters }
Where script is the name of a script configured on the proxy and parameters is an optional object with named parameter values. Parameter names must match the profile's params entries exactly, including the - or -- prefix, because the name is placed on the command line as the flag. A parameter with value null is passed as a bare flag without a value, for switch parameters.
Command mode: { command, parameters }
Where command is the shell command to execute and parameters is an optional string appended to the command line.

The result object contains the following fields:

data: the result of the execution, containing the stdout and stderr of the executed process and its exit_code.
When the complete output is valid JSON it is parsed, and the field contains the resulting value instead of a string. Otherwise the field contains the raw output as a string, with the trailing newline removed. This applies to both stdout and stderr.
err: the error message when the execution failed, otherwise null.
info: additional error details, otherwise null.

The following problems throw an error, and the call does not return a result object:

Invalid calls: the account is not a Proxy account, or the payload does not match the account's execution mode.
These are rejected by the automator itself; nothing is sent to the proxy.
Connection errors: the automator cannot reach the proxy, or the response cannot be decrypted with the account's key.
Timeouts: with the pull transport mode, the call throws when the proxy does not deliver a result within 5 minutes, so long-running scripts must finish within that window.

Problems detected by the proxy itself do not throw. The call returns normally and err describes the problem:

The script or command ran but failed.
The process output is still available in data, including the exit_code, and info contains further details. Whether a non-zero exit code counts as a failure depends on the profile's shell: with the unix and cmd shells it sets err, but with the powershell shell the call is reported as successful, so packages must check data.exit_code themselves.
The script is not configured on the proxy's profile, or a parameter is not in the profile's params list.
The payload contains a command while the profile uses the script execution mode.
The token or execution mode does not match the proxy's profile, indicating a mismatch between the account and the proxy configuration.

Example:

Run a shell command on an account with the Command execution mode and log its output:

const result = executeOnProxy("windows-proxy", {
  command: "Get-Service -Name W32Time",
});

log(result.data.stdout);
// => Status   Name     DisplayName
//    ------   ----     -----------
//    Running  W32Time  Windows Time

Example:

Run the createUser script configured on the proxy of an account with the Script execution mode, passing named parameters, and handle a failed execution:

const result = executeOnProxy("script-proxy", {
  script: "createUser",
  parameters: { "-Name": "jdoe", "-Department": "Finance" },
});

if (result.err) {
  log("createUser failed:", result.err, result.data.stderr);
} else {
  log("created:", result.data.stdout);
  // => created: User jdoe created in department Finance
}

The Run scripts and Run shell commands guides show how to configure the proxy side of these calls.

executeOnProxy​

executeOnProxy