The AEM as a Cloud Service SDK

The AEM as a Cloud Service SDK is composed of the following artifacts:

• Quickstart Jar - The AEM runtime used for local development
• Java™ API Jar - The Java™ Jar/Maven Dependency that exposes all allowed Java™ APIs that can be used to develop against AEM as a Cloud Service. Formerly referred to as the Uberjar
• Javadoc Jar - The javadocs for the Java™ API Jar
• Dispatcher Tools - The set of tools used to develop against Dispatcher locally. Separate artifacts for UNIX® and windows

In addition, some customers who were previously deployed with AEM 6.5 or earlier versions use the artifacts below. If local compilation is not working with the Quickstart jar, and you suspect it is from the removal of interfaces from AEM deployed as a Cloud Service, contact Customer Support. They can determine if you need access. It requires changes in the backend.

• 6.5 Deprecated Java™ API Jar - an extra set of interfaced that have been removed since AEM 6.5
• 6.5 Deprecated Javadoc Jar - the Javadocs for the additional set of interfaced

Building for the SDK

The AEM as a Cloud Service SDK is used to build and deploy custom code. See the AEM Project Archetype documentation. At a high level, the following steps are performed:

• Compile code. As expected, source code is compiled, generating the resulting content packages
• Build artifacts. Artifacts are built during this process
• Analyze bundles. Bundles are analyzed using the Maven analyzer plugin, which looks for problems in the Maven project such as missing dependencies
• Deploy artifacts. Artifacts are deployed to the local server.

The same steps are executed by Cloud Manager when deploying to Cloud Environments. Performing builds locally allows for local development and testing. Developers can efficiently discover code or structural issues before committing to source control and triggering Cloud Manager deployments, which can take longer.

Accessing the AEM as a Cloud Service SDK

• You can check the AEM Admin Console’s About Adobe Experience Manager icon to find out the version of AEM you are running on production.
• The quickstart jar and Dispatcher Tools can be downloaded as a zip file from the Software Distribution portal. Access to the SDK listings is limited to people who have environments on AEM Managed Services or AEM as a Cloud Service.
• The Java™ API Jar and Javadoc Jar can be downloaded through maven tooling, either command line or with your preferred IDE.
• The maven project poms should reference the following API Jar package. Dependency on any subpackage poms should also be referenced.

<dependency>
  <groupId>com.adobe.aem</groupId>
  <artifactId>aem-sdk-api</artifactId>
  <version>2019.11.3006.20191108T223635Z-191201</version>
  <scope>provided</scope>
</dependency>

Refreshing a Local Project with a New SDK Version

When is it recommended to refresh the local project with a new SDK?

Adobe recommends refreshing it after a monthly maintenance release.

It is optional to refresh it after any daily maintenance release. Customers are informed when their production instance has been successfully upgraded to a new AEM version. For the daily maintenance releases, it is not expected that the new SDK has changed significantly, if at all. Still, it is recommended to occasionally refresh the local AEM developer environment with the latest SDK, then rebuild and test the custom application. The monthly maintenance release typically includes more impactful changes and thus developers should immediately refresh, rebuild, and test.

Below is the recommended procedure for refreshing a local environment:

1. Make sure that any useful content is either committed to the project in source control or available in a mutable content package for later import.
2. Local development test content must be stored separately so that it is not deployed as part of the Cloud Manager pipeline build. The reason is because it is only used for local development.
3. Stop the currently running quickstart.
4. Move the crx-quickstart folder to a different folder for safe keeping.
5. Note the new AEM version, which is noted in Cloud Manager (it is used to identify the new QuickStart Jar version to download further on).
6. Download the QuickStart JAR whose version matches the Production AEM version from the Software Distribution Portal.
7. Create a brand new folder and put the new QuickStart Jar inside.
8. Start the new QuickStart with the desired run modes (either renaming file or passing in run modes by way of -r).
   • Make sure there’s no remnant of the old quickstart in the folder.
9. Build your AEM application.
10. Deploy your AEM application to local AEM by way of Package Manager.
11. Install any mutable content packages needed for local environment testing via Package Manager.
12. Continue development and deploy changes as needed.

If there is content that should be installed with each new AEM quickstart version, include it into a content package and in the project’s source control. Then, install it each time.

The recommendation is to update the SDK frequently (for example biweekly) and dispose full local state daily to not accidentally depend on stateful data in the application.

If you depend on CryptoSupport (either by configuring the credentials of Cloud services or the SMTP Mail service in AEM or by using CryptoSupport API in your application), the encrypted properties are encrypted by a key. This key is autogenerated on the first start of an AEM environment. While the cloud setup takes care of automatically reusing the environment-specific CryptoKey, it is necessary to inject the cryptokey into the local development environment.

By default, AEM is configured to store the key data within the data folder of a folder, but for convenience of easier reuse in development, the AEM process can be initialized on first startup with “-Dcom.adobe.granite.crypto.file.disable=true”. This process generates the encryption data at “/etc/key”.

To be able to reuse content packages that contain the encrypted values, follow these steps:

• When you initially start up the local quickstart.jar, make sure to add the below parameter: “-Dcom.adobe.granite.crypto.file.disable=true”. It is recommended, but optional, to always add it.
• The first time you started up an instance, create a package that contains a filter for the root “/etc/key”. This package holds the secret to be reused across all environments for which you would want them to be reused.
• Export any mutable content containing secrets, or look up the encrypted values by way of /crx/de so you can add it to the package that is reused across installations.
• Whenever you spin up a fresh instance (either to replace with a new version or as multiple development environments should share the credentials for testing), install the package produced in step 2 and 3. Doing so lets you reuse the content without the need to manually reconfigure. The reason is because now the cryptokey is in synch.