Migrate from DAM 4 JCR-based storage to DAM 5 with JCR or S3
This page explains how to migrate from DAM module 4.x, which stores all assets in the dam JCR workspace, to DAM module 5.x.
In DAM 5 and later, you can choose to store both asset metadata and binaries in JCR or to externalize binary storage to S3. In both cases, we recommend you migrate your assets.
Although migration is optional when storing assets in JCR with DAM 5, the migration process updates existing assets with a property introduced in DAM 5 (mgnlBinaryReference).
This property is added to all assets, regardless of storage choice, uploaded when using DAM 5.
Therefore, for consistency, we recommend running migration script step 1 when moving from DAM 4 to DAM 5 with JCR storage.
|
Prerequisites
| DAM module version | Compatible module versions |
|---|---|
5.0.0-beta2 |
Magnolia CMS 6.3.13+ |
DAM App module 5.0.0-beta2 (required) |
|
Imaging module 4.1.0-beta2 (required) |
|
Image Recognition module 3.0.0-beta2 (optional) |
-
If you want to store binaries in S3, make sure you install and configure the JCR S3 submodule to connect to an appropriate AWS S3 account.
Migrate assets from DAM 4 to DAM 5
Edit and run the migrateAssets Groovy script on your author instance to migrate binaries.
Only if migrating to external binary storage, you may also run the removeBinariesFromJcr to remove from JCR any binaries that have been successfully migrated.
Step 1: Migrate assets
-
Open the Groovy app in your Magnolia author instance.
-
Open the the
migrateAssetsGroovy script. -
Edit the script to point to your chosen destination.
The options are: ..
"jcr": Store both asset metadata and binaries in JCR. .."s3": Store asset metadata in JCR and binaries in AWS S3. -
Save your changes.
-
Enable the script and run the script.
This script copies binaries from JCR to the destination chosen and logs a summary of what was migrated.
You can run it multiple times. It skips already-migrated binaries and only processes the remaining ones. It does not remove anything from JCR.
MigrateAssets.groovyimport info.magnolia.dam.jcr.migration.AssetMigration import info.magnolia.dam.jcr.migration.MigrationConfig import info.magnolia.objectfactory.Components def startTime = System.currentTimeMillis() def service = Components.getComponent(AssetMigration) ?: { println "Error: GenericAssetMigration not found." return }() // Define provider def provider = "s3" // "s3" or "jcr", "azure", "obs" etc. (1) // Build config def config = MigrationConfig .builder(provider) .build() def results = service?.migrateAll(config) ?: { println "Info: No asset migrations needed." return }() print(AssetMigration.printSummary(results, startTime))1 Specify the target for binary storage such as`"jcr"`, "s3", or another provider. -
Review the script output to confirm migration results.
-
Run the script again if needed. It only processes binaries that haven’t yet been migrated.
Optional step 2: Only if using external binary storage - remove binaries from JCR
| Don’t follow this step if using JCR to store your binaries. |
After all binaries are copied to S3, run the removeBinariesFromJcr script to delete them from JCR.
The script only deletes binaries that were successfully migrated to S3.
Others remain untouched.
-
Open the Groovy app in your Magnolia author instance.
-
Run the
removeBinariesFromJcrGroovy script.RemoveBinariesFromJCR.groovyimport info.magnolia.dam.jcr.migration.AssetMigration import info.magnolia.objectfactory.Components def startTime = System.currentTimeMillis() def service = Components.getComponent(AssetMigration) ?: { println "Error: JcrToDam5BinaryMigration not found. Cannot proceed with JCR binary deletion." return }() def results = service?.removeBinariesFromJcr() if (!results) { println "Info: No binary data deletions needed." return } def totalSpaceFreed = results.stream() .filter { it.success() } .mapToLong { it.size() } .sum() def spaceMessage = "JCR Binary Deletion = total space freed up: " + AssetMigration.formatBytes(totalSpaceFreed) println spaceMessage print(service.printSummary(results, startTime)) -
Check that assets and any pages using the assets work correctly.