Skip to main content

1E SDK

Scripting.RunText

Method	Run
Module	Scripting
Library	Scripting
Action	Execute the specified script supplied as text.
Parameters	`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.
	`Text` (string): The text of the script. Warning The text should be in an appropriate format for the target operating system. For example, a multi-line bash script should have lines separated by just linefeed (newline) characters, not Windows' carriage-return + linefeed.
	`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. Warning If InterpretAsJson is set to true, then the output of the script must be serialized as JSON. PowerShell 3.0 and later has a ConvertTo-Json cmdlet. If using PowerShell 2.0 then LanguageVersion must be set to 2.0 and your script will need to include a function to convert to JSON; an example is provided here _Using PowerShell commands and scripts.
	`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. Warning Try to avoid using `TimeoutKill` if possible, and instead let the sub-process die in its own time. For example, consider the effect of killing an install partway through. Also, only the script interpreter is killed, not any sub-sub-processes it may invoke.
	`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. However, "`Bypass`" is probably the most useful and "`Undefined`" is pointless. In addition to the standard execution policy values, there is an additional special " `Override` " value. This 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` is 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. Note `IgnoreExitCode` only applies if the script actually executes and terminates. This is not a general "keep going regardless of anything failing" switch. For example, if an attempt is made to run a PowerShell script but `powershell.exe` itself is broken, then execution of the method fails regardless of the `IgnoreExitCode` setting.
	`WorkingDirectory` (string, optional): This will set the working directory for the script execution to the specified path. If the path does not exist, the 1E Client will return an error.
	`AsUser` (string; optional; default 1E.Client service user) Windows only: The "domain\user" (down-level logon) account name that the 1E Client will attempt to impersonate on the local machine. If this parameter is absent the command will be executed in the 1E Client process's user context. It is not an error if the specified user is not currently logged on (and this includes accounts that are not even defined). In this case execution is deemed successful but the method does nothing and returns no data. Warning The specified user must be currently logged on and running `explorer.exe` (Windows Explorer).
	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.
Return values	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. Warning Depending on the script, an exit code of 0 does not necessarily mean that execution was successful. `Output` (string): The text produced by the script's execution on standard output and standard error streams. `User` (string): Aligns the row output to the user that the output refers to.
Example	This generates an `Output` value of "`Hello\nGoodbye`" where `\n` is a newline character. Scripting.RunText(Language: "Bash", Text: "echo Hello; echo Goodbye"); AsUser example @users = Users.GetLoggedOnUsers(); @allExecutions = FOREACH @user IN @users DO @account = SELECT Account FROM @user; Scripting.RunText(Language: "Powershell", Text:"echo Hello; echo Goodbye", AsUser:@account); DONE; Passing a path as the Text It is possible to use this method to execute a pre-existing script file as the Text parameter exactly as if within a PowerShell prompt, for example: Scripting.RunText(Language:"PowerShell", Text:"C:\\ProgramData\\1E\\simpleEcho.ps1 $($args[0]) $($args[1])","hello","world"); Script arguments must be explicitly forwarded as shown, as only the author of the above line knows exactly where the parameters should go within the text field. However, the above is really what the Scripting.Run() method is designed for, which makes things far more readable.
Platforms	Windows - PowerShell Linux - bash MacOS - bash
Notes	This is an alternative to the Scripting.Run method which instead uses a script in a file. Because the 1E Client has multiple workers and so can run a number of instructions in parallel, it is possible that conflicting scripts could run at the same time, e.g. each attempting to install software. (Software packages can only usually be installed one at a time.) If this is likely to be a problem, the 1E Client's "`Exclusivity`" configuration value should be set to `true` which will ensure that only one script can run at any time across all workers, causing other scripts to be temporarily suspended. By default `Exclusivity` is `false`. This method does not have a SplitLines parameter. If the script output is a single text block and not JSON, then you can use the Utilities.SplitLines method to split the text block into lines. PowerShell script parameters are in effect surrounded by single quotes when the script is executed. This is to allow parameter values to contain embedded spaces, and to allow what can be metacharacters (e.g. '`(`' for PowerShell or '`$`' for bash) to be treated as literals. This means that PowerShell script parameters cannot contain embedded single quotes. bash scripts can contains embedded quotes. If the 1E Client is shut down while a script is running (with or without a timeout specified), the script subprocess is detached from the 1E Client (so that 1E Client shutdown is not blocked), and the Tachyon instruction's status is set to "execution failed" because the 1E Client cannot know the ultimate fate of the script. It is up to the user to decide whether to resubmit the instruction or not when the 1E Client resumes. By default, a long-running instruction will time out. "Long running" is 3600 seconds, i.e. 1 hour. This is to prevent a hanging script from completely blocking the 1E Client, because the 1E Client has an exclusivity feature for safety such that even if it runs with multiple workers then executing a script prevents any other worker from running an instruction in parallel. (This is because instructions that follow the script's execution might depend on that script having run to completion.) A script hanging indefinitely would completely block the 1E Client, including any instructions to kill the hanging script's process. If a script really must be run to completion, set `TimeoutSecs` to 0 to indicate no timeout.

In this section: