Bulk import from a shared drive

For larger and more structured uploads (especially when album folders arrive over time on a shared drive), VLIZ uses a folder-per-album workflow handled by the vliz-filesystem-importer service.

Roles

• VLIZ uploads each album as a folder of media files to the shared drive, and tells Inuits which folders are ready.
• Inuits prepares the three CSVs (album.csv, default_values_for_media.csv, media.csv) per folder, based on a shared template.
• VLIZ reviews the prepared folders and approves which ones are ready to import.
• The importer service ingests the approved folders into Elody.

Folder layout

Each album folder must contain three CSVs plus the media files referenced in media.csv:

my_album/
├── album.csv                       # one row: the album entity
├── default_values_for_media.csv    # one row: defaults applied to every media in this album
├── media.csv                       # one row per media file
├── img001.jpg
├── img002.jpg
└── img003.jpg

Service location

Templates and ingestion logic live in clients/vliz-dams/vliz-filesystem-importer/api/services/importer/importer.py and templates/album.csv, templates/default_values_for_media.csv. AI-assisted CSV generation lives in generate_elody_import_csvs_with_ai.py. This pipeline is active in production.

How the three files combine

File	Purpose	Cardinality
album.csv	Describes the album entity itself (title, context, archival collection, marine region, etc.)	exactly 1 row
default_values_for_media.csv	Default metadata applied to every media in this folder. Any column also present on a per-row basis in media.csv is overridden by that row.	exactly 1 row
media.csv	One row per media. The filename column must match a file present in the folder.	one row per media file

For multi-valued fields in album.csv or default_values_for_media.csv, place each value on a separate line — the same_entity trick is not needed here because each file already describes a single album / single defaults.

Workflow

1. VLIZ drops the album folder + media on the shared drive.
2. Inuits adds the three CSV files using the shared templates.
3. VLIZ reviews and approves the prepared folder.
4. Inuits triggers the import.
5. The importer:
   • Creates the album entity from album.csv.
   • Loads default media metadata from default_values_for_media.csv.
   • Imports each media row from media.csv, overriding the defaults where a column is non-empty.

Column types in the template files

Type	Meaning
elody	A UUID or the human-readable title/name of an existing entity in the DAMS.
vocab	An identifier from the VLIZ vocab server (e.g. an MRGID for a marine region).
text	Free-text field.
date	Date — typically dd/mm/yyyy.

Multi-valued fields: separate values on consecutive lines (within the same file) — for album.csv and default_values_for_media.csv no same_entity column is needed.

Notes & checks

• All CSVs must follow the standard Elody format — technical keys as column headers (the snake_case keys, not the localised labels).
• default_values_for_media.csv allows only one row.
• Per-file overrides in media.csv win over defaults.
• The filename in media.csv must match a real file in the folder, including extension.
• Linked entities (keywords, marine regions, partners, …) must already exist in the DAMS or vocab server before the import runs.