Programmable Media
Folder modes
Last updated: Dec-16-2024
All Cloudinary product environments are set up to work with either dynamic folders or fixed folders. While the majority of supported Cloudinary features are identical for both modes, dynamic folders provide Cloudinary users the flexibility to organize and manage media assets with high performance and without risk of breaking URLs in production. Each mode has a variety of behaviors, settings, options and interfaces to support its unique functionality.
-
In dynamic folder mode, assets are completely decoupled from the folders they are located in. This means that moving assets between asset folders, renaming folders, or even moving entire folders and their assets to a new location is supported and does NOT affect the asset's public ID value or delivery URL.
Dynamic folder mode also introduces the concept of a display name, which, like asset folders, can be freely modified without affecting the public ID and delivery URL.
-
In fixed folder mode, the asset's public ID (part of the delivery URL) consists of the asset name and its containing folder. Therefore, changing the asset name or moving an asset to another folder in the Media Library will modify the asset's URL, and if not done carefully, risks breaking production content.
NoteIn fixed folder mode, renaming and moving folders (which would in effect change the public ID of every asset under that folder and of any sub-folders), is not supported.
- To migrate one or more product environments to dynamic folders mode or to send questions and feedback related to dynamic folders, contact Cloudinary support.
- Once a product environment is migrated to dynamic folders mode, you can't revert it to fixed folders mode.
- It's recommended that you test every element of your Cloudinary implementation on a non-production product environment before applying this mode to a production product environment.
- To find out how folder modes impact the API, see Folder modes within the Programmable Media guide.
Checking your product environment folder mode
You can find out if dynamic folders is enabled for your product environment by navigating to the Product Environments settings page. From the (3-dots) option menu next to the relevant product environment select Edit. Your product environment is using dynamic folder mode if the Dynamic folder mode toggle button is on. If it's off, you're using fixed folder mode.
Asset identifiers and folder location
The table below summarizes the identifiers for assets in fixed and dynamic folder modes, including public ID, display name, asset ID, and folder location:
| Identifier or Property | Description | Dynamic Folders | Fixed Folders |
|---|---|---|---|
|
Public ID Unique Editable |
Identifies the asset in a Cloudinary delivery URL. Can include any language character (including non-English letters) as well as characters such as dots ( Editable in the Media Library or programmatically, but changing it can break production code. * Must be unique within its product environment and asset type. It's possible, though not recommended, to use the same ID for an image and a video in the same environment. |
Displayed with less prominence in the Media Library to avoid inadvertent edits that could break links to assets in production. It may contain slashes, but they don't reflect the folder path. |
Acts as the primary identifier in the Media Library, making it more prone to modifications that could potentially break links to assets in production. It reflects the folder location as shown in the Media Library, so moving assets risks breaking links to assets in production. |
|
Display Name Not Unique Editable |
A descriptive or user-friendly name for the asset unrelated to the delivery URL path. It's the primary identifier for assets in the Media Library, collections, and basic portals. Can be retrieved or set programmatically. Can include spaces and special characters, but not slashes (/). It's possible, though not recommended, for the same display name to be used for different assets, even in the same asset folder. |
Supported | Not supported |
| Folder Location | The asset's location within the folder hierarchy as shown in the Media Library. | Not reflected in the public ID, even though the public ID may contain slashes. Moving assets doesn't affect the asset's public ID or delivery URL, so it doesn't risk breaking links to assets in production. However, discrepancies may occur as the public ID path doesn't update to match the new folder location. Renaming and moving asset folders is also safe and supported. |
Reflected in the public ID path. Moving assets affects the asset's public ID and delivery URL, risking broken links to assets in production. Renaming and moving folders is not supported. |
Folder mode features
The following features differ in dynamic and fixed folder modes, or exist only in dynamic folders:
Moving assets between asset folders
Dynamic folder mode
Since dynamic asset folders are not directly tied to a physical storage location, you can move assets from one folder to another in milliseconds. Even moving thousands of assets, or very large assets has no impact on move time.
Additionally, the public ID path doesn't reflect the asset's folder location, so you can move assets freely between folders without risking breaking links to assets in production.
Fixed folder mode
Folders are directly tied to a physical storage location. As such, moving assets from one folder to another may take some time.
Moreover, since the public ID path reflects the asset's folder location, moving assets between folders risks breaking links to assets in production.
Moving and renaming asset folders (dynamic folders only)
In dynamic folder mode, moving and renaming asset folders is safe and fully supported. Use the folder right-click menu to access these options:
In fixed folder mode, moving and renaming folders is not supported.
Display name (dynamic folders only)
In dynamic folder mode:
- The asset name that's shown at the top of the Media Library Preview pane and in the Summary pane of the asset management drill-down page reflects the asset's display name. Editing this value doesn't impact the asset's public ID and delivery URL.
- The asset name shown in basic portals and collection web pages shared via public links reflects the asset's display name, as well.
In fixed folder mode, the display name is not supported.
Public ID
You can view and edit the public ID from both the asset management drill-down page and the Preview pane. The process differs depending on whether your product environment uses dynamic folder mode or fixed folder mode. Here’s where to find the public ID in each mode:
Dynamic folder mode:
Asset management drill-down page
Preview pane
Fixed folder mode:
Asset management drill-down page
Preview pane
In addition to where you can view and edit public IDs in the Media Library, the public ID differs in fixed and dynamic folder modes in the following ways:
Folder path
In dynamic folder mode, the public ID field shows the entire public ID value (full path). This value isn't directly related to the Media Library folder where it's currently located. This entire value can be directly modified.
In fixed folder mode, only the asset name (the last segment of the public ID) is displayed in the Name area and is directly editable. However, if the asset is located in a folder in the Media Library, then the full public ID includes the folder path.
Editing the public ID
In dynamic folder mode, click the edit icon and modify the public ID in the dialog box that opens.
In fixed folder mode, click in the Name area to edit the last segment of the public ID. To change other parts of the public ID path, move the asset to the desired folder hierarchy, which updates the public ID path accordingly.
In both folder modes, to edit the public ID, users with a Media Library user role need Can edit or Can manage folder permissions for the asset's folder. In dynamic folder mode, the Show delivery URL user permission, defined in the User Management page of the Console Settings by an account admin, is also required.
Upload preset options
When uploading, you may want to consider how to name new assets and which folder to store them in. Upload presets can establish naming and storage conventions for specific types of assets, or for your entire organization.
Each folder mode provides different naming and storing methods, reflected in upload preset options. For example, dynamic folders support display names, so display name options are available in that mode. Additionally, in fixed folders, the public ID always reflects the folder you select for upload, whereas in dynamic folders, the upload preset provides a special configuration option for this to happen.
Here is the interface that shows the different naming and storing options in fixed and dynamic folder modes:
Dynamic folder mode
Fixed folder mode
Below is a summary of the naming and storing options for dynamic and fixed folder modes:
| Option | Dynamic Folder Mode | Fixed Folder Mode |
|---|---|---|
| Destination folder | You can optionally specify a value in the Asset folder field to determine the folder where the asset will be placed within the Media Library. The value set here doesn't impact the asset's public ID (unless you also select the Prepend a path to the public ID and Use initial asset folder path options). | You can set the destination Folder in the Media Library for where all assets uploaded via this upload preset will be saved, overriding the folder that the user may have selected. The folder you set also automatically defines the URL path to prepend to the public ID of every asset uploaded using this upload preset. |
| Naming convention for the public ID used in delivery |
You can choose to Generate a random value for the public ID (default1). Alternatively, you can set the public ID to match the name of the file being uploaded, with or without a randomly generated unique suffix. |
The same options are available in fixed folder mode. |
| URL path (public ID prefix) |
By default, the public ID has no path (no public ID prefix). However, you can select Prepend a path to the public ID to define the URL path (public ID prefix) to be prepended to the public ID of every asset uploaded using this . You can either: - Use the initial asset folder path: Sets the public ID prefix to match the name of the asset folder the asset is initially uploaded to. If an asset is later moved to a different folder, the public ID path won't change to reflect the asset's new location. - Use a custom path: Allows you to define a custom public ID prefix. |
The URL path (public ID prefix) that's prepended to the public ID is determined by the Folder you select. If an asset is later moved to a different folder, the URL path changes accordingly, which risks breaking links to assets in production. |
| Display name |
The display name is a user-friendly name for assets that doesn't impact the delivery URL value. By default, the asset's display name will be automatically taken from the filename of the uploaded file. Alternatively, you can customize the asset's display name to be the same as the public ID (without the prefix). |
Display names don't exist in fixed folder mode. |
| Allow or prevent overwriting existing assets |
When Overwrite is enabled there are several ways to overwrite an asset:
|
Overwrite works the same way in fixed folder mode, except that there's no option to overwrite assets based on display name. |
-
For organizations using Cloudinary only for DAM use cases, it’s generally best not to change these default naming options (using the filename as the display name and a random value for the public ID).
If your organization uses both DAM and Programmable Media, it's recommended to consult with your developers on the preferred behavior.
Upload with existing display name (dynamic folders only)
More than one asset can have the same display name, even within the same folder. However, if you upload one or more assets using a display name that already exists, you'll be asked to decide how to proceed before uploading continues.
This situation will occur if you apply an upload preset with the Use the filename of the uploaded file as the asset's display name option selected (either within the Default or Custom options), and the file name of at least one of the assets you're uploading matches the display name of an existing asset or assets.
Depending on the scenario, you'll get different options to choose from:
-
If you're uploading an asset using the same display name as multiple existing assets in the same folder, you'll be asked which one of the following you want to do:
- Keep the new and existing assets with the same name
- Enter a different display name for the new asset being uploaded
-
If you're uploading an asset using the same display name as exactly one existing assets in the same folder, you'll be asked which one of the following you want to do:
- Replace the existing asset with the new one being uploadedNoteWhen a new asset replaces an existing asset (with the same display name in the same asset folder), the new asset retains the exact, existing public ID. Therefore, no public ID prefix is added to the incoming asset's public ID, even if the Prepend a path to the public ID settings in the upload preset were turned on.
- Keep the new and existing assets with the same name
- Enter a different display name for the new asset being uploaded
- Replace the existing asset with the new one being uploaded
-
If more than one asset that you're uploading has the same display name as existing asset in that folder, you'll be asked which one of the following you want to do:
- Keep the new and existing assets with the same display name
- Add a unique suffix to the display name of the new asset
You'll be able to apply the selected behavior to all of the assets that fall into this category or to determine the naming option for each uploaded asset individually.
Media Library search
In both fixed and dynamic folder modes, global searches via the free text search box return assets matching the search value by public ID. In dynamic folders, global searches also return assets matching the search value by display name.
Error
Rate this page:
