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.

Software Requirements

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

• PyGithub: For exporting and importing UAC Definitions from GitHub
• ruamel.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.

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.6 or higher. Tested with the Universal Agent bundled Python distribution.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported.

• Universal Agent for Windows x64 Version 7.2.0.0 and later with Python options installed.
• Universal Agent for Linux Version 7.2.0.0 and later with Python options installed.

Software Requirements for Universal Controller

Universal Controller Version 7.2.0.0 and later.

Network and Connectivity Requirements

UE Jobs As Code 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 store them from Git.

Key Features

Import Universal Template

To use the Universal Template, you first must perform the following steps.

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow these instructions.

3. When the files have been 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.

Input Fields

The input fields for this Universal Extension are described below.

Task Examples

List UAC Definitions

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 to Git Repository

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.

Import from Git Repository

User Scenario: Import from GitHub to UAC the specified files that are stored in the corresponding paths of Add, Modify and Remove Definitions Lists. Files under Add list will be added to UAC, and files under Modify list will modify existing definitions. Definitions which their paths are 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.

User Scenario: Import from Git Repository with a Webhook. 

Specifying all the files that have been added, modified, or removed on Git provider in Add, Modify and Remove Definitions List, and then executing manually this task can be a time-consuming process.
From UAC version 7.3, or later, using the “webhook“ UAC feature, this task can be executed automatically when a change happens in your git repository. With the proper configuration, webhook events can invoke a Jobs As Code Task, which after parsing the webhook payload, will extract the added/updated/removed file lists and trigger an import execution. To use this feature the following configuration steps should be completed:

1. Set up a commit webhook in your Git provider, giving the corresponding URL and "Push Events" Trigger option.
   For instance for GitLab, if the controller URL is https://somehost.yourdomain.com/uc/ the specified URL should be https://somehost.yourdomain.com/uc/resources/universalevent/push/gitlab.
   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.
2. Create a new Universal Event Template in order to allow monitoring of received webhook events by a Universal Monitor. Note that in the "Unmaped Attributes Policy" dropdown menu, "Inlude Attributes" should be selected.
3. Create also a Universal Monitor and link it with the Universal Event Template created in the previous step.
4. Create a Universal Monitor Trigger assigning to it the newly created Universal Monitor. Then select the Jobs as Code Task that you would like to be triggered when a new Git Webhook is invoked. Make sure that the user that is used to interact with the UAC and Git platforms must have
   the "Web Service Access" property set to True in order to be able to rim Web Service calls.

Please note that the Universal Task that is linked with the Universal Monitor Trigger, needs an additional configuration too:

• 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 using JSON path to extract the added, modified, and removed files from 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:
  

Task Output

Output Only Fields

The output fields for this Universal Extension are described below.

Cancellation logic

In case of a cancel event, the running action stops executing and returns provides a list of all the changes that took place until the cancellation request was received by the running extension instance (UAC definition exports or imports).

Exit Codes

The exit codes for this Universal Extension are described below.

Extension Output

List UAC Definitions

An example of the Extension Output for a successful List UAC Definitions Action execution is presented below.

{
	"exit_code": 0,
	"status": "SUCCESS",
    "status_description": "List UAC Definitions executed successfully.",
	"invocation": {
        "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
		}
	}
}

Export to Git Repository

An example of the Extension Output for a failed Export to Git repository Action execution is presented below.

{
    "exit_code": 1,
    "status": "FAIL",
    "status_description": "Export to Git Repository failed with error(s).",
	"invocation": {
		"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)."
		]
	}
}

Import from Git Repository

An example of the Extension Output for a successful Import from Git repository Action execution is presented below.

{
    "exit_code": 1,
    "status": "SUCCESS",
    "status_description": "import from Git Repository executed successfully.",
	"invocation": {
		"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: []
	}
}

STDOUT and STDERR

STDOUT

Table of Definitions

For better visualization, the extension provides a table that records the actual outcome of every file that listed, exported or imported. The columns of the table are:

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:

Document References

This document references the following documents.

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 with respect to 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 Stonebranch Support Desk.

Changelog

ue-jobs-as-code-1.0.2 (2023-07-28)

• 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 Software Requirements section for more information.

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

• Bugfix: Deletion of UC definitions via Webhook should not validate to-be-deleted files against specified Git Repository.

ue-jobs-as-code-1.0.0 (2023-03-09)

• Added: Initial Version