/
UAC Utility: Jobs As Code (JaC)

UAC Utility: Jobs As Code (JaC)

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at  Stonebranch Integration Hub - Terms of Use.

Overview

Jobs-as-code is an approach to automating software delivery pipelines in which the job configuration is managed as code. This approach allows developers to manage job configurations like their application code complete with version control, testing, and continuous integration.

Whether you create your Universal Automation Center (UAC) job definitions using the drag-and-drop designer or as code in a development environment, the UAC jobs-as-code solution provides guidance and tools to integrate those definitions with a Git repository.

Version Information

Template Name

Extension Name

Version

Status

Jobs As Code

ue-jobs-as-code

2 (Current 2.1.0)

Fixes and new features are introduced. Compatibility starts from UAC/UAG 7.4.0.0 onwards.

Jobs As Codeue-jobs-as-code1Hot Fixes Only (Until UAC 7.3's End of Support).

Refer to Changelog for version history information.

Version 2.0.0 introduces new features compatible only with Universal Controller and Universal Agent of version 7.4 onwards. Therefore version 2.0.0 should not be installed if your Universal Controller & Agent is of version less than 7.4

Customers are encouraged to upgrade their Universal Agents to 7.4 to benefit from features introduced in version 2.0.

Software Requirements

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

Area

Description

Python Version

Requires Python version >=3.7.16.  Tested with Python 3.7.16 and 3.11.6 .

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

Network and Connectivity

This integration needs outbound HTTPS connectivity with GitLab, GitHub, or Bitbucket Cloud for exporting and importing UAC Definitions in addition to HTTPS outbound connectivity to the Universal Controller for retrieving the UAC Definitions and importing them from Git.

GitLab

Supported editions:

  • GitLab Community Edition (REST API v16.6)

  • GitLab Enterprise Edition (REST API v16.6)

GitHub

Supported plans:

  • GitHub Free (X-GitHub-Api-Version:2022-11-28)

  • GitHub Pro (X-GitHub-Api-Version:2022-11-28)

  • GitHub Team (X-GitHub-Api-Version:2022-11-28)

  • GitHub Enterprise Cloud (X-GitHub-Api-Version:2022-11-28)

Bit Bucket

Support plans:

  • Bit Bucket Cloud

Azure DevOps

Supported plans:

  • Azure DevOps Services (Cloud Version) for Git Repos hosted on Azure DevOps Platform

Key Features

FeatureDescription
List UAC DefinitionsQuery UAC definitions prior to running an actual export to Git, to validate the selection criteria, without any write operations in the target repository. This feature should provide a list of UC 
definitions that can then be exported to a Git repository.
Export to Git RepositoryExport selected UAC Definitions to the selected Git Repository. By using this feature, the UAC user will be able to export the selected UAC Definitions to an external Git repository.
After the export, this repository can be used as a backup or as a basis for developer collaboration on top of a source version control system.
Import from Git RepositoryImport selected UAC Definitions. stored already in Git, back to the selected Universal Controller. This feature provides the opportunity for restoration of the UC server (recovery scenarios)
or for updating UAC Definitions. 
For UC version 7.3, or higher, the import feature can be triggered by using webhooks.


Feature Flags

There are cases where some functionalities could become deprecated and new features are introduced in a step-wise approach to inform customers early enough to take the necessary steps given potential future breaking changes. The activation/deactivation of those features is controlled by Feature Flags. Not all features are entering this lifecycle approach, but when this is applicable, related feature flags are documented. The Feature State Transition diagram and related information is presented below:



The following features are subject to this lifecycle approach

Feature Description

Feature State History

Information

Disable the default commit message prefix.

  • Version 2.0.0: “Default Deactivated”

This is a stable feature. To enable the feature set Environment variable UE_FF_DISABLE_DEFAULT_COMMIT_PREFIX=True. Any other value or not setting this environment variable, means that the feature is not activated.


Supported Actions

Action: List UAC Definitions

Query UAC definitions prior to running an actual export to Git, to validate the selection criteria, without any write operations in the target repository. This feature should provide a list of UC 
definitions that can later be exported to a Git repository.

Configuration examples


User Scenario:

Query all UAC Definitions that are stored in UAC except Scripts and Custom Days, without a proxy connection.

User Scenario:

Query all UAC Definitions that are part of a workflow with the name 'test-workflow', with a proxy connection.


Action Output

Output Type

Description 

Example

EXTENSION

Standard Universal Extension format

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” > “definitions_selected”: The UAC definitions that match the filter provided.

  • “result” > “errors”: The list of errors occurred during execution.

 Successful Execution
{
    "exit_code": 0,
    "status": "SUCCESS",
    "status_description": "List UAC Definitions executed successfully.",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "1.2.0",
        "fields": { ... },
    },
    "result": {
        "definitions_selected": {
            "agentcluster": 0,
            "bundle": 0,
            "businessservice": 0,
            "calendar": 1,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 1,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 2,
            "trigger": 1,
            "variable": 1,
            "virtual": 0
        }
    }
}
 Failed Execution
{
    "exit_code": 21,
    "status_description": "Some errors where produced during data synchronization process: 
Task completed with failure. See Extension Output for more details.",
    "status": "FAILED",
    "invocation": {
         "fields": { ...
         }
      },
    "result": {
        "definitions_selected": {},
        "errors": [
            "List task failed. Could not find agent with id a379367e65c94b918f46b71b0a69795e."
        ]
     }
}

