Sites Repository Restructuring in AEM 6.5

Last update: April 9, 2024

CREATED FOR:

  • Admin

As described on the parent Repository Restructuring in AEM 6.5 page, customers upgrading to AEM 6.5 should use this page to assess the work effort associated with repository changes impacting the AEM Sites Solution. Some changes require work effort during the AEM 6.5 upgrade process, while others can be deferred until a future upgrade.

With 6.5 Upgrade

Prior to Future Upgrade

With 6.5 Upgrade

ContextHub Segments

Previous location/etc/segmentation/contexthub
New location(s)

/apps/settings/wcm/segments

/conf/settings/settings/wcm/segments

/conf/<tenant>/settings/wcm/segments

Restructuring guidance

If any new or modified ContextHub Segments are edited in source control rather than being edited in AEM, they must be migrated to the new location:

  1. Copy any new or modified ContextHub Segments from the previous location to the appropriate new location (https://experienceleague.adobe.com/%3Ccode%3Eapps%3C/code%3E,%20%3Ccode%3E/conf/global%3C/code%3E%20or%20%3Ccode%3E/conf/<tenant>%3C/code%3E?lang=en)
  2. Update references to ContextHub Segments in the previous location to the migrated ContextHub Segments in the new locations (/apps, /conf/global, /conf/<tenant>).

The following QueryBuilder query locates all references to ContextHub Segments in the Previous Locations.

\

\

path=/content property=cq:segments property.operation=like property.value=/etc/segmentation/contexthub/%

\

\

This can be executed via

AEM QueryBuilder Debugger UI

. Note that this is a traversing query, so do not run it against production, and ensure traversal limits adjusted as needed.

Notes

ContextHub Segments persisted to the previous location display as read-only in AEM > Personalization > Audiences.

If ContextHub Segments are to be editable in AEM, they must be migrated to the new location (/conf/global or /conf/<tenant>). Any new ContentHub Segments segments created in AEM are persisted to the new location (/conf/global or /conf/<tenant>).

AEM Sites Page Properties only allow either the Previous Location (/etc) or a single new location (/apps, /conf/global or /conf/<tenant>) to be selected, thus ContextHub Segments must be migrated accordingly.

Any unused ContextHub Segments from AEM reference sites can be removed and not migrated to the New Location:

  • /etc/segmentation/geometrixx/
  • /etc/segmentation/geometrixx-outdoors

Note: If ClientContext is in use, it is recommended to convert to ContextHub.

Prior to Future Upgrade

Adobe Analytics Client Libraries

Previous location/etc/clientlibs/foundation/sitecatalyst
New location(s)/libs/cq/analytics/clientlibs/analytics
Restructuring guidance

Any custom use of these Client Libraries should reference the Client Library by category, and not by path:

  1. Any references to the Client Library by path at the Previous Location should be updated to use AEM's Client Library referencing framework.

  2. If AEM's Client Library referencing framework cannot be used, the absolute path of the Client Libraries can be referenced via AEM's Client Library Proxy servlet.

    • /etc.clientlibs/cq/analytics/clientlibs/sitecatalyst/appmeasurement.js
    • /etc.clientlibs/cq/analytics/clientlibs/sitecatalyst/plugins.js
    • /etc.clientlibs/cq/analytics/clientlibs/sitecatalyst/sitecatalyst.js
    • /etc.clientlibs/cq/analytics/clientlibs/sitecatalyst/tracking.js
    • /etc.clientlibs/cq/analytics/clientlibs/sitecatalyst/util.js
Notes

Editing of these Client Libraries was never supported.

To obtain the Client Library categories, visit each cq:ClientLIbraryFolder node via CRXDELite and inspect the categories property.

  • /libs/cq/analytics/clientlibs/sitecatalyst/appmeasurement
  • /libs/cq/analytics/clientlibs/sitecatalyst/plugins
  • /libs/cq/analytics/clientlibs/sitecatalyst/sitecatalyst
  • /libs/cq/analytics/clientlibs/sitecatalyst/tracking
  • /libs/cq/analytics/clientlibs/sitecatalyst/util

Classic Microsoft Word to Web Page Designs

Previous location/etc/designs/wordDesign
New location(s)

/libs/settings/wcm/designs/wordDesign

/apps/settings/wcm/designs/wordDesign

Restructuring guidance

For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.

  1. Copy the designs from the Previous Location to the New Location (/apps).
  2. Convert any CSS, JavaScript and static resources in the Design to a Client Library with allowProxy = true.
  3. Update references to the Previous Location in the cq:designPath property.
  4. Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
  5. Update AEM Dispatcher rules to allow serving of Client Libraries via the /etc.clientlibs/ proxy servlet.

For any Designs that NOT managed in SCM, and modified run-time via Design Dialogs:

  • Do not move author-able Designs out of /etc.
NotesN/A

Mobile Device Emulator Configurations

Previous location/etc/mobile
New location(s)

/libs/settings/mobile

/apps/settings/mobile

/conf/global/settings/mobile

/conf/<tenant>/settings/mobile

Restructuring guidance

Any new Mobile Device Emulator Configurations must be migrated to the New Location.

  1. Copy any new Mobile Device Emulator Configurations from the Previous Location to the new location (/apps, /conf/global, /conf/<tenant>).
  2. For any AEM Sites Pages that depend on these Mobile Device Emulator Configurations, update the Page's jcr ``:content node:
    [cq:Page]/jcr:content@cq: deviceGroups = String[ mobile/groups/responsive ]
  3. For any Editable Templates that depend on these Mobile Device Emulator Configurations, update the Editable Templates, pointing the cq : deviceGroups to the New Location.
Notes

Mobile Device Emulator Configurations resolution occurs in the following order:

  1. /conf/<tenant>/settings/mobile
  2. /conf/global/settings/mobile
  3. /apps/settings/mobile
  4. /libs/settings/mobile
  5. /etc/mobile

Multi-site Manager Blueprint Configurations

Previous location/etc/blueprints
New location(s)

/apps/msm (Customer Blueprint configurations)

/libs/msm (Out Of the Box Blueprint configurations for Screens, Commerce)

Restructuring guidance

Any new or modified Multi-site Manager Blueprint Configurations must be migrated to the New Location (/apps).

  1. Copy any new or modified Multi-site Manager Blueprint Configurations from the Previous Location to the New Location (/apps).
  2. Remove any migrated Multi-site Manager Blueprint Configurations from the Previous Location.
Notes

All AEM provided Multi-site Manager Blueprint Configurations exist in the New Location in /libs.

Content does not reference the Multi-site Manager Blue Configurations therefore there are not content references to adjust.

Multi-site Manager Rollout Configurations

Previous location/etc/msm/rolloutConfigs
New location(s)

/libs/msm/wcm/rolloutconfigs

/apps/msm/wcm/rolloutconfigs

Restructuring guidance

Any new or modified Multi-site Manager Rollout Configurations must be migrated to the New Location.

  1. Copy any new or modified Multi-site Manager Rollout Configurations from the Previous Location to the new location (/apps).
  2. Update any references on AEM Pages to Multi-site Manager Rollout Configurations in the Previous Location, to point to their counterparts in the New Locations (/libs or /apps).

Remove migrated Multi-site Manager Rollout Configurations from the Previous Location.

NotesFailing to remove migrated Multi-site Manager Rollout Configurations from the Previous Location results in duplicate rollout options displayed to AEM authors.

Page Event Notification E-mail Template

Previous location/etc/notification/email/default/com.day.cq.wcm.core.page
New location(s)

/libs/settings/notification-templates/com.day.cq.wcm.core.page

/apps/settings/notification-templates/com.day.cq.wcm.core.page

Restructuring guidance

The only supported new Page Event Notification E-mail Templates are to support new locales.

Page Event E-mail Template resolution occurs in the following order:

  1. /etc/notification/email/default/com.day.cq.wcm.core.page
  2. /apps/settings/notification-templates/com.day.cq.wcm.core.page
  3. /libs/settings/notification-templates/com.day.cq.wcm.core.page
Notes

Any new or modified Page Event Notification E-mail Templates must be migrated to the new location under /apps:

  1. Copy any new or modified Page Event Notification E-mail Templates from the Previous Location to the new location (/apps).
  2. Remove any migrated Page Event Notification E-mail Templates from the Previous Location.

Page Scaffolding

Previous location/etc/scaffolding
New location(s)/libs/settings/ wcm /template-types/scaffolding/scaffolding/apps/settings/ wcm /template-types/scaffolding/scaffolding
Restructuring guidanceScaffolding created under the Previous Location uses the legacy Scaffolding framework and cannot be migrated to the New Location. To align with the New Location any legacy Scaffolding must be re-developed using the supported Scaffolding framework.
NotesN/A

Responsive Grid LESS

Previous location/etc/clientlibs/wcm/foundation/grid/grid_base.less
New location(s)/libs/wcm/foundation/clientlibs/grid/grid_base.less
Restructuring guidance

Any references to the Previous Location in custom LESS files must be updated to import from the New Location.

  • Update any referencing custom LESS files that reference grid_base.less in the Previous Location to reference the new location.
NotesReferencing a non-existing grid_base.less file results in the Layout Mode of the Page and Template Editor not working, and a disruption of page layout.

Static Template Designs

Previous location/etc/designs/<custom-site>
New location(s)/apps/settings/wcm/designs/<custom-site>
Restructuring guidance

For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.

  1. Copy the designs from the Previous Location to the New Location (/apps).
  2. Convert any CSS, JavaScript and static resources in the Design to a Client Library with allowProxy = true.
  3. Update references to the Previous Location in the cq:designPath property via AEM > Sites > Custom Site Pages > Page Properties > Advanced Tab > Design Field.
  4. Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
  5. Update AEM Dispatcher rules to allow the serving of Client Libraries via the /etc.clientlibs/ proxy servlet.

For any Designs that NOT managed in SCM, and modified run-time via Design Dialogs:

  • Do not move author-able Designs out of /etc.
NotesThe recommended approach is to build AEM Sites and Pages using Editable Templates which use Structure Content and Policies in lieu of Designs.

Adobe Target Integration Client Libraries

Previous location/etc/clientlibs/foundation/target
New location(s)/libs/cq/testandtarget/clientlibs/testandtarget
Restructuring guidance

Any custom use of these Client Libraries should reference the Client Library by category, and not by path.

  1. Any references to the Client Library by path at the Previous Location should be updated to use AEM's Client Library referencing framework.
  2. If AEM's Client Library referencing framework cannot be used, the absolute path of the Client Libraries can be referenced via AEM's Client Library Proxy servlet:
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/testandtarget.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/atjs.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/atjs-integration.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/init.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/mbox.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/parameters.js
  • /etc.clientlibs/cq/testandtarget/clientlibs/testandtarget/util.js
Notes

Editing of these Client Libraries was never supported.

To obtain the Client Library categories, visit each cq:ClientLIbraryFolder node via CRXDELite and inspect the categories property:

  • /libs/cq/testandtarget/clientlibs/testandtarget/testandtarget
  • /libs/cq/testandtarget/clientlibs/testandtarget/atjs
  • /libs/cq/testandtarget/clientlibs/testandtarget/atjs-integration
  • /libs/cq/testandtarget/clientlibs/testandtarget/init
  • /libs/cq/testandtarget/clientlibs/testandtarget/mbox
  • /libs/cq/testandtarget/clientlibs/testandtarget/parameters
  • /libs/cq/testandtarget/clientlibs/testandtarget/util

WCM Foundation Client Libraries

Previous location/etc/clientlibs/wcm/foundation
New location(s)/libs/wcm/foundation/clientlibs
Restructuring guidance

Any custom use of these Client Libraries should reference the Client Library by category, and not by path.

  1. Any references to the Client Library by path at the Previous Location should be updated to use AEM's Client Library referencing framework.
  2. If AEM's Client Library referencing framework cannot be used, the absolute path of the Client Libraries can be referenced via AEM's Client Library Proxy servlet.
  • /etc.clientlibs/wcm/foundation/clientlibs/accessibility.css
  • /etc.clientlibs/wcm/foundation/clientlibs/main.css
  • /etc.clientlibs/wcm/foundation/clientlibs/main.js
Notes

Editing of these Client Libraries was never supported.

To obtain the Client Library categories, visit each cq:ClientLIbraryFolder node via CRXDELite and inspect the categories property:

  • /libs/wcm/foundation/clientlibs/accessibility
  • /libs/wcm/foundation/clientlibs/main

Experience Manager


Elevate and Empower Teams with Agentic AI for Exceptional Experiences

Online | Strategy Keynote | General Audience

Elevate and empower your CX teams with AI that transforms creativity, personalization, and productivity. Discover how Adobe is...

Tue, Mar 18, 1:00 PM PDT (8:00 PM UTC)

Register

3 Pillars of Purpose-driven Experiences: Trust, Data, and GenAI

In-person | Session | General Audience

Learn how leading B2B and B2C brands like AT&T and IBM are intersecting data, GenAI and trust to build “purpose-driven” experiences that...

Wed, Mar 19, 1:00 PM PDT (8:00 PM UTC)

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now