1E 23.7 (SaaS)

Scripting

Execute the specified script file.

Language (string): The shell language of the script. Currently "PowerShell" and "bash" (case is not significant) are supported.

LanguageVersion (string; optional): If specified, the version of the script interpreter, e.g. "3.0" for PowerShell if features not supported in older versions are used. A runtime error occurs if the requested version of the interpreter is not available on the host.

ScriptPath (string): The full path of the script file.

InterpretAsJson (boolean; optional, default false): If specified and has value true, assume that the output of the script is JSON and deserialize it. The return value is then the table produced.

TimeoutSecs (integer; optional, default 3600): If the script does not terminate within the specified number of seconds, return anyway. A value of 0 means an eternal timeout, i.e. none. A negative value is illegal.

TimeoutKill (boolean; optional, default false): If a timeout has been specified and is reached, attempt to kill the script execution sub-process. The method terminates even if killing the script fails for some reason, i.e. the method never hangs. Do not specify if there is no timeout.

ExecutionPolicy (string; optional, default empty): Can only be used with PowerShell scripts. If specified, set the named PowerShell execution policy at the Process scope (i.e. as if the command "powershell.exe -ExecutionPolicy policy ..." was used to execute the script). This can be used to get round lower-scope execution policy settings that might otherwise block script execution. All PowerShell execution policy values are accepted, including " Bypass". However ExecutionPolicy provides an additional special " Override " value, which allows the host's execution policy to be bypassed completely, even at the MachinePolicy and UserPolicy scopes. In other words, "Override" allows a PowerShell script to run whatever the local settings.

ExecutionPolicy values are not case-sensitive.

IgnoreExitCode (boolean, optional, default false): If true, the execution of the script will be considered successful, irrespective of the exit code returned. If false, any non-zero exit code will be interpreted as a failure and this method will return an error.

WorkingDirectory (string, optional): This will set the working directory for the script execution to the specified path. If the path does not exist, the agent will return an error.

script_params ... (optional): Zero or more "anonymous" parameters (i.e. just values, with no " name:" prefix) that will be passed directly to the script as its command line parameters. They can be of various types (string, int, etc.). The script parameters can be included anywhere in the list of method parameters, because they are anonymous.

If parameter InterpretAsJson was true, the data table produced.

Otherwise:

ExitCode (int): The exit code from execution of the script. -2 if the script timed out.

Output (string): The text produced by the script's execution on standard output and standard error streams.

The first PowerShell example runs a script that itself takes 2 positional parameters with values "script param 1" and 42; abandon (but do not kill) the script if it does not end within 5 seconds. Run the script regardless of PowerShell execution policy.

This also shows that usually a call to the Scripting.Run method is used in combination with the httpGetFile() function so that the agent itself supplies the local copy of the script file.

@resource1 = HttpGetFile(URL:"myscript.ps1", Size:483, 
Hash:"ff3f4bd8fb4e0e0ae0caeef8eb03cbc6dbf4d61b005bb5f43427710286811803");
Scripting.Run(Language: "PowerShell", LanguageVersion: "3.0", ScriptPath: @resource1, 
TimeoutSecs: 5, ExecutionPolicy: "Override", "script param 1", 42);

This next PowerShell example runs the script as each of the logged-on users (if any):

AsUser example

@script = HttpGetFile(URL:"myscript.ps1", Size:483, 
Hash:"ff3f4bd8fb4e0e0ae0caeef8eb03cbc6dbf4d61b005bb5f43427710286811803");

@users = Users.GetLoggedOnUsers();
@allExecutions = FOREACH @user IN @users
DO
    @account = SELECT Account FROM @user;
    Scripting.Run(Language: "PowerShell", LanguageVersion:"3.0", ScriptPath:@script, 
    TimeoutSecs:5, AsUser:@account, "script param 1", 42);
DONE;

This Bash example is rather artificial but shows the creation of a temporary bash script then execution of the script to produce "Hello" as the Output value (and an ExitCode of 0).

NativeServices.RunCommand(CommandLine: "/bin/bash -c 'echo echo Hello > /tmp/temp'");
Scripting.Run(Language:"Bash", ScriptPath:"/tmp/temp");

This is an alternative to the Scripting.RunText method which instead uses script text supplied as a parameter.