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.

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

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.

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.

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.

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:

Release Levels

Export Template sets the following release level attributes in the Universal Template JSON:

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.

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.