Object Backup Restore

Content Type: Module
Categories: Import/Export

Overview

Continuation of my work at Synobsys. Backup and restore of Mendix objects for Mendix 6.10.2 and newer.

Documentation

mendix-ObjectBackupRestore

Backup and restore of Mendix objects

Description

Continuation of the version I made while working at Synobsys.

Create a backup of one or more Mendix objects, including referenced objects and file document contents. Backup configurations are used to specify which referenced objects will be included in the backup.

Disclaimer

  • Please note that the ObjectBackupRestore module is not intended to replace a full database or cloud backup plan.
  • The functionality is provided without official support.
  • Support is provided through Git issues or the Mendix forum on best-effort basis only.
  • We do not accept responsibility for loss or corruption of data or any resulting damage.
  • Use at your own risk.

By using this module you agree to be bound by this disclaimer.

Typical usage scenario

  • Restore objects of one organization in a multi-tenant environment.
  • Duplicate a part of the data to another environment. (Note that you can also duplicate backup configurations this way.)

Multi-tenant environment

When one customer organization in a multi-tenant environment request a restore of their data, the daily backup cannot be used as that would affect all customers in the node.

The following steps allow restoring data of one customer:

  • Restore the full backup in another node or environment.
  • In that node, use this module to create a backup of the data of the customer.
  • Restore that backup in the production environment.

Features

  • Backup any object in the model
  • Use an XPath constraint to limit the objects included.
  • Drill-down into referenced objects. For each reference can be specified whether the referenced objects must be included in the backup.
  • FileDocument content is also included.
  • The restore checks, for objects that have a functional key, whether the object already exists in the target environment. Existing objects will never be overwritten or changed.

Limitations

It is a normal Mendix module

The ObjectBackupRestore module works like any other Mendix application. Restoring an object using this module is the same as creating a new object with the same values.

Attribute values supplied by the runtime

  • Object IDs and AutoNumber attribute values are different after a restore
  • Owner is set to the user that restored the backup.

If you need auditing of your data, do not rely on the default Owner and ChangedBy but implement this in your own attributes and associations. You could also use the Audittrail module, available in the appstore.

Entity events

Commit events are skipped, but there is currently no way to skip AfterCreate events, so the microflow that handles the event must be able to cope with this. A simple way is to use only MxAdmin to restore objects and have the microflow quit if the user is MxAdmin.

Only one attribute as functional key

See below at Object configuration.

Dependencies

  • MxModelReflection. Used on the configuration pages, not during backup and restore.
  • CommunityCommons.
  • Bootstrap TreeView widget (included).

Installation

Normal appstore installation. Link the page in the UseMe folder to your navigation or use the snippets. Include the Admin module role in the Administrator user role.

Configuration

Reflection

Any module that contains entities or associations must be synchronized in Reflection. That includes System, Administration or even MxModelReflection itself if your entities reference entities in those modules.

Backup group

A backup group allows backup configurations to be grouped.

Backup configuration

Backups are created using backup configurations. A backup configuration specifies which entity is the main entity of the backup. It also specifies the default XPath constraint (optional) for backup requests that are based on this configuration.

After creating a new backup configuration, the edit backup configuration page is displayed. It shows the main entity and its associations. The associations are displayed in red because for each association must be decided whether to include the referenced entity in the backup. A backup can only be created when all references have include status Yes or No.

By clicking on an association, its details are displayed. The key of the referenced entity, if any, can be selected by clicking on the link.

Include in backup: Yes

The referenced objects are also included in the backup. The association is expanded to show the next level. When there are multiple paths to an object, it is sufficient to expand the reference in one place. The backup and restore detect that the same object is referenced. An example is a multi-tenant model, where all entities are related to the customer organization entity.

Do not include entites of System or Administration in your backups! Just specify the functional key on the object type and the restore process will link your data to these entities.

(You can use the module to duplicate backup configurations.)

Include in backup: No

The object only holds the ID and, optionally, the functional key of the referenced object. A functional key is necessary when the referenced entity is not included in the backup, to allow the restore to link the restored object to the existing object.

Specializations

Take care when an entity has specializations. Each specialization must be treated as a separate part of the configuration. The backup does not take the generalization into account when processing a specialization.

Backup request

A backup request is necessary to create a backup. It refers to the backup configuration to use and allows for a specific XPath constraint.

Create a backup

From the backup request screen, a backup can be created by selecting a backup request and clicking the Run backup button. Please make sure that noone is changing the objects you want to backup.

Working with backups

The Backups page shows a list of backups.

Show backup details and download the backup file

Click on the Information button or double click an existing backup to show details and download the backup file.

Import a backup from another environment

Import a backup file using the Import button. The backup file will be checked and then added to the list.

Restore a backup

A backup can be restored from the Backups page. Select a backup and click Restore. A page is shown with some details and counts of the backup. If desired, the objects in the backup can be displayed by clicking Show objects.  This will produce the contents of the backup in JSON format. Note that FileDocument data is not included. For larger backups this can take some time to produce. The restore can be started by clicking Restore.

Restore requests

Each time a backup was selected for restore, a restore request is created. Each restore request has a log, which shows the number of objects restored after a succesful restore. If the restore was not succesful, the log will contain errormessages.

Object configuration: functional key

For each entity included in the backup, a functional key can be specified. This functional key is only used during the restore to check whether the object already exists. Objects without a functional key are always restored.

The functional key of an entity can consist of one attribute only, the value must be unique for the entire entity. It is strongly advised to enforce unique values using a unique rule on the attribute in the domain model.

Only Enumeration, Integer, Long and String attributes are supported. (AutoNumber is not possible because a new value is generated during the restore.)

As commit events are skipped, a before commit event can be used to generate a unique key if necessary.

Logging

The ObjectBackupRestore module logs to log node ObjectBackupRestore. Set this log node to debug level for detailed information about each object processed in a backup or restore. Trace level includes even more detail, for problem solving.

Releases

Version: 2.0.0
Framework Version: 8.17.0
Release Notes: Converted to Mendix 8.17.0. Solved Java deprecations. Cleanup of the UI. Now depends on Atlas text classes. Widget ObjectBackupRestoreAdditionalStyling.mpk no longer necessary, can be removed from the widgets folder