Universal Controller
Summary
The Universal Extension developer will create a new Universal Extension-based Universal Template, declaring:
Task fields required for defining and launching the process through the Universal Extension.
Task Instance fields required for capturing data coming back throughout the life-cycle of the Universal Extension process.
Task Instance commands, and their supported status(es), that can be executed through the Universal Extension.
The Universal Extension developer will then upload/attach an Extension Archive zip file to the Universal Template, recognized by the Universal Agent, which can either be deployed on-demand to registered agents, or automatically following a successful agent registration.
Once the Universal Template is created, and the Extension Archive zip file is attached, the Universal Extension developer can generate a zip package, recognized by the Universal Controller, containing both the Universal Template definition and the Extension Archive zip file recognized by the Universal Agent.
To create a Universal Extension, see Creating a Universal Template.
Agent Registration
All communication between the Universal Controller and the Universal Extension is managed through UAG; therefore, any registering agent that meets the release criteria can be a Universal Extension provider.
In order for the Universal Controller to know which Universal Extensions are supported by a registering agent, each Agent will report this information in the hello message handshake.
Universal Extension Deployment
Deployment of Universal Extensions is managed by the Universal Controller.
Any Universal Agent registering into the Universal Controller can automatically accept deployment of available Universal Extensions.
Note
It is important to review the Universal Agent configuration option, EXTENSION_ACCEPT_LIST, if you want to prohibit an agent from accepting deployment of any extension or if you want to limit deployment to specific extensions.
This allows full customization of the deployment approach, allowing agent extension configuration to be tailored based on corporate policy.
For automatic deployment of Universal Extensions to all registered agents, ensure that your agents are all installed with an accept any extension (default) configuration.
On-Registration Extension Deployment
On registration deployment of accepted Universal Extensions will commence immediately upon successful agent registration, depending on the configuration of the EXTENSION_DEPLOY_ON_REGISTRATION UAG configuration option.
On-Demand Extension Deployment
For Agents that are configured to accept extensions, but are not configured for on-registration deployment, their accepted extensions will be deployed only on-demand at task instance run time.
If on-demand deployment of an extension is required, the task instance will transition to the Queued Status with the Deploy Extension Status Attribute.
Upon successful deployment, the Deploy Extension Status Attribute will be cleared and the task instance will transition to the Running Status.
If the deployment is unsuccessful, the the Deploy Extension Status Attribute will be cleared and the task instance will transition to the Start Failure Status.
If an extension cannot be deployed to the destination agent due to the extension not being an accepted extension, the task instance will transition to Undeliverable Status.
Once the agent configuration has been updated, and the agent restarted, on-demand deployment can commence and the task instance will transition to Running Status upon successful deployment, as described above.
Universal Template/Extension Definition
The Universal Template definition will be enhanced to allow differentiating between a Universal Task that is executed by UAG in the form of a Script, and a Universal Task that is executed by a Universal Extension.
Under the Universal Template Details section, the user should still be able to refine the Agent Type (Any, Linux/Unix, or Windows), however, it can no longer be assumed that the Script related fields (Use Common Script, Linux/Unix Script, Windows Script, and Windows Script File Type) are applicable.
A new Template Type field, with options Script and Extension, will be introduced to distinguish between Script-based Universal Templates and Universal Extension-based Universal Templates, respectively.
The following fields, under their applicable sections, will be hidden when the Template Type is Extension.
Universal Template Details
Use Common Script
Linux/Unix Script
Windows Script
Windows Script File Type
Output Only Field
A Universal Extension may need to send back runtime attributes associated with a task instance.
These fields are not applicable at definition time; therefore, when specifying a Universal Template Field of type Text, Integer, Float, or Boolean, a Restriction option was added where you can specify No Restriction or Output Only.
Output Only fields will be rendered as read-only on the Universal Task Instance form, and not shown on the Universal Task form.
Output Only Field Validation
Text |
|
Integer |
|
Float |
|
Boolean |
|
Preserve Output On Re-run
When Restriction is Output Only, an option to Preserve Output On Re-run can be specified.
On task instance Re-run, all Output Only field values are cleared, by default. To change this behavior, on a per field basis, enable the Preserve Output On Re-run option.
Extension Status
A field can be specified as Extension Status if Restriction is Output Only. Only one field can be specified as Extension Status per Universal Template.
The Extension Status for a task instance will be mapped to the Output Only field that specified as Extension Status = true.
If the designated Extension Status Output Only field is changed in a universal template, the Extension Status of any pre-existing instances for that template will not be updated until the universal extension sends back an update for the new Extension Status Output Only field.
Text Field Text Type
For Extension-based Universal Templates only, a Text Type option will be introduced for Universal Template Fields of type Text.
This allows for the template administrator to designate a specific content type for a Text field, with the following content types currently supported.
Plain (default)
JSON
YAML
When JSON, or YAML is selected as a Text Type, the following applies.
The field value must be parsable at definition time, or at runtime, if the field contains an unresolved variable or function.
The field value will passed to the Universal Extension as its designated type.
Dynamic Choice Field
Choice field types need to support dynamic, Universal Extension-derived options.
To accommodate this, Universal Extension-based Universal Templates will introduce a new Dynamic Choice boolean option on the Universal Template Field form, when the field type is Choice.
When the Dynamic Choice option is enabled, the template administrator will no longer be able to define static Choices.
It is feasible that the dynamic options depend on the value of one or more Universal Template Fields; therefore, a template administrator also is able to specify dependent fields through a new Dependent Fields option.
From the Universal Task form, dynamic choice field options will be populated through a request/response mechanism, initiated by Universal Controller to the Universal Extension.
Dynamic Commands
A Universal Extension may support additional operations against a task instance, therefore, we need to allow for defining such operations, which in the Universal Controller we refer to as commands.
A new Commands tab on the Universal Template will become available if and only if the Template Type is Extension.
To define a command extension, the command definition will require the following fields.
Name | Unique command name, adhering to the same naming convention as a Universal Template field name. |
Label | User friendly display name for the command, to be displayed within the client. |
Supported Status(es) | Specifies the task instance status (or statuses) that the dynamic command should be enabled for. |
Dependent Fields | The administrator can select zero or more Universal Template fields that are required by the command. The values of those fields will be included in the command request. |
Timeout | Specifies an optional command timeout, in seconds, if the command requires longer than the System-level default of 60 seconds. If the Controller (server) does not receive a command response from the Extension prior to the timeout being reached, a timeout message will be sent to the client (user interface), and displayed in the Console: Command "command-name" on task instance "instance-name" with id instance-uuid timed out. |
Execution Option | Specification for whether the command runs out-of-process execution or in-process execution. |
Asynchronous | If Execution Option is in-process; Specification for whether the command runs synchronously or asynchronously. |
Command Permission
Users must have Universal (or ALL) command permission and Read permission for the Universal Task Instance, assigned by the Task Instance permission type, for authorization to execute a Universal dynamic command.
Universal Output
To allow for a Universal Extension-based Universal Task to contribute its own unique output upon job completion, the Controller added support for an EXTENSION output type that the Universal Extension can optionally return upon job completion.
Python Application Attachment
The Python Application implementing the Universal Extension must be packaged in a zip file, containing both an extension.py and an extension.yml.
The extension.yml is the YAML metadata configuration file, as shown below.
--- extension: name: extension1 version: "0.1.0" api_level: "1.0.0" requires_python: ">=2.9" python_extra_paths: "${extension_zip}/lib:${extension_zip}/test/lib" owner: name: John Doe organization: Stonebranch, Inc. comments: | These comments will appear in the Universal Template 'Extension Comments' field. The 'Extension Comments' field can be viewed from the Meta Data section, the List, or the Show Details.
The extension name
and api_level
are required, while the extension requires_python
(default “>=2.6”) and python_extra_paths
are optional.
Note
For requires_python
, you can use wildcards to select certain Python versions.
For example, the following configurations are supported:
requires_python
: "==2.7*"requires_python
: "!=3.9.1*"requires_python
: "!=3*"
The owner name
and organization
are optional.
From the Universal Template form, the zip will be uploaded by clicking the add [+] icon (tooltip Upload Extension Archive) next to the Extension field, and persisted in the Universal Controller database as a byte[] (BLOB).
To download an already attached Extension Archive, click the link [∞] icon (tooltip Download Extension Archive).
To remove an already attached Extension Archive, click the remove [-] icon (tooltip Delete Extension Archive).
During the upload process, the extension.yml metadata will be parsed and made available from the Universal Template Metadata fields.
Import/Export Template
The Import/Export Template feature supports importing/exporting a Universal Template as a zip file.
The Universal Template zip file includes the following entries:
File Name | Description | Optional |
---|---|---|
template.json | The Universal Template definition in JSON format. | No |
template_icon.png | The Universal Template Icon in PNG format. Note Icon metadata will be set as attributes in the Universal Template JSON. | Yes |
extension_archive.zip | The Universal Template Extension Archive in ZIP format. | Yes |
Export | To export an existing Universal Template as a zip file, click the Export Template button in the Universal Template Details. (You can also click Export Template in the Action menu that displays for that Universal Template record.) The exported Universal Template has the following filename format: {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl |
Import | To import a Universal Template zip file, click the Import Template… button on the Universal Templates list. |
Release Levels
Export Template sets the following release level attributes in the Universal Template JSON:
Attribute | Description |
---|---|
minReleaseLevel | The minimum Universal Controller release level required to import the Universal Template. "minReleaseLevel" : "7.0.0.0" |
exportReleaseLevel | The release level of the Universal Controller that the Universal Template was exported from. "exportReleaseLevel" : "7.0.0.0" |
Import Template validation prevents importing a Universal Template if the Universal Controller does not meet the minimum release level requirement:
Cluster Node release level is 7.0.0.0, which does not meet the minimum release level of 7.0.0.1 for the Template.
List Import/Export
The List Import/Export feature continues to support exporting the Universal Task and Universal Template, as it has in previously releases.
Comparable to the Universal Template Icon, the Extension Archive will be encoded in the XML as base64.
List Import validation prevents an extension name from being associated with more than one Universal Template:
The template 'template-name1' specifies an extension name 'extension-name' that is already associated with template 'template-name2'.
Log Level
Each registered Agent within the Universal Controller displays its configured Log Level, with one of the following options.
Trace
Debug
Info
Warn
Error
Severe
For Extension-based Universal Tasks/Templates, a Log Level option will be introduced at both the Universal Task-level, the Universal Task Instance-level, and the Universal Template-level to specify the Log Level for Universal Extension logging.
The option will have a default value of Inherited, meaning the following.
Universal Task |
|
Universal Task Instance |
|
Universal Template |
|
At Universal Task Instance runtime, if both the instance and the template are specified as Inherited, then the instance will inherit the agent Log Level.