Dynamic Media Masterclass: Configuration, Architecture, and the “One-File” Revolution

 

In today’s multi-device world, delivering rich media consistently across smartphones, tablets, desktops, and high-resolution displays is no longer optional—it’s expected. Traditional digital asset management approaches struggle here, often requiring multiple cropped, resized, and optimized versions of the same image or video.

Adobe Dynamic Media fundamentally changes this approach with a powerful idea:
👉 One primary asset file, delivered in unlimited variations—dynamically, in real time.

This article walks you through the philosophy, architecture, configuration, and advanced optimization techniques of Dynamic Media in Adobe Experience Manager (AEM) as a Cloud Service.

---

The Philosophy Behind Dynamic Media: One Asset, Infinite Renditions

In legacy systems, a single product image could easily result in dozens of files—thumbnails, banners, mobile crops, retina versions—each manually created and managed. This approach increases storage, introduces inconsistencies, and slows down content delivery.

Dynamic Media replaces this with a URL-driven rendering model.

Instead of storing static variations, you upload one high-quality primary asset. Dynamic Media then generates renditions on demand using URL parameters for size, format, quality, and crop. The result:

• Consistent brand presentation across devices

• Reduced asset duplication

• Faster time to market

• Optimized delivery based on device and bandwidth

This is the foundation of the “one-file revolution.”

---

Dynamic Media Architecture: How Assets Flow from AEM to CDN

Understanding the architecture helps clarify why Dynamic Media performs so well.

High-Level Flow

1. Asset Upload
   A primary image or video is uploaded into AEM as a Cloud Service.

2. Replication to Dynamic Media
   Once processed, the asset is replicated to the Dynamic Media service.

3. Processing & Intelligence
   Dynamic Media handles:

   • Video transcoding

   • Image rendition generation

   • Smart cropping and optimization

4. CDN Delivery
   Approved assets are cached and delivered via a global Content Delivery Network (CDN), ensuring low latency and high performance worldwide.

By simply switching your asset URLs to the Dynamic Media Image Server, you automatically benefit from bundled global caching and edge delivery.

---

Dynamic Media Configuration in AEM as a Cloud Service

Initial Setup

Configuration starts in AEM under:

Tools → Cloud Services → Dynamic Media Configuration

You’ll need:

• Company administrator email

• Password from Adobe provisioning

Key Configuration Decisions

Adobe supports only one Dynamic Media configuration per AEM instance, so this step requires careful planning.

You must choose how assets are published:

• Immediate Publish – Assets go live as soon as they’re uploaded

• Publish on Activation – Assets publish when activated

• Selective Publish – Useful for secure previews and controlled rollouts

Important Limitation

As of April 2025, Dynamic Media is not supported in Enhanced Security (HIPAA-ready) environments.

Existing Dynamic Media Classic customers can integrate legacy assets via point-to-point integration, but new implementations should always use the unified Dynamic Media setup.

---

Image Presets, Responsive Images, and Smart Imaging

Image Presets: The Core Control Mechanism

An Image Preset is essentially a reusable macro—a predefined set of commands that define how an image is delivered.

Create them under:
Tools → Assets → Image Presets

You can configure:

• Output format (JPEG, WebP, etc.)

• Compression quality (e.g., JPEG 75%)

• Sharpening for downscaled images

• Cropping and scaling behavior

Responsive Image Presets

For fluid, responsive layouts:

• Leave width and height blank

• Dynamic Media adapts the image to the container size automatically

Smart Imaging: AI-Driven Performance Boost

Smart Imaging takes optimization even further.

At the last millisecond of delivery, it:

• Detects browser capabilities

• Analyzes network conditions

• Chooses the most efficient image format and compression

This often results in 22%–47% smaller file sizes, significantly improving Core Web Vitals and page load speed.

---

Video Delivery with Adaptive Video Sets

Video delivery is traditionally complex—but Dynamic Media simplifies it.

How Adaptive Video Works

When you upload a video:

• Dynamic Media automatically transcodes it into multiple formats and bitrates

• These versions are grouped into an Adaptive Video Set

At runtime:

• The player detects user bandwidth (Wi-Fi, 4G, etc.)

• The best video quality is selected automatically

• Playback adjusts dynamically if conditions change or fullscreen is enabled

Performance Tuning for Video

