Importing items from command line

Command(s)

The import command uses Simple Archive Format (SAF) and is registered as a DSpace script (bin/dspace import). The command syntax in v7 is unchanged from earlier versions.

bin/dspace import -a -e USER_EMAIL -c COLLECTION_HANDLE -s /path/to/import -m /path/to/mapfile

• -a / --add — add items to DSpace
• -e / --eperson — email of the eperson performing the import (required)
• -c / --collection — destination collection Handle or database ID
• -s / --source — directory with SAF structure (see below)
• -m / --mapfile — output mapfile that will be created (required)

Other useful flags: -r (replace), -d (delete), -z (import from zip file), -w (send through workflow), -v (validate / test run without importing).

Docker deployments

When running inside a Docker-based deployment, execute the command inside the dspace container:

docker compose exec dspace /dspace/bin/dspace import -a -e USER_EMAIL -c COLLECTION_HANDLE -s /path/to/import -m /path/to/mapfile

Directory structure

The import directory uses Simple Archive Format (SAF), which is fully supported in DSpace v7. Create the structure by hand or explore the SAF Packager tool.

$ ls -R /path/to/import/
/path/to/import/:
1

/path/to/import/1:
contents         license.txt  metadata_local.xml
dublin_core.xml  Makefile     moses.ini

The format for dublin_core.xml and other schemas is the same, only difference is in the file name. For any other schema then dc you create metadata_SCHEMA.xml file. So if you are filling in the "local" SCHEMA you create metadata_local.xml.

head dublin_core.xml
<dublin_core>
   <dcvalue element="date" qualifier="issued">2014-11</dcvalue>
   <dcvalue element="language" qualifier="iso">eng</dcvalue>
   <dcvalue element="language">English</dcvalue>

head metadata_local.xml 
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<dublin_core schema="local">
  <dcvalue element="has" qualifier="files" language="*">yes</dcvalue>
  <dcvalue element="branding" qualifier="none" language="">LRT&#x20;+&#x20;Open&#x20;Submissions</dcvalue>

Required metadata

• for licensing to work put dc.rights.uri, dc.rights and dc.rights.label in your dublin_core.xml
  • these should match license uri, license name and license label of a defined license
• you'll want dc.title and dc.type

CLARIN bulk import REST API

For programmatic imports, CLARIN-DSpace v7 also provides a REST API at /api/clarin/import/*. This API exposes endpoints for importing items, workspace items, workflow items, bitstreams, licenses, handles, and other entities. See the ClarinItemImportController source for available endpoints.

Real-world examples:

• dspace-migrate — a CLARIN-developed Python tool for bulk migration and import using the CLARIN-DSpace REST API. It demonstrates how to programmatically drive the /api/clarin/import/* endpoints to migrate entire collections between repositories.
• lindat-repository-imports — an example project that uses the Simple Archive Format (SAF) for batch importing items into LINDAT/CLARIN repositories. It provides scripts and SAF-structured data as a reference for large-scale ingest workflows.
• NFA Imports - describes steps needed to import NFA(Národní Filmový Archiv) collection, by using lindat-repository-imports project.