Version Control for Dodeca Repository Artifacts

Dodeca Shell can export the artifacts for a tenant to a folder and import the artifacts from that folder back into a Dodeca repository. Because most Dodeca artifacts are exported as text-based XML files, you can store them in Git or another version control system to review changes and promote them between environments. Git is not integrated into Dodeca Shell and is not required to use the export and import commands. The Git commands in this guide are an optional workflow for tracking the exported files.

This example exports the DEMO tenant, changes a View artifact, commits the change to Git, and imports the updated artifacts.

Create a staging folder

Create an empty folder for the exported repository artifacts. The examples below use /path/to/DodecaSync; replace this path with the location of your staging folder.

Export a tenant to the staging folder

Start Dodeca Shell, connect to the tenant that you want to export, set a variable for the staging folder, and run sync-repository-to-folder:

dshell/DEMO:>set DODECA_FOLDER /path/to/DodecaSync
dshell/DEMO:>sync-repository-to-folder ${DODECA_FOLDER}

Dodeca Shell creates a subfolder named for the tenant and writes the exported artifacts to it. For this example, the artifacts are written to /path/to/DodecaSync/DEMO.

The tenant folder also contains a hidden .meta directory with metadata that Dodeca Shell uses to identify and import the artifacts. Keep the .meta directory together with the artifact files and include it in version control.

$ cd /path/to/DodecaSync
$ ls
DEMO
$ ls -a DEMO
.  ..  .meta
ADMIN.SMART_CLIENT_APPLICATION.1.xml
Adhoc_ExcelAddInMode.VIEW.1.xml
CustomToolControllers.MODULE.1.xml
...

An exported View artifact contains readable XML such as the following:

<View>
  <ViewInformation>
    <ID>Adhoc_ExcelAddInMode</ID>
    <Name>Adhoc Analysis</Name>
    <ViewTypeID>AdhocEssbase</ViewTypeID>
    <NamedPropertySets />
  </ViewInformation>
  <Properties>
    <AllowSave>true</AllowSave>
    <AutoBuildOnOpen>true</AutoBuildOnOpen>
    <ShowFormulaBar>true</ShowFormulaBar>
    <ExcelAddInMode>true</ExcelAddInMode>
  </Properties>
</View>

Optional: Track exports with Git

Git operates on the exported files independently of Dodeca Shell. You can initialize the staging folder as a Git repository and commit the initial export as a baseline:

$ cd /path/to/DodecaSync
$ git init
$ git add .
$ git commit -m "Initial Dodeca repository export"

If you already cloned a repository into the staging folder, commit or discard any existing changes before exporting artifacts into it.

Ensure that the tenant’s hidden .meta directory is not excluded by .gitignore. The artifact files alone are not sufficient for sync-folder-to-repository.

Edit and review an artifact

Edit the exported artifact with a text or XML editor. In this example, the ShowFormulaBar property in Adhoc_ExcelAddInMode.VIEW.1.xml is changed from true to false.

Use Git to review the change before importing it:

$ git status --short
 M DEMO/Adhoc_ExcelAddInMode.VIEW.1.xml
$ git diff -- DEMO/Adhoc_ExcelAddInMode.VIEW.1.xml

-    <ShowFormulaBar>true</ShowFormulaBar>
+    <ShowFormulaBar>false</ShowFormulaBar>

Commit the reviewed change:

$ git add DEMO/Adhoc_ExcelAddInMode.VIEW.1.xml
$ git commit -m "Turn off showing formula bar"

Import the staging folder into Dodeca

In Dodeca Shell, connect to the destination tenant and run sync-folder-to-repository with the staging folder. The destination tenant must match the tenant subfolder that contains the exported artifacts.

dshell/DEMO:>set DODECA_FOLDER /path/to/DodecaSync
dshell/DEMO:>sync-folder-to-repository ${DODECA_FOLDER}

The command imports all supported artifacts in the tenant subfolder, so review the complete set of pending changes before running it against another environment.

The sync commands save or update the artifacts they find, but they do not propagate deletions. sync-repository-to-folder does not remove stale files from the staging folder, and sync-folder-to-repository does not delete repository artifacts that are absent from the folder.

Use print-artifact to verify the imported artifact:

dshell/DEMO:>print-artifact Adhoc_ExcelAddInMode

<ShowFormulaBar>false</ShowFormulaBar>

Use cases

This technique can support:

Continuous integration and delivery for Dodeca solutions:
- Develop Dodeca applications, Views, selectors, and other artifacts in a development environment.
- Sync the development repository to a version-controlled folder.
- Review and approve changes in version control.
- Sync the approved folder to quality-assurance or production repositories.
An artifact-promotion process that keeps a Git history of changes between Dodeca environments.