For heavy video workflows, admins can tune:

• Granite Workflow Queues

• Maximum parallel jobs based on available CPU cores

This ensures faster processing without overwhelming system resources.

---

Advanced Configuration and Troubleshooting

Custom MIME Type Handling

Power users can fine-tune how assets are processed by editing MIME types in CRXDE Lite.

Examples:

• Automatically rasterize PDFs

• Convert Adobe Illustrator files into image renditions upon upload

Troubleshooting Tips

If Dynamic Media configuration fails:

• Check the AEM Inbox for status notifications

• Review logs for authentication or connection issues

Best Practices for Asset Quality

• Always upload highest-resolution, lossless formats (TIFF, PNG)

• Dynamic Media can ingest CMYK assets and convert them to RGB automatically

• Avoid maintaining separate print and web asset libraries—presets handle conversion

---

A Simple Analogy: Dynamic Media as a Master Chef’s Kitchen

Think of Dynamic Media like a master chef, not a frozen food factory.

Instead of pre-packaging thousands of identical meals (static assets), the chef keeps fresh, high-quality ingredients (primary assets). When a customer places an order (a URL request), the chef prepares the dish instantly—perfectly sized, optimized, and presented for that customer’s device.

Fresh. Fast. Perfect—every time.

---

Final Thoughts

By centralizing asset management and automating delivery:

• Dynamic Media ensures consistent brand experiences

• Improves performance and scalability

• Reduces operational overhead

• Prepares your content for any screen, any network

Whether you’re building high-performance AEM sites or delivering rich media globally, Dynamic Media is a foundational capability—not an optional add-on.

AEM RepoInit: Simplifying JCR Repository Initialization in AEM as a Cloud Service

AEM RepoInit is a powerful and declarative mechanism in Adobe Experience Manager (AEM) that helps developers initialize and configure the JCR repository during application startup. Introduced to support modern DevOps practices, RepoInit is especially important in AEM as a Cloud Service, where traditional runtime repository modifications are restricted.

What Is RepoInit in AEM?

RepoInit allows you to define repository structures, users, groups, access control lists (ACLs), and service users using plain text scripts. These scripts are executed automatically when the AEM instance starts, ensuring a consistent and repeatable repository state across all environments.

Why RepoInit Is Important in AEM as a Cloud Service

In AEM Cloud, direct repository changes using CRXDE or ad-hoc scripts are discouraged. RepoInit provides a cloud-compliant way to:

• Create folders and nodes in the JCR

• Define users and groups

• Assign permissions and ACLs

• Configure service users securely

• Maintain environment parity (local, dev, stage, prod)

Key Benefits of Using RepoInit

• Declarative and version-controlled: RepoInit scripts are stored in Git alongside your code.

• Environment consistency: Ensures the same repository setup across all AEM environments.

• Cloud-friendly: Fully supported and recommended for AEM as a Cloud Service.

• Reduced manual effort: Eliminates post-deployment manual configurations.

Common RepoInit Use Cases

• Creating application-specific folders under /content or /conf

• Setting up service users for OSGi services

• Defining permissions for editors and authors

• Initializing repository structures during CI/CD deployment

Conclusion

AEM RepoInit is an essential tool for modern AEM development, enabling safe, automated, and repeatable repository initialization. For teams adopting AEM as a Cloud Service, mastering RepoInit is critical to building scalable and maintainable AEM applications while following Adobe’s best practices.

Building Headless AEM Apps Using Content Fragments: A Complete Guide

 Adobe Experience Manager (AEM) is no longer just a traditional CMS for page-based websites-it has evolved into a powerful

This article explains how to build headless AEM applications using Content Fragments, with a step-by-step development flow, architectural guidance, and best practices.

---

 What Are Content Fragments in AEM?

Content Fragments are structured, channel-agnostic content units stored in AEM’s DAM.
They are ideal for headless scenarios because:

• They follow schema-defined models

• They deliver raw structured content (JSON)

• They are reusable across apps, channels, and devices

• They decouple content from presentation

Example use cases:

• Mobile app content (banners, FAQs, promotions)

• Product details and catalogs

• Multi-language content distribution

• Chatbot or voice assistant responses

• API-driven websites or micro frontends

---

 How Content Fragment Models Work

A Content Fragment Model (CFM) defines the structure of a fragment.
Typical field types include:

