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.

1. The Universal Controller will only run a Universal Extension task on an agent that supports the api_level specified by extension.
2. 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. The syntax and semantics are a subset of PEP 440 version specifiers. Its 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:

A single version specifier consists of one of the above operators, followed by a version which must use one of these formats.

The wildcard * is used in place of the minor number to mean that any version with a matching major number matches the specifier; or in place of the patch number to mean that any version with a matching major and minor number matches the specifier.

For example:

The comparison algorithm is as follows: given Python versions A and B,

1. If A.major > B.major, A > B

2. If A.major < B.major, A < B

3. If either A.minor or B.minor is a wildcard, A == B

4. If A.minor > B.minor, A > B

5. If A.minor < B.minor, A < B

6. If either A.patch or B.patch is a wildcard, A == B

7. If A.patch > B.patch, A > B

8. If A.patch < B.patch, A < B

9. A == B

python_extra_paths

The python_extra_paths attribute is optional.  This attribute provides a means for the extension developer to specify additional paths that will be included in the Python runtime environment in which the extension runs. Since it is impossible for the extension developer to know the path to the deployed extension at runtime, a special token is provided that will resolve to the deployed extension path at runtime: ${extension_zip}.

At runtime, ${extension_zip} will be replaced with the file system path to the deployed extension.  For example, if an extension archive included a directory for test modules:

├── extension.py
├── extension.yml
└── test
    └── test1.py
    └── test2.py
    └── test3.py

The following python_extra_paths value would setup pathing in the runtime environment allowing the extension code to access the test package:

python_extra_paths: ${extension_zip}/test

zip_safe

The zip_safe attribute is optional.  It specifies whether the extension should be run directly from the zip archive or extracted to the file system in a private cache and run from there.  The default value is true.

owner

This section pertains to the owner of the extension (the extension developer or developer's organization).

name

The name attribute is optional.  Specifies the Universal Extension owner's name.  This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller.  It is for informational purposes only.

organization

The organization attribute is optional.  Specifies the Universal Extension developer's organization.  This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller.  It is for informational purposes only.

comments

The comments section is optional. This attribute allows the extension developer to provide information about the extension. This field is displayed in the Metadata section of an extensions Universal Template in the Universal Controller.  It is for informational purposes only.