Partial Backup

Overview #

A “Partial Backup” saves the relevant configuration for a set of pages. Partial Backups are typically used to migrate content from one system to another. When creating a Partial Backup, the server will discover all the requisite configuration needed to produce the Visualizations on the selected set of Pages, and then package it up in an “.ESB” file. The .ESB file includes a variety of different objects:

  • All Visualization instances on the Page.
  • All Actions associated with Visualization instances on the Page.
  • The Data Pipeline for all datasets being displayed on the Page.
    • All Node Variables used inside of Feeds and Transforms in the relevant Pipeline nodes.
    • All Variable Constraints used to restrict input for Node Variables in the relevant Pipeline nodes.
    • All rulesets used inside of a Visualization’s renderer.
    • All Color Palettes and Icons used inside of rule sets.

Creating a Partial Backup #

For instructions on creating a Partial Backup, see Backup & Restore.

Restoring a Partial Backup #

Restoring a partial backup is a multi-step process.

Step 1: Restore Options #

Restore Profile #

A restore profile saves the decisions made for each conflict in a partial backup. edgeSuite will use those saved decisions as defaults for subsequent restore iterations, helping to streamline the restore process.

Conflict Strategy #

A conflict represents a pending change to something that already exists on the system. The conflict strategy sets a default behavior for handling conflicts when processing a partial backup.

Overwrite This option will replace existing content on the server with content in the backup.
Ignore This option will keep all existing content on the server as is. It will ignore any duplicates or changes, and only add NEW content that is in the backup.

Restore Suffix #

This suffix is applied to the names of elements when a conflict is detected. It helps with the versioning of content when partial backups are iteratively applied.


Step 2: Conflict Resolution #

If there are no conflicts with content on the system, then the following message will be displayed.

If conflicts are detected, a list of conflicts will be displayed.

For larger partial backups, the compound filter at the bottom of the view can help filter down results to a more manageable list of conflicts. The two button groups assume an AND operator. For example, it allows users to show only “Pages” that have “Conflicts”.

Conflict Strategy #

When restoring a Partial Backup, the server can encounter conflicts. This typically happens when making changes to an existing archive, and then sharing those changes with someone else. When attempting to merge content into an existing system, the IDs of objects in the Partial Backup could conflict with IDs already in the target system. This typically indicates different “versions” of that element. edgeSuite offers an itemized list of these conflicts, and provides options for how to handle them.

Overwrite Keep what is in the backup. Overwrite what is currently on the server with content from the backup.
Ignore Keep what is on the server. Ignore what is in the backup.

Custom icons and Partial Backups #

In partial backups, only icons used in Visualizations are backed up. This means that only custom icons used on the selected page(s) are exported, along with the associated custom.csv file. A Partial Backup will include the entire custom.csv, which can contain references to icons that are not included on the selected pages in the partial backup. This means some icons might not be copied over, and this can result in broken images appearing in the icon chooser. The broken images in the icon chooser will not affect any of the Visualizations.

Step 3: Summary #

The restore summary shows the end result of all the conflict resolution decisions that have been made in the wizard. This is a validation step that summarizes what will be brought into the system prior to performing a restore.

As a safety measure, the system will automatically perform a full backup prior to a restore. These automatic backups can be used to revert back to the system’s state prior to performing the restore. They are available through the “Recovery” tab in the “Backup & Restore” UI. See Backup and Restore for more information.

Advanced Options: Restore Profile #

Partial restore can be somewhat automatically controlled through the use of a Restore Profile. A typical profile for the purpose of migrating development content to a production system might look like this:

{
  "name" "dev-to-prod",
  "restoreType" "ALL",
  "collisionStrategy" "OVERWRITE",
  "useSrcPaths" true,
  "dropUnchangedEntities" false,
  "restoreRules" : [ {
    "archiveMatchString" "ConnectionDO",
    "archiveMatchType" "ENTITY_CLASS",
    "matchAction" "DROP",
    "doClass" "RestoreRuleDO"
  } ],
  "restoreSuffix" "",
  "entityActions" : [ ],
  "doClass" "RestoreProfileDO"
}

The profile above specifies that all Connections in the archive should be ignored in preference to those in the current (production) system. All other entities in the archive will be applied in the normal way (for example Feeds and Transforms, Visualization configuration, and Pages).

The restoreRules field is a list of matching rules that allow you to specify what attribute to match against, a matching pattern, and then a default action to perform for configuration entities that match. The current attributes that can be matched against are:

  • ENTITY_CLASS – match against the Java class implementing the entity. Common classes include:
    • ConnectionDO – all connection types
    • DataFeedDO – all feeds that are not Web Content feeds
    • ProxyFeedDO – Web Content feeds
    • TabularTransformDO
    • RelationalTransformDO
    • DataVisualizationDO
    • SecurityParameterDO – Secured Variables and Credentials
  • ENTITY_TYPE – match against the entity’s type (for example "Web Content Connection" or "Web.*")
  • ENTITY_NAME – match against the admin-specified name of the entity

