Changes in v2.1
Page Rewrite Rule
The Page Rewrite Rule has been updated to support restricting paths to which a given configuration can apply. This was added based on feedback from users where original pages for different tenants used the same Static Template, but the desired Editable Template was unique to the tenant.
Without this update, each tenant’s configuration would need to be installed, run, then removed for the next tenant configuration could be applied. Instead, now a path restriction is used to determine if a rule applies.
Thus the new configuration supports the following:
allowed.paths=["/content/geometrixx/en", "/content/geometrixx/de"]
static.template="/apps/geometrixx/templates/homepage"
sling.resourceType="geometrixx/components/homepage"
editable.template="/conf/geodemo/settings/wcm/templates/geodemo-home-page"
container.resourceType="geodemo/components/content/container"
remove.components=["newslist","image"]
rename.components=["par\=container/container","rightpar\=container_1659979946"]
order.components=["header","carousel","container","container_1659979946","container:lead"]
“Like” Sling Resource Type Support
This update allows node-based rule configurations to use a “relative” path for matching. The patterns shown below will all match any component with the resource type aem-modernize/components/text:
<patterns jcr:primaryType="nt:unstructured">
<text jcr:primaryType="nt:unstructured"
sling:resourceType="aem-modernize/components/text"/>
</patterns>
<patterns jcr:primaryType="nt:unstructured">
<text jcr:primaryType="nt:unstructured"
sling:resourceType="components/text"/>
</patterns>
<patterns jcr:primaryType="nt:unstructured">
<text jcr:primaryType="nt:unstructured"
sling:resourceType="text"/>
</patterns>
Finding rules that may match is done by looking at the source resource type and checking rules against each sub-portion. Thus a resource type of aem-modenrize/components/text, will perform a lookup for rules that have a sling:resourceType pattern of:
- aem-modernize/components/text
- components/text
- text
This means that [atterns should be very specific for other properties if the pattern’s resource type is very generic. This is especially true for highly-used components such as text.
Reasoning
This was added as teams found that a single component was used across multiple tenants, but each tenant’s rules were exactly the same. This required a rule to be defined as:
<patterns jcr:primaryType="nt:unstructured">
<text jcr:primaryType="nt:unstructured"
sling:resourceType="tenant-a/components/text"/>
<text jcr:primaryType="nt:unstructured"
sling:resourceType="tenant-b/components/text"/>
<text jcr:primaryType="nt:unstructured"
sling:resourceType="tenant-c/components/text"/>
</patterns>
But can now be defined as:
<patterns jcr:primaryType="nt:unstructured">
<text jcr:primaryType="nt:unstructured"
sling:resourceType="components/text"/>
</patterns>
Map Properties
This update allows Node based configurations to configure 1:1 mapping of original-to-new values. In the previous iterations, in order to convert a specific property from the source to destination, each source property required its own pattern. Now, a more generic pattern can be used and rules are applied post copy to create the desired output. For details configuring for a rule, see the reference documentation.
Consolidate Properties
This update allows Node based configurations to consolidate properties into a single array property. Details on use/configuration can be found on the see the reference documentation.
Use Cases
This was intended to allow conversions to take original Dialog based/managed properties, and convert them into cq:styleIds references. This allows for applying policies to individual component instances on pages during conversions.
Changes in v2.0
Cloud Service Compatibility
The latest release of these tools is now AEM Cloud Service compatible. This has multiple connotations, but the most important of these is that the processes for conversions is done asynchronously using Sling Jobs.
When a user creates a configuration for any of the tools, that configuration is persisted in the repository and then a Sling Job is scheduled against it. Only one job can be scheduled at a time, but they are queued as soon as they are configured. Moving to Sling Jobs allows for use in the context of the AEM as a Cloud Service product.
To prevent overloading the system, depending on the number of paths submitted for processing, more than one Job may be scheduled. Each tool processes a specific set of paths, be it the page, design nodes, or individual components. If there are more than 500 paths to process, a job will be created for every 500 paths or portion there-of. So 1250 paths would create three scheduled jobs.
In order for the jobs to run asynchronously, a Service User performs the transformations. This user has permissions to all the normal paths in the repository. To ensure that users do not schedule a conversion for which they do not have the appropriate permissions, a check is performed during the scheduling of the job. If the user requesting the job does not have rights to all the paths necessary, the job scheduling will fail.
All-in-One Conversion Tool
This version of the tool introduces a new feature, the All-in-One conversion. This tool performs the operations of the other three tools on every page submitted. By performing all the operations concurrently, additional capabilities are made available, most notably: applying policies to the Editable Template.
More information on the All-in-One conversion tool can be found on its about or usage page.
Page Handling
Another new feature of the All-in-One and Structure conversion tools, is page handling before processing. This is an option presented to the users to determine how a page should be pre-processed, before the conversion rules are applied. There are three options made available:
No Handling
This option will simply process the page as-is in place in the repository.
Restore
Copy to Target
This option will copy a page from the source location, to a new path in the repository. Each page must exist under the source path selection. When processing that portion of the path will be replaced with the target path.
The user scheduling the job must have write access to the target location in the repository, or the job will not be scheduled.
The target path must not have a page that already exists in that location, or that page conversion will fail.
Dialog Conversion Tool
Since the intent of these tools is to transform content and not code, the Dialog Conversion tool has been removed as of version 2.0. The tool is still available in v1.0. However, since its addition in this feature set caused confusion with other AEM modernization tool sets, it was removed to clarify intent.
Advanced Component Rules
This update introduces the ability to aggregate or consolidate multiple components into a single component using just the Node based rule definitions. This allows teams to identify a specific sequence of components, that are better implemented as a single updated reference.
More information on how to configure and a demonstration of its use can be found on the Component Converter configuration page.
Column Control Rule
In the previous release of the Modernization tools, the Column Control rewrite rule was considered a Structure conversion. Thus it was applied when running the Page/Structure rewrite rules. This has been updated to be a Component conversion. Therefore, updating a Column Control to a set of containers will only occur during either the All-in-One conversion, or the Component Conversion.
If during a job, you do not see the Column Control conversion being applied, check out the Component Converter details page to see what may be occurring.
Paragraph Rewrite Rule
In the previous release of the Modernization there existed a Structure rewrite rule to convert a Paragraph System (parsys) component to a Responsive Grid component. This feature has been removed from v2.0 of the tools.
This was done as using the Responsive Grid directly in a project is considered an anti-pattern. Instead, teams should use a Container Core Component proxy. There is an example rule for accomplishing this documented on the Component Converter details page.