STDOUT

All definitions matched the selection criteria, in table format.

 STDOUT Example
================= ========= ========================================= 
Type              Subtype   Name 
================= ========= =========================================
Business Services -         jobs-as-code-win 
Tasks             Manual    jobs-as-code-manual-task-win
================= ========= =========================================


Action: Export to Git Repository

Export selected UAC Definitions to the selected Git Repository. By using this feature, the UAC user can export the selected UAC Definitions to an external Git repository. After the export, this repository can be used as a backup or as a basis for developer collaboration on top of a source control versioning system.

Configuration examples



User Scenario:

Export to Gitlab UAC Definitions contained in Bundle with name uc_bundle except for Email and Peoplesoft Connections. The selected definitions will be stored under the "/export folder" under the "export/7.3" branch in .yaml format.

User Scenario:

Export to Azure DevOps UAC Definitions. Organization and repository names must be included in the Git Service Provider 
URL.



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”>“definitions_selected”: The UAC definitions that match the filter provided.

    • “result”>“definitions_exported”: The UAC definitions that actually exported to the Git provider.

    • “result”>“errors”: The list of errors occurred during execution.

 Successful Execution
{

    "exit_code": 0,
    "status_description": "SUCCESS: Task executed successfully.",
    "status": "SUCCESS",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "2.0.2",
        "fields": { ... }
    },
    "result": {
        "definitions_selected": {
            "agentcluster": 0,
            "businessservice": 1,
            "bundle": 0,
            "calendar": 0,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 0,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 1,
            "trigger": 0,
            "variable": 0,
            "virtualresource": 0
        },
        "definitions_exported": {
            "agentcluster": 0,
            "businessservice": 1,
            "bundle": 0,
            "calendar": 0,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 0,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 1,
            "trigger": 0,
            "variable": 0,
            "virtualresource": 0
        },
        "errors": [],
    }
 Failed Execution
{

    "exit_code": 21,
    "status": "FAIL",
    "status_description": "Export to Git Repository failed with error(s).",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "2.0.2",
        "fields": { ... }
    },
    "result": {
        "definitions_selected": {
            "agentcluster": 0,
            "bundle": 0,
            "businessservice": 0,
            "calendar": 1,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 1,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 1,
            "task": 2,
            "trigger": 1,
            "variable": 1,
            "virtual": 0
        },
        "definitions_exported": {
            "agentcluster": 0,
            "bundle": 0,
            "businessservice": 0,
            "calendar": 1,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 1,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 2,
            "trigger": 1,
            "variable": 1,
            "virtual": 0
        },
        errors: [
            "Failed to create git object for definition 'TestScript' (Git path: /path/script/TestScript.yml)."
        ]
    }
}

STDOUT

All definitions matched the selection criteria, in table format.

 STDOUT Example
=================  =========  =========================================  ===========================================================  ========
Type               Subtype    Name                                       Git Path                                                     Status
=================  =========  =========================================  =================================================