• Text (plain or rich)

• Multi-line text

• Number

• Boolean

• Enumeration

• Date/time

• JSON objects

• References to other fragments (nested content)

• Content references (DAM, images, etc.)

A well-designed CFM acts like a lightweight backend schema.

Example CFM (Blog Post):

• Title

• Summary

• Body (rich text)

• Author

• Tags

• Publish Date

• Related Articles (fragment reference)

---

 Why Use Content Fragments for Headless Apps?

1. Pure Headless JSON Output

AEM provides out-of-the-box JSON endpoints via:

• Content Fragment APIs

• AEM GraphQL APIs

• Sling Model Exporter (optional for custom structures)

2. Reusable Structured Content

CFs can be reused across:

• Apps

• Websites

• Campaigns

• Voice interfaces

• Third-party systems

3. Built-in Governance

• Versioning

• Workflows

• Approvals

• Translation

• Multi-site management

4. Cloud-Ready Scaling

In AEM as a Cloud Service, headless delivery automatically scales globally.

---

 Building a Headless AEM App Using Content Fragments (Step-by-Step)

Step 1: Create a Content Fragment Model

1. Go to Tools → Assets → Content Fragment Models

2. Create a new model (ex: “Product Details”)

3. Add fields:

   • Product Name

   • Price

   • Description

   • Image

   • Specifications (JSON)

4. Save and publish the model

Step 2: Create Content Fragments

1. Go to Assets → Files

2. Create a new fragment using your model

3. Enter structured content

4. Add references or nested fragments if needed

5. Publish the fragments

Step 3: Expose Content via JSON (Two Options)

---

Option A: Using AEM GraphQL APIs (Recommended)

GraphQL is the preferred headless API for complex queries.

Example query:

{ productList { items { name price description image { ... on Asset { _path } } } } }

Endpoint example:
/content/graphql/global/endpoint.json

Benefits:

• Dynamic filtering

• Query only required fields

• Faster payloads

---

Option B: Direct CF JSON API

Default JSON endpoint:

https://publish.author-domain/content/dam/path/to/cf.model.json

Best for:

• Simple apps

• Static integrations

• Low-logic use cases

---

 Step 4: Consume Content in Your App

Use CF JSON in any frontend:

• React

• Angular

• Vue

• iOS / Android

• Flutter

• Next.js / Nuxt.js

Example React fetch:

fetch("https://publish-domain/content/dam/app/products/product1.model.json") .then(res => res.json()) .then(data => console.log(data));

Or use GraphQL:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client'; const client = new ApolloClient({ uri: '/content/graphql/global/endpoint.json', cache: new InMemoryCache() }); client.query({ query: gql` { productList { items { name price description } } } ` }).then(result => console.log(result));

---

 Step 5: Deploy & Integrate at Scale

On AEM as a Cloud Service:

• CF APIs are globally cached

• Publish tier auto-scales

• CDN caching + edge delivery optimizes load

• Pipelines ensure safe deployments

---

 Best Practices for Headless AEM Using CFs

1. Keep CF Models small & reusable

Avoid bloated schemas; break content into smaller fragments.

2. Use fragment references for relationships

Good for product families, related posts, FAQs, etc.

3. Prefer GraphQL over JSON endpoints

More efficient, especially for filtering and multi-level queries.

4. Enable caching with immutable paths

CF JSON paths work great with CDN caching.

5. Use AEM workflows for approvals

Ensure consistent publishing across channels.

6. Don’t mix presentation logic into CFs

UI should be controlled by the consuming app.

---

 Conclusion

Content Fragments make AEM a powerful headless CMS.
By combining robust content modeling, GraphQL APIs, and cloud scalability, AEM enables developers to build fast, flexible, and enterprise-grade omnichannel applications.

Whether you’re building a mobile app, a React SPA, or a global multi-channel platform, Content Fragments deliver clean structured content that fits seamlessly into modern headless architectures.

Decoding AEM's JCR: A Developer's Guide to Node Types and Content Structure

If Adobe Experience Manager (AEM) is the heart of your digital experience, then

Nodes form a tree-like, hierarchical structure within the repository, much like a computer's file system, serving as the building blocks for all content. Each node is defined by a specific type, which dictates the permitted properties (name-value pairs holding the actual data) and allowed child nodes.

