Intro

On Q4 of 2021 a functionality has been added that allows us to have versioned platform elements, such as ontologies, dashboards, gadgets, apis..., in a Git repository, so that we can have a control of changes on these elements and restore a previous version at any time.

In addition, we can generate tagged versions of the elements (tags in Git), so that in case of migration or if we want to restore a particular version of the elements, we can do it without problems.

Requirements to enable versioning

In order to enable the versioning of elements in a platform installation we will need:

• Git repository (GitHub or GitLab) with an API token with writing permissions.

• Administrator role: only administrators can configure this functionality.

Git repository configuration

Firstly, we will have to configure the Git repository that the platform will use to version the elements. The platform will always work in the same Git branch that is established in the configuration.

To configure it, we will go to the menu > Version Control > Configuration

Open

Here we will fill in all the necessary fields and mark the option to create repository if we want:

Open

If we already have a repository created, we uncheck the option.

Once configured, we can modify the configuration at any time, including temporarily disabling resource versioning (top left button). We can also delete the configuration altogether.

In addition, at the time of configuring it, a SNAPSHOT of the current resources in the repository will be generated:

Element Serialization Format

To serialize the entities or elements of the versioning system, we have chosen the Yaml format, because, for elements such as Dashboards or Gadgets, it allows us to display the HTML content in a readable way.

Besides, if we want to edit the file and then restore it, it will be much easier.

There are some elements such as Web Projects, Dataflows, flows and notebooks, which in addition to having a serialized file with the information of the database entity, will have an associated zip file (or several ones) that will contain the physical resources of said element. .

Commit message on edit and create

When the versioning system is enabled, pop-ups will begin to appear with a text box to enter a commit message when creating or updating versionable elements.

For example, when editing an ontology:

If we leave the commit empty, a generic commit message will be used, indicating the user who has edited or created the element.

Commit messages for Dataflows, Flows and Notebooks

As these elements have associated physical disk resources, it is necessary to commit them "manually and intentionally" from their list, using a special button.

History of changes, restoration and edition of an element

In the Restore Resource menu option, available to all users who have a role equal to or greater than developer, a screen will open where we can see the history of changes for any element to which we have access, restore it and even modify the current version.

Restoring an existing item

If the element currently exists on the platform, we will choose the first option “Restore existing resource”.

Here we will get a dropdown with all the platform elements that are versionable.

Once the type of element has been selected, a drop-down will appear with the specific element that we want to restore.

Finally, when selecting the element to restore, a dropdown will appear with the commits. When one element is selected, we will be shown the content of the element in that commit.

A code viewer will appear with the differences between the current element (editable, to the right) and the element in the selected commit (not editable, to the left).

Once there, we can restore the commit version (Restore button), or edit the current version to merge changes, for example. To edit the current version, we will modify the content of the element in the editor, and click on Save Changes (cmd + s / ctrl + s).

Restoring a deleted item

In case we want to recover an element that was deleted in a commit, we can do it from the “Restored deleted entity” option.

Here we will choose the type of entity, the relative path to the item in the Git repository, and the commit from where we want to restore it. Finally we will select “Load content” to verify that the content is correct and then “Restore”.

Git Snapshot and Tag Creation

We can generate a Snapshot of the platform’s versionable elements at any time.

Snapshot with all elements

If we want to generate a version including all the elements, we should make sure that all the elements are checked.

In this case, the Tag name will be optional.

Snapshot with selected items

If we want to generate a version with only certain elements of the system, we will have to mark only the resources that we want to include.

Bear in mind that, if we uncheck users, the resources associated with those users will be automatically excluded, even if they are checked.

In this case it will be necessary to indicate the name of the Git Tag.

Restore the platform

With this functionality, we can also restore all the platform elements from a Git repository indicating a tag or branch.

This process can also be done to migrate/promote environments, for example, to move elements from a development environment to a pre-production environment.

This process will delete all versionable items that are not in the Git repository.

Modifying items from Git repository

It is also possible to manually modify elements from the repository, and then restore them to the platform.

To do this, we will go to any versioning screen (for non-administrator users, Restore Resource screen), and look for the “Sync repository” button.

This will synchronize the changes with the database.