Versions Compared

Old Version 22

changes.mady.by.user Stonebranch

Saved on

compared with

New Version Current

changes.mady.by.user Stonebranch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel

Table of Contents
maxLevel2

...

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 just like they manage their application code complete with version control, testing, and continuous integration.

Regardless of whether 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.

...

Template Name

Extension Name

Version

Status

Jobs As Code

ue-jobs-as-code

2 (Current 2.0.02)

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.

Note

Version 2.0.0 introduces new features that are compatible only for 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 on in version 2.0.


Software Requirements

Anchor
Requirements
Requirements

...

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

...

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


Image Modified


Image Modified

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.

...

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.


Expand
titleSuccessful Execution


Code Block
{

    "exit_code": 0,
    "status_description": "SUCCESS: Task executed successfully.",
    "status": "SUCCESS",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "1.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": [],
    }



Expand
titleFailed Execution


Code Block
{

    "exit_code": 21,
    "status": "FAIL",
    "status_description": "Export to Git Repository failed with error(s).",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "1.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.



Expand
titleSTDOUT Example


Code Block
=================  =========  =========================================  ===========================================================  ========
Type               Subtype    Name                                       Git Path                                                     Status
=================  =========  =========================================  ===========================================================  ========
Business Services  -          jobs-as-code-win                           Business Services/jobs-as-code-win.yaml                      exported
Tasks              Manual     jobs-as-code-manual-task-win               Tasks/Manual/jobs-as-code-manual-task-win.yaml               exported 
Scripts            Data       TestScript                                 Scripts/Data/TestScript.yaml                                 failed
=================  =========  =========================================  ===========================================================  ========



...

Import UC definitions manually

User Scenario: 

Import the specified files stored in the corresponding paths of Add, Modify, and Remove Definitions Lists from GitHub to UAC. Files under the Add list will be added to UAC, and files under the Modify list will modify existing definitions. Definitions of their paths under the Remove list will be deleted from UAC.

User Scenario: 

Import from GitHub all the files that are stored under the "export/7.3" branch and modify the existing corresponding UAC Definitions.

...

  1. Create a new Global Event Template that shall receive the Git provider’s Webhook payload. Set option "Unmapped Attributes Policy" to "Include Attributes".

  2. Create a Universal Monitor and link it with the Global Event Template created in Step 1.

  3. Create a Universal Monitor Trigger assigning to it

    1. the Universal Monitor created in Step 2

    2. a Jobs as Code Task that should be triggered when a new Git Webhook is invoked. The integration task should be configured to utilize the event’s webhook payload (see sections Parse GitLab/GitHub Webhook Payload, Parse Bit Bucket and Azure DevOps Webhook Payload, stored in UAC built-in variable ${ops_trigger_<universal_monitor_name>_payload}.

  4. Set up a repository Webhook in the integrated GitLab/GitHub/BitBucket platform and select the "Push" trigger option. Link the Webhook to the Universal Controller Event created in Step 1 as follows:

    1. If the controller URL is https://somehost.yourdomain.com/uc/, the Webhook’s target URL should be https://<uc_user>:<us_password>@somehost.yourdomain.com/uc/resources/universalevent/push/<name of the event>.
      A Webhook can also be configured with a secret token for enhanced security. More information about this feature can be found for GitHub and GitLab providers.11.

...

  • In the 'Actions' section of the task, three variables need to be set, one for each import list. The name of the variable should be put also in the corresponding field of the template. The value of the variable should be a UC function that uses a JSON path to extract the added, modified, and removed files from the Git Webhook payload. 

  • The Universal Task that will be triggered by the webhook should have the name of the Action Variables inside Add, Modify, and Remove UC Definitions Lists, with the prefix var: enclosed in a list, as demonstrated in the example below:


Image Modified

Image Modified

Parse UAC variable holding the webhook payload, using UAC built-in JSON Path function:

${_varJsonPath('ops_trigger_<universal_monitor_task_name>_payload','$.commits[*].added[*]','',',')}

Import from GitLab/GitHub via Webhook

...

Output Type

Description

Example

EXTENSION

The extension output provides the following information:

  • “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 are actually exported to the Git provider.

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


Expand
titleSuccessful Execution


Code Block
"exit_code": 1,
    "status": "SUCCESS",
    "status_description": "import from Git Repository executed successfully.",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "12.10.02",
        "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
		},
        "definitions_added": {
			"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
		},
        "definitions_removed": {
			"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
		},		
        "definitions_modified": {
			"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: []
	}
}




Expand
titleFailed Execution


