CSV import via the upload form

This page walks through the most common bulk-upload scenario: uploading a set of media files plus their metadata in a single step, using the Upload entities with mediafiles form in the DAMS UI.

The example mirrors the one previously published at csv-vliz-import-example.md, with the column reference refreshed against the current validators.

When to use this flow

• You have up to a few hundred files and metadata you can edit in a spreadsheet.
• All files share an album / context / collection.
• You can drop the files into the form together (individual files — ZIP archives are not accepted; up to 999 files per upload).

For larger or recurring imports — especially when files arrive structured per-album on a shared drive — use Bulk from shared drive instead.

Step-by-step example

The scenario: upload three photos from the Koksijde 2014 coastal-management campaign, link them as a single Media entity with three Mediafiles.

1. Open the upload form

In the sidebar: Upload → Upload entities with mediafiles.

2. Download the CSV template

Under the CSV drop zone, open the Download example with instructions for dropdown and pick upload-csv-template-media-with-mediafiles.csv (there are also map and document variants). Open it in your spreadsheet tool.

3. Set the context

Fill in the context column — for general VLIZ data this is general vliz. The context controls who within VLIZ can see the resulting entities; ask internally if you're unsure. The context cell is required on every entity.

4. Use same_entity to group rows

All rows that belong to the same media entity must share an identifier in the same_entity column. Use 1 throughout for this example (one media, three mediafiles).

5. Fill in media-level metadata (row 1)

Media-level fields go on the first row only:

• title → Koksijde 2014
• media_keyword → Coastal Management (the keyword must already exist in the DAMS or be created first)
• marine_region → Mediterranean Sea
• album → Belgium Coast (album must exist)
• collection_part → Tourist Destination (collection part must exist)

6. Fill in per-mediafile metadata (rows 1–3)

These fields apply per row, so they can vary by file:

• filename → mediafile-1.jpg, mediafile-2.jpg, mediafile-3.jpg — must exactly match the files you drop in the form
• confidentiality → Confidentiality 1, Confidentiality 2, Confidentiality 3 (must exist)
• usage_guidelines_until → 31/12/2030 on the second mediafile only
• external_link → URL on the third mediafile only

7. Add multiple keywords for the same entity

To attach a second keyword (Beach profiles) to the same media, put it on a new row in the media_keyword column with the same same_entity value. Each new keyword goes on its own line; everything joined by same_entity belongs to the same media.

8. Remove placeholder data

The template ships with placeholder text like title of a keyword for mediafile. Replace those with real values or clear the cell.

9. Upload

Drop the CSV in the small (CSV) drop zone and the three image files in the large (files) drop zone, then click Upload.

10. Validate

The Validate step runs a dry-run of the CSV before anything is imported. Errors are reported per line number in the upload window (missing required columns, referenced entities that don't exist, filenames that don't match an uploaded file). Nothing is imported until validation passes — fix the CSV and drop it in again. Each import also creates a job on the Jobs page where you can review the outcome afterwards.

Example CSV

A minimal version of the example, with the current column set:

same_entity	title	context	media_keyword	marine_region	album	collection_part	type	filename	confidentiality	usage_guidelines_until	external_link
1	Koksijde 2014	general vliz	Coastal Management	Mediterranean Sea	Belgium Coast	Tourist Destination	media	mediafile-1.jpg	Confidentiality 1
1			Beach profiles				media	mediafile-2.jpg	Confidentiality 2	31/12/2030
1							media	mediafile-3.jpg	Confidentiality 3		https://example.org/ref

→ For the full list of importable columns and their target types, see Column reference.

Common gotchas

• context is required. Forget it and the row fails validation (title is required too, on media).
• Linked entities must exist first. Keywords, marine regions, partners, etc. must already be in the DAMS or the vocab server.
• Unknown columns are silently skipped, not rejected. Several columns in the shipped templates (creator_person, owner_person, creator_partner, owner_partner, mediafile_creator_person, mediafile_owner_person, their _partner variants, mediafile_copyright_color, qualityRating) are not recognised by the current validators — values in them are dropped without warning. See the column reference for the working alternatives.
• No ZIP archives. Drop the individual media files into the file zone (JPEG, PNG, TIFF, GIF, MP4, MP3, PDF, XML).
• Map dates are nested objects ({ value: ... }) — they cannot be expressed as a flat CSV cell without the parser knowing it's a map. Stick to date_description for free-form dates on maps in CSVs.
• Multi-line per same_entity group is the only way to express list-valued fields. Don't try comma-separating values in a single cell.