Thank you, Ajit @alondhe for supporting the initiative

Notes:

• the new functionality is available for Concept Sets, Cohort Definitions, Cohort Characterizations, Incidence Rates, Cohort Pathways ("Assets") and might be added for the other entities in the future

Data Model

An Asset’s Version entity consists of the following attributes:

• ID
• created by - user ID
• created at - server local time
• expression - a JSON representing this Asset Version
• version - a sequenced number (supplement “created by“ and “created at“ values while visualizing versioned Assets)
• reference ID to an Asset
• annotation / comment (optional) - to be used as an additional descriptive text encompassing last changes been made by a user

Key principles

⚠️ If a version is not explicitly specified in a WebAPI request the current Asset’s Version should be used, it should guarantee no breaking changes are introduced with the new functionality

Tags / Tag Groups are not versioned, they are not a part of the JSON model

In between Asset’s Versions the assigned Tags should not be gone so that a user should assign Tags repetitively and redo their previous work

If an Asset’s Version is used to create a copy (a separate Asset to be created starting a new versioning timeline) assigned Tags should not be copied to the newly created Asset

A new Asset’s Version is created each time the Save button is clicked

⚠️ Each UI control where an Asset has been selected / visualized will be not changed or enhanced, the current Asset’s Version is taken into consideration as it was in previous ATLAS versions

When an Asset’s Version is previewed or a copy is created out of an Asset’s Version and some of the referenced artifacts are no longer present in the system (for instance, being deleted) there will be an error dialogue displayed that the operation can not be successfully finished

UI extensions

Information about the current version is not displayed to a user not to mislead existing users who used to non-versioned Assets. If one of Asset’s Versions is displayed and it is not the current one then the Asset’s title is extended with the version number, the other attributes “created at” and “created by“ will be also displayed. When an Asset’s Version is previewed and it is not the current one only the meaningful tabs are displayed and the other ones which are usual for the non-versioned Assets are hidden to avoid any confusion

A new “Versions“ tab to be added in which a tabular view of all the Asset’s Versions to be displayed including the current one on top. In addition to the mandatory attributes like the version number, who is the version’s author and when it was created there will be a few additional columns added with actionable links

• “Comment“ - so that a user could annotate an Asset’s Version leaving a comment
• “Preview“ - so that a user will be able to preview a specific Asset’s Version
• “Copy” - to make a copy out of the underlying Asset’s Version as a separate Asset with the new versioning timeline

There will be an additional button added “Back to the current version“ in between the “Save“ and “Close“ buttons when a user is in the Asset’s Version preview mode and they would like to get back to the current version. If they decided to make changes in a particular version clicking on the “Save“ button an additional message dialogue will be popped up questioning “Save as current version?“ so that they could agree or cancel

API

To support versioning the following methods have been added to each Asset controller:

• GET /{assetType}/{id}/version/ - to get a list of Versions for an Asset with the ID={id}
• GET /{assetType}/{id}/version/{version} - to get a Version {version} for an Asset with the ID={id}
• PUT /{assetType}/{id}/version/{version} - to update the Version’s attributes
• DELETE /{assetType}/{id}/version/{version} - to delete an Asset's version (not available from the UI)
• PUT /{assetType}/{id}/version/{version}/createAsset - create a new Asset based on a particular {version}