Common Repository Restructuring in AEM 6.5
- Topics:
- Upgrading
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 potentially impacting all solutions. 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
- ContextHub Configurations
- Classic Cloud Services Designs
- Classic Dashboards Designs
- Classic Reports Designs
- Default Designs
- Adobe DTM JavaScript Endpoint
- Adobe DTM Web-Hook Endpoint
- Inbox Tasks
- Multi-site Manager Blueprint Configurations
- AEM Projects Dashboard Gadget Configurations
- Replication Notification E-mail Template
- Tags
- Translation Cloud Services
- Translation Languages
- Translation Rules
- Translation Widget Client Library
- Tree Activation Web Console
- Vendor Translation Connector Cloud Services
- Workflow Notification Email Templates
With 6.5 Upgrade
ContextHub Configurations
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.
- Navigate to the root of the site.
- Open the page properties of the root page and select the Personalization tab.
- 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.
- Open the properties of ContextHub configuration node in CRX DE Lite, for example,
/apps/settings/cloudsettings/legacy/contexthub - Change
sling:resourceTypefrom/libs/granite/contexthub/cloudsettings/components/baseconfigurationtogranite/contexthub/cloudsettings/components/baseconfiguration
I.e. the sling:resourceType of the ContextHub configuration must be relative rather than absolute.
Workflow Models
/etc/workflow/models/libs/settings/workflow/models
/conf/global/settings/workflow/models
/var/workflow/models
Any new or modified Workflow Models must be migrated to /conf/global/workflow/models.
-
Deploy the modified Workflow Models into a local AEM 6.5 development instance, such that they exist in the Previous location.
-
Edit the Workflow Model using AEM's Workflow Model Editor at AEM > Tools > Workflow > Models.
-
When migrating modified AEM-provided Workflow Models
- 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
- 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.
-
Enable Edit mode in the Workflow Model Editor which will copy the Workflow Model definition to /conf/global/workflow/models.
-
Select the Sync button to sync the changes to the Runtime Workflow Model under /var/workflow/models.
-
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.
-
For example, export:
/conf/global/settings/workflow/models/dam/my_workflow_model
and/var/workflow/models/dam/my_workflow_model
-
Workflow Model resolution occurs in the following order:
/conf/global/settings/workflow/models/libs/settings/workflow/models/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
/etc/workflow/instances/var/workflow/instancesNo 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.
custom code to the Previous Location should also account for the New Location. It is recommended that this code is refactored to use the AEM Workflow APIs.Workflow Launchers
/etc/workflow/launcher/config/libs/settings/workflow/launcher/config
/conf/global/settings/workflow/launcher/config
Any new or modified Workflow Launchers must be migrated to /conf/global/workflow/launcher/config.
- Copy any new or modified Workflow Launcher configurations from the Previous Location to New Location (
/conf/global).
Workflow Launcher resolution occurs in the following order:
/conf/global/settings/workflow/launcher/libs/settings/workflow/launcher/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
/etc/workflow/scripts/libs/workflow/scripts
/apps/workflow/scripts
Any new or modified Workflow Scripts must be migrated to the New Location and the referencing Workflow Models updated to reflect the New Location.
- Copy any new or modified Workflow Scripts from the Previous Location to the New Location.
/apps/workflow/scriptsshould be maintained in SCM.
- Update any references to the Workflow Scripts at the Previous Location in Workflow Models to point to the New Locations.
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 Future Upgrade
ContextHub Configurations
/etc/cloudsettings/libs/settings/cloudsettings
/conf/global/settings/cloudsettings
/conf/<tenant>/settings/cloudsettings
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.
- Copy any new or modified ContextHub Configurations from the previous location to the new location.
- Associate the applicable AEM configurations with the AEM content hierarchies.
- AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
- Disassociate any migrated legacy ContextHub Configurations from the aforementioned AEM content hierarchies.
Classic Cloud Services Designs
/etc/designs/cloudservices/libs/settings/wcm/designs/cloudservices
/apps/settings/wcm/designs/cloudservices
For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.
- Copy the designs from the Previous Location to the New Location (
/apps). - Convert any CSS, JavaScript and static resources in the Design to a Client Library with
allowProxy = true. - Update references to the Previous Location in the
cq:designPathproperty. - Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
- 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.
Classic Dashboards Designs
/etc/designs/dashboards/libs/settings/wcm/designs/dashboards
/apps/settings/wcm/designs/dashboards
For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.
- Copy the designs from the Previous Location to the New Location (https://experienceleague.adobe.com/apps?lang=en).
- Convert any CSS, JavaScript and static resources in the Design to a Client Library with
allowProxy = true. - Update references to the Previous Location in the
cq:designPathproperty. - Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
- 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.
Classic Reports Designs
/etc/designs/reports/libs/settings/wcm/designs/reports
/apps/settings/wcm/designs/reports
For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.
- Copy the designs from the Previous Location to the New Location (https://experienceleague.adobe.com/apps?lang=en).
- Convert any CSS, JavaScript and static resources in the Design to a Client Library with
allowProxy = true. - Update references to the Previous Location in the
cq:designPathproperty. - Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
- 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.
Default Designs
/etc/designs/default/libs/settings/wcm/designs/default
/apps/settings/wcm/designs/default
For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.
- Copy the designs from the Previous Location to the New Location (https://experienceleague.adobe.com/apps?lang=en).
- Convert any CSS, JavaScript and static resources in the Design to a Client Library with
allowProxy = true. - Update references to the Previous Location in the
cq:designPathproperty. - Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
- 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.
Adobe DTM JavaScript Endpoint
/etc/clientlibs/dtm/var/cq/dtm/clientlibsNo action required.
The public previous location acts as a proxy endpoint for the private new location.
Adobe DTM Web-Hook Endpoint
/etc/dtm-hook/var/cq/dtm/web-hookNo action required.
The public previous location acts as a proxy endpoint for the private new location.
Inbox Tasks
/etc/taskmanagement/var/taskmanagementNo 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
/etc/blueprints/libs/msm
/apps/msm
- Copy custom configurations from
/etc/blueprintsto/apps/msm. - Remove
/etc/blueprints.
AEM Projects Dashboard Gadget Configurations
/etc/projects/dashboard/gadgets/libs/cq/core/content/projects/dashboard/gadgets
/apps/cq/core/content/projects/dashboard/gadgets
Any new or modified AEM Projects Dashboard Gadget Configurations must be migrated to the new location (/apps).
- Copy any new or modified AEM Projects Dashboard Gadget Configurations from the previous location to the new location (
/apps).- Do not copy unmodified AEM Projects Dashboard Gadget Configurations as these now exist in the new location (
/libs).
- Do not copy unmodified AEM Projects Dashboard Gadget Configurations as these now exist in the new location (
- Update any AEM Projects templates that reference the Previous Location to point to the appropriate new location.
Replication Notification E-mail Template
/etc/notification/email/default/com.day.cq.replication/libs/settings/notification-templates/com.day.cq.replication
/apps/settings/notification-templates/com.day.cq.replication
Any new or modified Replication Notification E-mail Templates must be migrated to the new location (/apps)
- Copy any new or modified Replication Notification E-mail Templates from the previous location to new location (
/apps). - Remove any migrated Replication Notification E-mail Templates from the previous location.
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:
/etc/notification/email/default/com.day.cq.replication/apps/settings/notification-templates/com.day.cq.replication/libs/settings/notification-templates/com.day.cq.replication
Tags
/etc/tags/content/cq:tagsAll Tags must be migrated to /content/cq:tags.
- Copy all Tags from the Previous Location to the New Location.
- Remove all Tags from the Previous Location.
- 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.
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 uses 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 use the TagManager Java API, in tandem with this migration.
Translation Cloud Services
/etc/cloudservices/translation/libs/settings/cloudconfigs/translation/translationcfg
/apps/settings/cloudconfigs/translation/translationcfg
/conf/global/settings/cloudconfigs/translation/translationcfg
/conf/<tenant>/settings/cloudconfigs/translation/translationcfg
Any new Translation Cloud Services must be migrated to the new location (/apps, /conf/global or /conf/<tenant>).
-
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/globalor/conf/<tenant>).
- Manually recreate new Translation Cloud Services configurations via the AEM authoring UI at Tools > Cloud Services > Translation Cloud Services.
-
Associate the applicable AEM configurations with the AEM content hierarchies.
- AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
- AEM Experience Fragment hierarchies via AEM Experience Fragments > Experience Fragment > Properties > Cloud Services Tab > Cloud Configuration.
- AEM Experience Fragment Folder hierarchies via AEM Experience Fragments > Folder > Properties > Cloud Services Tab > Cloud Configuration.
- AEM Assets folder hierarchies via AEM Assets > Folder > Folder Properties > Cloud Services Tab > Configuration.
- AEM Projects via AEM Projects > Project > Project Properties > Advanced Tab > Cloud Configuration.
-
Disassociate any migrated legacy Translation Cloud Services from the aforementioned AEM content hierarchies.
Translation Cloud Services resolution occurs in the following order:
/conf/<tenant>/settings/cloudconfigs/translations/translationcfg/conf/global/settings/cloudconfigs/translations/translationcfg/apps/settings/cloudconfigs/translations/translationcfg/libs/settings/cloudconfigs/translations/translationcfg
Migrated Translation Cloud Services must be compatible with AEM 6.4.
Translation Languages
/etc/translation/supportedLanguages/libs/settings/translation/supportedLanguages
/apps/settings/translation/supportedLanguages
Any new or modified Translation Language definitions require a migration of all Translation Language definitions to the new location (/apps).
- 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).
Translation Language path resolution occurs in the following order:
/etc/translation/supportedLanguages/apps/settings/translation/supportedLanguage/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
/etc/workflow/models/translation/translation_rules.xml/libs/settings/translation/rules/translation_rules.xml
/apps/settings/translation/rules/translation_rules.xml
/conf/global/settings/translation/rules/translation_rules.xml
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.
Replication Translation Rules XML resolution occurs in the following order:
/conf/global/settings/translation/rules/translation_rules.xml/apps/settings/translation/rules/translation_rules.xml/etc/workflow/models/translation/translation_rules.xml/libs/settings/translation/rules/translation_rules.xml
Translation Widget Client Library
/etc/designs/translation/translationwidget/libs/settings/wcm/designs/translation/translationwidget
/apps/settings/wcm/designs/translation/translationwidget
For any Designs that are managed in SCM, and not written to at run-time via Design Dialogs.
- Copy the designs from the Previous Location to the New Location (https://experienceleague.adobe.com/apps?lang=en).
- Convert any CSS, JavaScript and static resources in the Design to a Client Library with
allowProxy = true. - Update references to the Previous Location in the
cq:designPathproperty. - Update any Pages referencing the Previous Location to use the new Client Library category (this requires updating Page implementation code).
- 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.
Tree Activation Web Console
/etc/replication/treeactivation/libs/replication/treeactivationVendor Translation Connector Cloud Services
/etc/cloudservices/<vendor>/libs/settings/cloudconfigs/translation/<vendor>
/apps/settings/cloudconfigs/translation/<vendor>
/conf/global/settings/cloudconfigs/translation/<vendor>
/conf/<tenant>/settings/cloudconfigs/translation/<vendor>
Any new Vendor Translation Connector Cloud Services must be migrated to the new location (/apps, /conf/global or /conf/<tenant>).
-
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/globalor/conf/<tenant>).
- Manually create net-new Vendor Translation Connector Cloud Services configurations via the AEM authoring UI at Tools > Cloud Services > Translation Cloud Services.
-
Associate the applicable AEM configurations with the AEM content hierarchies.
- AEM Sites page hierarchies via AEM Sites > Page > Page Properties > Advanced Tab > Cloud Configuration.
- AEM Experience Fragment hierarchies via AEM Experience Fragments > Experience Fragment > Properties > Cloud Services Tab > Cloud Configuration.
- AEM Experience Fragment Folder hierarchies via AEM Experience Fragments > Folder > Properties > Cloud Services Tab > Cloud Configuration.
- AEM Assets folder hierarchies via AEM Assets > Folder > Folder Properties > Cloud Services Tab > Configuration.
- AEM Projects via AEM Projects > Project > Project Properties > Advanced Tab > Cloud Configuration.
-
Disassociate any migrated legacy Translation Cloud Services from the aforementioned AEM content hierarchies.
Translation Cloud Services resolution occurs in the following order:
/conf/<tenant>/settings/cloudconfigs/translations/<vendor>/conf/global/settings/cloudconfigs/translations/<vendor>/apps/settings/cloudconfigs/translations/<vendor>/libs/settings/cloudconfigs/translations/<vendor>
Workflow Notification Email Templates
/etc/workflow/notification/libs/settings/workflow/notification
/conf/global/settings/workflow/notification
Any modified Workflow Notification Email Templates must be migrated to the New Location (/conf/global).
- Copy any modified Workflow Notification Email Templates from the previous location to the new location.
- Remove migrated Workflow Notification Email Templates from the previous location.
Workflow Notification Email Template resolution occurs in the following order:
/etc/workflow/notification/conf/global/settings/workflow/notification/libs/settings/workflow/notification
Workflow Packages
/etc/workflow/packages/var/workflow/packagesExisting Workflow Packages in the previous location should be migrated to the new location.
- Remove any Workflow Packages in the previous location that are not referenced by other content and are otherwise not required.
- Move any Workflow Packages in the previous location that are not referenced by other content but otherwise required in the new location.
- Leave any Workflow Packages that are referenced by other content in the previous location.
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.