Migrate from Hybrid Assets to DAM 5

This page explains how to migrate from Hybrid Assets, an incubator-level module, to DAM module 5.x with S3 binary storage.

If you haven’t installed the Hybrid Assets module, you can skip this page.

Prerequisites

  1. Upgrade Hybrid Assets to the latest available version of the module.

  2. Back up your current Hybrid Assets metadata in the JCR dam workspace.

  3. Upgrade to the latest maintenance release of Magnolia 6.3.

  4. Read the release notes for the version you are upgrading to as well as for all intermediate versions.

  5. Back up the dam JCR workspace.

  6. Make sure you have the following module versions installed:

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)

  1. 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.

  2. Ensure Magnolia’s AWS credentials have read/write access to all S3 buckets involved (source and target), especially if you use multiple buckets.

Migrate assets from Hybrid Assets 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

  1. Open the Groovy app in your Magnolia author instance.

  2. Open the the migrateAssets Groovy script.

  3. 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.

  4. Save your changes.

  5. 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.groovy
    import 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.

  6. Review the script output to confirm migration results.

  7. 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.

  1. Open the Groovy app in your Magnolia author instance.

  2. Run the removeBinariesFromJcr Groovy script.

    RemoveBinariesFromJCR.groovy
    import 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))

  3. Check that assets and any pages using the assets work correctly.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DAM module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules