I85PREP
⌘ K
AEM Sites Business Practitioner Expert study materials
AEM Sites Business Practitioner Expert study resources

Component Dialog Change Breaks 3,000 Existing Pages

AEM Sites Business Practitioner Expert · Put your knowledge to work in context.

All case studies

Component Dialog Change Breaks 3,000 Existing Pages

A media company has a custom 'Article Teaser' component used on roughly 3,000 pages across the site. The component's dialog currently stores a single teaserPath property pointing to an asset. The design team wants to support multiple teasers per component and a new required 'category' field. A developer proposes changing the dialog to a multifield and making category mandatory. The site has a large amount of live content, editors are mid-campaign, and there is no formal content-freeze window. The component is also used inside an Experience Fragment that appears on 40 pages. The team uses editable templates; the Article Teaser is allowed on the article template and the landing template.

1. What are the main risks of making `category` a required field and switching `teaserPath` to a multifield, and how should the practitioner sequence the change?

Read the worked answer

Risks:

  1. Required field + existing content. Making category mandatory means the ~3,000 existing instances have no value. Depending on dialog validation, authors may be blocked from saving pages until every teaser is edited. That is a content migration, not a dialog tweak.
  2. Data shape change. teaserPath (single value) → multifield (multi-value) changes the stored property type. Existing HTL/Sling Model code reading a single string will break or render nothing until migrated. A multifield usually writes a String[] or child nodes, which is a different contract.
  3. Experience Fragment blast radius. The component inside an XF means a change affects 40 pages indirectly; editors may not connect the XF edit to those pages.

Sequencing:

  1. Make the new fields optional first; add the multifield alongside the old property with fallback logic in the model (read multifield if present, else legacy single value).
  2. Backfill/migrate content via a controlled script or workflow, verifying on a sample.
  3. Only after migration coverage is confirmed, consider enforcing category (and even then, prefer a soft warning or default over a hard block).
  4. Test the XF path explicitly and republish affected XFs.

Judgement: never make a field mandatory on a component with thousands of live instances without a migration and a fallback period.

2. The developer wants to change the component's resource type name and the template policy in the same release. Why is that risky, and what should the practitioner advise?

Read the worked answer

Changing the resource type (e.g., .../articleTeaser → .../articleTeaser/v2) means every existing instance still points at the old resource type. Unless the old component remains and proxies to the new one, those 3,000 pages render with a missing/blank component. Combined with a template policy change in the same release, you lose the ability to isolate which change caused a regression.

Advice:

  1. Keep the old resource type as a shim that delegates to the new implementation, or migrate instances in a separate step.
  2. Separate the releases: (a) ship new component + shim + optional fields, (b) migrate content, (c) update template policies to allow/require the new component, (d) retire the old one after verification.
  3. Template policy changes affect what authors can drop on the article and landing templates; do this after content migration so editors are not blocked mid-campaign.
  4. Verify the XF still resolves after the resource type change.

Judgement: resource type renames are effectively a content migration. Bundling them with policy changes removes rollback safety and makes incident triage impossible.