Moving AEM content between environments with packages
Adobe Experience Manager teams across Brisbane, Sydney, and Melbourne regularly face the challenge of moving content between author instances, staging servers, and production environments. Content portability remains a core operational concern for Australian enterprises running regulated industries like mining, banking, and government, where audit trails and controlled releases matter. The ability to package a site tree, export it, and re-import it cleanly on another instance is foundational to any AEM deployment workflow.
Packages have long served as the primary vehicle for transferring content hierarchies, page assets, and configuration nodes between AEM instances. Unlike ad-hoc file copies or direct database exports, packages preserve metadata, versioning history, and access control lists, making them suitable for repeatable deployment workflows. For teams spread across Australian time zones, packages also provide a tangible artifact that can be checked into version control or attached to change records.
This article examines how to build reliable packages, manage dependencies, integrate transfers into automated pipelines, and recover when things go wrong. It also covers tools and patterns shared at past CIRCUIT conferences in Chicago, many of which apply directly to distributed teams collaborating from Sydney to Perth. Whether you manage a single regional site or a national network of portals, the same fundamentals apply.
How AEM packages are constructed
A package is a ZIP archive containing a serialized content tree, a filter definition, and metadata such as the package version, group, and thumbnail. The package manager in AEM author instances allows teams to define inclusion and exclusion rules using path expressions. For example, a content package targeting /content/dam/retail might exclude renditions or only include specific MIME types, keeping the archive manageable.
When working with large media libraries common in Australian retail and tourism sites, package size quickly becomes a concern. Brisbane-based teams often split DAM packages by brand or campaign to keep individual archives under 2 GB. This avoids timeout errors during upload and makes it easier to roll back individual content sets when a promotion goes wrong. Splitting also helps when uploading over Australia's NBN, where upload speeds can be significantly lower than download rates in regional areas.
Metadata fields within the package definition deserve attention. Setting the package group consistently across environments allows for better filtering in the package manager UI. Australian teams operating in regulated sectors often add a custom description field containing a Jira ticket reference or a change request ID, ensuring traceability for audits required by the Australian Prudential Regulation Authority or state government IT governance frameworks.
Building packages for environment migration
Most teams follow a dev โ QA โ staging โ production promotion path. Each environment requires its own package export, and the filter rules often need adjustment. A package built from a local author instance may include /content/users that should never reach production, or test pages under /content/test that are irrelevant in live. Authors often forget to exclude their own draft pages, leading to embarrassing content leaks.
Content authors in Sydney and Melbourne sometimes need to move pages between lower and higher environments without including workflow history. A separate filter configuration targeting /content/<site>/en with the exclude rule /content/<site>/en/jcr:content/workflowData keeps the transfer clean. When integrating with external CMS platforms, the content API patterns offer a complementary approach for hybrid scenarios. The table below outlines the main package types and their typical use cases.
| Package Type | Typical Contents | Common Use Case | Size Considerations |
|---|---|---|---|
| Content Package | Pages, components, assets under /content | Site migration, content refresh | Can exceed 5 GB for large sites |
| Configuration Package | OSGi configs under /apps, /conf, /etc | Environment setup, service users | Usually under 50 MB |
| ACL Package | Permission nodes under /content and /etc | Security replication | Small, rarely above 10 MB |
| Hybrid Package | Mix of content and configuration | Full environment bootstrap | Varies widely |
Australian government departments in Canberra often rely on hybrid packages for initial environment bootstrap, while marketing teams in Sydney prefer pure content packages for campaign rollouts. The choice affects both build time and rollback granularity. A hybrid package that fails midway is harder to recover than a small content package that can be re-imported in seconds.
Dependencies and complex content trees
Dependencies between packages are a frequent source of deployment failures. A page package may reference assets stored under /content/dam, components defined under /apps, and templates under /conf. If the target environment lacks any of these, the imported page renders incorrectly or shows up as a broken component placeholder. Debugging these issues often requires checking the bundle status on the target instance.
Many Australian AEM teams working in financial services in the Sydney CBD or federal agencies in Canberra maintain separate configuration packages for OSGi services, service users, and ACLs. Importing these in the correct order prevents the "red icon" failure state in the package manager. A typical sequence installs configuration first, then components, then content. Some teams encode this sequence in a deployment script that uses the AEM Package Manager API to check the status of each package before proceeding.
Several Asia-Pacific teams have adopted dependency mapping standards for their release processes. Mapping package relationships in a spreadsheet or diagram helps new team members understand the deployment order without trial and error. This is especially valuable for rotating on-call engineers who may not be familiar with the full site topology.
Automating transfers in CI/CD pipelines
Manual package uploads do not scale for teams running daily deployments. Tools like the FileVault Content Maven Plugin and Groovy Console scripts allow packages to be built, downloaded, and uploaded through HTTP endpoints. Jenkins, GitHub Actions, and GitLab CI all support these patterns through standard HTTP steps. The key is to externalize credentials and use service users rather than personal accounts.
For teams spread across Adelaide and Perth, time zone differences make automation essential. A pipeline that builds a package on commit, deploys it to a test environment, runs smoke tests, and promotes it to staging reduces the need for after-hours manual interventions. Engineers in Perth can review the next morning's deployment status without staying up to watch logs. The 2.5-hour time difference between Sydney and Perth makes synchronous collaboration difficult, so automated pipelines fill the gap.
Resources like the AEM content sync walkthrough cover similar automation patterns for remote field operations, particularly relevant for mining sites in the Pilbara or agricultural operations in regional Queensland. Reliable content delivery to remote sites often requires the same dependency management principles as standard package imports.
Troubleshooting common portability issues
Package upload failures often stem from filter misconfigurations or repository permission problems. Checking the error.log on the target instance reveals whether the issue is path-based, validation-based, or transport-based. Transient network failures during large uploads are increasingly rare on Australia's NBN but still occur on satellite links in remote areas. Having a retry policy in your upload script handles most transient failures gracefully.
When packages include references to components not present in the target environment, authors see broken page rendering. Importing the corresponding /apps package first usually resolves this. Teams in Hobart and Darwin managing smaller regional sites often keep a baseline component package ready for quick repair of broken imports. This is faster than debugging the exact missing dependency and re-exporting a corrected package.
For bulk content uploads outside the package workflow, the WebDAV integration approach offers a complementary method when ZIP archives prove unwieldy. Each method has its place depending on volume, frequency, and the need for atomic operations.
Review the session recordings from the 2015 and 2016 Chicago conferences on the CIRCUIT website to see these patterns in action. Subscribe to the event updates to hear about future gatherings, or share your own packaging approaches with the AEM community through the site's contact page.