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 media files 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 ≤ a few hundred files and metadata you can edit in a spreadsheet.
• All files share an album / context / collection.
• You can upload the files together as a single ZIP.

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: Menu → Upload → Upload entities with mediafiles.

2. Prepare a starter CSV

Drop the three image files (mediafile-1.jpg, mediafile-2.jpg, mediafile-3.jpg) onto the form. Click Download sample CSV — this gives you a template with the filenames pre-filled.

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.

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
• mediafile_owner_person → vliz (in every row)
• 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 sample CSV ships with placeholder text like title of a keyword for mediafile. Replace those with real values or clear the cell.

9. Upload

Upload the CSV in the top window of the upload form together with the ZIP archive of mediafiles.

10. Validate

After import, the UI shows whether files are linked correctly and flags any errors. You can download an error-annotated CSV and re-upload it after fixes.

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	mediafile_owner_person	usage_guidelines_until	external_link
1	Koksijde 2014	general vliz	Coastal Management	Mediterranean Sea	Belgium Coast	Tourist Destination	media	mediafile-1.jpg	Confidentiality 1	vliz
1			Beach profiles				media	mediafile-2.jpg	Confidentiality 2	vliz	31/12/2030
1							media	mediafile-3.jpg	Confidentiality 3	vliz		https://example.org/ref

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

Common gotchas

• has_context is required. Forget it and the row fails validation.
• Linked entities must exist first. Keywords, marine regions, partners, etc. must already be in the DAMS or the vocab server.
• mediafile_creator_partner and mediafile_owner_partner are not currently valid columns despite being in the older documentation — only the _person variants exist on Mediafile. Use the parent media's partner field if you want a partner link.
• 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.