Universal Extension for 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
  • The value cannot be more than 255 characters for text fields and 4000 characters for large text fields.

  • The following warning will be logged in the uc.log if the output field update is rejected by the controller.

    • Output Fields: Field value for field with template id uuid and field name "field-name" cannot be more than [255|4000] characters. {field-value}

Integer
  • The value must be an integer between -2147483648 and 2147483647, inclusive.

  • The following warning will be logged in the uc.log if the output field update is rejected by the controller.

    • Output Fields: Field value "field-value" for field with template id uuid and field name "field-name" is not a valid integer.

Float
  • The value must be a valid double-precision float.

  • The following warning will be logged in the uc.log if the output field update is rejected by the controller.

    • Output Fields: Field value "field-value" for field with template id uuid and field name "field-name" is not a valid float.

Boolean
  • Any value other than true will be evaluated as false.

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.

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.

AsynchronousIf 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.zipThe 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:

unv-tmplt-UniversalTemplateName-extensionVersion.zip

ImportTo 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
  • Specify Inherited to inherit the template Log Level setting.
Universal Task Instance
  • Specify Inherited to inherit the template Log Level setting.

  • The initial Log Level is derived from the Universal Task definition at Universal Task Instance creation time.

Universal Template
  • Specify Inherited to inherit the agent Log Level setting.

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.