DocumentationAEM 6.4Deploying Guide

Common Repository Restructuring in AEM 6.4 common-repository-restructuring-in-aem

Last update: Wed May 03 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

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

With 6.4 Upgrade

Prior to 6.5 Upgrade

With 6.4 Upgrade with-upgrade

ContextHub Configurations contexthub-6.4

From AEM 6.4 onwards, there is no default ContextHub configuration. Therefore on the root level of the site a cq:contextHubPathproperty should be set to indicate which configuration should be used.

  1. Navigate to the root of the site.
  2. Open the page properties of the root page and select the Personalization tab.
  3. In the Contexthub Path field enter your own ContextHub configuration path.

Additionally on the ContextHub configuration, the sling:resourceType needs to be updated to be relative and not absolute.

  1. Open the properties of ContextHub configuration node in CRX DE Lite, e.g. /apps/settings/cloudsettings/legacy/contexthub
  2. Change sling:resourceType from /libs/granite/contexthub/cloudsettings/components/baseconfiguration to granite/contexthub/cloudsettings/components/baseconfiguration

I.e. the sling:resourceType of the ContextHub configuration must be relative rather than absolute.

Workflow Models workflow-models

Previous location
/etc/workflow/models
New location(s)

/libs/settings/workflow/models

/conf/global/settings/workflow/models

/var/workflow/models

Restructuring guidance

