Skip to main content

UAC Utility: UC Task Comparison Tool

Disclaimer​

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

Version Information​

Template Name

Extension Name

Version

Status

Compare

ue-compare

1 (Current 1.0.0)

Initial version.

Refer to the Changelog for version history information.

Overview​

This integration for Stonebranch Universal Automation Center (UAC) enables users to validate the consistency of Task definitions across two different Universal Controllers. This integration is designed to help teams ensure configuration alignment between environments.

By selecting a Task from a primary controller, the integration retrieves and compares its definition against the corresponding Task on a secondary controller. If discrepancies are detected, the integration produces a clear, well-structured output on the STDOUT to highlight differences. Optionally, users can enforce strict validation by failing the task when mismatches are found.

Key Features​

Feature

Description

Cross-Controller Task Comparison

Compare a single Task definition between two Universal Controllers to ensure consistency across environments.

Dynamic Task Selection

The Task Name field is dynamically populated from the primary controller, allowing users to easily browse available Tasks.

It also supports glob patterns. For example, "Task_*".

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 Python 3.11.8.

Universal Agent Compatibility

  • Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0.
  • Compatible with Universal Agent for Linux and version >= 7.6.0.0.

Universal Controller Compatibility

Universal Controller Version >= 7.6.0.0.

Network and Connectivity

Network Connectivity towards the Primary and Secondary Universal Controllers.

Supported Actions​

Compare Task​

Compares the definition of a specified Task between two Universal Controllers.

Action Output​

  • exit_code, status, status_description: General info regarding the task execution. In case of failure, it is set according to the specific error that happened during the execution. A list of possible values is provided in the exit codes table in this document.
  • invocation.fields: The task configuration used for this task execution.
  • result.diff: Raw diff output generated by the extension.
    • Included only when differences are found between the tasks.

Examples:

Successful Execution of "Compare Task" Action
{
    "exit_code": 0,
    "status_description": "Differences found",
    "invocation": {
        "extension": "ue-compare",
        "version": "1.0.0",
        "fields": {
            "action": "Compare Task",
            "primary_url": "http://ue-uac-dev.stonebranch.org:8089/uc",
            "primary_credentials": {
                "user": "ops.****",
                "password": "****",
                "token": "****",
                "key_location": null,
                "passphrase": "****"
            },
            "authentication_method_uc1": "Basic Auth",
            "secondary_url": "http://ue-uac-dev.stonebranch.org:8088/uc",
            "secondary_credentials": {
                "user": "user",
                "password": "****",
                "token": "****",
                "key_location": null,
                "passphrase": "****"
            },
            "authentication_method_uc2": "Bearer Auth",
            "task_name": "Manual: Trigger Sync Job",
            "fail_on_differences": false
        }
    },
    "result": {
        "diff": {
            "values_changed": {
                "root['agent']": {
                    "new_value": "ue-agt-lin-dev - lindev78",
                    "old_value": "ue-agt-lin-dev - lindev79"
                },
                "root['choiceField2']['value']": {
                    "new_value": "Reset",
                    "old_value": "Sync"
                },
                "root['choiceField3']['value']": {
                    "new_value": "Connection 2",
                    "old_value": "connection1"
                },
                "root['choiceField4']['value']": {
                    "new_value": "Workspace 2",
                    "old_value": "workspace1"
                },
                "root['credentialField1']['value']": {
                    "new_value": "Airbyte Trial",
                    "old_value": "AI TEST"
                },
                "root['intField2']['label']": {
                    "new_value": "Poll Interval",
                    "old_value": "Poll Interval (sec)"
                },
                "root['intField2']['value']": {
                    "new_value": 5,
                    "old_value": 60
                },
                "root['textField1']['value']": {
                    "new_value": "https://api.airbyte.com",
                    "old_value": "https:wwatg.com"
                }
            }
        }
    }
}
Failed Execution
{
    "exit_code": 1,
    "status_description": "Failed to fetch task from 'http://ue-uac-dev.stonebranch.org:8089/uc': Client error '404 ' for url 'http://ue-uac-dev.stonebranch.org:8089/uc/resources/task?taskname=Task+Truee'\nFor more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404",
    "invocation": {
        "extension": "ue-compare",
        "version": "1.0.0",
        "fields": {  
          ...
        }
    },
    "result": null
}

Configuration Examples​

Compare Task and Fail on Differences​

This configuration compares a task on two Controllers with different versions. The task is retrieved from both the Controllers and compared. If a difference is detected, the task instance fails, and the differences are printed to the STDOUT.

image-20260416-095700.png

Input Fields​

Name

Type

Description

Version Information

Action

Choice

The action to be executed. The following options are available.

  • Compare Task

Introduced in 1.0.0

Primary Universal Controller URL

Text

The Full URL of the Primary Universal Controller instance.

For example, https://uac-prod-01.example.com/uc

Introduced in 1.0.0

Primary UC Authentication Method

Choice

The type of authentication method to use for authenticating with the Primary Universal Controller.

Available options are as follows.

  • Basic Auth
  • Bearer Auth

Introduced in 1.0.0

Primary UC SSL Verification

Checkbox

Enable verification of the Primary Universal Controller server's SSL certificate. Disable to skip verification.

CA Bundle is specified using the UE_PRIMARY_UC_SSL_CERT_FILE environment variable.

Introduced in 1.0.0

Primary UC Credentials

Credentials

The Credentials definition should be as follows.

  • For "Bearer Auth"
    • Universal Controller PAT as "Token".
    • Any value as "Runtime User".
  • For "Basic Auth"
    • Universal Controller Username as "Runtime User".
    • Universal Controller Password as "Runtime Password"

Introduced in 1.0.0

Secondary Universal Controller URL

Text

The Full URL of the Secondary Universal Controller instance.

For example, https://uac-prod-02.example.com/uc

Introduced in 1.0.0

Secondary UC Authentication Method

Choice

The type of authentication method to use for authenticating with the Secondary Universal Controller.

Available options are as follows.

  • Basic Auth
  • Bearer Auth

Introduced in 1.0.0

Secondary UC SSL Verification

Checkbox

Enable verification of the Secondary Universal Controller server's SSL certificate. Disable to skip verification.

CA Bundle is specified using the UE_SECONDARY_UC_SSL_CERT_FILE environment variable.

Introduced in 1.0.0

Secondary UC Credentials

Credentials

The Credentials definition should be as follows.

  • For "Bearer Auth"
    • Universal Controller PAT as "Token".
    • Any value as "Runtime User".
  • For "Basic Auth"
    • Universal Controller Username as "Runtime User".
    • Universal Controller Password as "Runtime Password"

Introduced in 1.0.0

Task Name

Dynamic Choice

Dynamic Choice field for the retrieval and selection of the Name of the task to compare.

Fetches the task names from the Primary Controller filtered by the text provided in its field. Additionally, it supports glob. For example, to list all tasks starting with LIN, use LIN*.

Introduced in 1.0.0

Fail on Differences

Checkbox

When enabled, the extension fails if differences are detected between the two task definitions. See Exit Codes.

When disabled, the extension succeeds regardless of any differences between the two task definitions.

Introduced in 1.0.0

Environment Variables​

Environment Variables can be set from the Environment Variables task definition table. The following environment variables can affect the behavior of the extension.

Environment Variable Name

Description

Version Information

UE_PRIMARY_UC_SSL_CERT_PATH

When connecting to the Primary Universal Controller using HTTPS, it might be necessary to provide a CA Bundle.

To do so, set the UE_PRIMARY_UC_SSL_CERT_PATH environment variable to the path of the desired CA Bundle.

Introduced in 1.0.0

UE_SECONDARY_UC_SSL_CERT_PATH

When connecting to the Secondary Universal Controller using HTTPS, it might be necessary to provide a CA Bundle.

To do so, set the UE_SECONDARY_UC_SSL_CERT_PATH environment variable to the path of the desired CA Bundle.

Introduced in 1.0.0

UE_HTTP_TIMEOUT

Specifies the timeout (in seconds) for HTTP requests made by the Task Instance. A higher value allows for slower responses, while a lower value enforces stricter time constraints. If not set, a default of 60 seconds is used. When a timeout happens, the Task Instance fails.

Introduced in 1.0.0

Exit Codes​

Exit Code

Status

Status Description

Meaning

0

Success

If no differences are found,

  • "No differences found"

If differences are found and the Fail on Differences input field is not checked,

  • "Differences found"

Successful Execution.

If the Fail on Differences input field is not checked, it means that the two task definitions have been compared successfully.

If the Fail on Differences input field is checked, it means that the two task definitions are identical.

1

Failure

"Execution Failed: <<Error Description>>"

Failed Execution.

  • This error code also acts as a generic error code. Raised when an error does not fall into the other error scenarios.

20

Failure

"Data Validation Error: <<Error Description>>"

Input fields validation error.

41

Failure

If differences are found and the Fail on Differences input field is checked,

  • "Differences found"

Failed Execution.

  • The task instance has successfully compared the two task definitions and found inconsistencies between them.

42

Failure

"STDOUT Render Error: <<Error Description>>"

Failed Execution.

  • Unable to display differences to the STDOUT.

101

Failure

"Primary Universal Controller Task Fetch Error: <<Error Description>>"

Failed Execution.

  • This error code acts as a generic error code for failures when fetching a task from the Primary Controller.

102

Failure

"Primary Universal Controller Task Not Found Error"

Task does not exist on the Primary Controller.

201

Failure

"Secondary Universal Controller Task Fetch Error: <<Error Description>>"

Failed Execution.

  • This error code acts as a generic error code for failures when fetching a task from the Secondary Controller.

202

Failure

"Secondary Universal Controller Task Not Found Error"

Task does not exist on the Secondary Controller.

STDOUT and STDERR​

STDOUT is used for displaying the differences between task definitions after comparing them.

STDERR provides additional information to the user, the verbosity of which is controlled by the Log Level Task Definition field.

info

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

How To​

Import the Universal Template into your Controller:

  1. Extract the zip file that you downloaded from the Integration Hub.
  2. In the Controller UI, select Services > Import Integration Template option.
  3. Browse to the "export" folder under the extracted files for the ZIP file (Name of the file will be unv_tmplt_*.zip) and click Import.
  4. When the file is 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", and "Icon" should not be changed.
    • Universal Template Details Section
      • "Template Type", "Agent Type", "Send Extension Variables", and "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, concerning the "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 the success or failure of a task.

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

Changelog​

ue-compare-1.0.0 (2026-04-23)​

Initial Version