Page History
AIP Backup & Restore for DSpace
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
...
| 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 | |
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 DSDOCDEV:Common Issues or Error Messages), 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 DSDOCDEV:Additional Packager Options 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 DSDOCDEV:Common Issues or Error Messages for more details.) <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0266f747-2ea2-48da-991b-f1b8cd588cd2"><ac:plain-text-body><![CDATA[ | |
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 your also backup parts of your DSpace directory – note, you wouldn't need to backup the '[DSDOCDEV:dspace]/assetstore' folder again, as those files are already included in AIPs) | ]]></ac:plain-text-body></ac:structured-macro> |
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).
Note | ||
---|---|---|
| ||
If you choose to use the AIP Backup and Restore option, do not forget to also backup your local DSpace configurations and customizations. Depending on how you manage your own local DSpace, these configurations and customizations are likely in one or more of the following locations: unmigrated-wiki-markup
|
How does this work help DSpace interact with DuraCloud?
...
There are two types of AIP Dissemination you can perform:
- DSDOCDEV:Single AIP (default, using
-d
option) - Exports just an AIP describing a single DSpace object. So, if you ran it in this default mode for a Collection, you'd just end up with a single Collection AIP (which would not include AIPs for all its child Items) - DSDOCDEV:Hierarchy of AIPs (using the
-d --all
or-d -a
option) - Exports the requested AIP describing an object, plus the AIP for all child objects. Some examples follow:- For a Site - this would export all Communities, Collections & Items within the site into AIP files (in a provided directory)
- For a Community - this would export that Community and all SubCommunities, Collections and Items into AIP files (in a provided directory)
- For a Collection - this would export that Collection and all contained Items into AIP files (in a provided directory)
- For an Item – this just exports the Item into an AIP as normal (as it already contains its Bitstreams/Bundles by default)
...
Ingestion of AIPs is a bit more complex than Dissemination, as there are several different "modes" available:
- DSDOCDEV:Submit/Ingest Mode (
-s
option, default) – submit AIP(s) to DSpace in order to create a new object(s) (i.e. AIP is treated like a SIP – Submission Information Package) - DSDOCDEV:Restore Mode (
-r
option) – restore pre-existing object(s) in DSpace based on AIP(s). This also attempts to restore all handles and relationships (parent/child objects). This is a specialized type of "submit", where the object is created with a known Handle and known relationships. - DSDOCDEV:Replace Mode (
-r -f
option) – replace existing object(s) in DSpace based on AIP(s). This also attempts to restore all handles and relationships (parent/child objects). This is a specialized type of "restore" where the contents of existing object(s) is replaced by the contents in the AIP(s). By default, if a normal "restore" finds the object already exists, it will back out (i.e. rollback all changes) and report which object already exists.
...
It's worth understanding the primary differences between a Submission (specified by -s
parameter) and a Restore (specified by -r
parameter).
- DSDOCDEV:Submission Mode (
-s
mode) - creates a new object (AIP is treated like a SIP)- By default, a new Handle is always assigned
- However, you can force it to use the handle specified in the AIP by specifying
-o ignoreHandle=false
as one of your parameters
- However, you can force it to use the handle specified in the AIP by specifying
- By default, a new Parent object must be specified (using the
-p
parameter). This is the location where the new object will be created.- However, you can force it to use the parent object specified in the AIP by specifying
-o ignoreParent=false
as one of your parameters
- However, you can force it to use the parent object specified in the AIP by specifying
- By default, will respect a Collection's Workflow process when you submit an Item to a Collection
- However, you can specifically skip any workflow approval processes by specifying
-w
parameter.
- However, you can specifically skip any workflow approval processes by specifying
- Always adds a new Deposit License to Items
- Always adds new DSpace System metadata to Items (includes new 'dc.date.accessioned', 'dc.date.available', 'dc.date.issued' and 'dc.description.provenance' entries)
- By default, a new Handle is always assigned
- DSDOCDEV:Restore / Replace Mode (
-r
mode) - restores a previously existing object (as if from a backup)- By default, the Handle specified in the AIP is restored
- However, for restores, you can force a new handle to be generated by specifying
-o ignoreHandle=true
as one of your parameters. (NOTE: Doesn't work for replace mode as the new object always retains the handle of the replaced object) Although a Restore/Replace does restore Handles, it will not necessarily restore the same internal IDs in your Database.
- However, for restores, you can force a new handle to be generated by specifying
- By default, the object is restored under the Parent specified in the AIP
- However, for restores, you can force it to restore under a different parent object by using the
-p
parameter. (NOTE: Doesn't work for replace mode, as the new object always retains the parent of the replaced object)
- However, for restores, you can force it to restore under a different parent object by using the
- Always skips any Collection workflow approval processes when restoring/replacing an Item in a Collection
- Never adds a new Deposit License to Items (rather it restores the previous deposit license, as long as it is stored in the AIP)
- Never adds new DSpace System metadata to Items (rather it just restores the metadata as specified in the AIP)
- By default, the Handle specified in the AIP is restored
...
The Submission mode (-s
) always creates a new object with a newly assigned handle. In addition by default it respects all existing Collection approval workflows (so items may require approval unless the workflow is skipped by using the -w
option). For information about how the "Submission Mode" differs from the "Replace / Restore mode", see DSDOCDEV:The difference between "Submit" and "Restore/Replace" modes above.
...
Warning | ||
---|---|---|
| ||
Please note: If you are submitting a larger amount of content (e.g. multiple Communities/Collections) to your DSpace, you may want to tell the 'packager' command to skip over any existing Collection approval workflows by using the
|
Submitting AIP(s) while skipping any Collection Approval Workflows
Warning | ||
---|---|---|
| ||
Please note, if you are using AIPs to move an entire Community or Collection from one DSpace to another, there is a known issue (see DS-1105) that the new DSpace instance will be unable to (re-)create any DSpace Groups or EPeople which are referenced by a Community or Collection AIP. The reason is that the Community or Collection AIP itself doesn't contain enough information to create those Groups or EPeople (rather that info is stored in the SITE AIP, for usage during Full Site Restores).
|
Submitting AIP(s) while skipping any Collection Approval Workflows
By default, the Submission mode (-s
) By default, the Submission mode (-s
) always respects existing Colleciton approval workflows. So, if a Collection has a workflow, then a newly submitted Item will be placed into that workflow process (rather than immediately appearing in DSpace).
...
This -w
flag may also be used when DSDOCDEV:Submitting an AIP Hierarchy. For example, if you are migrating one or more Collections/Communities from one DSpace to another, you may choose to submit those AIPs with the -w
option enabled. This will ensure that, if a Collection has a workflow approval process enabled, all its Items are available immediately rather than being all placed into the workflow approval process.
...
Restoring is slightly different than just submitting. When restoring, we make every attempt to restore the object as it used to be (including its handle, parent object, etc.). For more information about how the "Replace/Restore Mode" differs from the "Submit mode", see DSDOCDEV:The difference between "Submit" and "Restore/Replace" modes above.
There are currently three restore modes:
- DSDOCDEV:Default Restore Mode (
-r
) = Attempt to restore object (and optionally children). Rollback all changes if any object is found to already exist. - DSDOCDEV:Restore, Keep Existing Mode (
-r -k
) = Attempt to restore object (and optionally children). If an object is found to already exist, skip over it (and all children objects), and continue to restore all other non-existing objects. - DSDOCDEV:Force Replace Mode (
-r -f
) = Restore an object (and optionally children) and overwrite any existing objects in DSpace. Therefore, if an object is found to already exist in DSpace, its contents are replaced by the contents of the AIP. WARNING: This mode is potentially dangerous as it will permanently destroy any object contents that do not currently exist in the AIP. You may want to perform a secondary backup, unless you are sure you know what you are doing!
...
Note | ||||
---|---|---|---|---|
| unmigrated-wiki-markup||||
In some cases, when you restore a large amount of content to your DSpace, the internal database counts (called "sequences") may get out of sync with the Handles of the content you just restored. As a best practice, it is *highly recommended to always* re-run the "update-sequences.sql" script on your DSpace database after a larger scale restore. This database script can be run while the system is online (i.e. no need to stop Tomcat or PostgreSQL). The script can be found in the following locations for PostgreSQL and Oracle, respectively:
{{\ |
Info | ||
---|---|---|
| ||
|
...
When the "Force Replace" flag (-f
option) is specified, the restore will overwrite any objects found to already exist in DSpace. In other words, existing content is deleted and then replaced by the contents of the AIP(s).
Info | ||
---|---|---|
| ||
This mode may also be used to restore missing objects which refer to existing objects. For example, if you are restoring a missing Collection which had existing Items linked to it, you can use this mode to auto-restore the Collection and update those existing Items so that they again link back to the newly restored Collection. |
Warning | ||
---|---|---|
| ||
Because this mode actually destroys existing content in DSpace, it is potentially dangerous and may result in data loss! You may wish to perform a secondary full backup (assetstore files & database) before attempting to replace any existing object(s) in DSpace. |
...
- Notice that you are running this command in "Force Replace" mode (
-r -f
). This is necessary as your empty DSpace install will already include a few default groups (Administrators and Anonymous) and your initial administrative user. You need to replace these groups in order to restore your prior DSpace contents completely. <eperson>
should be replaced with the Email Address of the initial Administrator (who you created when you reinstalled DSpace).<site-handle-prefix>
should be replaced with your DSpace site's assigned Handle Prefix. This is equivalent to thehandle.prefix
setting in yourdspace.cfg
/full/path/to/your/site-aip.zip
is the full path to the AIP file which represents your DSpace SITE. This file will be named whatever you named it when you actually DSDOCDEV:exported your entire site. All other AIPs are assumed to be referenced from this SITE AIP (in most cases, they should be in the same directory as that SITE AIP).
Note | ||
---|---|---|
| ||
|
Additional Packager Options
...
Option | Ingest or Export | Default Value | Description |
---|---|---|---|
| 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.) |
| 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:
|
| ingest-only | Restore/Replace Mode defaults to 'false', | 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 |
| ingest-only | Restore/Replace Mode defaults to 'false', | 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 |
| 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. |
| both | false | If 'true', the AIP Disseminator will export an AIP which only consists of the METS Manifest file (i.e. result will be a single 'mets.xml' file). This METS Manifest contains URI references to all content files, but does not contain any content files. This option is experimental, and should never be set to 'true' if you want to be able to restore content files. |
| 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. |
| import-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 DSDOCDEV:Common Issues or Error Messages. |
| 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. |
| 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. |
| both | Export defaults to 'true', | 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 "AIP Configurations To Improve Ingestion Speed while Validating" 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. |
...
The following configurations allow you to specify what metadata is stored within each METS-based AIP. In 'dspace.cfg', the general format for each of these settings is:
{{Wiki Markup aip.disseminate.<setting>
=
<mdType>:<DSpace-crosswalk-name>
\[
DSDOCDEV:,
...
\]
}}- <setting> is the setting name (see below for the full list of valid settings)
- <mdType> is optional. It allows you to specify the value of the @MDTYPE or @OTHERMDTYPE attribute in the corresponding METS element.
- <DSpace-crosswalk-name> is required. It specifies the name of the DSpace Crosswalk which should be used to generate this metadata.
- Zero or more
<label-for-METS>:<DSpace-crosswalk-name>
may be specified for each setting
...
mets.xsd.<abbreviation> = <namespace> <local-file-name>
<abbreviation>
is a unique abbreviation (of your choice) for this schema<namespace>
is the Schema namespaceunmigrated-wiki-markup- {{
<local-file-name>
}} the full name of the cached schema file (which should reside in your {{\[
DSDOCDEV:dspace
\]/config/schemas/
}} directory, by default this directory does not exist -- – you will need to create it)
...
The default settings are all commented out. But, they provide a full listing of all schemas currently used during validation of AIPs. In order to utilize them, uncomment the settings, download the appropriate schema file, and save it to your {{\[
DSDOCDEV:dspace
\]/config/schemas/
}} directory (by default this directory does not exist -- – you will need to create it) using the specified file name:
Code Block |
---|
#mets.xsd.mets = http://www.loc.gov/METS/ mets.xsd #mets.xsd.xlink = http://www.w3.org/1999/xlink xlink.xsd #mets.xsd.mods = http://www.loc.gov/mods/v3 mods.xsd #mets.xsd.xml = http://www.w3.org/XML/1998/namespace xml.xsd #mets.xsd.dc = http://purl.org/dc/elements/1.1/ dc.xsd #mets.xsd.dcterms = http://purl.org/dc/terms/ dcterms.xsd #mets.xsd.premis = http://www.loc.gov/standards/premis PREMIS.xsd #mets.xsd.premisObject = http://www.loc.gov/standards/premis PREMIS-Object.xsd #mets.xsd.premisEvent = http://www.loc.gov/standards/premis PREMIS-Event.xsd #mets.xsd.premisAgent = http://www.loc.gov/standards/premis PREMIS-Agent.xsd #mets.xsd.premisRights = http://www.loc.gov/standards/premis PREMIS-Rights.xsd |
...
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 DSDOCDEV:Restore an Entire Site, but are not running the command in Force Replace Mode ( |
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 'skipIfParentMissing=true' option (see DSDOCDEV:Additional Packager Options). 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 'skipIfParentMissing=true' option. All your Item Mappings should still be restored correctly.<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="aa3bbad7-337c-43f7-8404-9c5e887c41f9"><ac:plain-text-body><![CDATA[ |
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 |