Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

However, the new AIP Backup & Restore option seeks to try and resolve many of the complexities of a traditional backup and restore. The below table details some of the differences between these two valid Backup and Restore options.


Traditional Backup & Restore (Database and Files)

AIP Backup & Restore

Supported Backup/Restore Types



Can Backup & Restore all DSpace Content easily

Yes (Requires two backups/restores – one for Database and one for Files)

Yes (Though, will not backup/restore items which are not officially "in archive")

Can Backup & Restore a Single Community/Collection/Item easily

No (It is possible, but requires a strong understanding of DSpace database structure & folder organization in order to only backup & restore metadata/files belonging to that single object)

Yes

Backups can be used to move one or more Community/Collection/Items to another DSpace system easily.

No (Again, it is possible, but requires a strong understanding of DSpace database structure & folder organization in order to only move metadata/files belonging to that object)

Yes

Can Backup & Restore Item VersionsYes (Requires two backups/restores – one for Database and one for Files)No (Currently Item Level Versioning is not fully compatible with AIP Backup & Restore. AIP Backup & Restore can only backup/restore the latest version of an Item)

Supported Object Types During Backup & Restore



Supports backup/restore of all Communities/Collections/Items (including metadata, files, logos, etc.)

Yes

Yes

Supports backup/restore of all People/Groups/Permissions

Yes

Yes

Supports backup/restore of all Collection-specific Item Templates

Yes

Yes

Supports backup/restore of all Collection Harvesting settings (only for Collections which pull in all Items via OAI-PMH or OAI-ORE)

Yes

No (This is a known issue. All previously harvested Items will be restored, but the OAI-PMH/OAI-ORE harvesting settings will be lost during the restore process.)

Supports backup/restore of all Withdrawn (but not deleted) Items

Yes

Yes

Supports backup/restore of Item Mappings between Collections

Yes

