AEM as Cloud Service Project Structure - 1

 

In AEM as Cloud Service, Project Structure has changed & is one of the important exercises to be done if any projects wish to migrate from On-Premises to AEM as CS. In this article we will explore on project structure, code repository, run modes & tools and tips.

This section describes the changes required to "AEM On-Premises Maven Project to be AEM as Cloud Service Compatible Project".

1.     AEM as Cloud Service brings the concept of mutable & immutable content. The dependencies are established to create non-conflicting, deterministic deployments & that they are packaged in deploy-able structure.

2.     AEM application deployments must be comprised of a single AEM Package. This package should in turn contain sub packages that comprises everything to run the application.

 

Mutable vs Immutable

1.     /apps & /libs are considered immutable areas of AEM as they cannot be changed (CRUD Operations) after AEM starts (i.e. at run-time). Any attempt to change an immutable area at run-time will fail which means direct write operations on CRX/DE is restricted.

2.     Everything else in the repository are all mutable areas & can be changed at run-time.

 

Repository Structure

Adobe recommends below project structure to be maintained in AEM as Cloud Service.

SI No.	CRX Folder Name	Project Module Name	Purpose
1	All Packages	all	Deployment Package (Embed)
2	/apps /oak:index	ui.apps	Components, Templates, Customizations, Oak Indexes etc.
3	/apps	ui.apps.structure	Define Package Roots
4	/apps/<project>/osgiconfig	ui.config	OSGI Configurations
5	/conf /content /etc /home /var	ui.content	Content & Configs for Editable Templates, Tags, Workflow Models, ClientLibs, Users & Groups etc.
6	/apps/<project>/install	core	Core bundles
7	/apps OR /etc	ui.frontend	JavaScript & CSS

 

AEM as Cloud Service Project Structure (Courtesy: Adobe)

 

Repository Project Structure

This is very simple project structure module “ui.apps.structure” containing only a POM file yet very important & can’t be ignored when restructuring the codebase to AEM as Cloud Service.

1.     Its sole purpose is to define the JCR repository roots in which the project's code sub-packages deploy into. This ensures the installation of packages in AEM as Cloud Service is automatically ordered by JCR resources dependencies.

2.     Possible Issue - Missing Dependencies may lead to a scenarios where sub-structures would be installed ahead of their parent structures & therefore be unexpectedly removed, breaking the deployment.

3.     Local SDK Development & Deployment – In local environment, it is important to build the project with this module & deploy this package otherwise you will see issue where packages gets installed, uninstalled & the same repeats which breaks the deployment.

Example: - If a project named ‘<project>’ exists under root as ‘/apps/<project>’ then it needs to be defined under ‘<filter-root>’ tag in POM else without this definition, project even with ‘filter.xml’ will break the deployment since the root is not defined in structure module POM file.

AEM as Cloud Service Repository Project Structure (Courtesy: Adobe)

 

OSGI Run Modes

1.     Changes to OSGi settings can only come via Git persistence as JCR-based OSGi settings. New or updated OSGi bundles must be introduced via Git as part of the CI/CD pipeline build process.

2.     Configuration changes are defined in the AEM Project’s code packages (ui.apps or ui.config) as configuration files (.cfg.json) under runmode specific config folders.

/apps/<project>/osgiconfig/config.<runmode>

3.     The format of OSGi configuration files is JSON-based using the .cfg.json

4.     Types of OSGI Configuration Values

a.     Inline Values – which are hard-coded in the OSGI configurations & stored in Git.

b.     Secret Values – which are values that must not be stored in Git for security reasons.

c.      Environment Specific Values – which are values that vary between development & thus cannot be accurately targeted by run mode.

Example:-

{

"connection.timeout": 1000, ß Inline Value

"api-key": "$[secret:server-api-key]", ß Secret Value

"url": "$[env:server-url]" ß Environment Specific Value

}

5.     AEM as Cloud Service only allows below run modes out-of-the-box & custom run modes are not supported.

a.     author

b.     publish

c.      prod

d.     author.prod

e.     publish.prod

f.       stage

g.     author.stage

h.     publish.stage

i.       dev

j.       author.dev

k.      publish.dev

 

Managing Code

Maven Version Handling

For Stage & Production, Cloud Manger generates a unique & incremental version. This version can be seen on the pipeline execution details as well as the activity page.

If the original project version meets certain criteria, the updated maven project version will merge both the original project version & Cloud Manager generated version. Below table shows good & bad practices of versioning. Assume Cloud Manger generated version is as 2019.926.121356.0000020490 then

Version	Version in POM	Comments
1.0.0	1.0.0.2019_0926_121356_0000020490	Properly formed original version
1.0.0-SNAPSHOT	2019.926.121356.0000020490	Snapshot version, overwritten
1	2019.926.121356.0000020490	Incomplete version, overwritten

 

Git with Cloud Manager

1.     Adobe Cloud Manager comes with a "Single Git Repository" that is used to deploy code using Cloud Manager CI/CD pipelines.

2.     Accessing Git Repository is self-service from Cloud Manager UI. Users who have access to Cloud Manager can access repository information in “Access Repo Info” in Cloud Manager UI.

a.     Repository URL & Git Command Line

b.     Username

c.      Password (Generate Password)

3.     Customers also have the option of integrating On-Premises or "Customer-Managed Git Repository" with Cloud Manager.

 

Deprecated Features

1.     Classic UI – The Classis UI is no longer available in AEM as Cloud Service.

2.     Replication Agents – Replication Agents are replicated by “Replication Service” which uses “Sling Content Distribution” to publish the content. Impacted areas are as below.

a.     Custom workflows that push the content to replication agents of preview server.

b.     Customizations to replication agents to transform content.

c.      Using reverse replication to bring content back from publish to author.

3.     Asset Handling & Delivery – As AEM as Cloud Service introduced “AEM as Asset Services” below are impacted.

a.     The default workflow “DAM Update Asset” in previous version is no longer available.

b.     Web site components that deliver a “binary without transformation” should use direct download.
→ The Sling GET servlet has been changed to do this by default.

c.      Web site components that deliver a “binary with transformation” (Example: - resize via servlet) can continue to operate as they have.

d.     Asset that come in via Package Manager require manual re-processing using the “Reprocess Asset” action in the Asset Interface.

 

 

Added Features

1.     Client Library Versioning – By Default, Client Library Versioning is enabled in AEM as Cloud Service. Hence projects need not depend on ACS Commons for the functionality. In fact, ACS Commons have highlighted out in their documentation that this feature is removed for their cloud compatible version.

 

References

·       https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/developing/repository-structure-package.html?lang=en

·       https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/managing-code/accessing-git.html?lang=en

·       https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/managing-code/integrating-with-git.html?lang=en

·       https://github.com/adobe/aem-guides-wknd