| Panel | ||||
|---|---|---|---|---|
|
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
...
Template Name
...
Extension Name
...
Version
...
Status
...
Jobs As Code
...
ue-jobs-as-code
...
2.0.0
...
Fixes and new features are introduced. Compatibility starts from UAC/UAG 7.4.0.0 onwards.
Refer to Changelog for version history information.
| Note |
|---|
Version 2.0.0 introduces new features that are compatible only for 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 version 2.0 |
Software Requirements
...
| Panel | ||||
|---|---|---|---|---|
|
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
| Template Name | Extension Name | Extension Version |
|---|---|---|
| Jobs As Code | ue-jobs-as-code | 1.2.1 |
Refer to ChangeLog for version history information.
| Anchor | ||||
|---|---|---|---|---|
|
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. |
Tested with the Universal Agent bundled Python distribution (python version 3.7.16 |
Universal Agent
) | |
Python Libraries |
|
Universal Agent | Both Windows and Linux agents are supported:
|
|
| |
Universal Controller | Universal Controller Version >= 7. |
2.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:
|
GitHub | Supported plans:
|
BitBucket | Support plans:
|
| Azure DevOps | Supported plans:
|
Key Features
| Feature | Description |
|---|---|
| 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 then be exported to a Git repository. |
| Export to Git Repository | Export 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 Repository | Import 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 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
...
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 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 (Successful Execution) | Example (Successful Execution) | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXTENSION | Standard Universal Extension format The extension output follows the standard Extension output format, providing:
Result fields
| | Expand | | ||||||||||
|
| Code Block |
|---|
{
|
"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 |
} |
} } |
Description (Failed Execution)
Standard Universal Extension format
The extension output follows the standard Extension output format, providing:
“exit_code“, “status“, “status_description“: Will be set according to the specific error that happened during the execution. A list of possible values is provided in the exit codes table in this document.
“invocation”
“fields”: The task configuration used for this task execution.
Result fields
“result”:
“definitions_selected”: The UAC definitions that match the filter provided
“errors”: The list of errors occurred during execution.
| Code Block |
|---|
{ |
"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.
Action Output
Output Type | Description | Example | |
|---|---|---|---|
EXTENSION | The extension output follows the standard Extension output format, providing:
| | Expand | |
|
| Code Block |
|---|
================= ========= ========================================= 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.
Expand |
Code Block | |
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 (Successful Execution) | Example (Successful Execution) | ||||
|---|---|---|---|---|---|---|
EXTENSION | Standard Universal Extension format The extension output follows the standard Extension output format, providing:
Result fields
|
| ||||
Description (Failed Execution) | Example (Failed Execution) | |||||
Standard Universal Extension format The extension output follows the standard Extension output format, providing:
Result fields
|
| |||||
STDOUT | All definitions matched the selection criteria, in table format. Expand | |
|
Action: Import from Git Repository
...
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. |
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.
...
|
|---|
...
| 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.
Create a new Global Event Template that shall receive the Git provider’s Webhook payload. Set option "Unmapped Attributes Policy" to "Include Attributes".
Create a Universal Monitor and link it with the Global Event Template created in Step 1.
Create a Universal Monitor Trigger assigning to it
the Universal Monitor created in Step 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}.
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:
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
|
|---|
...
| Filter out webhooks that were triggered from the "Export to git Repository" Action. |
Parse GitLab/GitHub Webhook Payload
| Anchor | ||||
|---|---|---|---|---|
|
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 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 |
| Note |
|---|
|
Parse Bit Bucket and Azure DevOps Webhook PayloadAnchor bitbucket_webhook bitbucket
| bitbucket_webhook | |
| bitbucket |
...
...
_webhook
| _webhook |
|
|---|
| Import from Bitbucket via Webhook |
| Note |
|---|
In this scenario, any input in Add/Modify/Remove UC Definition List fields will be ignored. |
...
Action Output
Output Type | Description (Successful Execution) | Example (Successful Execution) | |||||||
|---|---|---|---|---|---|---|---|---|---|
EXTENSION | Standard Universal Extension format The extension output provides the following informationfollows the standard Extension output format, providing:
Result fields | title | Successful Execution|||||||
| Expand |
| ||||||||
Description (Failed Execution) | Example (Failed Execution) | ||||||||
Standard Universal Extension format The extension output follows the standard Extension output format, providing:
Result fields
|
| ||||||||
STDOUT | All definitions matched the selection criteria, in table format. expand |
|
Input Fields
The input fields for this Universal Extension are described below.
Field | Default value | Type | Required | Description | Introduced In Version |
|---|
Action | List UAC Definitions | Choice | Required | Action performed upon the task execution. Available actions are as follows.
|
|
1.0.0 | ||||
Universal Controller URL | - | Text | Required | The Universal Controller URL will be used to query and import UC Definitions. |
1.0.0 | ||||
Universal Controller Credentials | - | Credentials | Required | Universal Controller credentials that provide access to the Universal Controller Web Services. The user should be configured with "Web Service Access=True". |
1.0.0 |
UC SSL Certificate Verification |
True | Boolean | Required | Enables/Disables certificate verification against Universal Controller URL. For example, if self-signed certificates are used to connect with UAC |
. |
1.0.0 | ||
Selection Method | Business Service | Choice |
Required | Select or filter specific UC Definitions for listing or exporting to Git repository.
|
Visible only when the selected action is List UAC Definitions or Export to Git Repository. |
1.0.0 | ||||
Selection Name | - | Dynamic Choice | Required | The corresponding filter value for the Selection Method Field. When the selected Selection Method is Definition Name, the value provided in the Visible only when the selected action is List UAC Definitions or Export to Git Repository. |
1.0.0 | ||||
Selection Exclude List | - | Choice | Optional | 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. |
1.0.0 | |
Git SSL Certificate Verification | True |
Boolean | Optional | 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 |
. |
1.0.0 | ||||
Git Service Provider | GitLab | Choice | Optional | The Git service provider the task is using.
|
Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Service Provider URL | - | Text | Optional | The Git service provider URL the task is using.
Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Credentials | - | Credentials | Optional | The credentials that should be used to access the Git repository. The Credentials definition should be as follows.
Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Repository | - | Dynamic Choice | Optional | The repository the task will use to import or export UAC Definitions. The list of values is retrieved from the Git Service Provider. Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Repository Branch | - | Dynamic Choice | Optional | 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. Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Repository Path | - | Text | Optional |
Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Repository File Format | Yaml | Choice | Required | The file format is used to read and write in the Git repository. The available options are as follows.
|
Visible only when the selected action is Import from Git Repository or Export to Git Repository. |
1.0.0 | ||||
Git Commit Message | - | Text | Optional | The optional git commit message for the commits that will take place during export. The commit message |
For example, if the commit message is "test export" the |
provider will be "[uac push] test_export". Visible only when the selected action is Export to Git Repository. |
1.0.0 | ||||
Add UC Definitions List | - | Text | Optional | 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 Visible only when the selected action is Import from Git Repository. |
1.0.0 | ||||
Modify UC Definitions List | - | Text | optional | 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 Visible only when the selected action is Import from Git Repository. |
1.0.0 | ||||
Remove UC Definitions List | - | Text | Optional | 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 Visible only when the selected action is Import from Git Repository. |
1.0.0 | ||||
Proxy Type | -- None -- | Choice | Optional | What type of proxy is in use (if any). The available options are as follows.
|
|
1.0.0 | ||||
Proxy | - | Text | Optional | Proxy server and port. |
1.0.0 | ||||
Proxy Credentials | - | Credentials | Optional | Credentials to be used for the proxy when the selected Proxy Type is HTTPS With Credentials. |
1.0.0 | ||||
Proxy CA Bundle File | - | Text | Optional | 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. |
1.0.0 | ||||
Webhook Payload | - | Text | Optional | 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. |
1.1.0 |
Output Fields
Field | Type | Default Value | Description | Introduced in Version |
|---|---|---|---|---|
Extension status | Text | - | Through this field, the user will be able to receive info about the internal status of execution, more detailed than the general task execution result code. Based on the status of the execution this field will be updated as follows:
| 1.1.0 |
...
The exit codes for this Universal Extension are described below.
| Exit Code | Status Classification Code | Status Classification Description | Status Description |
|---|---|---|---|
| 0 | SUCCESS | Successful Execution | SUCCESS: Task Executed successfully. |
| 1 | FAIL | Failed Execution | FAIL: Task Failed to execute with error(s) |
| 10 | CONNECTION_ERROR | Failed Execution | “Connection failed for API: <url>“ |
| 11 | CONNECTION_AUTH_ERROR | Failed Execution | “Auth failed for action: <action details>, on API: <url>“ |
| 20 | DATA_VALIDATION_ERROR | Failed Execution | “Incorrect Field Data, see STDERR for more details“ |
| 21 | DATA_SYNC_ERROR | Failed Execution | “Some errors were produced during the data synchronization process: Task completed with failures. See Extension Output for more details." |
...
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
...
.
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
| Anchor | ||||
|---|---|---|---|---|
| Anchor | ||||
|
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
| Anchor | ||||
|---|---|---|---|---|
|
This document references the following documents.
| Document Link | Description | |
|---|---|---|
| Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. | |
| Universal Event Template | Use documentation for creating Universal Event Templates | Universal Tasks|
| User documentation for creating Universal Tasks in the Universal Controller user interface. | ||
| Credentials | User documentation for creating and working with credentials. | |
| Resolvable Credentials Permitted Property | User documentation for Resolvable Credentials Permitted Property. |
Changelog
...
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 it is 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).
...
| User documentation for creating Universal Tasks in the Universal Controller user interface. | |
| Credentials | User documentation for creating and working with credentials. |
| Resolvable Credentials Permitted Property | User documentation for Resolvable Credentials Permitted Property. |
| Anchor | ||||
|---|---|---|---|---|
|
Changelog
ue-jobs-as-code-1.2.1 (
...
2024-01-
...
25)
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).
...
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).
...
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 Requirements section for more information.
...