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.yml

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
>=	Greater than or equal to

An asterisk may be used as a "wild card" in the version specification. For example ==3* specifies any version 3 Python.

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.

This attribute was introduced in Universal Extension API level 1.4.0. In order for zip_safe: false to have any impact, the extension must specify a Universal Extension API level >= 1.4.0 via the api_level attribute in extension.yml.

If an extension requires "dependency packages" (introduced in Universal Extension API 1.4.0), the extension must specify zip_safe: false.

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.