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_levelspecified 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_levelis 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: trueowner: 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.