The extension.yml
document contains metadata pertaining to a Universal Extension. This document must be included in the Universal Extension zip archive at the root level (along with extension.py
).
extension: name: extension1 version: "0.1.0" api_level: "1.4.0" requires_python: ">=3.6" python_extra_paths: "${extension_zip}/lib:${extension_zip}/test/lib" zip_safe: true owner: name: John Doe organization: Stonebranch, Inc. comments: | These comments will appear in the Controller 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 file contains three sections: extension, owner, and comments.
extension
The extension section contains attributes that pertain to extension management and operation. Some fields are optional.
name
The name
attribute is required. It is used to identify the extension within the UAC system and therefore, must be unique within that system.
version
The version
attribute is required. This attribute is used in the generation of dependency package file names for a given extension.
api_level
The api_level
attribute is required. This attribute is used to specify the Universal Extension API level required by the extension. There are two important things controlled by the api_level
.
- The Universal Controller will only run a Universal Extension task on an agent that supports the
api_level
specified by extension. - The agents running the extension will only "activate" the functionality associated with the specified API level - regardless of the API level supported by the agent. Therefore, the
api_level
is the upper bounds of API support that will be available to the extension.
The extension developer should consider the target API level carefully. Specifying the latest API level will make the most functionality available to the extension. However, it will also restrict the extension to only running on the latest agents.
In general, an extension should not specify an API level higher than what is required by the extension. Doing so only servers to restrict the range of agent versions it can run on.
requires_python
The requires_python
attribute is optional. This attribute allows the extension to specify the versions of Python it can work with. A The requires_python
value consists of one or more version specifier clauses delimited by commas. A specifier clause consists of a comparison operator and a version number. if not specified, a default value of >=2.7
will be used. Valid comparison operators are as follows:
Operator | Meaning |
---|---|
== | Equal to |
!= | Not equal to |
< | Less than to |
<= | Less than or equal to |
> | Greater than |
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.4.0" requires_python: ">=3.6" python_extra_paths: "${extension_zip}/lib:${extension_zip}/test/lib" zip_safe: true owner: name: John Doe organization: Stonebranch, Inc. comments: | These comments will appear in the Controller 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.