Adovo

AEM Sites Playbook, Chapter 3: Engineering foundations and maintainable customization

How should the application be extended and diagnosed?

November 10, 2026

Know where behavior comes from

An AEM feature usually spans several layers. Repository content supplies data and structure. Sling resolves resources and requests. Sling Models and services provide application behavior; HTL renders markup. OSGi supplies modular services and configuration, while client libraries provide browser assets. Adobe's technical foundations explain those roles. A useful diagnosis identifies which layer produced the unexpected result before changing another layer.

The platform owner maintains an inventory of application modules, external dependencies, service identities, configurations, custom endpoints and component extensions. For each customization, record the requirement it serves, its owner, supported versions and the test that would reveal a break. A small copied workaround can become expensive when nobody knows why it exists.

Use supported extension points and compatible Core Components where they meet the requirement. Keep product-owned code separate from application code; Adobe identifies /libs as product-owned in its foundations guidance. Review a proposed overlay or private-method override against a supported alternative and the cost of retesting it after upgrades.

Trace a request before editing configuration

Step 1. Capture the intended method, public URL, identity, payload shape and expected response using approved diagnostic tooling.

Step 2. Inspect status and redirect locations, then correlate the request across available edge, web-tier and application logs.

Step 3. Confirm the application component or endpoint exists on the target deployment, with the expected configuration and content.

Step 4. Change one hypothesis at a time in a suitable non-production environment and repeat the same request.

The Cloud Service POST-servlet discussion began with a 404 symptom and speculation about filters. Later headers showed a redirect appending .html; the author reported success after correcting the rewrite exclusion and its placement. That sequence supports checking routing evidence. It does not justify exposing all servlet paths or copying the discussion's snippets into another project.

Keep service behavior bounded

Give custom code a defined input contract, validation rules, permitted content scope and useful error responses. Use an appropriately scoped service identity for the supported operation, and keep credentials in the deployment's approved secret mechanism. A servlet's internal permissions do not determine whether an external request can authenticate to it; chapter 14 handles that separate boundary.

For Cloud Service, design work to tolerate interruption and clustered execution. The development guidelines require that assessment. For 6.5 and LTS, review the actual runtime and deployment arrangement instead of assuming the same configuration and maintenance procedures apply.

Keep code, mutable content and index deployment responsibilities explicit. The local index-packaging discussion reports success after changing a package type in one project. Cloud Service projects still need the documented package structure and managed-index process. A local workaround cannot replace those requirements.

Use observed behavior to select the engineering intervention

Community discussions show why the same visible failure can require different investigations. A Cloud Service migration may expose routing behavior, while a restore failure can follow earlier custom repository changes. Preserve the sequence of requests and changes, and confirm the actual release before selecting a repair.

Build an engineering change record with the failing operation, last known working revision, actual input, caller identity and first observed divergence. Confirm what reached the application before changing application logic. Conversely, once the application runs, inspect its preceding mutations rather than continue changing an edge rule that has already allowed the request.

Scroll horizontally if needed.

Use observed behavior to select the engineering intervention: table 6
ObservationNext investigationAvoid treating this as proof
Redirect appears before the expected servletHost, method, Location and matching rewrite/configurationThat the servlet itself is absent
Bundle/service is unavailableDependency compatibility, activation and target configurationThat broad permissions will repair activation
UI works but custom code failsSame content/version/identity and earlier custom mutationsThat the supported API is universally broken
A local package installs but target validation failsPackage responsibility and platform rulesThat bypassing validation is acceptable
A custom overlay breaks after an upgradeSupported extension and compatibility optionsThat another private API patch will remain stable

Keep a minimal reproducer that another maintainer can execute with approved tooling. It should specify the fixture and expected result, not depend on a developer's unrecorded local state. Remove credentials and unrelated customer data from shared evidence.

Worked scenario of a failing page service

The following environment, requests and results are hypothetical. An engineering team adds an endpoint that creates a product landing page under an approved subtree. The operation works locally. On the deployed development route, the browser reports failure. The team initially proposes broadening service-user privileges.

The engineer captures the original request without silently following redirects, correlates timestamps and checks the supported endpoint registration. The proposed acceptance matrix is:

Scroll horizontally if needed.

Worked scenario of a failing page service: table 9
Input or conditionRequired behaviorResponsible owner
Authorized caller, valid approved path and payloadOne correctly created/updated pageApplication owner
Caller without the required authorityDenied without content changesIdentity/application owners
Payload points outside the permitted subtreeRejected or safely constrainedApplication owner
Repeated business requestDocumented idempotent/conflict behaviorApplication/integration owners
Wrong method or unexpected redirectDiagnosable response with no unintended writeRoute/application owners
Remote dependency unavailableDefined failure/retry behaviorIntegration owner

Suppose the trace shows a redirect changes the intended URL before the endpoint runs. The existing service-user permissions therefore cannot explain that particular observation. The route owner corrects the rule on the test environment and repeats the identical request. The valid request now reaches the application, revealing a separate payload validation error. The team fixes that error without relaxing resource scope.

The value of the trace is that it separates two failures. Reporting only the final success would conceal why the permission proposal was unnecessary. Retain both observations, the relevant configuration/source revisions and the test that now prevents recurrence.

Make customization an owned dependency

Scroll horizontally if needed.

Make customization an owned dependency: table 12
Proposed approachUse whenAcceptance condition
Configure supported behaviorThe documented capability meets the requirementConfiguration survives deployment and required tasks work
Extend a supported component/service contractAn identifiable requirement needs additional behaviorExtension boundary, ownership and compatibility tests are explicit
Create a new application capabilityExisting supported options do not meet the contractInputs, permissions, errors, observability and recovery are designed
Retain an old overlay/private call temporarilyA supported replacement cannot be delivered immediatelyNamed exception, restricted scope, regression evidence and retirement date

A temporary exception should include the failure that would force a hold, not merely a promise to revisit it later. Assess the cost of understanding and retesting the customization during every relevant release.

The practical handover is a runnable task description, version/configuration inventory, bounded permissions, useful diagnostics and an understood way to disable or recover the capability. That is stronger evidence of maintainability than a successful demonstration by its original developer.

Demonstrate maintainability

Complete W03 with dependencies and customizations. Test valid and invalid inputs, denied identities, missing content, remote failure and relevant configuration differences. Retain evidence that no secret reaches a browser response or shared log. Include an uninstall, disable or rollback approach appropriate to the change. Business owners approve the capability; engineers should also be able to explain how another maintainer will diagnose it after the original developer leaves.

W03 Engineering and customization inventory

Use with chapter 3. Give each dependency or extension a requirement and an owner.

Scroll horizontally if needed.

W03 Engineering and customization inventory: table 16
RecordEntry
Module/component/service and requirement served[enter]
Owner, dependency version and compatible target[enter]
Extension point, configuration and content scope[enter]
Service identity, input contract and secret mechanism by reference[enter]
Request trace and valid/invalid/denied test cases[enter]
Disable/uninstall/rollback approach and regression evidence[enter]

Continue exploring

Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 1: Strategy, value, ownership and adoption

What outcome justifies the work, and who will operate it?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 10: Preview, publication, scheduling and withdrawal

How do we release and remove the complete approved experience?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 11: Delivery, Dispatcher, CDN, domains and caching

Which layer controls the request, redirect or stale response?

Read more
Explore data and analytics services →