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.0.1 |
Refer to Changelog for version history information.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
For exporting and importing UAC Definitions from GitHub, manual installation of the below package to a Universal Agent is required:
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 or GitHub 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
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 back up 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 features provides the opportunity for restoration of 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. |
Known Issues
When using Gitlab as the git service provider and at the same time a proxy certificate is provided, the SSL verification of Gitlab certificate fails. Until a fix is available, the "Git SSL Certificate Verification" option should be unchecked for the case of Gitlab.
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
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.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | List UAC Definitions | Choice | Action performed upon the task execution. Available actions are as follows.
|
Universal Controller URL | Required | - | Text | The Universal Controller URL that will be used to query and import UC Definitions. |
Universal Controller Credentials | Required | - | Credentials | Universal Controller credentials that provide access to the Universal Controller Web Services. |
UC SSL Certificate Verification | Required | True | Boolean | Enables/Disables certificate verification against Universal Controller URL. For example, if self-signed certificates are used to connect with UAC. |
Selection Method | Required | Business Service | Choice | Select or filter specific UC Definitions for listing or exporting to Git repository.
Visible only when selected action is List UAC Definitions or Export to Git Repository. |
Selection Name | Required | - | 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 workds 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 contains 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 selected action is List UAC Definitions or Export to Git Repository. |
Selection Exclude List | Optional | - | Choice | Exclude various UC Definition types of resources from the selection. Visible only when selected action is List UAC Definitions or Export to Git Repository. |
Git SSL Certificate Verification | Optional | True | Boolean | Enables/Disables certificate verification against Git Service Provider URL. Visible only when selected action is Import from Git Repository or Export to Git Repository. |
Git Service Provider | Optional | GitLab | Choice | The Git service provider the task is using.
Visible only when selected action is Import from Git Repository or Export to Git Repository. |
Git Service Provider URL | Optional | - | Text | The Git service provider URL the task is using. Visible only when selected action is Import from Git Repository or Export to Git Repository. |
Git Credentials | Optional | - | Credentials | The credentials that should be used to access the Git repository. Visible only when selected action is Import from Git Repository or Export to Git Repository. |
Git Repository | Optional | - | 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 selected action is Import from Git Repository or Export to Git Repository. |
Git Repository Branch | Optional | - | 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 selected action is Import from Git Repository or Export to Git Repository. |
Git Repository Path | Optional | - | Text |
|
Git Repository File Format | Required | Yaml | Choice | The file format used to read and write in Git repository. The available options are as follows.
|
Git Commit Message | Optional | - | Text | Optional git commit message for the commits that will take place during export. The commit message |
Add UC Definitions List | Optional | - | Text | The comma separated list of Git files paths that should be used to create UC Definitions. Type "*" to select all files from Git provider and add them to UAC. Accept also UC variables as input. Visible only when selected action is Import from Git Repository. |
Modify UC Definitions List | OIptional | - | Text | The comma separated list of Git files 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 also UC variables as input. Visible only when selected action is Import from Git Repository. |
Remove UC Definitions List | Optional | - | Text | The comma separated list of Git files 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 also UC variables as input. Visible only when selected action is Import from Git Repository. |
Proxy Type | Optional | -- None -- | Choice | What type of proxy is in use (if any). The available options are as follows.
|
Proxy | Optional | - | Text | Proxy server and port. |
Proxy Credentials | Optional | - | Credentials | Credentials to be used for the proxy when the selected Proxy Type is HTTPS With Credentials. |
Proxy CA Bundle File | Optional | - | 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. |
Task Examples
List UAC Definitions
User Scenario: Query all UAC Definitions stored in UAC except Scripts and Custom Days, without proxy connection.
User Scenario: Query all UAC Definitions that that are part of a workflow with name 'test-workflow', with proxy connection.
Export to Git Repository
User Scenario: Export to Gitlab UAC Definitions contained in Bundle with name uc_bundle except from Email and Peoplesoft Connections. The selected definitions will be stored under "/export folder" under "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 correspoding paths of Add, Modify and Remove Definitions Lists. Files under Add list will be added to UAC, files under Modify list will modify existing definititions. Definitions which their paths are under Remove list will be deleted from UAC.
User Scenario: Import from GitHub all the files that are stored under "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 proccess.
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:
- Set up a commit webhook in your Git provider.
- Create a new Universal Event Template in order to allow monitoring of received webhook events by a Universal Monitor. Note that in "Unmaped Attributes Policy" dropdown menu, "Inlude Attributes" should be selected.
- Create also a Universal Monitor and link it with the Universal Event Template created in the previous step.
- Finally, 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.
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 correspoding 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: like enclosued in a list, as demonstrated in the example below:
Task Output
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.
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 where produced during data synchronization process: Task completed with failures. See Extension Output for more details." |
Extension Output
List UAC Definitions
Attribute | Type | Description |
---|---|---|
definitions_selected | string | The UAC definitions that match the filter provided |
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
Attribute | Type | Description |
---|---|---|
definitions_selected | dictionary | The UAC definitions that match the filter provided. |
definitions_exported | dictionary | The UAC definitions that actually exported to the Git provider. |
errors | list | The list of errors occured during execution. |
An example of the Extension Output for a fail 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
Attribute | Type | Description |
---|---|---|
definitions_selected | dictionary | The UAC definitions that match the filter provided. |
definitions_added | dictionary | The UAC definitions added. |
definitions_modified | dictionary | The UAC definitions modified. |
definitions_removed | dictionary | The UAC definitions removed. |
errors | list | The list of errors occured during execution. |
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
STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.
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:
Type | Subtype | Name | Git Path | Status |
---|---|---|---|---|
UAC definition type | The Subtype of the definition, as shown in Universal Controller | The name of the definition | The git path the the definition will be exported to or imported from | The outcome of the action |
For example, an 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.
Document Link | Description |
---|---|
Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
Universal Event Template | Uset 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. |
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", "Icon" should not be changed.
- Universal Template Details Section
- "Template Type", "Agent Type", "Send Extension Variables", "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 "Exit Code Processing Fields" section.- Success/Failure exit codes need to be respected.
- 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 success or failure of a task.
- General Section
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Changelog
ue-jobs-as-code-1.0.1 (YYYY-MM-DD)
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