Code Block
{
    "exit_code": 21,
    "status_description": "Some errors where produced during data synchronization process:
Task completed with failures.See Extension Output for more details.",
    "status": "FAILED",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "1.2.0.2",
        "fields": {...}
    },
    "result": {
        "definitions_selected": {
            "agentcluster": 0,
            "businessservice": 0,
            "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_added": {
            "agentcluster": 0,
            "businessservice": 0,
            "bundle": 0,
            "calendar": 0,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 0,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 0,
            "trigger": 0,
            "variable": 0,
            "virtualresource": 0
        },
        "definitions_modified": {
            "agentcluster": 0,
            "businessservice": 0,
            "bundle": 0,
            "calendar": 0,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 0,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 0,
            "trigger": 0,
            "variable": 0,
            "virtualresource": 0
        },
        "definitions_removed": {
            "agentcluster": 0,
            "businessservice": 0,
            "bundle": 0,
            "calendar": 0,
            "databaseconnection": 0,
            "emailconnection": 0,
            "peoplesoftconnection": 0,
            "sapconnection": 0,
            "snmpmanager": 0,
            "customday": 0,
            "emailtemplate": 0,
            "script": 0,
            "task": 0,
            "trigger": 0,
            "variable": 0,
            "virtualresource": 0
        },
        "errors": [
            "Failed to add UAC definition TestScript: Create script failed.
A duplicate value has been detected. Name must be unique."
        ]
    }
}




STDOUT

All definitions matched the selection criteria, in table format.


Expand
titleSTDOUT Example


Code Block
=================  =========  =========================================  ===========================================================  ========
Type               Subtype    Name                                       Git Path                                                     Status
=================  =========  =========================================  ===========================================================  ========
Business Services  -          jobs-as-code-win                           Business Services/jobs-as-code-win.yaml                      imported
Tasks              Manual     jobs-as-code-manual-task-win               Tasks/Manual/jobs-as-code-manual-task-win.yaml               imported
Scripts            Data       TestScript                                 Scripts/Data/TestScript.yaml                                 failed
=================  =========  =========================================  ===========================================================  ========



...

Field

Type

Description

Version Information

Action

Choice

Action performed upon the task execution. Available actions are as follows.

  • List UAC Definitions (default)

  • Export to Git Repository

  • Import from Git Repository

Introduced in 1.0.0

Universal Controller URL

Text

The Universal Controller URL will be used to query and import UC Definitions.

Introduced in 1.0.0

Universal Controller Credentials

Credentials

Universal Controller credentials that provide access to the Universal Controller Web Services.

The user should be configured with "Web Service Access=True".

Introduced in 1.0.0

UC SSL Certificate Verification

Checkbox

Enables/Disables certificate verification against Universal Controller URL. For example, if self-signed certificates are used to connect with UAC.


Default setting is checked.


Introduced in 1.0.0

Selection Method

Checkbox

Select or filter specific UC Definitions for listing or exporting to Git repository. 
The available options are as follows.

  • Business Service (default)

  • Bundle

  • Definition Name (Regex)

  • Workflow

  • Trigger

Visible only when the selected action is List UAC Definitions or Export to Git Repository.

Introduced in 1.0.0

Selection Name

Dynamic Choice

The corresponding filter value for the Selection Method Field. When the selected Selection Method is Definition Name, the value provided in the
field works as a filter applied on UC Definitions name. The value should be a regex as well as a free text. For example, if the selection name is
"jobs-as-code" then all the definitions that contain this name will be listed. On the other hand, if the value is ".*" then the all supported definitions
of UC will be listed (or exported).

Visible only when the selected action is List UAC Definitions or Export to Git Repository.

Introduced in 1.0.0

Selection Exclude List

Choice

Exclude various UC Definition types of resources from the selection.

Visible only when the selected action is List UAC Definitions or Export to Git Repository.

Introduced in 1.0.0

Git SSL Certificate Verification

Checkbox

Enables/Disables certificate verification against Git Service Provider URL. 

Visible only when the selected action is Import from Git Repository or Export to Git Repository.


Default setting is checked.

Introduced in 1.0.0

Git Service Provider

Choice

The Git service provider the task is using.
The available options are as follows.

  • GitLab (default)

  • GitHub

  • Bitbucket

  • Azure DevOps 

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Service Provider URL

Text

The Git service provider URL the task is using. 

Examples for each Git Provider Version:

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Credentials

Credentials

The credentials that should be used to access the Git repository. The Credentials definition should be as follows.

  • A username of your choice is "Runtime username".

  • Git Service Provider "Token" as "Token".

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Repository

Dynamic Choice

The repository the task will use to import or export UAC Definitions. The list of values is retrieved from the Git Service Provider.
Accepts also UC variables set with Set Variable Action. 

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Repository Branch

Dynamic Choice

The repository branch that the task will use to import or export UAC Definitions. The list of values is retrieved from the Git Service Provider.
Accepts also UC variables set with Set Variable Action. 

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Repository Path

Text

  • For Export: Specify a specific path in a repository as a target.

  • For Import: validate the Git files against the Git folder path they belong to, or leave them empty for no validation.

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Repository File Format

Choice

The file format is used to read and write in the Git repository. The available options are as follows.

  • Yaml (default)

  • JSON

Visible only when the selected action is Import from Git Repository or Export to Git Repository.

Introduced in 1.0.0