Any new or modified Workflow Models must be migrated to /conf/global/workflow/models.

  1. Deploy the modified Workflow Models into a local AEM 6.4 development instance, such that they exist in the Previous location.

  2. Edit the Workflow Model using AEM's Workflow Model Editor at AEM > Tools > Workflow > Models.

  3. When migrating modified AEM-provided Workflow Models

    1. With the Workflow Model Editor open, modify the browser's address URL, and replace the path segment /libs/settings/workflow/models with /etc/workflow/models.
      • For example, change: http://localhost:4502/editor.html /libs/settings/workflow/models/dam/update_asset.html to http://localhost:4502/editor.html /etc/workflow/models/dam/update_asset.html

  4. Enable Edit mode in the Workflow Model Editor which will copy the Workflow Model definition to /conf/global/workflow/models.

  5. Tap the Sync button to sync the changes to the Runtime Workflow Model under /var/workflow/models.

  6. Export both the Workflow Model (https://experienceleague.adobe.com/conf/global/workflow/models/<workflow-model>?lang=en) and Runtime Workflow Model (https://experienceleague.adobe.com/var/workflow/models/<workflow-model>?lang=en) and integrate into the AEM project.

    1. For example, export:

      • /config/settings/workflow/models/dam/my_workflow_model
        and
      • /var/workflow/models/dam/my_workflow_model
Notes

Workflow Model resolution occurs in the following order:

  1. /conf/global/settings/workflow/models
  2. /libs/settings/workflow/models
  3. /etc/workflow/models

Thus, any customizations of AEM-provided Workflow Models persisted in the Previous location must be moved to /conf/global/settings/workflow/models if they are to be retained, otherwise they will be superseded by the AEM-provided Workflow Model definition in /libs/settings/workflow/models.

Workflow Instances workflow-instances

Previous location
/etc/workflow/instances
New location(s)
/var/workflow/instances
Restructuring guidance

No action is required to align with the New Location.

Historical Workflow Instances can safely continue residing in the Previous Location, and new Workflow Instances will be created in the New Location.

Notes
Any explicit path references in custom code to the Previous Location should also take into account the New Location. It is recommended that this code is refactored to use the AEM Workflow APIs.

Workflow Launchers workflow-launchers

Previous location
/etc/workflow/launcher/config
New location(s)

/libs/settings/workflow/launcher/config

/conf/global/settings/workflow/launcher/config

Restructuring guidance

Any new or modified Workflow Launchers must be migrated to /conf/global/workflow/launcher/config.

  1. Copy any new or modified Workflow Launcher configurations from the Previous Location to New Location (/conf/global).
Notes

Workflow Launcher resolution occurs in the following order:

  1. /conf/global/settings/workflow/launcher
  2. /libs/settings/workflow/launcher
  3. /etc/workflow/launcher

Thus, any customizations of AEM-provided Workflow Launcher persisted in the Previous location must be moved to the New Location (/conf/global/settings/workflow/launcher if they are to be retained, otherwise they will be superseded by the AEM-provided Workflow Launcher definition in /libs/settings/workflow/launcher.

Workflow Scripts workflow-scripts

Previous location
/etc/workflow/scripts
New location(s)

/libs/workflow/scripts

/apps/workflow/scripts

Restructuring guidance

Any new or modified Workflow Scripts must be migrated to the New Location and the referencing Workflow Models updated to reflect the New Location.

  1. Copy any new or modified Workflow Scripts from the Previous Location to the New Location.
    • /apps/workflow/scripts should be maintained in SCM.
  2. Update any references to the Workflow Scripts at the Previous Location in Workflow Models to point to the New Locations.
Notes

AEM 6.4 SP1, when it is released, makes it so this restructuring can be deferred until 6.5 upgrade .

If upgrading to AEM 6.4 prior to AEM 6.4 SP1 being released, this restructuring should be performed as part of the upgrade project. Without doing so, editing and saving Workflow Steps referencing scripts in the Previous Location will remove the Workflow Script reference from the Workflow Step entirely, and only Workflow Scripts in New Locations will be available in the script selection drop-down.

Prior to 6.5 Upgrade prior-to-upgrade

ContextHub Configurations contexthub-configurations

Previous location
/etc/cloudsettings
New location(s)

/libs/settings/cloudsettings

/conf/global/settings/cloudsettings

/conf/<tenant>/settings/cloudsettings

Restructuring guidance

Any new or modified ContextHub Configurations must be migrated to the new location and the referencing AEM Sites pages must be updated to reflect the new location.

  1. Copy any new or modified ContextHub Configurations from the previous location to the new location.
  2. Associate the applicable AEM configurations with the AEM content hierarchies.
    1. AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
  3. Disassociate any migrated legacy ContextHub Configurations from the aforementioned AEM content hierarchies.
Notes
N/A

Classic Cloud Services Designs classic-cloud-services-designs

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

/libs/settings/wcm/designs/cloudservices

/apps/settings/wcm/designs/cloudservices

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 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.
Notes
N/A

Classic Dashboards Designs classic-dashboards-designs

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

/libs/settings/wcm/designs/dashboards

/apps/settings/wcm/designs/dashboards

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 (https://experienceleague.adobe.com/apps?lang=en).
  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 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.
Notes
N/A

Classic Reports Designs classic-reports-designs

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

/libs/settings/wcm/designs/reports

/apps/settings/wcm/designs/reports

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 (https://experienceleague.adobe.com/apps?lang=en).
  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 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.
Notes
N/A

Default Designs default-designs

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

/libs/settings/wcm/designs/default

/apps/settings/wcm/designs/default

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 (https://experienceleague.adobe.com/apps?lang=en).
  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 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.
Notes
N/A

Adobe DTM JavaScript Endpoint adobe-dtm-javascript-endpoint

Previous location
/etc/clientlibs/dtm
New location(s)
/var/cq/dtm/clientlibs
Restructuring guidance

No action required.

The public previous location acts as a proxy endpoint for the private new location.

Notes
N/A

Adobe DTM Web-Hook Endpoint adobe-dtm-web-hook-endpoint

Previous location
/etc/dtm-hook
New location(s)
/var/cq/dtm/web-hook
Restructuring guidance

No action required.

The public previous location acts as a proxy endpoint for the private new location.

Notes
N/A

Inbox Tasks inbox-tasks

Previous location
/etc/taskmanagement
New location(s)
/var/taskmanagement
Restructuring guidance
Use the Inbox Purge Maintenance Task to remove old tasks from the previous location as needed.
Notes

No action is required to migration Tasks to the new location.

  • Tasks present in the Previous Location continue to be available and function.
  • New Tasks are created in the New Location.

Multi-site Manager Blueprint Configurations multi-site-manager-blueprint-configurations

Previous location
/etc/blueprints
New location(s)

/libs/msm

/apps/msm

Restructuring guidance
  1. Copy custom configurations from /etc/blueprints to /apps/msm.
  2. Remove /etc/blueprints.
Notes
N/A

AEM Projects Dashboard Gadget Configurations aem-projects-dashboard-gadget-configurations

Previous location
/etc/projects/dashboard/gadgets
New location(s)

/libs/cq/core/content/projects/dashboard/gadgets

/apps/cq/core/content/projects/dashboard/gadgets

Restructuring guidance

Any new or modified AEM Projects Dashboard Gadget Configurations must be migrated to the new location (/apps).

  1. Copy any new or modified AEM Projects Dashboard Gadget Configurations from the previous location to the new location (/apps).
    1. Do not copy unmodified AEM Projects Dashboard Gadget Configurations as these now exist in the new location (/libs).
  2. Update any AEM Projects templates that reference the Previous Location to point to the appropriate new location.
Notes
If the AEM 6.4 compatibility package is applied, it will be necessary to perform the repository alignment activities at the time of the compatibility package's removal.

Replication Notification E-mail Template replication-notification-e-mail-template

Previous location
/etc/notification/email/default/com.day.cq.replication
New location(s)

/libs/settings/notification-templates/com.day.cq.replication

/apps/settings/notification-templates/com.day.cq.replication

Restructuring guidance

Any new or modified Replication Notification E-mail Templates must be migrated to the new location (/apps)

  1. Copy any new or modified Replication Notification E-mail Templates from the previous location to new location (/apps).
  2. Remove any migrated Replication Notification E-mail Templates from the previous location.
Notes

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

Replication Notification E-mail Template resolution occurs in the following order:

  1. /etc/notification/email/default/com.day.cq.replication
  2. /apps/settings/notification-templates/com.day.cq.replication
  3. /libs/settings/notification-templates/com.day.cq.replication

Tags tags

Previous location
/etc/tags
New location(s)
/content/cq:tags
Restructuring guidance

All Tags must be migrated to /content/cq:tags.

  1. Copy all Tags from the Previous Location to the New Location.
  2. Remove all Tags from the Previous Location.
  3. Via the AEM Web Console, restart the Day Communique 5 Tagging OSGi bundle at https://serveraddress:serverport/system/console/bundles/com.day.cq.cq-tagging for AEM to recognize the New Location contains content and should be used.
Notes

Restarting the Day Communique Tagging OSGi bundle will only register the New Location as the tag root if the Previous Location is empty.

References to the Previous Location will continue to work after migrating to New Location for all functionality that leverages AEM's TagManager API for tag resolution.

Any custom code that explicitly references the path

/etc/tags

must be updated to /content/

cq

:tags

, or preferably rewritten to leverage the TagManager Java API, in tandem with this migration.

Translation Cloud Services translation-cloud-services

Previous location
/etc/cloudservices/translation
New location(s)

/libs/settings/cloudconfigs/translation/translationcfg

/apps/settings/cloudconfigs/translation/translationcfg

/conf/global/settings/cloudconfigs/translation/translationcfg

/conf/<tenant>/settings/cloudconfigs/translation/translationcfg

Restructuring guidance

Any new Translation Cloud Services must be migrated to the new location (/apps, /conf/global or /conf/<tenant>).

  1. Migrate existing configurations in the previous location to the new location.

    • Manually recreate new Translation Cloud Services configurations via the AEM authoring UI at Tools > Cloud Services > Translation Cloud Services.
      OR
    • Copy any new Translation Cloud Services configurations from the Previous Location to the New Location (/apps, /conf/global or /conf/<tenant>).

  2. Associate the applicable AEM configurations with the AEM content hierarchies.

    1. AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
    2. AEM Experience Fragment hierarchies via AEM Experience Fragments > Experience Fragment > Properties > Cloud Services Tab > Cloud Configuration.
    3. AEM Experience Fragment Folder hierarchies via AEM Experience Fragments > Folder > Properties > Cloud Services Tab > Cloud Configuration.
    4. AEM Assets folder hierarchies via AEM Assets > Folder > Folder Properties > Cloud Services Tab > Configuration.
    5. AEM Projects via AEM Projects > Project > Project Properties > Advanced Tab > Cloud Configuration.

  3. Disassociate any migrated legacy Translation Cloud Services from the aforementioned AEM content hierarchies.

Notes

Translation Cloud Services resolution occurs in the following order:

  1. /conf/<tenant>/settings/cloudconfigs/translations/translationcfg
  2. /conf/global/settings/cloudconfigs/translations/translationcfg
  3. /apps/settings/cloudconfigs/translations/translationcfg
  4. /libs/settings/cloudconfigs/translations/translationcfg

Migrated Translation Cloud Services must be compatible with AEM 6.4.

Translation Languages translation-languages

Previous location
/etc/translation/supportedLanguages
New location(s)

/libs/settings/translation/supportedLanguages

/apps/settings/translation/supportedLanguages

Restructuring guidance

Any new or modified Translation Language definitions require a migration of all Translation Language definitions to the new location (/apps).

  1. If any additions or modifications have been made to the Translation Language definitions, then copy all Translation Language definitions from the previous location to the new location (/apps).
Notes

Translation Language path resolution occurs in the following order:

  1. /etc/translation/supportedLanguages
  2. /apps/settings/translation/supportedLanguage
  3. /libs/settings/translation/supportedLanguages

This resolution does not support a merging overlay, meaning the resolved path must contain all Supported Languages, and will not inherit Supported Languages from higher-order resolutions.

Translation Rules translation-rules

Previous location
/etc/workflow/models/translation/translation_rules.xml
New location(s)

/libs/settings/translation/rules/translation_rules.xml

/apps/settings/translation/rules/translation_rules.xml

/conf/global/settings/translation/rules/translation_rules.xml

Restructuring guidance

A modified Translation Rules XML file must be migrated to the new location (/apps, or /conf/global).

1. Copy the modified Translation Rules XML file from the previous location to the new location.

Notes

Replication Translation Rules XML resolution occurs in the following order:

  1. /conf/global/settings/translation/rules/translation_rules.xml
  2. /apps/settings/translation/rules/translation_rules.xml
  3. /etc/workflow/models/translation/translation_rules.xml
  4. /libs/settings/translation/rules/translation_rules.xml

Translation Widget Client Library translation-widget-client-library

Previous location
/etc/designs/translation/translationwidget
New location(s)

/libs/settings/wcm/designs/translation/translationwidget

/apps/settings/wcm/designs/translation/translationwidget

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 (https://experienceleague.adobe.com/apps?lang=en).
  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 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.
Notes
N/A

Tree Activation Web Console tree-activation-web-console

Previous location
/etc/replication/treeactivation
New location(s)
/libs/replication/treeactivation
Restructuring guidance
No action required.
Notes
The Tree Activation Web Console is now available via Tools > Deployment > Replication > Activate Tree.

Vendor Translation Connector Cloud Services vendor-translation-connector-cloud-services

Previous location
/etc/cloudservices/<vendor>
New location(s)

/libs/settings/cloudconfigs/translation/<vendor>

/apps/settings/cloudconfigs/translation/<vendor>

/conf/global/settings/cloudconfigs/translation/<vendor>

/conf/<tenant>/settings/cloudconfigs/translation/<vendor>

Restructuring guidance

Any new Vendor Translation Connector Cloud Services must be migrated to the new location (/apps, /conf/global or /conf/<tenant>).

  1. Migrate existing configurations in the Previous Location to the New Location.

    • Manually create net-new Vendor Translation Connector Cloud Services configurations via the AEM authoring UI at Tools > Cloud Services > Translation Cloud Services.
      OR
    • Copy any new Vendor Translation Connector Cloud Services configurations from previous location to the new location (/apps, /conf/global or /conf/<tenant>).

  2. Associate the applicable AEM configurations with the AEM content hierarchies.

    1. AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
    2. AEM Experience Fragment hierarchies via AEM Experience Fragments > Experience Fragment > Properties > Cloud Services Tab > Cloud Configuration.
    3. AEM Experience Fragment Folder hierarchies via AEM Experience Fragments > Folder > Properties > Cloud Services Tab > Cloud Configuration.
    4. AEM Assets folder hierarchies via AEM Assets > Folder > Folder Properties > Cloud Services Tab > Configuration.
    5. AEM Projects via AEM Projects > Project > Project Properties > Advanced Tab > Cloud Configuration.

  3. Disassociate any migrated legacy Translation Cloud Services from the aforementioned AEM content hierarchies.

Notes

Translation Cloud Services resolution occurs in the following order:

  1. /conf/<tenant>/settings/cloudconfigs/translations/<vendor>
  2. /conf/global/settings/cloudconfigs/translations/<vendor>
  3. /apps/settings/cloudconfigs/translations/<vendor>
  4. /libs/settings/cloudconfigs/translations/<vendor>

Workflow Notification Email Templates workflow-notification-email-templates

Previous location
/etc/workflow/notification
New location(s)

/libs/settings/workflow/notification

/conf/global/settings/workflow/notification

Restructuring guidance

Any modified Workflow Notification Email Templates must be migrated to the New Location (/conf/global).

  1. Copy any modified Workflow Notification Email Templates from the previous location to the new location.
  2. Remove migrated Workflow Notification Email Templates from the previous location.
Notes

Workflow Notification Email Template resolution occurs in the following order:

  1. /etc/workflow/notification
  2. /conf/global/settings/workflow/notification
  3. /libs/settings/workflow/notification

Workflow Packages workflow-packages

Previous location
/etc/workflow/packages
New location(s)
/var/workflow/packages
Restructuring guidance

Existing Workflow Packages in the previous location should be migrated to the new location.

  1. Remove any Workflow Packages in the previous location that are not referenced by other content and are otherwise not required.
  2. Move any Workflow Packages in the previous location that are not referenced by other content but otherwise required in the new location.
  3. Leave any Workflow Packages that are referenced by other content in the previous location.
Notes

Workflow Packages created via the Classic UI Miscadmin console are persisted in the previous location, while all others are persisted to the new location.

Workflow Packages stored in either the previous or lew locations can be managed via the Classic UI Miscadmin console.

recommendation-more-help
6a71a83d-c2e0-4ce7-a6aa-899aa3885b56