Packages enable the importing and exporting of repository content. You can use packages to install new content, install new functionality, transfer content between instances, and back up repository content.
Using Package Manager, you can transfer packages between your AEM instance and your local file system for development purposes.
A package is a zip file holding repository content in file-system serialization form, called vault serialization, providing an easy-to-use and easy-to-edit representation of files and folders. Content included in the package is defined by using filters.
A package also contains vault meta information, including the filter definitions and import configuration information. Additional content properties, which are not used for package extraction, can be included in the package, such as a description, a visual image, or an icon. These additional content properties are for the content package consumer and for informational purposes only.
Packages represent the current version of the content at the time the package is built. They do not include any previous versions of the content that AEM keeps in the repository.
Package Manager manages the packages on your AEM installation. After you have assigned the necessary permissions you can use Package Manager for various actions, including configuring, building, downloading, and installing your packages.
To create, modify, upload, and install packages, users must have the appropriate permissions on the following nodes:
/etc/packages
Granting permissions for packages may lead to sensitive information disclosure and data loss.
To limit these risks, it is highly recommended to grant specific group permissions over dedicated subtrees only.
You can access Package Manager in three ways:
http://<host>:<port>/crx/packmgr/
Package Manager is divided into four main functional areas:
Clicking an option in the Left Navigation Panel immediately filters the Package List.
Clicking a package name expands the entry in the Package List to show more detail about the package.
There are number of actions that can be taken on a package via the toolbar buttons available when the package detail is expanded.
Further actions are available beneath the More button.
Each entry in the package list has a status indicator to let you know at a glance the status of the package. Hovering over the status reveals tooltip with the detail of the status.
If the package has been changed or was never built, the status is presented as a link to take quick action to rebuild or install the package.
A package is essentially a set of filters and the repository data based on those filters. Using the Package Manager UI, you can click on a package and then the Edit button to view the details of a package including the following settings.
You can edit a variety of package settings to define information such as the package description, dependencies, and provider details.
The Package Settings dialog is available via the Edit button when creating or editing a package. After any changes are made, click Save.
Field | Description |
---|---|
Name | The name of the package |
Group | For organizing packages, you can type the name of a new group or select an existing group |
Version | Text to use for the version |
Description | A brief description of the package allowing HTML markup for formatting |
Thumbnail | The icon that appears with the package listing |
A thumbnail provides a quick-reference visual representation of what the package contains. This is then shown in the package list and can help easily identify the package, or the class of package.
The following are examples of conventions are used for official packages:
Official Hotfix
Official AEM Installation of Extension
Official Service Pack
Use a unique icon for your package. Do not reuse an icon used by Adobe.
Filters identify the repository nodes to include in the package. A Filter Definition specifies the following information:
Add rules using the + button. Remove rules using the - button.
Rules are applied according to their order so position them as required using the Up and Down arrow buttons.
Filters can include zero or more rules. When no rules are defined, the package contains all content below the root path.
You can define one or more filter definitions for a package. Use more than one filter to include content from multiple root paths.
When creating filters, you can define a path or use a regular expression to specify all the nodes that you want to include or exclude.
Rule Type | Description |
---|---|
include | Including a directory will include that directory and all the files and folders in that directory (i.e. the entire subtree) but will not include other files or folders from under the specified root path. |
exclude | Excluding a directory will exclude that directory and all files and folders in that directory (i.e. the entire subtree). |
Package filters are most often defined when you first create the package. However they can also be edited later, after which the package should be rebuilt to update its content based on the new filter definitions.
One package can contain multiple filter definitions so that nodes from different locations can easily be combined into one package.
Field | Description | Example/Details |
---|---|---|
Tested with | The product name and version this package is targeted to or is compatible with. | 6.5 |
Fixed issues | A text field allowing for listing details of bugs fixed with this package, one bug per line | - |
Depends on | Lists other packages necessary so that the current package runs as expected when installed | groupId:name:version |
Replaces | A list of deprecated packages that this package replaces | groupId:name:version |
Field | Description | Example/Details |
---|---|---|
Name | The name of the provider of the package | WKND Media Group |
URL | URL of the provider | https://wknd.site |
Link | Package-specific link to a provider page | https://wknd.site/package/ |
Requires | Defines if there are any restrictions when installing the package | Admin - The package must only be installed with admin privileges Restart - AEM must be restarted after installing the package |
AC Handling | Specifies how the access control information defined in the package is handled when the package is imported | Ignore - Preserve ACLs in the repository Overwrite - Overwrite ACLs in the repository Merge - Merge both sets of ACLs MergePreserve - Merge access control in the content with the one provided with the package by adding the access control entries of principals not present in the content Clear - Clear ACLs |
You can attach multiple screenshots to your package to provide a visual representation of how the content appears.
There are many actions that can be taken on a package.
Click Create Package.
If your instance has a lot of packages, there might be a folder structure in place. In such cases, it is easier to navigate to the required target folder before creating the new package.
In the New Package dialog, enter the following fields:
Package Name - Select a descriptive name to help you (and others) easily identify the contents of the package.
Version - This is a textual field for you to indicate a version. This is appended to the package name to form the name of the zip file.
Group - This is the target group (or folder) name. Groups help you organize your packages. A folder is created for the group if it does not already exist. If you leave the group name blank, it will create the package in the main package list.
Click OK to create the package.
AEM lists the new package at the top of the list of packages.
Click Edit to define the package contents. Click Save after you are finished editing the settings.
You can now Build your package.
It is not compulsory to immediately build the package after creating it. An unbuilt package contains no content and consists of only the filter data and other metadata of the package.
A package is often built at the same time as you create the package, but you can return at a later point to either build or rebuild the package. This can be useful if the content within the repository has changed or the package filters have changed.
Open the package details from the package list by clicking the package name.
Click Build. A dialog asks for confirmation that you do want to build the package since any existing package contents will be overwritten.
Click OK. AEM builds the package, listing all content added to the package as it does so in the activity list. When complete AEM displays a confirmation that the package was built and (when you close the dialog) updates the package list information.
Once a package is uploaded to AEM, you can modify its settings.
Open the package details from the package list by clicking the package name.
Click Edit and update the Package Settings as required.
Click Save to save.
You may need to rebuild the package to update its contents based on the changes you made.
Once a package has been built, it can be rewrapped. Rewrapping changes the package information without such as thumbnail, description, etc., without changing the package content.
Open the package details from the package list by clicking the package name.
Click Edit and update the Package Settings as required.
Click Save to save.
Click More -> Rewrap and a dialog will ask for confirmation.
Because every version of a package appears in the list as any other package, Package Manager can find other versions of a selected package.
Open the package details from the package list by clicking the package name.
Click More -> Other Versions and a dialog opens with a list of other versions of the same package with status information.
After a package has been built, you can view the contents.
Open the package details from the package list by clicking the package name.
To view the contents, click More -> Contents, and Package Manager lists the entire contents of the package in the activity log.
To perform a dry run of the installation click More -> Test Install and Package Manager reports in the activity log the results as if installation were performed.
Open the package details from the package list by clicking the package name.
Click the Download button or the linked file name of the package in the package details area.
AEM downloads the package to your computer.
Package Share was a centralized public service to distribute content packages. Package Share has ben superseded by Software Distribution and this button no longer works.
Select the group folder into which you want the package to be uploaded.
Click the Upload Package button.
Provide the necessary information about the uploaded package.
Click OK and the selected package is uploaded and the package list is updated accordingly.
The package content now exists on AEM, but o make the content available for use, be sure to install the package.
Because packages can modify existing content, it is often useful to validate these changes before installing.
Package Manager can perform the following validations:
What’s Checked
This validation inspects the package for all JAR files (OSGi bundles), extracts their manifest.xml
(which contains the versioned dependencies on which said OSGi bundle relies), and verifies the AEM instance exports said dependencies with the correct versions.
How It’s Reported
Any versioned dependencies that cannot be satisfied by the AEM instance are listed in the Activity Log of Package Manager.
Error States
If dependencies are unsatisfied, then the OSGi bundles in the package with those dependencies will not start. This results in a broken application deployment as anything relying on the unstarted OSGi bundle will in turn not function properly.
Error Resolution
To resolve errors due to unsatisfied OSGi bundles, the dependency version in the bundle with unsatisfied imports must be adjusted.
What’s Checked
This validation determines if the package being installed contains a file that is already overlaid in the destination AEM instance.
For example, given an existing overlay at /apps/sling/servlet/errorhandler/404.jsp
, a package that contains /libs/sling/servlet/errorhandler/404.jsp
, such that it will change the existing file at /libs/sling/servlet/errorhandler/404.jsp
.
How It’s Reported
Any such overlays are described in the Activity Log of Package Manager.
Error States
An error state means that the package is attempting to deploy a file that is already overlaid, thus the changes in the package will be overridden (and thus “hidden”) by the overlay and not take effect.
Error Resolution
To resolve this issue, the maintainer of the overlay file in /apps
must review the changes to the overlaid file in /libs
and incorporate the changes as needed into the overlay ( /apps
), and redeploy the overlaid file.
The validation mechanism has no way to reconcile if the overlaid content has been properly incorporated into the overlay file. Therefore this validation will continue to report over conflicts even after the necessary changes have been made.
What’s Checked
This validation checks which permissions are being added, how they will be handled (merge/replace), and if the current permissions will be impacted.
How It’s Reported
The permissions are described in the Activity Log of Package Manager.
Error States
No explicit errors can be provided. The validation simply indicates whether any new ACL permissions will be added or impacted by installing the package.
Error Resolution
Using the information provided by the validation, the impacted nodes can be reviewed in CRXDE and the ACLs can be adjusting in the package as needed.
As best practice it is recommended that packages should not affect AEM-provided ACLs as this may result in unexpected behavior.
Validation of packages can be done in two different ways:
Validation should always occur after uploading the package but before installing it.
Open the package details from the package list by clicking the package name.
To validate the package, click More -> Validate,
In the modal dialog box that then appears, use the checkboxes to select the type(s) of validation and begin the validation by clicking Validate.
The chosen validation(s) is/are then run and the results are displayed in the Activity Log of Package Manager.
The POST request takes the following form.
https://<host>:<port>/crx/packmgr/service.jsp?cmd=validate&type=osgiPackageImports,overlays,acls
The type
parameter can be any comma-separated, unordered list consisting of:
osgiPackageImports
overlays
acls
The value of type
defaults to osgiPackageImports
if not explicitly passed.
When using cURL, execute a statement similar to the following:
curl -v -X POST --user admin:admin -F file=@/Users/SomeGuy/Desktop/core.wcm.components.all-1.1.0.zip 'http://localhost:4502/crx/packmgr/service.jsp?cmd=validate&type=osgiPackageImports,overlays,acls'
When validating via POST request, the response is sent back as a JSON object.
Packages are defined by their filters. You can have Package Manager apply filters of a package to your existing repository content to show what content of the repository is covered by the filter definition of the package.
Open the package details from the package list by clicking the package name.
Click More -> Coverage.
The coverage details are listed in the Activity Log.
Uploading a package only adds the package content to the repository, but it is not accessible. You must install the uploaded package in order to use the package’s content.
Installing a package can overwrite or delete existing content. Only upload a package if you are sure that it does not delete or overwrite content that you need.
Prior to installation of your package, Package Manager automatically creates a snapshot package that contains the content that will be overwritten. This snapshot will be reinstalled if you uninstall your package.
Open the package details of the package you wish to install from the package list by clicking the package name.
Either click the Install button in the item details or the Install link in the package status.
A dialog will request confirmation and allow for additional options to be specified.
Click Install.
The Activity Log details the progress of the installation.
Once the installation is complete and successful, the package list is updated and the word Installed appears in the package status.
Reinstalling packages performs the same steps on an already installed package that are processed when initially installing the package.
You can forego Package Manager altogether when installing packages. AEM can detect packages placed in a specific location on the local filesystem of the host machine and upload and install them automatically.
Under the AEM installation folder, there is a crx-quicksart
folder alongside the jar and license.properties
file. Create a folder named install
under crx-quickstart
resulting in the path <aem-home>/crx-quickstart/install
.
In this folder, add your packages. They will automatically be uploaded and installed on your instance.
Once upload and installation is complete, you can see the packages in Package Manager as if you had used the Package Manager UI to install them.
If the instance is running, the upload and the installation begins immediately when you add it to the package to the install
folder
If the instance is not running, packages placed in the install
folder are installed at startup in alphabetical order.
Uninstalling package reverts the contents of the repository to the snapshot made automatically by Package Manager prior to installation.
Open the package details of the package you wish to uninstall from the package list by clicking the package name.
Click More -> Uninstall, to remove the contents of this package from the repository.
A dialog will request confirmation and list all changes being made.
The package is removed and the snapshot is applied. Progress of the process is shown in the Activity Log.
Deleting a package only deletes its details from Package Manager. If this package was already installed, then the installed content will not be deleted.
Open the package details of the package you wish to delete from the package list by clicking the package name.
Package Manager asks for confirmation that you want to delete the package. Click OK to confirm the deletion.
The package information is deleted and details are reported in the Activity Log.
Replicate the contents of a package to install it on the publish instance.
Open the package details of the package you wish to replicate from the package list by clicking the package name.
Click More -> Replicate.
The package is replicated and details are reported in the Activity Log.
AEM Packages can be used to create and share content across AEM environments.
Software Distribution is a centralized service designed to simplify the search and download of AEM packages.
For more information, please refer to the Software Distribution documentation.
Package Manager is not currently integrated with Software Distribution as it was with the former Package Share service. Therefore the share buttons and other links to Package Share within Package Manager no longer work. The solution is to download packages to your local disk.