Bulk import (SAF)

When you need to load many items at once — like the 50-thesis pilot — you don't enter them one by one. You build a Simple Archive Format (SAF) package and import it with the dspace command-line tool.

What SAF is

SAF is DSpace's bulk-import layout: a source folder containing one sub-folder per item. Each item folder holds its files plus small sidecar files that describe it:

saf-batch/                     ← the --source folder you point the import at
├── item_001/
│   ├── dublin_core.xml        ← the item's standard metadata (title, author, date …)
│   ├── metadata_local.xml     ← optional: the local.* fields (local.college, local.identifier.ark …)
│   ├── contents               ← lists the files to ingest, one per line
│   └── thesis.pdf             ← the actual file(s)
├── item_002/
│   ├── dublin_core.xml
│   ├── contents
│   └── thesis.pdf
└── …

A minimal dublin_core.xml looks like this:

<dublin_core>
  <dcvalue element="title">A Study of Coastal Erosion in Awdal</dcvalue>
  <dcvalue element="contributor" qualifier="author">Ahmed, Fadumo</dcvalue>
  <dcvalue element="date" qualifier="issued">2025</dcvalue>
  <dcvalue element="type">Thesis</dcvalue>
  <dcvalue element="language" qualifier="iso">en</dcvalue>
</dublin_core>

The contents file simply names each bitstream:

thesis.pdf

Two things SAF must get right for AU-IR

• Set dc.language.iso = en per item explicitly — don't rely on the XOAI fallback. This is required for BASE harvest conformance.
• The DOI and ARK share one suffix, so the ARK back-fill must complete before any DOI is deposited. See Identifiers (DOI & ARK).

The import process

1. Build the package. Produce one folder per item (files + dublin_core.xml + contents) under a single source directory. The Part 22 SAF builder tooling generates these from a PDF + a metadata source.

2. Validate first (dry run). The -v / --validate flag does a test run — it parses everything and reports problems without importing anything:

   docker exec au-ir-backend /dspace/bin/dspace import \
     --add --validate \
     --eperson admin@amoud.edu.so \
     --collection <collection-handle-or-uuid> \
     --source /tmp/saf-batch \
     --mapfile /tmp/saf-batch.map
   

3. Import for real. Drop --validate. Keep --mapfile — it records the UUID of every item created, which is what lets you undo the batch later:

   docker exec au-ir-backend /dspace/bin/dspace import \
     --add \
     --eperson admin@amoud.edu.so \
     --collection <collection-handle-or-uuid> \
     --source /tmp/saf-batch \
     --mapfile /tmp/saf-batch.map
   

   Add --workflow to send each item through the collection's review queue instead of installing it straight to the archive — use this when the RIC should approve the batch. Without it, items are archived immediately (and become eligible for DOI minting on the next cron run).

4. Back-fill ARKs. ARKs are not written on import unless an explicit ARK is in the metadata. Run the finalisation step — scripts/mint-arks.sh — which mints an ARK on every archived item that lacks one (idempotent; supports DRY_RUN=1).

5. Verify (see below).

Flag	Meaning
-a, --add	Add new items.
-c, --collection	Target collection (Handle or UUID).
-e, --eperson	The admin performing the import.
-s, --source	The SAF source directory.
-m, --mapfile	Records created item UUIDs — keep it; it enables rollback.
-v, --validate	Test run; imports nothing.
-w, --workflow	Route items through the collection's review workflow.
-x, --exclude-bitstreams	Metadata only, no files.

Undo a batch (rollback)

Because the import wrote every new item's UUID to the mapfile, you can remove the whole batch in one command — essential after a test import:

docker exec au-ir-backend /dspace/bin/dspace import \
  --delete \
  --eperson admin@amoud.edu.so \
  --mapfile /tmp/saf-batch.map

Post-load verification

After import, confirm:

• the item count matches what you loaded,
• all ARKs are populated and resolve (302 redirect),
• the items appear in OAI ListRecords,
• Discovery facets render and the PDFs display inline.

Identifier safety during a bulk load

Protect Crossref from test data

DOIs are minted automatically and are permanent. For a test or dry-run import, pause the Crossref pipeline cron on the server first, and delete the test items before re-enabling it (use the --delete rollback above) so nothing reaches Crossref. The ARK is local and recoverable; the DOI is the irreversible one. See Identifiers (DOI & ARK).

Who owns the pilot

The 50-thesis pilot is owned by the RIC: RIC uploads and approves; ICT provides the SAF tooling and runs post-load verification.

Next steps

• Identifiers (DOI & ARK)
• Troubleshooting