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.
| Observation | Next investigation | Avoid treating this as proof |
|---|---|---|
| Redirect appears before the expected servlet | Host, method, Location and matching rewrite/configuration | That the servlet itself is absent |
| Bundle/service is unavailable | Dependency compatibility, activation and target configuration | That broad permissions will repair activation |
| UI works but custom code fails | Same content/version/identity and earlier custom mutations | That the supported API is universally broken |
| A local package installs but target validation fails | Package responsibility and platform rules | That bypassing validation is acceptable |
| A custom overlay breaks after an upgrade | Supported extension and compatibility options | That 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.
| Input or condition | Required behavior | Responsible owner |
|---|---|---|
| Authorized caller, valid approved path and payload | One correctly created/updated page | Application owner |
| Caller without the required authority | Denied without content changes | Identity/application owners |
| Payload points outside the permitted subtree | Rejected or safely constrained | Application owner |
| Repeated business request | Documented idempotent/conflict behavior | Application/integration owners |
| Wrong method or unexpected redirect | Diagnosable response with no unintended write | Route/application owners |
| Remote dependency unavailable | Defined failure/retry behavior | Integration 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.
| Proposed approach | Use when | Acceptance condition |
|---|---|---|
| Configure supported behavior | The documented capability meets the requirement | Configuration survives deployment and required tasks work |
| Extend a supported component/service contract | An identifiable requirement needs additional behavior | Extension boundary, ownership and compatibility tests are explicit |
| Create a new application capability | Existing supported options do not meet the contract | Inputs, permissions, errors, observability and recovery are designed |
| Retain an old overlay/private call temporarily | A supported replacement cannot be delivered immediately | Named 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.
| Record | Entry |
|---|---|
| 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] |
