Partner integrations with AEM as a Cloud Service
Partners should implement their connectors as described in this guide, according to AEM as a Cloud Service best practices. In general, code can be adapted from AEM 6.x, but some patterns may require redesign in order to adhere to AEM as a Cloud Service’s cloud native implementation requirements.
Partners will need an AEM as a Cloud Service sandbox environment, which can be provisioned through the Experience Cloud Exchange team: see Adobe Experience Manager: Sandbox Info for more info. If you have previously been provisioned access to an on-premise version of AEM (v6.x), send us a request via Support to get access.
The development workflow will involve iterations of:
- modifying the connector code using a maven project with local SDK development which should be built with the most recent AEM Project Archetype. A recommended maven directory structure is described later in this document.
- local environment validation that the connector works as expected.
- occasional deployment via Cloud Manager into an AEM as a Cloud Service development sandbox environment, validating in that cloud environment that the connector works as expected.
It is important that partners write custom functional tests that are executed during staging/production deployments, which can be exercised in sandbox stage and production environments that partners can self-provision via Cloud Manager. Learn how to manage environments and write tests at the respective documentation links:
The submission workflow is as follows:
- When the connector has been validated to work both locally and in the sandbox Cloud environment, mark down the git tag, which can be found in the Cloud Manager production pipeline’s build details screen.
- While in the future it may be possible to download an Adobe-signed connector artifact directly from Cloud Manager, today partners are required to build the artifact locally on a partner engineer’s computer.
The partner engineer responsible for the build should set their git context to the git tag noted in the previous step, in order to be confident that they are building a version that has been proven to work correctly.
- The partner engineer will run the “maven release” target, which sets a git release tag and generates an artifact filename with a version suffix corresponding to that git release tag; for example, myconnector-1.0.1.
The mapping between filename and git release tag is important so AEM engineers can find the source code for a particular connector version if they need to investigate an issue in a customer’s deployment.
- Partners should upload the artifact in a maven repository that they own or host.
This maven repository can either be public (no credentials needed) or password protected. See https://docs.adobe.com/content/help/en/experience-manager-cloud-manager/using/getting-started/create-an-application-project.html#password-protected-maven-repositories for details on how customers can reference packages in password protected repositories.
Note that partners, who both do not have an authentication requirement nor a desire to host the repository, are free to use the publicly available Maven Central repository.
- Once uploaded, a partner should modify their maven project’s pom.xml to reference the hosted artifact. It should be deployed to the sandbox environment using Cloud Manager and the proper functioning of the connector should be validated. Referencing the hosted artifact is also how a customer will access the connector.
It’s notable that this special project serves two purposes: inclusion of source code so Adobe can reference it if needed, as well as a reference to the hosted connector artifact to represent the access pattern in a real customer’s application.
The maven setup to achieve this has the following git directory layout:
+ connectorThe pom.xml in the root directory is a reactor pom, and it contains a modules section with two modules, connector and reference.
+ connector code
+ reference project code
The connector module is a maven project building the connector and the reference module is an AEM reference application. As the reference application is using the connector, it will have a dependency on at least one of its pom.xml files to the connector.
The dependency can either point to the exact same SNAPSHOT version as the connector module is using, or it can reference the latest released version.
- Create or update public listing on Experience Cloud Exchange via the Exchange partner portal. Partners should update instructions in the “Installation” section to include a link to the current hosted artifact and note the filename along with current version suffix for clarity and to facilitate access by customers. When submitting the listing please add the version number in the notes, this will get updated in the listing during the approval process.
- Partners should notify the Exchange technical team via the Support form to inform them of the new connector availability.
Updating an existing connector code is similar to the initial implementation. Please follow the guidance in the “connector implementation” section above.
Each connector update must adhere to the instructions in the “connector submission” section above, but of course using an updated version number. Notify the Exchange technical team when a new version of the connector is available and the Exchange listing has been updated.
AEM as a Cloud Service is updated regularly with daily maintenance releases and monthly feature releases.
While AEM has a commitment to backwards compatibility, it’s unlikely, but theoretically possible, for the daily small AEM updates and larger monthly AEM updates to impact the connector code. With this in mind, we recommend that partners occasionally update the AEM versions on their sandbox environments by clicking the Update button next to their production environment in Cloud Manager, as described in the Managing Environments documentation. The upgrade will execute any functional tests; while unexpected, any failures that point to backward compatibility issues should be immediately be reported to Adobe.
In the future, we expect that AEM will proactively push AEM updates to sandbox environments so partners would not need to do it themselves; AEM engineering would become aware if something breaks and would trigger an investigation, reaching out to the partner if their support is needed.
Note that AEM will test the partner’s reference implementation with the latest release, but will not test previous versions of the connector, which some customers will still be using.
It is recommended that partners notify customers to update the connector version referenced in the maven pom.xml of their application and to redeploy it; Adobe does not modify the connector on the customer’s behalf.