Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Version Information

Template Name	Extension Name	Version	Status
Command Execution	ue-cmd	1 (Current 1.0.0)	Fixes and new Features are introduced.

Refer to Changelog for version history information.

Overview

This Universal Task allows command execution on Windows and on Linux. If the command requires a file, users can optionally include a local file or create a file on the Agent, allowing the Controller to serve as the source for the file.

Key Features

Feature

Description

Run Command

Execute a Windows or Linux command as if it were run from a user's default shell. Full command lines are supported, and commands can either be located on the system's PATH or executed via full file paths, as is typical in a command-line environment.

In the Optional Additional File field, a file can be used either as a parameter in the command or as a script to be executed with an interpreter.

Task Output

STDERR and STDOUT are captured in near real-time during command execution, which is essential for monitoring long-running tasks.
If the command outputs JSON to STDOUT, it is included in the EXTENSION_OUTPUT in JSON format, ensuring standardized information flow to subsequent tasks in the workflow.

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area

Details

Python Version

Requires Python of version 3.7 or 3.11. Tested with the Universal Agent bundled Python distribution.

Universal Agent

Both Windows and Linux agents are supported:

Universal Agent for Windows x64 Version >= 7.4.0.0
Universal Agent for Linux Version >= 7.4.0.0

Universal Controller

Universal Controller Version >= 7.4.0.0

Supported Actions

Action: Run Command

Users can execute a single command by specifying the command and its parameters. Full command lines are also supported. The command can be executed if it is available in the PATH environment variable; otherwise, the full path to the command must be provided.

Task authors may optionally include an additional file on the agent, which can be used either as part of the command parameters or as a script to be executed via the command line, using the interpreter of their choice. The contents of this file are stored as a Univeral Controller Data Script. This feature is particularly useful when the required files are not present on the agent’s filesystem, allowing the Controller to serve as the source for these files. The additional file can be accessed using the UE_CMD_ADDFILE environment variable. This environment variable is set internally and can be used within the command line. When running scripts on Windows, the Script name needs to include the file extension. For example, a batch file should be named <name>.bat, and a PowerShell script should be named <name>.ps1.

Configuration examples

This extension enables a wide range of shell functionalities, including command stacking, conditional execution, and output redirection. Additionally, users can directly execute scripts provided inside of the Optional Additional File field, by specifying an interpreter in the command and referencing the provided script through the UE_CMD_ADDFILE environmental variable. Below are some configuration examples:

Task authors should consider the following best practices:

Although the Runtime Directory field is optional, it is strongly recommended to configure it. This provides clarity about the directory from which the command or script is executed.
Thoroughly test your commands before running them in production to avoid any unintended behavior.
Although not always necessary, it is recommended to quote the environmental variable UE_CMD_ADDFILE when attempting to reference it, as there is a chance for the path to it to contain spaces.

OS	Task Configuration	Scenario/Description
Linux		Scenario: Execution of an `ls` command. Task instance success or failure depends on the exit code of the command being executed. If the command is executed with exit code = 0, the task instance completes with Success status. Otherwise, the task instance status is Failed with exit code = 1. This example shows the execution of an `ls` command, including outputs for both success and failure cases. Extension Output when File exists Expand source { "exit_code": 0, "status_description": "Task executed successfully", "invocation": { "extension": "ue-cmd", "version": "1.0.0", "fields": { ... } }, "result": { "metadata": { "runtime_directory": "/tmp", "command": "ls existing_file.txt", "exit_code": 0 }, "command_json_output": "existing_file.txt" } } Extension Output when File does not exists Expand source { "exit_code": 1, "status_description": "Execution returned exit code other than 0", "invocation": { "extension": "ue-cmd", "version": "1.0.0", "fields": { ... } }, "result": { "metadata": { "runtime_directory": "/tmp", "command": "ls non_existent.txt", "exit_code": 2 }, "command_json_output": null } }
Linux		Scenario: Command execution that produces a valid JSON result. This example shows a command that produces JSON output on STDOUT. In such a case, the output is also visible in the task instance EXTENSION output. Extension Output containing JSON object Expand source { "exit_code": 0, "status_description": "Task executed successfully", "invocation": { "extension": "ue-cmd", "version": "1.0.0", "fields": { "action": "Run Command", "command": "echo '{\"name\": \"John\", \"age\": 30, \"city\": \"Athens\"}'", "additional_file": null } }, "result": { "metadata": { "runtime_directory": "/tmp", "command": "echo '{\"name\": \"John\", \"age\": 30, \"city\": \"Athens\"}'", "exit_code": 0 }, "command_json_output": { "name": "John", "age": 30, "city": "Athens" } } }
Linux		Scenario: Execution of a shell script stored in the Controller. The example shows execution of script.sh. Environment variable ${UE_CMD_ADDFILE} points to the script full path referenced from Optional Additional File field. Note: In this example, the reference to the environmental variable UE_CMD_ADDFILE is surrounded by quotes. This was done because the path to this variable contains spaces, so it must be quoted in order for the shell to resolve it correctly.
Linux		Scenario: Conditional execution of commands. This example shows a scenario that depends on the result of grep. If there is a pattern match, a success message is displayed; otherwise, an error message is printed to indicate the pattern wasn't found.
Linux		Scenario: Command Stacking. This example shows multiple commands being executed: execute a shell script provided in the Optional Additional File field pause for 2 seconds print a message indicating that execution has completed.
Linux		Scenario: Redirection of output. In this example, the contents of the current directory are listed in long format using ls -l, and then redirected to the output.log file. Afterwards, the contents are displayed through the cat command.
Windows		Scenario: PowerShell script execution. The example shows execution of a PowerShell script provided by the Optional Additional File field referenced through the UE_CMD_ADDFILE environment variable. PowerShell can execute scripts when related execution policy is granted. For more information, refer to the official Microsoft website. PowerShell Scripts need to be saved with a .ps1 extension.
Windows		Scenario: Execution of a batch file. The example shows execution of a batch file provided by the Optional Additional File field referenced through the UE_CMD_ADDFILE environment variable. Batch Scripts need to be saved with a .bat extension.

Action Output

Output Type

Description

Example

EXTENSION

The extension output follows the standard Extension Output format, providing:

exit_code, status, status_description: General info regarding the task execution.
invocation.fields: The task configuration used for this task execution.
result.metadata:
- runtime_directory: The directory on the Agent Host just before the execution of the command or script
- command: The resulting command line
- exit_code: The command line exit code
result.command_json_output: The JSON result if the STDOUT of the executed command is either a JSON object or a JSON primitive.

Extension output for a simple command line execution

{
	"exit_code": 0,
	"status_description": "Task executed successfully.",
	"invocation": {
		"extension": "ue-cmd",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
		"metadata": {
			"runtime_directory": "/home/user/dir",
			"command": "cat ${UE_CMD_ADDFILE}",
			"exit_code": 0
		},
		"command_json_output": null
	}
}

Extension output in case the STDOUT of the executed command is in JSON format

{
	"exit_code": 0,
	"status_description": "Task executed successfully",
	"invocation": {
		"extension": "ue-cmd",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
		"metadata": {
			"runtime_directory": "/tmp",
			"command": "echo '{\"name\": \"John\", \"age\": 30, \"city\": \"Athens\"}'",
			"exit_code": 0
		},
		"command_json_output": {
			"name": "John",
			"age": 30,
			"city": "Athens"
		}
	}
}

Extension output in case of failure.

{
	"exit_code": 1,
	"status_description": "Execution returned exit code other than 0",
	"invocation": {
		"extension": "ue-cmd",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
	"metadata": {
		"runtime_directory": "/home/user/dir",
		"command": "cat ${UE_CMD_ADDFILE}",
		"exit_code": 1
	},
	"command_json_output": null
	}
}

STDOUT

The STDOUT of the executed command also appears on the STDOUT of the Universal Task.

STDERR

Provides messages from the task instance itself, and from the STDERR or the executed command for informational & debugging purposes. Messages produced by the executed command are prefixed with [[CMD]]

Input Fields

Field	Type	Description	Version Information
Action	Choice	The action performed upon the task execution. Available options: Run Command	Introduced in 1.0.0
Optional Additional File	Script	An optional field to include a file used either as a parameter in the command or as a script to be executed with an interpreter. This file can be referenced in the command line using the UE_CMD_ADDFILE environment variable. This field is particularly useful when the required files are not present on the agent’s filesystem, allowing the Controller to serve as the source for these files.	Introduced in 1.0.0
Command	Large Text	The Command Line to be executed. It should be provided as a single line. Any additional lines will be ignored. Environment variable UC_CMD_ADDFILE can be used here to reference the additional file provided. Required when Action is “Run Command”	Introduced in 1.0.0
Runtime Directory	Text	The Runtime Directory just before the execution of the command. While the Runtime Directory field is not mandatory, it is highly recommended to be configured. This ensures clarity about the directory from which the command is executed	Introduced in 1.0.0

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	“Task executed successfully. “	If the executed command succeeds, it returns an exit code of 0. The task will reflect this success by also returning exit code = 0.
1	Failure	““Execution Failed: <<Error Description>>”	This indicates that the executed command failed, or the task itself failed for some other reason.
20	Failure	“Data Validation Error: <<Error Description>> “	Input fields validation error.

STDOUT and STDERR

STDOUT of the Task Instance includes the STDOUT of the executed command.
STDERR of the Task Instance provides log messages of the task, as well as the STDERR messages from the executed command. The messages from the executed command are prefixed with [[CMD]]. STDERR is for user information purposes. It is not advised to be used for machine processing (like workflow logic).

Backwards compatibility is not guaranteed for the content of STDERR and can be changed in future versions without notice

How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The setup of the template does not impose any restrictions, however with respect to "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.

Changelog

ue-cmd-1.0.0 (2024-10-31)

Initial Release

Browser not supported