Backup file structure

Backups that are exported through the UI are in CSV format. As said in the parent page Import/export of Requirement Yogi data to a Confluence or Jira instance, backups can be used to export the entire Requirement Yogi data of a space and reimport it to another space or instance.

Example

Structure of the files

It’s a CSV export built wih Apache’s commons-csv, with the following configuration:

The CSVFormat.DEFAULT has the Javadoc comment:

Beginning of files

• BEING is hard-coded (Don’t ask me, I must have been tired that day),

• The plugin key,

• The plugin version,

• The most ancient compatible plugin version

• Name of the table (Those records are kept in the table DBBackupItem),

• METADATA is hard-coded

• null is the hard-coded,

• The scope key.

  • In case of a Confluence export, it’s the space key (before exporting);

  • In Jira it’s the project key (before exporting).

  • If all data was exported, null,

  • This field has the effect that all data in Confluence or Jira within this scope will be deleted.

  • This field is mapped on the target instance. If you export the space ABC, and you map ABC → DEF on the target instance, then DEF will be deleted and reimported.

  • If you need to ignore the scope and not delete any data, then one idea is to set this value to a non-existing space/project. However, in Jira, links will be imported in duplicate if they already exist, so you must clean up the data yourself before an import.

• The author key,

• The date of the export.

First half of files

Note that this CSV data is directly loaded without transformation into the backup tables (DBBackupItem and DBBackupMapping), then the sysadmin performs the mappings which updates data in DBBackupMapping, then only the import is performed into such tables as DBREMOTEREQUIREMENT.

• Name of the table (plain data is kept in DBBackupItem, mappings are in DBBackupMapping),

• Name of the target table,

• Old ID: ID in the old system. In this example, it’s the ID of DBRemoteRequirement. During reimport, the creation of the record will generate a fresh ID, which is written in DBBackupItem.NEWID, just to keep an archive of what has been migrated (and eventually perform mappings).

• Then all columns of the table. The order is specified by the annotation @ExportMapping(order = 2) on each column in the code.

The detail of the structure of each table is visible on those two pages:

• Database schema for Confluence backups

• Database schema for Jira backups

Second half of the files

It contains the “mappings”, i.e. the list of Confluence or Jira entities that we rely on. For example, it could contain the details of a space. During reimport, mappings are loaded in the table DBBackupMapping, and the system administrator can remap a space key to another; During the reimport, every time we reference this space, we’ll take the new key instead of the old one.

• Name of the table,

• Name of the target table,

• Key of the record. It is not exactly the primary key, since the full primary key is the key + dependencies. For example, if we save a page version, then the key is the versionId, and the dependencies are type=PAGE, app=page, documentId=271532.

• Then various “FYI” fields which can help the sysadmin infer or guess the new ID of the record:

  • The space key,

  • The page type,

  • The page id,

  • The user key,

  • The applink,

  • The page version,

  • The title (of the page, applink, user, etc.),

  • The URL (i.e. of the applink),

  • The username,

  • The extension document id,

  • The issue key

Footer of the files

It’s hard-coded.