UAC Utility: Enhanced Windows

Disclaimer

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

Version Information

Template Name	Extension Name	Version	Status
Enhanced Windows	ue-enhanced-windows	1.0.0	Initial Version.

Refer to Changelog for version history information.

Overview

Windows workloads are typically executed as commands or batch scripts through the Windows command interpreter. Such workloads often depend on a specific set of environment variables being in place and on their output being written to a known location.

This Universal Task allows customers to run Windows commands and batch scripts on a Universal Agent for Windows straight from the Universal Controller, with control over the environment applied before execution and over where standard output and standard error are written.

Key Features

Feature	Description
Command and Script Execution	Run a Windows command or an inline batch script and return its exit code and output to the task instance.
Profile Sourcing	Apply environment variables from a profile file before execution, either from a batch file or from a file of KEY=VALUE pairs.
Output Redirection	Write STDOUT and STDERR to files, append to existing files, or cross-redirect one stream into the other.

Requirements

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

Area	Details
Python Version	Requires Python 3.11, tested with Agent bundled python distribution.
Universal Agent Compatibility	Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0.
Universal Controller Compatibility	Universal Controller Version >= 7.6.0.0.
Network and Connectivity	Network connectivity to the target Windows host running the Universal Agent is required.

Supported Actions

There is one Top-Level action controlled by the Action Field:

The Launch Windows Task action runs either a Windows command or an inline batch script through the Windows command interpreter on the Universal Agent host. A profile file is sourced first when one is configured, and the task ends once the command or script has terminated, returning its exit code and captured output.

Action Output

EXTENSION

The extension output provides the following information:

• exit_code, status_description: General info regarding the task execution.
• invocation.fields: The task configuration used for this execution. For more information refer to exit codes table.
• result.rc: The return code of the executed command or script.
• result.output: The output captured from the executed command or script, taken from STDOUT, or from STDERR when STDOUT is empty.
• result.errors: List of errors that might have occurred during execution.

Examples:

Successful execution

{
  "exit_code": 0,
  "status_description": "Successful Execution",
  "invocation": {
    "extension": "ue-enhanced-windows",
    "version": "1.0.0",
    "fields": {
      "action": "Launch Windows Task",
      "profile_file": "C:\\Stonebranch\\profiles\\batch_env.txt",
      "profile_format": "Environment Variable File",
      "command_or_script": "Command",
      "command": "dir %BATCH_HOME%\\input",
      "stdout_file": "C:\\Stonebranch\\logs\\daily_load.out",
      "stderr_file": "C:\\Stonebranch\\logs\\daily_load.err",
      "append_stdout": false,
      "append_stderr": false
    }
  },
  "result": {
    "rc": 0,
    "output": " Volume in drive C has no label.\r\n Directory of C:\\data\\input\r\n\r\n27/08/2026  09:14            18.432 orders.csv\r\n"
  }
}

Failed execution

{
  "exit_code": 1,
  "status_description": "Execution Failed: File not found: 'C:\\Stonebranch\\profiles\\batch_env.txt'",
  "invocation": {
    "extension": "ue-enhanced-windows",
    "version": "1.0.0",
    "fields": {
      "action": "Launch Windows Task",
      "profile_file": "C:\\Stonebranch\\profiles\\batch_env.txt",
      "profile_format": "Environment Variable File",
      "command_or_script": "Command",
      "command": "dir %BATCH_HOME%\\input",
      "stdout_file": "",
      "stderr_file": "",
      "append_stdout": false,
      "append_stderr": false
    }
  },
  "result": {
    "errors": ["Execution Failed: File not found: 'C:\\Stonebranch\\profiles\\batch_env.txt'"]
  }
}

STDOUT

Contains the command or the script that was executed, followed by the output captured from the execution, labelled with OUTPUT for content coming from STDOUT and ERROR for content coming from STDERR. When a redirection file is configured, the contents of that file are printed as well.

Example:

COMMAND: dir %BATCH_HOME%\input
OUTPUT:  Volume in drive C has no label.
 Directory of C:\data\input

27/08/2026  09:14            18.432 orders.csv

Configuration Examples

Example: Command execution, environment variable profile, output redirected to files

Command or Script is "Command", the Profile File points to a file of KEY=VALUE pairs, and Profile Format is "Environment Variable File", so the variables it declares are applied to the environment before the command runs. The Command field holds a command that references one of those variables. STDOUT File and STDERR File name two separate files, and neither append option is selected, so both files are overwritten on every run. The task ends when the command terminates, and the contents of both files are printed back to the task instance STDOUT and STDERR.

Example: Script execution, Windows batch profile, no output redirection

Command or Script is "Script", the Profile File is a batch file and Profile Format is "Windows Batch File", so the file is called and every variable it leaves set is applied before execution. The Script field holds a batch script, which is executed as a Windows batch script. Neither STDOUT File nor STDERR File is configured, so the output of the script is returned directly to the task instance STDOUT and STDERR without being written to a file on the Agent host.

Example: Command execution, no profile, both streams appended to one file

Command or Script is "Command" and no Profile File is configured, so the command runs with the environment of the Universal Agent. STDOUT File and STDERR File name the same file and both Append STDOUT and Append STDERR are selected, so the output and the errors of every run are written to a single combined log file that grows across task instances.

Input Fields

Name	Type	Description	Version Information
Action	Choice	The action to be executed. Available options: Launch Windows Task (default)	Introduced in 1.0.0
Profile File	Text	The path to a file that is sourced before the command or the script runs, so that the environment variables it declares are available during execution. Environment variables are supported in the path.	Introduced in 1.0.0
Profile Format	Choice	The format of the file named in Profile File. Available options: Environment Variable File (default) - a file containing only KEY=VALUE pairs. Windows Batch File - a batch file that is called, with every variable it leaves set applied to the environment.	Introduced in 1.0.0
Command or Script	Choice	The kind of workload to execute. Available options: Command (default) - a single command line. Script - an inline script.	Introduced in 1.0.0
Command	Text	The command to be executed. Environment variables are supported. This field is visible and required when Command or Script is "Command".	Introduced in 1.0.0
Script	Script	The script to execute. Scripts are executed as Windows batch scripts. This field is visible and required when Command or Script is "Script".	Introduced in 1.0.0
STDOUT File	Text	The file that STDOUT is redirected to. The content of the file is also printed to the task instance STDOUT.	Introduced in 1.0.0
STDERR File	Text	The file that STDERR is redirected to. The content of the file is also printed to the task instance STDERR.	Introduced in 1.0.0
Append STDOUT	Checkbox	Check to append to the file named in STDOUT File instead of overwriting it.	Introduced in 1.0.0
Append STDERR	Checkbox	Check to append to the file named in STDERR File instead of overwriting it.	Introduced in 1.0.0

Importable Configuration Examples

This integration provides importable configuration examples along with their dependencies, grouped as Use Cases to better describe end to end capabilities.

warning

These examples aid in allowing task authors to get more familiar with the configuration of tasks and related Use Cases. Such tasks should be imported in a Test system and should not be used directly in production.

Initial Preparation Steps

• STEP 1: Go to Stonebranch Integration Hub and download this integration along with the UAC Utility: Email integration, which is required by the Use Case. Extract the downloaded archives in a local directory.
• STEP 2: Locate and import the above integrations to the target Universal Controller. For more information refer to the How To section in this document.
• STEP 3: Inside the directory named "configuration_examples" you will find a list of definition zip files. Upload them one by one respecting the order presented below, by using the "Upload" functionality of Universal Controller:
  • 1_variables.zip
  • 2_credentials.zip
  • 3_scripts.zip
  • 4_tasks.zip
  • 5_workflows.zip