Here is a comprehensive overview of the node structure that powers AEM.

---

The Three Pillars of AEM Node Types

AEM’s robust structure stems from its underlying technologies. Because AEM leverages both the Apache Sling framework for request processing and the Java Content Repository (JCR) specification for data storage, it utilizes node types originating from three distinct categories:

1. JCR Node Types: The foundational, core types defined by the JCR specification (e.g., nt: and mix:).
2. Sling Node Types: Types introduced by the Apache Sling framework, often related to resource resolution and folder structures (e.g., sling:).
3. AEM Custom Node Types: Specific types created by Adobe to manage high-level CMS concepts like pages, components, workflows, and assets (e.g., cq: and dam:).

To inspect the definitive, current list of all associated properties and definitions, developers can always use CRXDE to browse the AEM repository at /jcr:system/jcr:nodeTypes.

---

1. JCR Node Types: The Foundation

JCR node types provide the basic blueprint for storing data, enforcing rules, and creating hierarchy.

Primary Node Types (The Structure)

Every node must have one declared primary node type.

• nt:base: This is the abstract base primary node type from which all others inherit. It is crucial because it ensures every node exposes two properties related to its type: jcr:primaryType (the node’s type name) and jcr:mixinTypes (a list of applied mixin types).
• nt:unstructured: This is a highly flexible type used for storing unstructured content. It allows for any number of child nodes or properties with arbitrary names, and it supports client-orderable child nodes.
• nt:hierarchyNode: This abstract node type serves as the supertype for structural elements like nt:file and nt:folder.
• nt:file / nt:folder: These types are used to represent standard file system concepts. An nt:file node requires a child node, typically named jcr:content, which often uses the nt:resource type to hold the actual file content.
• nt:resource: Used to represent file content itself, notably defining the mandatory binary property jcr:data.

Mixin Node Types (The Features)

Mixin node types are added to specific node instances to incorporate additional characteristics, often related to repository features or metadata. A node can have zero or more mixin types.

• mix:title: Adds standardized metadata properties, namely jcr:title and jcr:description.
• mix:created: Used to add creation tracking properties, such as jcr:created (the date) and jcr:createdBy (the user). These properties are often auto-created and protected by the repository.
• mix:lastModified: Provides modification tracking via jcr:lastModified and jcr:lastModifiedBy.
• mix:referenceable: Makes a node capable of being referenced, adding the mandatory, protected, auto-created jcr:uuid property which exposes the node's identifier.

2. Sling Node Types

Apache Sling defines node types generally focused on resource and folder handling. Examples of Sling node types defined primarily in the JCR resource bundle include sling:Resource, sling:Folder, and sling:VanityPath. Notably, the cq:PageContent node type inherits from sling:Resource.

3. AEM Custom Node Types

These types, typically prefixed with cq: (for content query/core) or dam: (for digital asset management), define the functionality that AEM developers interact with every day.

Web Content Management (WCM) Structures

AEM organizes content using specific WCM node types:

Node Type	Description	Key Properties / Subnodes
cq:Page	Defines the overall AEM page structure.	Mandatory child node jcr:content (which holds the primary content).
cq:PageContent	Defines the content node underneath cq:Page. This node holds WCM-specific properties.	jcr:title, cq:template (path to the template), navTitle (used in navigation), hideInNav, onTime, and offTime.
cq:Template	Defines an AEM template.	jcr:content (default content for new pages), allowedParents, allowedChildren, and ranking.
cq:Component	Defines an AEM component.	jcr:title, componentGroup, dialog (primary dialog node), design_dialog (design dialog node).
cq:EditConfig	Defines the configuration for the edit bar of a component.	cq:dialogMode, cq:layout, cq:actions, and subnode cq:inplaceEditing.

Digital Asset Management (DAM)

The DAM structure uses specialized nodes for managing assets:

• dam:Asset: Defines a DAM asset. It is a hierarchy node that requires a mandatory child node named jcr:content of type dam:AssetContent.
• dam:AssetContent: Defines the content structure of an asset, containing subnodes for metadata and renditions.

Operational and Workflow Nodes

AEM uses node types to track system state and processes:

• cq:ReplicationStatus: A critical mixin that exposes replication status information, including properties like cq:lastReplicated, cq:lastReplicatedBy, and cq:lastReplicationAction (which can be 'activate' or 'deactivate').
• cq:Workflow: Represents an active instance of a workflow.
• cq:WorkflowModel: Represents the definition of a workflow.
• cq:Tag: Defines a single tag, which can also contain other tags, thus creating a taxonomy.
• cq:Taggable: An abstract base mixin used for content that can be tagged.

By mastering these fundamental building blocks—from the JCR nt:base that ensures node identity, to the cq:PageContent that holds your page's metadata, and the cq:ReplicationStatus that tracks publishing state—you gain the ability to efficiently organize and retrieve all the data in your AEM instance.

---

In essence, understanding AEM nodes is like knowing the alphabet before writing a novel. Each node type is a specific letter or punctuation mark, and only by using the correct ones in the right hierarchy can you construct a coherent and functioning piece of content architecture.

The OSGi Framework: Unlocking Dynamic Modularity in Java and AEM

The development of large-scale Java applications often struggles with complexity and rigidity. Historically, updating a single feature meant stopping and redeploying the entire application. The -OSGi Framework- (Open Services Gateway initiative) was created to solve this problem by introducing true modularity and dynamism.

OSGi is a -modular, dynamic Java framework- designed for building Java applications as a set of loosely-coupled modules. This dynamic, modular architecture serves as the foundation for how Adobe Experience Manager (AEM) organizes its backend modules and components.

# 1. The Core Unit: Bundles

In the OSGi architecture, the basic modular unit is the -bundle-. A bundle is essentially a standard Java Archive (JAR) file, but it is combined with a manifest file (-MANIFEST.MF-) enriched with OSGi-specific headers.

This manifest is vital because it defines important metadata, including the bundle's unique symbolic name and version. Crucially, it dictates how the code interacts with the outside world by specifying -exported packages- (what code is exposed) and -imported packages- (what dependencies are required). By strictly managing these package definitions, the OSGi framework enforces the modular, loosely-coupled design philosophy.

# 2. The Dynamic Advantage: Runtime Management

The key differentiator of OSGi is its dynamic runtime capability, which governs the -bundle lifecycle-.

Unlike monolithic applications, bundles go through a lifecycle managed by OSGi: they can be -installed-, -resolved- (meaning dependencies are satisfied), and -started- (activated). The immense flexibility stems from the ability to manage these states dynamically. Bundles can be -stopped, updated, or removed at runtime-—without requiring a full application restart. This means that bugfixes or new features can replace only the relevant bundles, dramatically streamlining maintenance and upgrades.

# 3. OSGi as the Foundation of AEM

In the context of AEM, this dynamic architecture is fundamental. Instead of acting as a monolithic Java web-app, AEM and its extensions are built as many small, modular bundles. This structure enables easier maintenance, upgrades, reuse, and the crucial dynamic runtime behavior that AEM developers rely on.

Many functional pieces within the AEM context, such as custom services, utilities, and third-party integrations, are packaged specifically as OSGi bundles.

# 4. Communication and Customization

With so many independent modules running, the OSGi Framework requires structured ways for them to communicate and be customized:

## Services and Components

To facilitate communication between bundles, OSGi provides a -service registry- mechanism.

1.  -Services:- These are Java interfaces or classes that provide specific functionality. Bundles that implement a feature can -register a service implementation- with the service registry.
2.  -Components:- A -component- is the logical module—the class within a bundle—that either implements services or depends on other services. Other bundles or components can then dynamically -discover and consume- that service via the registry. Components manage their own lifecycle within the OSGi runtime.

## Configuration

For true flexibility, components must be customizable without changing the underlying code. OSGi supports the -external configuration- of components to manage configurable parameters, such as external API URLs, feature toggles, or environment-specific settings.

In AEM, these configurations are defined using JSON-based -.cfg.json- files. By placing these files in run-mode specific folders, developers can ensure different settings are applied for environments like DEV, QA, or PROD.

# Summary

The OSGi Framework successfully integrates these concepts to achieve enterprise-level modularity:

*   -Bundles- package the code.
*   -Components- inside bundles implement functionality and provide or consume -Services- via the registry.
*   -Configurations- allow customizing behavior dynamically per environment.

Fixing Author-to-Author Migration Mistakes in AEM as a Cloud Service: How to Recover Publish State Correctly

