Fragment Library Drift Across Environments
An enterprise maintains 40 Adaptive Forms assembled from a shared library of 120 form fragments (panels, address blocks, consent sections). Development, staging, and production are separate AEM author instances with package-based promotion. After a release, production forms show an outdated consent fragment (v3) while staging shows v4. The fragments are referenced by path, and the promotion package was built from a filtered package that included only the 40 form pages, not the fragment nodes. Two forms also fail to render on production with a missing-resource error for a fragment path that exists in staging. The team wants a repeatable promotion process and asks whether fragments should be embedded or referenced.
1. Diagnose why production shows v3 consent and why two forms throw missing-resource errors.
Read the worked answer
Both symptoms share one root cause: the promotion package did not carry the fragment dependency graph.
- Consent v3 on production: the fragment node was never updated by the package, so production retains its prior content. Staging shows v4 because v4 was authored there. The forms themselves were promoted, but a form is only a reference to the fragment path; promoting the form does not promote the fragment.
- Missing-resource errors: those two forms reference fragment paths that exist in staging but were never created on production - a path that was authored after the last full fragment sync. A reference to a nonexistent path fails at render.
So the failure is dependency management, not form logic. The filtered package was scoped to form pages and silently excluded the fragment subtree.
2. Recommend how to make promotion repeatable, including how to choose between referenced and embedded fragments.
Read the worked answer
Make the dependency explicit and promote it atomically.
- Build the package to include the fragment library subtree (or the specific fragment paths the forms reference) alongside the forms, so a release is one consistent unit. Verify with a package dependency/preview check before promotion.
- Add a pre-promotion validation that resolves every fragment reference in the target package against the target environment and fails the build on dangling paths. This catches the two missing-resource forms before they reach production.
- Version fragments deliberately: if consent is a compliance artifact, treat fragment versions as release-gated content, not free-floating authoring.
Referenced vs embedded:
- Referenced fragments are right when the same fragment must stay consistent across many forms and updates should propagate - but only if the promotion process carries the fragment. That is the fix here.
- Embedded fragments are right for one-off, form-specific content that must not change when the shared library changes. Embedding the consent block would freeze it per form and defeat the goal of a single compliance source.
Given 40 forms sharing a consent block, keep it referenced and fix the pipeline, rather than embedding 40 copies.