The Git versioning plug-in is only available through the Advanced Governance package.
The Git versioning plug-in tracks workbook events for you and allows you to roll back to previous versions of a workbook. Every workbook artifact has an UUID, which makes it unique and is used with the plug-in to restore previous versions of a workbook.
Don't touch the Git repository if Datameer is running to avoid conflicts while storing new commits.
To use this plug-in, you need to install Git on the same machine as the Datameer server. The Datameer service depends on the Git repository for constant writes, so a low response time is necessary. As a result, the repository folder needs to be locally set up on Datameer server and cannot be remote.
Datameer highly recommends that a MySQL application database be in production before the Git plug-in is installed. If the internal HSQL database is being used with Datameer when the Git plug-in is installed, a later HSQL to MySQL migration is not possible due to a discrepancy between the application databases' schemas.
Installing the Plug-in
Before you install the plugin, you might want to configure the folder where plug-in configurations are stored. To check the current path setting, open the file system for Datameer and navigate to the
conf/default.propertiesfile. Search for the property that defines the folder where plug-in configurations are stored.
It is important to note where plug-in configurations are stored if you are upgrading Datameer in the future, since you need to copy the contents of the previous plug-in configurations folder into the file system of the upgraded version of Datameer.
Create a new folder to store the Git repository on the Datameer server. Make sure the user who is running Datameer has read and write capabilities for this folder.
In the command line, go to your Git folder and type in the command
git init. If it is working correctly, you receive a response that the Git repository was initialized.
- Use the directions under Managing Plug-ins and Extension Points to install the plug-in. On the Plug-ins page, click the cog symbol next to Git Versioning Plug-in to configure the settings.
The following example creates a Git repository in Datameer's installation folder:
Create a first backup of the Git repository. In the future, back up this repository frequently.
Configuring the Plug-in
- On the Plug-ins page, click the cog symbol next to Git Versioning Plug-in to configure the settings.
- In the Local Path field, enter the path to the folder created on the Datameer server.
- Select the Request Snapshots of File Browser Artifacts
Understanding the Repository Structure
The repository is structured in two ways: directories that you see in Datameer, and directories that contain files and folders by UUID. It helps to understand the folder structure in order to find the workbooks and commits you need.
Take the following example:
In this example:
!files-by-uuid/directorystores symbolic links to the metadata of all workbooks in Datameer, identified by their UUID.
!folder.jsonfile shows the metadata of the root folder of the File Browser, including permissions and UUID.
!folders-by-uuid/is a directory that stores symbolic links to the metadata all folders in Datameer, identified by their UUID.
.git/is a directory that represents the local Git repository.
.system/is a hidden directory in Datameer's File Browser with internal artifacts.
- The directories from
Analytics/on represent the folders that the user has set up in the File Browser.
Roll back a workbook
To roll back changes while Datameer is running, create a clone of the configured Git repository to avoid conflicts while Datameer is writing to the original repository using the
Sync the cloned repository with the original repository to make sure the commits are the same using
See a history of changes to a workbook by using the
git logcommand to see all commits over time for a specific workbook.
Make sure to use
git logon the real file of the workbook which lies in the directory, as opposed to using the command on a symbolic link. If you look for the history on the symbolic link, it shows only the creation of the link itself.
To see what actually was changed within the workbook, look at a specific commit.
This command gives an output similar to the following, which shows who changed the formula and who changed the type from a float to an integer:
To restore a specific version of the workbook, check out the related state of the repository using its commit ID using the
If you want to review the workbook to make sure you have the right version, you can print the metadata of the workbook using the
Restore the workbook by using the roll back a workbook REST API.
Reset the repository to the latest state using the
Re-sync the cloned repository with the original using the
git pullcommands, to make sure both are up-to-date.
Other REST API tools
Installing the Git Versioning Plug-in After Upgrade
After upgrading Datameer, you might need to re-install the plug-in.
- Double-check that the Datameer service is stopped.
Create a folder to store the Git repository on the Datameer server. Make sure the user who is running Datameer has read and write capabilities for the new folder.
Unpack the Git repository backup.
Move the configuration file to the correct folder.
Install the downloaded Git versioning plug-in into the plug-ins folder. This installation ensures that plug-in becomes loaded automatically during Datameer service start.
The plug-in is installed now and the Datameer service is safe for start.
Backing Up to a Remote Git Repository
While the Git repository being used for the plug-in must reside on the same machine as the Datameer server, it is possible to back up this local repository to a remote repository outside of Datameer.
In order to push to a central (remote) Git repository, it is recommend to set up a cron job that syncs with that repository frequently. It is important that only the local Git repository is set to provide commits. This recommendation is to avoid merge conflicts or any other inconsistent states.
In this setup, you have the local Git repository, located on the Datameer server, with both read and write permissions and one remote Git repository that has only read permission that pulls from the local repository.