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

Feature: Import Mode

The Import Mode input field introduced in version 2.2.0 is available for the "Import from Git Repository" Action. The field covers the following scenarios.

• "Generic Webhook and Custom" Mode - This mode provides import of UC definitions manually using lists for Add, Modify, or Remove definitions on the Controller, or using Webhook Payloads. For manual imports, operations are processed in the following order: Add operations first, then Modify operations, and finally Remove operations. 

• "Insert or Update" Mode - This mode provides import of UC definitions manually using a single Modify list for both adding and modifying definitions on the Controller. Each definition specified in the list is separately processed and, based on the presence on the Controller, it is either added or modified. For this mode, there is no specific order requirement. Both add and modify definitions can be included in the list, as the handling is done internally.

In case of dependencies between the entities to be imported, these relationships are automatically detected. Entities are then processed in the correct order. For creation/modification, dependencies are resolved first. For deletion, the order is reversed to prevent conflicts.

Feature Flags

There are cases where some functionalities could become deprecated, and new features are introduced in a stepwise 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 given below:

Open

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

User Scenario: Query all UAC Definitions that are stored in UAC, except Scripts and Custom Days.

Open

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

Open

Action Output

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 UAC Definitions to Gitlab using "HTTP(S)" Git Protocol, contained in the Bundle named 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.

Open

User Scenario: Export UAC Definitions to Azure DevOps using "HTTP(S)" Git Protocol. Organization and repository names must be included in the Git Service Provider URL.

Open

User Scenario: Export UAC Definitions to GitHub using "SSH" Git Protocol, contained in the Bundle named uc_bundle. Sign the commit with the exported definition using a private key. Use the environment variables GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL for setting up the author and committer of the commit. These values can point to the same user, or different users can be the author and committer.

Open

Action Output

Action: Import from Git Repository

Import selected UAC Definitions, already stored in Git, back to the selected Universal Controller. This feature provides the opportunity for restoration of the Universal Controller server (recovery scenarios) or for updating UAC Definitions. 

Import UC definitions manually

User Scenario: Import the specified files using Git Protocol "HTTP(S)", stored in the corresponding paths of Add, Modify, and Remove Definitions Lists from GitHub to UAC. Files in the Add list will be added to UAC, files in the Modify list will modify existing definitions, and files in the Remove list will be deleted from UAC.

Open

User Scenario: Import from GitHub, using Git Protocol "HTTP(S)", all the files that are stored in the "jac-branch" branch and modify the existing corresponding UAC Definitions.

Open

User Scenario: Import from Azure DevOps, using Git Protocol "SSH", the file specified in Modify list, stored in "test-branch".

Open

Import UC definitions automatically via Webhooks

Starting from UAC 7.3 and utilizing Global Universal Events, this integration can be configured to get triggered automatically when a change is made in a Git repository.

With the proper configuration, Universal Events can invoke a Jobs As Code Task, which will parse the Git webhook payload, define the added/modified/removed file lists, and trigger an import execution. 

Process Flow

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

Import from Git Repository using Git Webhooks and Global Universal Events

Open

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

Avoidance of Cyclic Imports

When an “Export to Git Repository” action is performed through a Universal Task, it triggers a push event towards the configured Git Service Provider. This push event leads to the triggering of the Git Service Provider Webhook. If configured as above, this webhook should create a Universal Event to UAC, for further processing to trigger an “Import from Git Repository” action. To prevent this cyclic behavior, a configuration is required to filter out those unnecessary imports. This can be accomplished if the Universal Monitor that listens for Webhook Events triggers a workflow configured appropriately to filter such cyclic requests.

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

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

Open

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 also be put 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. Parse the UAC variable holding the webhook payload, using UAC built-in JSON Path function: ${_varJsonPath('ops_trigger_<universal_monitor_task_name>_payload','$.commits[*].added[*]','',',')}

Open

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:

Open

Parse Bit Bucket and Azure DevOps Webhook Payload

Import from Bitbucket via Webhook

Open

Import UC definitions: "Insert or Update" Mode

User Scenario: Import from GitHub all the files that match a regular expression pattern stored in the "jac-branch" branch, and add or modify the existing corresponding UAC Definitions.

Open

Action Output

Input Fields

The input fields for this Universal Extension are described below.