• STEP 4: Update the uploaded UAC Credential entity with the Azure Client ID and Azure Client Secret of the Azure application registration used to send the report. Review the credential's description for guidance on what to provide.
• STEP 5: Update the UAC global variables introduced with the 1_variables.zip file. Their name is prefixed with the extension name using underscores instead of hyphens. Review the descriptions of the variables as they include information on how they should be populated.
• STEP 6: Create the directories assigned to the ue_enhanced_windows_report_dir and ue_enhanced_windows_archive_dir global variables on the Windows Agent host, and ensure the Agent user has write access to both.

info

• The order indicated above ensures that the dependencies of the imported entities need to be uploaded first.
• All imported entities are prefixed with the Use Case number (e.g. UC1, UC2, UC3) they belong to.

How to "Upload" Definition Files to a Universal Controller

The "Upload" functionality of Universal Controller allows Users to import definitions exported with the "Download" functionality.

Login to Universal Controller and:

• STEP 1: Click "Tasks" → "All Tasks"
• STEP 2: Right click on the top of the column named "Name"
• STEP 3: Click "Upload..."

In the pop-up "Upload..." dialogue:

• STEP 1: Click "Choose File".
• STEP 2: Select the appropriate zip definition file and click "Upload".
• STEP 3: Observe the Console for possible errors.

Use Case 1: Collect a Windows Host Report and Email it to Stakeholders

Description

A configuration report is collected from a Windows host, sent to the stakeholders as an email attachment, and archived on the host. This Use Case demonstrates executing both a script and a command on a Windows Agent, capturing their output to files, and appending to a log that is retained across runs.

The workflow is composed of the following components:

1. UC1: Enhanced Windows - Collect Host Report - an Enhanced Windows task that runs the UC1: Enhanced Windows - Host Report Script batch script on the Windows Agent host. STDOUT File points to the report file, so the collected configuration is written to disk and printed to the task instance STDOUT.
2. UC1: Enhanced Windows - Email Host Report - a UAC Utility: Email task that sends the report to the stakeholders as an attachment, authenticating against Microsoft Graph with an Azure application registration.
3. UC1: Enhanced Windows - Archive Host Report - an Enhanced Windows task that copies the report into the archive directory using a command, with the outcome of the copy appended to a history log.

All three tasks run on the Agent named by the ue_enhanced_windows_agent global variable. The Email task reads the attachment from the filesystem of its own Agent, and the archive task copies the file written by the first task, so the tasks must not be distributed across different Agents.

How to Run

Execution Steps

1. Ensure all Initial Preparation Steps have been completed successfully.
2. Ensure the Azure application registration is authorised to send email on behalf of the mailbox assigned to the ue_enhanced_windows_sender_account global variable.
3. Launch the workflow task UC1: Enhanced Windows - Collect a Windows Host Report and Email it to Stakeholders and monitor the execution in Universal Controller.

Expected Results

• The report file is created in the directory assigned to ue_enhanced_windows_report_dir, and the collected host configuration is printed to the STDOUT of UC1: Enhanced Windows - Collect Host Report.
• The email is delivered to the recipient assigned to ue_enhanced_windows_email_to with the report attached.
• The report is copied into the directory assigned to ue_enhanced_windows_archive_dir, and the history log in that directory gains one entry per workflow run.
• The workflow completes in the Success state.

Exit Codes

Exit Code	Status	Description
0	Success	Successful Execution.
1	Failure	Generic Error. Raised when not falling into the other Error Codes.

Document References

Document Link	Description
Microsoft Windows Commands: cmd	Reference for the Windows command interpreter that executes the configured command or batch script.
Microsoft Windows Commands: call	Reference for the command used to invoke a profile file when Profile Format is "Windows Batch File".
Microsoft Windows Commands: set	Reference for displaying and setting Windows environment variables, which is relevant when authoring a profile file.
Microsoft Windows Commands Reference	Complete reference of the Windows commands available to the Command field and to batch scripts.

Changelog

ue-enhanced-windows-1.0.0 (2026-09-22)

Initial Version