Migrating from AEM On-Premise to AEM as a Cloud Service (AEMaaCS) involves a precise content strategy. The industry-standard and Adobe-recommended practice is:

• Author → Author migration for authored content

• Publish → Publish migration for live site content

  
  
  

This ensures that the AEM Cloud Publish environment accurately reflects real production, while Author carries the drafts, workflows, approvals, and creation history.

However, mistakes do happen—and one of the most common (and most damaging) is migrating everything from Author → Author and then accidentally publishing all content to Cloud Publish.

This article explains why this is a problem, what risks it introduces, and—most importantly—how to fix it safely and correctly.

---

Understanding the Mistake: Author-to-Author Migration Followed by “Publish All”

In the mistaken scenario:

1. Your team migrated all content from On-Prem Author → AEM Cloud Author

2. Then executed a bulk publish, sometimes unintentionally

3. As a result:

   • Draft-only content is now publicly visible

   • Deactivated pages from on-prem are active again

   • Historical publish status is lost

   • AEMaaCS Publish does not reflect the real production environment

   • Audit records and approval workflows have been bypassed

This leads to a polluted publish repository, breaking the very purpose of maintaining a trusted live environment.

---

Why This Is Serious

Incorrect publish data affects:

1. SEO & Public Visibility

Internal pages, test pages, and drafts may get indexed by Google.

2. Compliance & Governance

Pages that were intentionally un-published are suddenly active.

3. Authoring Confidence

Teams can no longer trust what is “live.”

4. Replication Metadata

Original activation dates, users, and states are lost forever.

5. Future Deployments

Content freeze and UAT validation become unreliable.

Fixing this requires a structured, safe approach.

---

How to Fix Wrong Author-to-Author Publishing During Migration

Below are the best and safest approaches, starting with the recommended one.

---

Option 1: Re-Do Publish Migration Properly (Recommended Solution)

This is the cleanest and most accurate method—ideal if you are still in pre-production stages.

Steps:

1. Reset AEM Cloud Publish Environment
   Request Adobe/Cloud Manager to wipe and reinitialize Publish.

2. Re-export content from On-Prem Publish

   Use cloned instance and Content Transfer Tool 

3. Import to AEM Cloud Publish → Publish
   This restores the true, correct, production content.

4. Re-run Author-only delta migration
   If content changed on on-prem author, sync only those changes.

Result:
AEM Cloud Publish now accurately matches your pre-migration live site.

---

Option 2: Use Replication Metadata to Undo Incorrect Publishing

If restarting migration is not feasible, you can restore state using metadata.

Steps:

1. Export /var/replication metadata from On-Prem Publish

2. Compare it with AEM Cloud’s metadata

3. Identify:

   • Pages that should NOT be published

   • Pages that were previously deactivated

   • Pages with mismatched activation timestamps

4. Using a script or ACS Bulk Replicator:

   • Deactivate incorrect pages

   • Re-publish only valid published pages

This is effective, but not perfect—you may miss some edge cases.

---

Option 3: Partial Cleanup for Limited Content Areas

Use this if only some sections of the site were impacted.

Steps:

1. Identify URLs incorrectly published

2. Get confirmation from business/UAT

3. Use Bulk Unpublish scripts to deactivate

4. Re-publish only approved content

Good for small or medium-sized sites, but not for large enterprise DAM/content.

---

What You Should NOT Do

• Do not manually check pages one-by-one — impossible for large sites

• Do not trust authors to identify wrong-published pages — risky & incomplete

• Do not keep the polluted publish environment — it breaks future releases

• Do not adjust publish directly without metadata analysis — creates inconsistencies

---

Recommended Final Strategy

If you need a clean and correct fix:

➡️ Reset Publish + Re-import Publish-to-Publish Migration

Then:

➡️ Run a delta Author migration

This is how 90% of enterprise projects recover from this mistake and move forward safely.

---

Conclusion

Migrating to AEM as a Cloud Service requires strict alignment between Author and Publish flows.
When everything is migrated Author → Author and mistakenly published, it disrupts production integrity, governance, SEO, and live accuracy.

Fortunately, with the methods described:

• Full republish rebuild

• Metadata-driven cleanup

• Partial environment correction

You can restore your AEM Cloud Publish environment back to the correct state.

No matter where you are in your migration cycle, there is a safe recovery path.