Exporting and importing AEM packages with confidence

AEM’s Package Manager treats an export as a delivery unit, not a backup. A package can carry authored content, application code and selected configuration as a ZIP-based artefact, but every inclusion becomes part of the change entering a target environment. A useful package therefore has a clear purpose: which capability is changing, which audience receives it and which dependencies must travel with it.

Most package failures are not caused by a damaged archive. They come from unclear boundaries: content is exported without referenced assets, a broad filter copies transient data, an environment-specific endpoint is frozen into configuration, or a replacement import overwrites a node maintained by another team. These faults become harder to detect when one package moves through development, QA, staging and production.

For useful historical context, the CIRCUIT developer conference archive describes Adobe’s two-day Chicago gathering for Java developers, AEM architects, front-end engineers and systems specialists. Its practical lesson still applies: a package is one part of a delivery system that also needs source control, automated builds, controlled permissions and operational verification.

Why package boundaries decide the outcome

A dependable package has a deliberate scope and a named owner. Content, code and configuration should not be bundled simply because they are easy to export from the same instance. Each category has a different review path and rollback consequence. Keeping them conceptually separate makes approval clearer and reduces the chance that a routine editorial update will carry an unrelated service change.

Target platform differences deserve equal attention. AEM 6.x deployments may use author and publish instances, CRXDE, bundles and locally managed configuration. AEM as a Cloud Service uses managed deployment pipelines and protects system-owned areas, including portions of /libs and /system. Package design must therefore follow the target’s supported tooling rather than assume that an archive accepted by one environment is valid in another.

Australian delivery adds constraints without changing these fundamentals. Programmes are often staffed across Sydney, Melbourne and Brisbane, while daily handovers commonly move through Microsoft Teams or Slack. Daylight saving means a 9:00 a.m. Sydney release can occur at 8:00 a.m. in Brisbane. The local mix of enterprise, government and agency work calls for traceable approvals, and the Privacy Act 1988 and Spam Act 2003 make it poor practice to move test records or contact data inside an unrelated package.

Export patterns that survive real delivery

Export from a known baseline. Build or refresh an author instance, apply the required content and test it before capture. Use Package Manager or CRXDE to create a narrowly filtered package. Include referenced nodes, assets, Sightly templates, client libraries and any service configuration needed to operate the feature; otherwise the target may render broken fragments or leave a component unusable.

Define roots deliberately. A full /content or /apps export often conceals large binaries and unrelated edits. Exclude /var, /tmp, logs, audit output, user data and session state, and treat /system and /libs according to the target version. Never include passwords, private keys or production secrets. Keep dispatcher and CDN rules in their own reviewed deployment path rather than disguising them as application content.

Treat the package as build output. Keep templates, Java code, client libraries and configuration sources in version control, then generate the package through a documented command or pipeline. Record its name, filter roots, source revision, target AEM release, creator, change reference, build time and SHA-256 checksum in the release record. The historical published agenda lists architecture and integration sessions that remain useful prompts for reviewing these decisions.

Package pre-flight controls for exports and imports

Automation cannot repair a package with the wrong scope. Apply explicit checks before an artefact leaves the build and before it reaches a shared environment. For exports, apply these controls:

  • Confirm every filter root and included node has a named business or technical owner.
  • Include dependencies and referenced assets, but no unrelated sibling content.
  • Exclude runtime state, audit data, credentials, endpoints and environment secrets.
  • Record the source revision, AEM version, change reference and artefact checksum.

After export, compare the archive with the release record rather than trusting the file name. Inspect the package definition and contents without changing the original archive; make corrections in source control and regenerate it. Then run these import gates:

  • Match the checksum to the release record and confirm the artefact has not changed.
  • Check target compatibility, required dependencies, permissions and selected import mode.
  • Test on a non-production instance with representative content and configuration.
  • Capture logs, validation output, activation status and a rollback owner.

A failed test should stop promotion rather than trigger an improvised archive repair. Editing ZIP contents by hand can invalidate metadata, omit dependency information or conceal the difference between tested and delivered code. If a package is unsuitable, return to the source, make the change there and repeat the build. Teams that build package-validation utilities can also benefit from writing cleaner C# code with StyleCop and analyzers, while recognising that static analysis cannot determine business scope.

Import controls across shared environments

Control access to every import route. Use named service accounts with the minimum permissions needed to read an artefact and start a deployment, and separate authors who approve content from operators who publish it. On AEM as a Cloud Service, follow the supported Cloud Manager deployment model; on AEM 6.x, restrict Package Manager and CRXDE access. Record who requested the import and who authorised it.

Treat an import as a controlled change even when the interface presents it as a single action. Select merge, replace or overwrite deliberately, since each can affect existing paths differently across AEM releases. Review package validation and server logs, then inspect the affected nodes, bundle state, OSGi configuration and rendered pages. Confirm that services have started and that queued replication or dispatcher cache invalidation has completed before declaring success.

Operational verification should include the path a customer will actually use, including published pages, forms, assets and analytics events where relevant. A package may import cleanly but still expose broken references, stale cache content or an authorisation rule missing from the local environment. Archived session videos offer a practical way to revisit AEM architecture, microservices and integration concerns when designing these checks.

Build a repeatable package workflow

Turn these practices into a small, owned workflow. Maintain one package register linking the source revision, artefact, filter roots, environment, approval, test evidence and deployment outcome. Give developers a supported export command, give reviewers a readable package definition, and give operations a concise import and verification checklist. Store artefacts in an access-controlled repository with retention rules that match the organisation’s audit needs.

Begin with a bounded use case, such as a component rollout that includes its Sightly template, client library and content dependencies. Run it through a clean author instance, QA and a production-like publish tier before adopting the process broadly. Measure rework, failed imports and time spent locating artefacts; these signals show where package boundaries or documentation need attention without turning the workflow into a paperwork exercise.

Make ownership explicit: the developer owns dependency completeness, the reviewer owns scope and credentials, and the operator owns import mode, verification and rollback. Schedule releases around Australian daylight-saving differences and leave an engineering owner available during the observation window. Create the package register today, choose one upcoming AEM change to use it, and make that first successful promotion the standard for every subsequent package.