When importing an entity from an archive, the restore rules are applied in the order they appear in the profile – the first one that matches is used. The matchAction provides a default action to perform for the entity. This can be overridden in the Restore Wizard in the Conflict Resolution step. Supported values for matchAction are:

  • DROP (ignore the entity from the archive)
  • OVERWRITE (use the values of the entity from the archive to replace those of the corresponding existing entity in the system)

Every edgeSuite instance has a Default restore profile, and new restore profiles can be found in [INSTALL_HOME]/exports/profiles/.

Command Line Partial Backup/Restore #

edgeSuite also allows server administrators to create and restore backups via the operating system command line interface.

Create a Partial Backup via Edge CLI (v3.8.5+) #

To create a partial backup via command line using the new Edge CLI, the server must be running. The command is as follows:

bin/es-cli.sh backup [--listpages] [-l] [-p PAGES] [-c] [-f FILENAME] --user username [--pass password]
Option
Description

–listpages

View a list of archivable content pages.
-l Include the log files within the archive.
-p PAGES Specify the folders and pages to be backed up by setting PAGES to be a comma-separated list of folder and page names. If the names contain spaces, PAGES should be wrapped in double quotes. To view a list of archivable pages, run the backup command with the –listpages option.

Note that while all of the folders and pages exist under the Content Menu, “Content Menu/” should not precede any of the given names as it will be automatically prepended by the server.

-c Set the “coerce” flag. This must be included if creating a backup on a non-admin server within a cluster.
-f FILENAME Adding this option and specifying a filename is optional. The default value is “edgeSuite-export-” followed by a timestamp. If setting FILENAME, no extension is needed as it will be added automatically when the backup is created.

See Edge CLI for more information, including instructions for running the new Edge CLI on Windows.

Create a Partial Backup via Legacy Edge CLI #

The backuppage command in the legacy Edge CLI (edge.sh) will be deprecated in edgeSuite 4.0. For now, however, it is still available and can be run as follows:

bin/edge.sh backuppage [-l] -p PAGES -f FILENAME

Note that the resultant backup image will be found in [INSTALL_HOME]/exports/FILENAME. An extension of .esb is automatically added to the name if not specified. Similar to the new Edge CLI, the -l option can be added to include the log files in the backup file. The -p PAGES option is similar to that of the new Edge CLI, however, the legacy Edge CLI requires “Content Menu/” to come before any named pages or folders.

For systems running on Windows, use edge.bat instead.

Restore a Partial Backup via Edge CLI (v3.8.5+) #

To restore a partial backup via command line using the new Edge CLI, the server must be running. The command is as follows:

bin/es-cli.sh restore [--list OPTION] [-p PROFILE] [-c] -f FILENAME --user username [--pass password]
Option
Description
–list OPTION View a list of restorable archives or available restore profiles by setting OPTION to archives or profiles accordingly.
-p PROFILE Set the restore profile name. Default is ‘Default’. Use –list profiles to view a list of available profiles. For more information about restore profiles, refer to Advanced Options: Restore Profile above.
-c Set the “coerce” flag. This must be included if restoring a backup on a non-admin server within a cluster.
-f FILENAME Specify the archive to be restored. The extension must be included. FILENAME can refer either to a named archive within edgeSuite’s exports folder (the archive names can be viewed using –list archives), or to an archive that exists on the same system as edgeSuite (i.e. FILENAME in this case should be a path to the backup file).

FILENAME is required unless running the restore command with –list OPTION.

See Edge CLI for more information, including instructions for running the new Edge CLI on Windows.

Restore a Partial Backup via Legacy Edge CLI #

The restore command in the legacy Edge CLI (edge.sh) will be deprecated in edgeSuite 4.0. For now, however, it is still available and can be run as follows:

bin/edge.sh restore [-o STRATEGY] [-d SUFFIX] [-p PROFILE] -f FILENAME
Option
Description
-o STRATEGY

Set the conflict strategy to either OVERWRITE or DROP. Only takes effect if -p PROFILE is not set.

-d SUFFIX

Set the suffix to append to entity names that conflict. Only takes effect if -p PROFILE is not set.

-p PROFILE

Set the restore profile name. Default is ‘Default’. For more information about restore profiles, refer to Advanced Options: Restore Profile above.

-f FILENAME FILENAME must be the path (relative or absolute) to the backup file that is to be restored.

Note that, for restore purposes, the backup image may exist in any folder on the system.

For systems running on Windows use edge.bat instead.