capability-versions.rst

Capability Version Architecture

A capability request contains three components: The request itself, at least one version, and at least one execution. On capability request creation, and initial capability version is automatically created. Upon version submission, a capability execution is created with an associated Workflow Request.

Additional versions and executions can be created. When this occurs, the system maintains an awareness of the current version and current execution. These are called the "current version" and "current execution," and are highlighted in the following diagram:

What is a Capability Version?

The concept of Capability Versions was based in part on the VLASS Manager Jobs System and is meant to allow for multiple processing iterations of the same requested dataset with differing input parameters and files. This allows for the best results to be more easily obtained.

Many important lessons were learned from the VLASS Manager system and the Workspaces developers have endeavored to avoid the worst of the VLASS pitfalls with the design of the Workspaces Capability Version System. To that end, while it is possible to create multiple versions and executions of Workspaces Capability Requests, this functionality is subject to a set of restrictions meant to ensure that system stability is easily maintained.

Restrictions on Capability Versions

Given that a capability request may contain two or more versions, rules governing the disposition of capability request versions become necessary. These rules are implemented as follows.

• While a Capability Request can have multiple versions, only one version may be QA Passed.
• When one Capability Version is QA Passed, all other versions of the Request must be QA Failed.
• Once a request is Completed as a result of QA Pass, the user is not permitted to make new versions.
• While a Capability Version can have multiple Capability Executions, a new execution may only be created if the previous executions have all errored.
• The user is not permitted to alter the Version’s parameters when creating a new execution.
• Any Capability Execution should have one, and only one, workflow request.
• There should only be one mutable version - i.e. one where the user can manipulate parameters and files - at any given time and this should be the current version. If a mutable version already exists a new version cannot be created.

These restrictions are enforced by the Workspaces Restriction Engine, please see :doc:`restriction-engine` for more information.

Are all Capabilities Multiple Version Capable? No.

While Workspaces is designed to allow for the creation of multiple versions on any request there are some Capabilities where having multiple versions makes no logical sense.

Single Version Requests vs. Multi-Version Requests

There are two types of Workspaces Capabilities with respect to the version system: Single Version Only Requests and Multi-Version Capable Requests

Single Version Only

Currently, there is only one type of single version request possible: the Download Capability. There is no logical reason to allow multiple versions of downloads. A download either succeeds or fails.

Multi-Version Capable Requests

There are two types of Multi-Version requests: QA Requests and Non-QA Requests.

When QA is required by the specified Capability definition, there are specific restrictions that come into play, such as the restriction preventing new versions after QA pass. Once QA Pass is run on a QA-able request, that request is sealed against any further alterations, and it’s chosen products are ingested.

When QA is not required by the specified Capability definition, a request cannot be sealed and a user may make as many versions as they wish, subject of course to restrictions, such as the restriction on mutable versions.