Merge pull request #14 from cloudinary/v2.1.1-release

V2.1.1 release

CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+[2.1.1] / 2024-12-30
+====================
+
+### Added
+- Documentation for the `SkippedAlreadyExists` upload operation status
+
+### Changed
+- Updated outdated dependencies
+- Sample payload in the `__input-to-api-payload.js` for better clarity
+- Explanation for "estimated number of records" in progress bar
+- Runtime setup instructions per peer review feedback
+
 
 [2.1.0] / 2024-11-12
 ====================

__input-to-api-payload.js

@@ -21,25 +21,31 @@
  *  - options: options for the Cloudinary Upload API call
  */
 exports.input2ApiPayload = function(csvRec) {
-    // Pass value from 'Url' column with the asset URLs or paths
-    const file = csvRec['Url'];
+    // Where to load the asset from 
+    // Any source supported by Cloudinary Upload API: https://cloudinary.com/documentation/upload_parameters#required_file_parameter
+    const file = csvRec['File_Path_or_URL_ColumnName'];
 
     // Optional parameters for the Cloudinary API
     const options = {                       
-        public_id:       csvRec['Id'],            // Pass value from 'Id' column to be used as public_id
-        unique_filename: false,                   // Do not add random suffix to the public_id
-        resource_type:   'auto',                  // Let Cloudinary determine the resource type
-        overwrite:       false,                   // Do not overwrite the asset with same public_id if it already exists
-        type:            'upload',                // Explicitly set delivery type
-        tags:            csvRec['Tags'],          // Pass value from 'Tags' column as tags
+        public_id:       csvRec['Asset_Public_Id_ColumnName'],     // Pass value to be used as public_id (addressed by column name from the input CSV file)
+        unique_filename: false,                                    // Do not add random suffix to the public_id
+        resource_type:   'auto',                                   // Let Cloudinary determine the resource type
+        overwrite:       false,                                    // Do not overwrite the asset with same public_id if it already exists
+        type:            'upload',                                 // Explicitly set delivery type
+        tags:            csvRec['Asset_Tags_ColumnName'],          // Pass value to be set as tags on the uploaded asset (addressed by column name from the input CSV file)
 
+
+        // Example: Assigning contextual metadata
+        // See specs at https://cloudinary.com/documentation/contextual_metadata
         context: {
-            caption: csvRec['Description'],       // Pass value from 'Description' column as contextual metadata
+            caption: csvRec['Asset_Description_ColumnName'],       // Pass value to be set as caption field in contextual metadata (addressed by column name from the input CSV file)
         },
 
+
+        // Example: Assigning structured metadata
+        // See specs at https://cloudinary.com/documentation/structured_metadata
         metadata: {
-            sample_field: csvRec['SampleField'],  // Pass value from 'SampleField' column into the structured metadata field
-                                                  // with external_id of 'sample_field'
+            sample_field: csvRec['SampleField_Value_ColumnName'],  // Pass value to the structured metadata field with external_id of 'sample_field' (addressed by column name from the input CSV file)
         },
     };
 

cld-bulk.js

@@ -57,7 +57,7 @@ function configureProgram(program) {
     program
         .name('cld-bulk')
         .description('Extensible CLI tool to efficiently translate CSV file records into Cloudinary API operations')
-        .version('2.1.0');
+        .version('2.1.1');
 }
 
 

lib/output/progress.js

@@ -61,7 +61,7 @@ async function init_Async(filePath) {
         fps: 5
     });
     _statusBar = _multiBar.create(totalCount, 0, init_stats, {
-        format: 'Attempted: {value} (✅{succeeded} /❌{failed}) out of estimated {total}',
+        format: 'Attempted: {value} (✅{succeeded} /❌{failed}) out of estimated* {total}  (* counted newlines in the input file)',
         fps: 5
     });
 }

package.json

@@ -21,5 +21,5 @@
   "scripts": {
     "test": "node ./test/jest.run-all-tests.js"
   },
-  "version": "2.1.0"
+  "version": "2.1.1"
 }

readme/identify-reattempt-failed.md

@@ -17,6 +17,9 @@ The migration script adds the following additional columns to the migration repo
     + `Overwritten` - if the Cloudinary asset already existed and was overwritten
         * This may indicate undesired behavior, for example if several assets in the migration input file were assigned the same `public_id`
     + `Uploaded` - if a new Cloudinary asset was created 
+    + `SkippedAlreadyExists` - indicates that upload operation was not performed because:
+        * `overwrite` upload API parameter was set to `false`
+        * AND asset with the `public_id` value specified for the upload already exists
 - `Cld_Error` : the error details for troubleshooting (if an asset failed to migrate) 
 - `Cld_PublicId`: `public_id` reported back by Cloudinary after uploading an asset
     + Should be used as "source of truth" when addressing migrated assets via Cloudinary API (as [Cloudinary may have to replace some of the characters](https://support.cloudinary.com/hc/en-us/articles/115001317409--Legal-naming-conventions))

readme/provision-runtime.md

@@ -2,19 +2,19 @@
 
 For smaller-scale migrations involving thousands or tens of thousands of assets, running the script from your local machine should suffice. 
 
-For larger migrations with hundreds of thousands of assets, it's advisable to run the script from a virtual machine (VM).
+For larger migrations with hundreds of thousands of assets, it's advisable to run the script from a stable, always-on environment with reliable internet connectivity (for example, an AWS EC2 VM).
 
 # Guidelines for Provisioning a Virtual Machine Runtime
 
 ## Important Considerations ❗️
 
-- If you're planning to run the script on a VM via an SSH connection, consider using a terminal multiplexer like `screen` or `tmux`.
-    - Failing to use a multiplexer may result in the termination of the migration process if your SSH connection closes and your VM session is terminated.
+- If you're planning to run the script on a VM via an SSH connection, make sure to use a terminal multiplexer like `screen` or `tmux`.
+    - Not using a multiplexer will likely result in the migration process stalled or even terminated.
 
 ## CPU and Memory ⚙️
 
 - The script is not resource-intensive as most of the heavy lifting is done by Cloudinary's back-end systems.
-    - For example, an AWS `t2.micro` VM should suffice.
+    - For example, an AWS `t2.micro` EC2 VM is usually sufficient
 
 ## Storage Requirements 💾
 
@@ -32,7 +32,7 @@ For larger migrations with hundreds of thousands of assets, it's advisable to ru
 
 ## Clone the Repository 👯
 
-- Clone the forked repository onto your VM.
+- Clone the forked repository onto your system.
 
 ## Install Node.js 🛠️