Restoring Data

Attention: Up to CMS Fiona 6.7.3, with productively used systems, data must not be restored from partial dumps since this might result in data loss.

Only start the restore process if you have ensured that no write access to the data takes place while restoring. Otherwise the existing or restored data will become incomplete or corrupted. Make sure that the CM is not running as a server and that no other CMs are running or started in single mode while data is being restored.

Please observe the following when dumping and restoring mirror files: The dump needs to include the original files of the mirror files, and these originals must be restorable along with their mirror files.

In order to restore your data, please proceed as follows:

  • Log on to the operating system as NPS administrator. The NPS administrator is the user whose login was specified for this purpose during the installation.

  • Stop the Content Management Server.

  • Change to the bin directory of the instance concerned and execute the following command in a shell.

    CM -restore dumpDir  targetPub \
      [{entity ident}| file deffile] \
      [-batch [{(entity | all) conflictStrategy}]]

Please specify as dumpDir the directory to which the data was dumped. A relative path refers to the current directory.

If the optional parts of the command line are completely omitted, the Content Manager assumes that all data contained in the dump is to be restored.

The targetPub parameter is required to specify a target CMS folder for the files to be restored.

Specify as entity one of the keywords object, objectTree, attribute, workflow, or objClass.

If object or objectTree is specified as entity, provide a file ID or a file path as ident. For all other entities provide their respective name.

Using the option file deffile, the entities to be restored can be provided by means of a definition file (deffile) instead of entering them on the command line. In such a definition file, every line consists of an entity type, followed by an ident which is the name (or path or ID for CMS files) of the respective entity. Comments can be placed on separate lines beginning with a hash mark (#).

By means of the -batch option, interactive conflict handling (see below) can be switched off. If -batch has been specified, one of the following conflict handling strategies can be specified for each entity type:

  • w = Always overwrite
  • a = Always restore under an automatically generated name
  • k = Always skip the entity

You can use all for entity to set the strategy for all entity types. The default conflict handling strategy is w (always overwrite). However, in CMS Fiona 6.0.0 and later, a CMS file contained in a partial dump is never restored if the file already exists in the target system, independently of the chosen conflict handling strategy.

As with a full restoration process, an interrupted partial restoration can be continued using the resume option:

CM -restore dumpDir resume

Example: The following command restores the data from the dump located in the myDir directory to the destination folder with the ID 4812. The complete folder hierarchies /de and 12345 as well as the file format newsdoc are to be restored:

CM -restore myDir 4812 objectTree /en objectTree 12345 objClass newsdoc

Conflict Handling

When a complete dump is restored, the original file IDs are preserved. This is not the case when data from a partial dump is restored. This would lead to conflicts if files with these IDs already exist. Therefore, files are created using the next available ID.

However, name conflicts can still occur, if files contained in partial dumps already exist under the same name in the destination folder. In this case an error message is displayed and the restoration process is aborted. If entities of the other types (fields and workflows, for example) already exist, the conflict is handled, meaning that you can decide how to proceed.

If the interactive conflict handling has not been switched off using -batch, all conflicts must be solved interactively. If an entity already exists, the Content Manager will offer the following options in the case of a conflict:

  • o = Overwrite (replaces the existing entity with the saved one).
  • w = Always overwrite (like o, but also for all other entities of the same type).
  • r = Rename (restore the entity under a different name which is to be specified by the user).
  • a = Always rename (like r, but using automatically generated new names for the other entities of the same type).
  • s = Skip (the entity is not restored).
  • k = Always skip (like s, but also for all other entities of the same type).

Mirror File Handling

From CMS Fiona 6.8.0, the partial dump/restore procedure also restores mirror files. As with other entities, restoring mirror files can lead to situations that require special treatment, e.g. if a dump contains mirror files but not their original files. In interactive mode (if -batch has not been specified) the user is asked how to proceed if such a situation occurs. In batch mode, on the other hand, the desired behavior of the Content Management Server can be defined in advance using up to two more keywords for entity:

  • unrestorableMirrors: If mirror files cannot be restored at all (because mirror files of the target folder exist), the restoration process can be terminated by specifying q as the conflict handling strategy (this is the default behavior). If, instead, k has been specified, the process is continued without restoring mirror files.

  • replaceOriginal: If the original of a mirror file is not contained in the dump but is present in the target system under the known path, strategy a restores the mirror file using the existing original file. Strategy k (the default) causes such mirror files to be skipped instead.

Thus, in batch mode, the restoration process is terminated if the dump contains mirror files, and if mirror files cannot be restored in principle. However, if mirror files are restorable, they are still not restored if their originals are missing from the dump. This is the default behavior.

In the following example, mirror files whose originals are not contained in the dump will nevertheless be restored if their originals are present in the target system. Otherwise, if the originals are neither contained in the dump nor in the target system, they will be omitted.

CM -restore sourceDir /target/folder -batch replaceOriginal a 

Listing the Contents of a Partial Dump

The data that can be restored from a partial dump can comfortably be listed using the -listDump option:

CM -listDump dumpDir [entity]

dumpDir refers to the directory containing the dumped data. By specifying the entity type entity, the output can be restricted to the files of this type. Example:

CM -listDump dumpDir object

Additional Technical Information

The Content Manager saves the current state of the dumping procedure to the file dumpstate.xml in the respective dump directory.

In case the restoration process is interrupted, the Content Manager saves the current state of the process in the file restorestate.xml in the tmp directory below the instance directory as well as in the database. Only one unfinished restoration process can exist for each instance.