# Edit assets metadata via CSV

## Overview

This feature allows you to update the metadata of multiple files in bulk by importing a CSV file. It is useful when you need to edit tags, titles, descriptions, or custom fields across many files quickly.

### When to use this feature

Editing metadata via CSV is useful in the following cases:

* bulk metadata assignment after upload of multiple files
* correction of any metadata mistakes across multiple assets
* renaming multiple files
* moving multiple files to a new folder as an alternative to the standard "Move" action from the context menu

### Prerequisites

* a software tool for editing CSV files (Excel, Google Sheets, Numbers, etc)
* [Gallery permission](https://docs.scaleflex.com/digital-asset-management-dam/folders#steps-for-managing-folder-access) to edit the assets metadata in the relevant folder
* get to know [the project's metadata structure](https://hub.scaleflex.com/settings/dam/metadata/assets)
* read the section about [the accepted format of the values](#structure-of-the-csv-file)
* before editing metadata, review your team's metadata guidelines to ensure consistent usage of tags, titles, and values
* (optional) get a text editing tool that allows you to open the CSV file as a simple text file - it is useful for troubleshooting purposes in case of any unexpected issues in the CSV processing

### CSV format requirements

The CSV (Comma-Separated Values) file is a format that may contain comma (`,`), semi-colon (`;`) or pipe (`|`) as a column separator.

{% hint style="warning" %}
The "Edit via CSV" feature works when comma is used as a delimiter.
{% endhint %}

Some software tools for editing CSV files tend to overwrite the default column separator. It means that the initial file might be downloaded as comma-separated, but after saving the changes, the tool may convert it to a semicolon-separated file. These files may cause issues. DAM will likely reject them during upload.

Steps how to troubleshoot such problems, if they appear on your device, are described in [What to do if the updated CSV is semi-colon separated and DAM doesn't accept it?](#what-to-do-if-the-updated-csv-is-semi-colon-separated-and-dam-doesnt-accept-it)

## How to edit metadata via CSV

### Step 1: Download the initial CSV file

First, you need to select the files that require editing. They can be:

* the content of a specific folder - in this case, go to Folders view and navigate to the target folder. Then open the context menu and choose "Edit files via CSV"
* the files uploaded in a specific period, files that contain a specific value in a metadata field, files with a specific label, My favourites, etc - in this case, apply the corresponding filters in the Assets view in order to get only the files that require changes. Scroll to the bottom of the page to load all results. For large volumes of  results (50+), lazy loading may be triggered, so you need to scroll to the very end of the results set. Click on "Select all visible files" and then choose option "Bulk edit via CSV"

Once the files are selected, download the CSV file containing their existing metadata.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2F9nUa271oKOvs2n6L8Z5W%2FScreenshot%202025-07-14%20at%2017.41.09.png?alt=media&#x26;token=337cf9e0-5caf-4b7c-966a-d02be4fce31e" alt="" width="188"><figcaption></figcaption></figure>

### Structure of the CSV file

<details>

<summary>System metadata fields</summary>

<table><thead><tr><th width="119.6197509765625">Field</th><th width="281.701171875">Description</th><th>Editable?</th></tr></thead><tbody><tr><td>Item type</td><td>Information if the record describes a FILE or a FOLDER</td><td>Non-editable</td></tr><tr><td>Path</td><td>File location in DAM.</td><td><p>Editing the folder path will move the file.</p><p>Editing the filename will rename it.<br><br>Caution: Renaming or moving files may affect links, embeds, or published content that rely on the original location or filename.</p></td></tr><tr><td>CDN Link</td><td>The CDN link where you can access the optimised, publicly available version of this file (no CDN link for Private assets and Folders).</td><td>Non-editable</td></tr><tr><td>Mime type </td><td>The MIME type of the file (jpeg, png, pdf, txt, etc).</td><td>Non-editable</td></tr><tr><td>Size</td><td>The asset's size in bytes</td><td>Non-editable</td></tr><tr><td>SHA1</td><td>The sha1 value of the asset. A unique identifier for the asset content.</td><td>Non-editable</td></tr><tr><td>UUID</td><td>The unique identifier of the asset in DAM.</td><td>Non-editable</td></tr><tr><td>Created at</td><td>The date when the file has been uploaded. In <code>yyyy-MM-dd hh:mm:ss</code> format.</td><td>Non-editable</td></tr><tr><td>Updated at</td><td>The date when the file has been edited for last time. In <code>yyyy-MM-dd hh:mm:ss</code> format.</td><td>Non-editable</td></tr><tr><td>Visibility</td><td><p>It could be:</p><ul><li> <code>inherited</code> - sharing the same visibility settings as the ones of the parent folder.</li><li><code>public</code> - visible to everyone. </li><li><code>private</code> - restricted access. </li></ul></td><td>Editable.<br>Caution is advised to avoid exposing protected data or disrupting public asset delivery.</td></tr></tbody></table>

</details>

<details>

<summary>General metadata fields</summary>

| Field       | Description                              | Editable? |
| ----------- | ---------------------------------------- | --------- |
| Title       | Title of the file(if any)                | Editable  |
| Description | Description of the file content (if any) | Editable  |

{% hint style="info" %}
[If Regional variants are enabled for your project and it has several Languages](https://hub.scaleflex.com/settings/dam/metadata/assets), each of these fields will appear in a separate column for each of the configured languages.
{% endhint %}

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2F6rr1W5kOBHHcoyf8iexH%2FScreenshot%202025-07-14%20at%2018.11.46.png?alt=media&#x26;token=d50bebf0-bf35-4e6e-a83f-960f059259f2" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary>Custom metadata fields</summary>

The next part of the CSV consists of [a list of custom metadata fields and their language variations (if any)](https://hub.scaleflex.com/settings/dam/metadata/assets). The custom metadata fields are specific to every project.

{% hint style="warning" %}
When editing metadata in multiple languages, make sure each language-specific column contains relevant, localized content. Empty values in one language will not copy from another automatically.
{% endhint %}

</details>

## Step 2: Modify the CSV file

As a general rule, it is good to review [the metadata structure of your project](https://hub.scaleflex.com/settings/dam/metadata/assets) so to know what kind of values are expected in every field.

In case some metadata field is set with "Regional Variant: Languages", there will be a dedicated column for every language configured for the project.

<details>

<summary>Accepted values for the custom metadata fields</summary>

* Short/Long text type - use plain text without line breaks and new line symbols to avoid CSV parsing issues.
* Numbers - only whole numbers are accepted. No decimal values like `123.00`
* Booleans - accepts only `true` or `false`&#x20;
* List (single select) - only existing values are accepted. Invalid values will be replaced with "-" (none).
* List (multiple select) - several values can be provided, separated by `;` In the same way, like the rule for the Single-select lists, the value should already exist in the metadata structure.&#x20;
* Date - should be supplied in format yyyy-MM-dd
* Tags - this kind of field accepts new values that may not currently exist in the project metadata structure. Supply the tag values separated by `;`

{% hint style="warning" %}
As a good practice, always check if there is an existing variant for the tag value, so not to create duplicated tags and inconsistency in the project (for example, to have assets tagged with `winter-campaign`  and another set of assets tagged with `WinterCampaign` )
{% endhint %}

</details>

## Step 3:  Upload the updated CSV to apply metadata changes

## Metadata validation

Even if you modify some of the non-editable fields, DAM will not reflect the changes.

If you submit an invalid list option for the Single-select and Multi-select List custom fields, the CSV will be uploaded, but the value in these fields will become `-`  (none)

Empty cells will not replace an existing metadata value in DAM.

Change in the folder's path of the asset would result in moving the file to the new location (and eventually creating a new folder if it does not already exist in the Folders structure)

A change in the filename would result in renaming the file.

The updated CSV can be renamed; however, its first line (the Headers row) should always remain unchanged.

Up to 50 000 assets can be updated in a single CSV file.

{% hint style="warning" %}
As a general rule, before attempting bulk edit of hundreds or thousands of metadata values and files, test the changes using a CSV with 1-2 records only. Inspect the results and ensure the updated metadata values match your intentions.  \
This approach would protect you from inadvertently modifying a very large number of assets in a non-desired way.
{% endhint %}

## Troubleshooting common issues during CSV edit

{% hint style="warning" %}
Always save the edited CSV file as a new document and keep the original version of the downloaded CSV. In that way, if some mistake happens and some assets are unintentionally edited, you have a back-up and you can always upload the initial CSV and restore the initial metadata structure.
{% endhint %}

<details>

<summary>What to do if the updated CSV is semi-colon separated and DAM doesn't accept it?</summary>

In order to verify what the column separator of the file that your software tool is creating is, you can open the edited version with any text-editing tool that will show the CSV content as simple text. In that way, you can inspect what is the delimiter of your file.

If your CSV-editing tool is creating semi-colon separated files on Save, you need to modify the way your laptop is showing the Numbers format.

For Windows:

1. Open Windows regional settings.
2. Inspect the Numbers variant set for your device and set it to show the decimal numbers with a dot (`.`).&#x20;

For Mac:

1. Open "System settings" -> "Language & Region"
2. Set the "Number format" to `1234567.89` (to use dot, not comma)

</details>

<details>

<summary>Some metadata fields are not updated</summary>

1. [Check](#structure-of-the-csv-file) if the metadata field is editable or not
2. For custom metadata fields that are Single-select or Multi-select type, open the [Metadata structure](https://hub.scaleflex.com/settings/dam/metadata/assets) of the project -> find the problematic field and click on "Edit"
3. Then, inspect if the non-updated value is in the list of existing values.
4. If not, please create it and save the changes.
5. After updating the field values, re-upload the CSV file.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FRfmHEMyM2wbG54wT7ZWc%2FScreenshot%202025-07-14%20at%2019.45.58.png?alt=media&#x26;token=0a287f64-d4dd-4ead-a49c-d28ae4405326" alt=""><figcaption></figcaption></figure>

</details>