Disclaimer

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

Version Information

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

Requirements

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

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:

OS	Task Configuration	Scenario/Description
Linux		Scenario: Based on the exit code of the command, the task instance is executed with success or failure. If the command is executed with exit code = 0, the default behavior is that the Task Instance FAILED status is exit code = 1. This example shows the execution of the ls command 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

{
	"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
	}
}

{
	"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"
		}
	}
}

{
	"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
	}
}

Input Fields

Exit Codes

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).

How To

Import Universal Template

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

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow these instructions.

3. 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:

Changelog

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

Initial Release