Yes (During restore, the AIP Ingester may throw a false "Could not find a parent DSpaceObject" error (see 81953672), if it tries to restore an Item Mapping to a Collection that it hasn't yet restored. But this error can be safely bypassed using the 'skipIfParentMissing' flag (see 81953672 for more details).

Supports backup/restore of all in-process, uncompleted Submissions (or those currently in an approval workflow)

Yes

No (AIPs are only generated for objects which are completed and considered "in archive")

Supports backup/restore of Items using custom Metadata Schemas & Fields

Yes

Yes (Custom Metadata Fields will be automatically recreated. Custom Metadata Schemas must be manually created first, in order for DSpace to be able to recreate custom fields belonging to that schema. See 81953672 for more details.)

Supports backup/restore of all local DSpace Configurations and Customizations

Yes (if you backup your entire DSpace directory as part of backing up your files)

Not by default (unless you also backup parts of your DSpace directory – note, you wouldn't need to backup the '[dspace]/assetstore' folder again, as those files are already included in AIPs)

Based on your local institutions needs, you will want to choose the backup & restore process which is most appropriate to you. You may also find it beneficial to use both types of backups on different time schedules, in order to keep to a minimum the likelihood of losing your DSpace installation settings or its contents. For example, you may choose to perform a Traditional Backup once per week (to backup your local system configurations and customizations) and an AIP Backup on a daily basis. Alternatively, you may choose to perform daily Traditional Backups and only use the AIP Backup as a "permanent archives" option (perhaps performed on a weekly or monthly basis).

...

Again, this would export the DSpace Site AIP into the file "sitewide-aip.zip", and export AIPs for all Communities, Collections and Items into the same directory as the Site AIP.

The XML file in sitewide-aip.zip contains information about repository users, groups and top level communities.

Ingesting / Restoring AIPs

...

The following flags are valid to pass to the [dspace]/bin/dspace packager command:

FlagIngest or ExportDescription / Usage
-a (--all)both ingest and export

For Ingest: recursively ingest all child AIPs (referenced from this AIP).

For Export: recursively export all child objects (referenced from this parent object)

-d (--disseminate)export-onlyThis flag simply triggers the export of AIPs from the system. See 81953672
-e (–eperson) [email-address]ingest-onlyThe email address of the EPerson who is ingesting the AIPs. Oftentimes this should be an Administrative account.
-f (--force-replace)ingest-onlyIngest the AIPs in "81953672" (must be specified in conjunction with -r flag), where existing objects will be replaced by the contents of the AIP.
-h (--help)both ingest and exportReturn help information. You should specify with -t for additional package specific help information
-i (--identifier) [handle]both ingest and export

For Ingest: Only valid in "81953672". In that mode this is the identifier of the object to replace.

For Export: The identifier of the object to export to an AIP

-k (--keep-existing)ingest-onlySpecifies to use "81953672" during ingest (must be specified in conjunction with -r flag). In this mode, existing objects in DSpace will NOT be replaced by their AIPs, but missing objects will be restored from AIPs.
-o (--option) [setting]=[value]both ingest and exportThis flag is used to pass 81953672 to the Packager command. Each type of packager may define its own custom Additional Options. For AIPs, the valid options are documented in the 81953672 section below. This is repeatable (e.g. -o [setting1]=[value] -o [setting2]=value)
-p (--parent) [handle]ingest onlyHandle(s) of the parent Community or Collection to into which an AIP should be ingested. This may be repeatable.
-r (--restore)ingest onlySpecifies that this ingest is either "Restore Mode" (when standalone), "81953672" (when used with -k flag) or "81953672" (when used with -f flag)
-s (--submit)ingest onlySpecifies that this ingest is in "Submit Mode" where an AIP is treated as a new object and assigned a new Handle/Identifier, etc.
-t (--type) [package-type]both ingest and exportSpecifies the type of package which is being ingested or exported. This controls which Ingester or Disseminator class is called. For AIPs, this is always set to "-t AIP"
-u (--no-user-interaction)both ingest and exportSkips over all user interaction (e.g. question prompts). This flag can be used when running the packager from a script or cron job to bypass all user interaction. See also 81953672


Additional Packager Options

In additional to the various "modes" settings described under "81953672" above, the AIP Packager supports the following packager options. These options allow you to better tweak how your AIPs are processed (especially during ingests/restores/replaces).

Option

Ingest or Export

Default Value

Description

createMetadataFields=[value]

ingest-only

true

Tells the AIP ingester to automatically create any metadata fields which are found to be missing from the DSpace Metadata Registry. When 'true', this means as each AIP is ingested, new fields may be added to the DSpace Metadata Registry if they don't already exist. When 'false', an AIP ingest will fail if it encounters a metadata field that doesn't exist in the DSpace Metadata Registry. (NOTE: This will not create missing DSpace Metadata Schemas. If a schema is found to be missing, the ingest will always fail.)

filterBundles=[value]

export-only

defaults to exporting all Bundles

This option can be used to limit the Bundles which are exported to AIPs for each DSpace Item. By default, all file Bundles will be exported into Item AIPs. You could use this option to limit the size of AIPs by only exporting certain Bundles. WARNING: any bundles not included in AIPs will obviously be unable to be restored. This option can be run in two ways:

  • Exclude Bundles: By default, you can provide a comma-separated list of bundles to be excluded from AIPs (e.g. "TEXT, THUMBNAIL")
  • Include Bundles: If you prepend the list with the "+" symbol, then the list specifies the bundles to be included in AIPs (e.g. "+ORIGINAL,LICENSE" would only include those two bundles). This second option is identical to using "includeBundles" option described below.

    (NOTE: If you choose to no longer export LICENSE or CC_LICENSE bundles, you will also need to disable the License Dissemination Crosswalks in the aip.disseminate.rightsMD configuration for the changes to take affect)

ignoreHandle=[value]

ingest-only

Restore/Replace Mode defaults to 'false',
Submit Mode defaults to 'true'

If 'true', the AIP ingester will ignore any Handle specified in the AIP itself, and instead create a new Handle during the ingest process (this is the default when running in Submit mode, using the -s flag). If 'false', the AIP ingester attempts to restore the Handles specified in the AIP (this is the default when running in Restore/replace mode, using the -r flag).

ignoreParent=[value]

ingest-only

Restore/Replace Mode defaults to 'false',
Submit Mode defaults to 'true'

If 'true', the AIP ingester will ignore any Parent object specified in the AIP itself, and instead ingest under a new Parent object (this is the default when running in Submit mode, using the -s flag). The new Parent object must be specified via the -p flag (run dspace packager -h for more help). If 'false', the AIP ingester attempts to restore the object directly under its old Parent (this is the default when running in Restore/replace mode, using the -r flag).

includeBundles=[value]

export-only

defaults to "all"

This option can be used to limit the Bundles which are exported to AIPs for each DSpace Item. By default, all file Bundles will be exported into Item AIPs. You could use this option to limit the size of AIPs by only exporting certain Bundles. WARNING: any bundles not included in AIPs will obviously be unable to be restored. This option expects a comma separated list of bundle names (e.g. "ORIGINAL,LICENSE,CC_LICENSE,METADATA"), or "all" if all bundles should be included.

(See "filterBundles" option above if you wish to exclude particular Bundles. However, this "includeBundles" option cannot be used at the same time as "filterBundles".)

(NOTE: If you choose to no longer export LICENSE or CC_LICENSE bundles, you will also need to disable the License Dissemination Crosswalks in the aip.disseminate.rightsMD configuration for the changes to take affect)

manifestOnly=[value]

both ingest and export

false

If 'true', the AIP Disseminator will only import/export a METS Manifest XML file (i.e. result will be an unzipped 'mets.xml' file), instead of a full AIP. This METS Manifest contains URI references to all content files, but does not contain any content files. This option is experimental and is meant for debugging purposes only. It should never be set to 'true' if you want to be able to restore content files. Again, please note that when you use this option, the final result will be an XML file, NOT the normal ZIP-based AIP format.

passwords=[value]

export-only

false

If 'true' (and the 'DSPACE-ROLES' crosswalk is enabled, see #AIP Metadata Dissemination Configurations), then the AIP Disseminator will export user password hashes (i.e. encrypted passwords) into Site AIP's METS Manifest. This would allow you to restore user's passwords from Site AIP. If 'false', then user password hashes are not stored in Site AIP, and passwords cannot be restored at a later time.

skipIfParentMissing=[value]

ingest-only

false

If 'true', ingestion will skip over any "Could not find a parent DSpaceObject" errors that are encountered during the ingestion process (Note: those errors will still be logged as "warning" messages in your DSpace log file). If you are performing a full site restore (or a restore of a larger Community/Collection hierarchy), you may encounter these errors if you have a larger number of Item mappings between Collections (i.e. Items which are mapped into several collections at once). When you are performing a recursive ingest, skipping these errors should not cause any problems. Once the missing parent object is ingested it will automatically restore the Item mapping that caused the error. For more information on this "Could not find a parent DSpaceObject" error see 81953672.

unauthorized=[value]

export-only

unspecified

If 'skip', the AIP Disseminator will skip over any unauthorized Bundle or Bitstream encountered (i.e. it will not be added to the AIP). If 'zero', the AIP Disseminator will add a Zero-length "placeholder" file to the AIP when it encounters an unauthorized Bitstream. If unspecified (the default value), the AIP Disseminator will throw an error if an unauthorized Bundle or Bitstream is encountered.

updatedAfter=[value]

export-only

unspecified

This option works as a basic form of "incremental backup". This option requires that an ISO-8601 date is specified. When specified, the AIP Disseminator will only export Item AIPs which have a last-modified date after the specified ISO-8601 date. This option has no affect on the export of Site, Community or Collection AIPs as DSpace does not record a last-modified date for Sites, Communities or Collections. For example, when this option is specified during a full-site export, the AIP Disseminator will export the Site AIP, all Community AIPs, all Collection AIPs, and only Item AIPs modified after that date and time.

validate=[value]

both ingest and export

Export defaults to 'true',
Ingest defaults to 'false'

If 'true', every METS file in AIP will be validated before ingesting or exporting. By default, DSpace will validate everything on export, but will skip validation during import. Validation on export will ensure that all exported AIPs properly conform to the METS profile (and will throw errors if any do not). Validation on import will ensure every METS file in every AIP is first validated before importing into DSpace (this will cause the ingestion processing to take longer, but tips on speeding it up can be found in the "81953672" section below). DSpace recommends minimally validating AIPs on export. Ideally, you should validate both on export and import, but import validation is disabled by default in order to increase the speed of AIP restores.

How to use additional options

...

The below table lists common fixes to issues you may encounter when backing up or restoring objects using AIP Backup and Restore.

Issue / Error Message

How to Fix this Problem

Ingest/Restore Error: "Group Administrator already exists"

If you receive this problem, you are likely attempting to Restore an Entire Site, but are not running the command in Force Replace Mode (-r -f). Please see the section on Restoring an Entire Site for more details on the flags you should be using.

Ingest/Restore Error: "Unknown Metadata Schema encountered (mycustomschema)"

If you receive this problem, one or more of your Items is using a custom metadata schema which DSpace is currently not aware of (in the example, the schema is named "mycustomschema"). Because DSpace AIPs do not contain enough details to recreate the missing Metadata Schema, you must create it manually via the DSpace Admin UI. Please note that you only need to create the Schema. You do not need to manually create all the fields belonging to that schema, as DSpace will do that for you as it restores each AIP. Once the schema is created in DSpace, re-run your restore command. DSpace will automatically re-create all fields belonging to that custom metadata schema as it restores each Item that uses that schema.

Ingest Error: "Could not find a parent DSpaceObject referenced as 'xxx/xxx'"

When you encounter this error message it means that an object could not be ingested/restored as it belongs to a parent object which doesn't currently exist in your DSpace instance. During a full restore process, this error can be skipped over and treated as a warning by specifying the '-o skipIfParentMissing=true' option (see 81953672). If you have a larger number of Items which are mapped to multiple Collections, the AIP Ingester will sometimes attempt to restore an item mapping before the Collection itself has been restored (thus throwing this error). Luckily, this is not anything to be concerned about. As soon as the Collection is restored, the Item Mapping which caused the error will also be automatically restored. So, if you encounter this error during a full restore, it is safe to bypass this error message using the '-o skipIfParentMissing=true' option. All your Item Mappings should still be restored correctly.

Submit Error: PSQLException: ERROR: duplicate key value violates unique constraint "handle_handle_key"

This error means that while submitting one or more AIPs, DSpace encountered a Handle conflict. This is a general error the may occur in DSpace if your Handle sequence has somehow become out-of-date. However, it's easy to fix. Just run the [dspace]/etc/postgres/update-sequences.sql script (or if you are using Oracle, run: [dspace]/etc/oracle/update-sequences.sql).