Extracting Asset Data for Bulk Migration to Cloudinary

Cloudinary supports multiple ways to migrate your visual media assets. If you’re doing a programmatic bulk asset migration using the migration script, this blog post offers a proven methodology to get it done (and done right).

You don’t have to reinvent the wheel: Start by splitting your migration efforts into “data” and “technical” parts.

• Data. Your team extracts the asset’s information into a data file from the system(s) of origin.

• Technical. Use customizable bulk migration tooling.

The steps and roles required to support both parts are covered below in more detail.

This, more often than not, ends up being an iterative process as quirks and inconsistencies are discovered and ironed out.

Those closely familiar with the nuances of asset operations should own this process, such as a:

• Representative from the team who uses the asset in day-to-day operations to validate extracted data and provide guidance.
• Representative from the IT team in charge of maintaining the current system hosting the assets to extract asset information.

The outcome is a CSV data file that meets the following common sense considerations:

• There is one dedicated record (row) for each distinct asset.
• There is a designated column for each taxonomy property that needs to be assigned to the migrated asset in Cloudinary.
  • Examples: Tags, DAM folder, category, alt text, etc.
• There is a column with a download link to the original version of the asset from a source supported by the Cloudinary Upload API.
• Each distinct asset has a unique identifier (typically a file name) to be used as the public_id in Cloudinary, since it determines the asset delivery URL.

By having all asset records in one file at this point, your team can make sure that the asset taxonomy (e.g., metadata fields) uses consistent values, they can identify outdated assets early in the process, and more.

This effort prevents accruing technical debt and losing operational efficiency due to inconsistencies, as your team will be using the migrated assets in business workflows.

As an example, below is what a data file might look like:

Typically, your team will have a process to extract asset data as CSV files from the system of origin. Make sure to use the originally extracted CSV file when migrating.

Spreadsheet applications, by default, attempt to “guess” the format of the values when opening a data file. For example, Jan-24 intended as an asset name can be converted to 1/24/2025. These automatic conversions usually occur “silently” and are almost impossible to notice.

If using a spreadsheet app is necessary (e.g., to review the extracted asset data), make sure to use the app settings to prevent automatic format conversion.

After the asset data file has been extracted and validated, the customizable bulk migration tooling can be used as a starting point to quickly finalize how to pass information to Cloudinary with each migrated asset.

The tooling produces detailed records on migration of each asset. Below is an example of a migration report based on the previously used asset data file example:

Where:

• Cld_Status. Indicates if the migration was successful (failed assets can then be retried).
• Cld_Operation. Indicates if a new asset was created or a previously existing asset was overwritten.
• Cld_Error. A technical issue that prevented the upload operation to migrate the asset.
• Cld_Etag. The MD5 checksum (you can think of it as a “digital fingerprint”) of the uploaded file contents, which can be used to identify duplicate assets.

Records for those assets that failed to migrate can be filtered out from the report file and then used with the tooling again to re-attempt the migration after the root cause had been addressed.

Need help with complex asset migrations? Cloudinary offers implementation packages with Professional Services. Contact us today to learn more.