Git Commit Message

Text

The optional git commit message for the commits that will take place during export. The commit message
that will be displayed in the Git provider will have [uac push] as prefix.

For example, if the commit message is "test export" the
resulting commit message that will be displayed on the Git provider will be "[uac push] test_export".

To adjust the default prefix, use the Feature Flag UE_FF_DISABLE_DEFAULT_COMMIT_PREFIX.

Visible only when the selected action is Export to Git Repository.

Introduced in 1.0.0

Add UC Definitions List

Text

The comma-separated list of Git file paths that should be used to create UC Definitions. Type "*" to select all files from Git provider and 
add them to UAC.
Accept UC variables as input.

Visible only when the selected action is Import from Git Repository.

Introduced in 1.0.0

Modify UC Definitions List

Text

The comma-separated list of Git file paths that should be used to modify UC Definitions. Type "*" to select all files from Git provider and 
modify the corresponding definitions of UAC.
Accept UC variables as input.

Visible only when the selected action is Import from Git Repository.

Introduced in 1.0.0

Remove UC Definitions List

Text

The comma-separated list of Git file paths that should be used to remove UC Definitions. Type "*" to select all files from Git provider and 
remove the corresponding definitions of UAC.
Accept UC variables as input.

Visible only when the selected action is Import from Git Repository.

Introduced in 1.0.0

Proxy Type

Choice

What type of proxy is in use (if any). The available options are as follows.

  • -- None – (default)

  • HTTP

  • HTTPS

  • HTTPS With Credentials

Introduced in 1.0.0

Proxy

Text

Proxy server and port.

Introduced in 1.0.0

Proxy Credentials

Credentials

Credentials to be used for the proxy when the selected Proxy Type is HTTPS With Credentials.

Introduced in 1.0.0

Proxy CA Bundle File

Text 

The path to a custom certificate bundle to use when establishing SSL/TLS connections with proxy.

Visible only when the selected Proxy Type is HTTPS With Credentials.

Introduced in 1.0.0

Webhook Payload

Text

Through this field the user can provide the Bitbucket webhook payload from which the task executed will extract the Added, Modified, and Removed Definition Lists.

Note: Pass the webhook payload in this field only when integrating with Bitbucket. For all other Git webhook integrations, use the other three Definitions' List fields.

Introduced in 1.1.0

...

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.

Dependencies Manual Installation

Note

External dependences dependencies installation is not required from version 2.0 onwards.The following information is valid only for version 1.x.

...

  • PyGithub: For exporting and importing UAC Definitions from GitHub

  • ruamelruamel.yaml : The installation of the package is recommended but not mandatory for the "Export to Git Repository" action in YAML format. This package ensures that the exported UAC definitions are well-structured with optimal layout and indentation.

...

Document LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Event Template Use documentation for creating Universal Event Templates
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
CredentialsUser documentation for creating and working with credentials.
Resolvable Credentials Permitted PropertyUser documentation for Resolvable Credentials Permitted Property.


Changelog

...

ue-jobs-as-code-2.0.2 (2024-05-16)

Fixes

  • Fixed: Resolved issue where duplicate entries in UC definitions were not filtered out. (#36551).

ue-jobs-as-code-2.0.1 (2024-04-25)

Fixes

  • Fixed: Resolved compatibility issues with Linux systems utilizing glibc version 2.17 (#36552).

ue-jobs-as-code-2.0.0 (2024-03-21)

...

  • Added: Dependent libraries PyGithub and ruamel.yaml are now bundled within the extension and it is are not required to be installed manually. This is only possible from Controller/Agent version 7.4 onwards. (#35980).

...

ue-jobs-as-code-1.2.1 (2023-01-23)

Fixes

  • Fixed: Http Code 404 when validating git file paths for Azure DevOps in action `Import from Git Repository` (#35567).

  • Fixed: Wrongly picking up from `Webhook Payload`, committed files that include keywords `yaml` or `json` in their file path, for Azure DevOps in action `Import from Git Repository` (#35570).

...

  • Added: Support for Azure DevOps Services (Cloud Version) for Git Repos hosted on Azure DevOps Platform (#34932). 

Fixes

  • Fixed: Error when executing an Import action specifying "*" in the added, modified or deleted uc definition list(#35167).

...

  • Added: Support Bit Bucket Git Service Provider (#32243).

  • Added: Update output only field “Extension Status” with execution information (#32153).

Fixes

  • Fixed: Connect to GitLab client over Proxy with “Git SSL Verification” set to True (#32138).

  • Fixed: Connect to GitHub Enterprise Server edition (#34507).

  • Fixed: Handle exception HTTPError 500, raised when listing UC definitions with unresolved items (for instance: unresolved Credentials) (#32982).

...

  • Bugfix: The "Export to Git Repository" action now retains UAC definitions in a well-structured YAML format with optimal layout and indentation. Please check the the Requirements section section for more information.

ue-jobs-as-code-1.0.1 (2023-03-14)

...