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

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

...

Refer to ChangeLog for version history information.

...

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

Refer to Changelog for version history information.

Software Requirements

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

Key Features

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

...

Image Removed

...

Image Removed

...

Action Output

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:

Image Added

The following features are subject to this lifecycle approach

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

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

Action Output

{
    

"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

        }
    }
}

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

=================

 =========

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

...

Image Removed

...

...

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.

...

Action Output

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

=

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

Image Added	Image Added
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

{

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

{

    "exit_code": 21,
    

"status": "FAIL",
    

"status_description": "Export to Git Repository failed with error(s).",
  

  "invocation": {
      

"extension": "ue-jobs-as-code"

,
      

  "version": "

2.0.1",
        

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

]
  

  }
}

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

Action: Import from Git Repository

...

Import UC definitions manually

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

Import UC definitions automatically via Webhooks

...

The following image demonstrates the flow of events that occur as soon as a GitLab/GitHub/Bitbucket Webhook is triggered.

Image Modified

...

                               Import from Git Repository using Git Webhooks and Global Universal

...

Events

Configuration

The following steps are a guide to setting up UAC and the integrated Git provider’s Webhook to automatically trigger Jobs As Code Tasks.

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

...

The best practice suggested to filter out those cyclic imports is to ignore the imports initiated by UAC by configuring a dedicated git user for the “Export” related tasks. The triggered workflow can start with a task that evaluates ${ops_trigger_<universal_monitor_name>_payload} to check if the request is initiated by the UAC git User. If yes, the request can be ignored. If no, the “Import from Git Repository” task can be executed.

The following image demonstrates the example above

Image Modified

                                Filter out webhooks that were triggered from the "Export to git Repository" Action.

Parse GitLab/GitHub Webhook Payload

• 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:

Parse Bit Bucket and Azure DevOps Webhook Payload

Image Modified

...

                                                                         Import from Bitbucket via Webhook

...

Action Output

"exit_code": 1,
    "status": "SUCCESS",
    "status_description": "import from Git Repository executed successfully.",
    "invocation": {
        "extension": "ue-jobs-as-code",
        "version": "

2.0.1

",
        "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: []
	}
}

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

2.0.1",
        "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."
        ]
    }
}

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

Input Fields

The input fields for this Universal Extension are described below.

Output Fields

...

The exit codes for this Universal Extension are described below.

...

For example, execution of an Export to Git Repository Action for a workflow that has three tasks inside and belongs to a business service called 'jobs-as-code' will lead to the table below:

                                                                                                                                                                  Example of STDOUT

How To

Import Universal Template

...

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

. For more information refer to 98795535.

Dependencies Manual Installation

On the Universal Agent that should execute this integration, perform pip install on the following libraries:

...

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.

...

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

Document References

...

This document references the following documents.

...

Changelog

.

Changelog

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)

Breaking Changes

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

Enhancements

• Added: When Action is 'Export to Git Repository' commit all selected definitions with a single commit (#36044).

• Added: Feature Flag 'UE_FF_DISABLE_DEFAULT_COMMIT_PREFIX' is introduced to provide the capability of adjusting the default commit message prefix (#35074).

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

ue-jobs-as-code-1.2.0 (2023-12-24)

Enhancements

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

ue-jobs-as-code-1.1.0 (2023-11-09)

Enhancements

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

...