Package Manager

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.

What are Packages?

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.

Package Manager

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.

Required Permissions

To create, modify, upload, and install packages, users must have the appropriate permissions on the following nodes:

• Full rights excluding delete on /etc/packages
• The node that contains the package contents

Accessing Package Manager

You can access Package Manager in three ways:

1. From the AEM main menu -> Tools -> Deployment -> Packages
2. From CRXDE Lite using the top switcher bar
3. Directly by accessing http://<host>:<port>/crx/packmgr/

Package Manager UI

Package Manager is divided into four main functional areas:

• Left Navigation Panel - This panel allows you to filter and sort the list of packages.
• Package List - This is the list of packages on your instance filtered and sorted per selections in the Left Navigation Panel.
• Activity Log - This panel is minimized at first and expands to detail the activity of Package Manager such as when a package is built or installed. There are additional buttons in the Activity Log tab to:
  • Clear Log
  • Show/Hide
• Toolbar - The toolbar contains refresh buttons for the Left Navigation Panel and Package list as well as buttons for searching, creating, and uploading packages.

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.

• Edit
• Build
• Reinstall
• Download
• Share

Further actions are available beneath the More button.

• Delete
• Coverage
• Contents
• Rewrap
• Other Versions
• Uninstall
• Test Install
• Validate
• Replicate

Package Status

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.

Package Settings

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.

• General Settings
• Package Filters
• Package Dependencies
• Advanced Settings
• Package Screenshots

General 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.

Package Thumbnails

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.

Package Filters

Filters identify the repository nodes to include in the package. A Filter Definition specifies the following information:

• The Root Path of the content to include
• Rules that include or exclude specific nodes below the root path

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.

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.

Dependencies

Advanced Settings

Package Screenshots

You can attach multiple screenshots to your package to provide a visual representation of how the content appears.

Package Actions

There are many actions that can be taken on a package.

Creating a Package

1. Access Package Manager.

2. Click Create Package.

   TIP

   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.

3. 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.

4. Click OK to create the package.

5. AEM lists the new package at the top of the list of packages.

   

6. Click Edit to define the package contents. Click Save after you are finished editing the settings.

7. 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.

Building a 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.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click Build. A dialog asks for confirmation that you do want to build the package since any existing package contents will be overwritten.

4. 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.

Editing a Package

Once a package is uploaded to AEM, you can modify its settings.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click Edit and update the Package Settings as required.

4. Click Save to save.

You may need to rebuild the package to update its contents based on the changes you made.

Rewrapping a Package

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.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click Edit and update the Package Settings as required.

4. Click Save to save.

5. Click More -> Rewrap and a dialog will ask for confirmation.

Viewing Other Package Versions

Because every version of a package appears in the list as any other package, Package Manager can find other versions of a selected package.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click More -> Other Versions and a dialog opens with a list of other versions of the same package with status information.

Viewing Package Contents and Testing Installation

After a package has been built, you can view the contents.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. To view the contents, click More -> Contents, and Package Manager lists the entire contents of the package in the activity log.

   

4. 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.

   

Downloading Packages to Your File System

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click the Download button or the linked file name of the package in the package details area.

4. AEM downloads the package to your computer.

Sharing a Package

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.

Uploading Packages from Your File System

1. Access Package Manager.

2. Select the group folder into which you want the package to be uploaded.

3. Click the Upload Package button.

4. Provide the necessary information about the uploaded package.

   

   • Package - Use the Browse… button to select the required package from your local file system.
   • Force Upload - If a package with this name already exists, this option forces the upload and overwrites the existing package.

5. 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.

Validating Packages

Because packages can modify existing content, it is often useful to validate these changes before installing.

Validation Options

Package Manager can perform the following validations:

• OSGi Package Imports
• Overlays
• ACLs

Validate OSGi Package Imports

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.

Validate Overlays

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.

Validate ACLs

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.

Performing Validation

Validation of packages can be done in two different ways:

• Via the Package Manager UI
• Via HTTP POST request such as with cURL

Validation should always occur after uploading the package but before installing it.

Package Validation Via Package Manager

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. To validate the package, click More -> Validate,

4. 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.

5. The chosen validation(s) is/are then run and the results are displayed in the Activity Log of Package Manager.

Package Validation Via HTTP POST Request

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.

Viewing Package Coverage

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.

1. Access Package Manager.

2. Open the package details from the package list by clicking the package name.

3. Click More -> Coverage.

4. The coverage details are listed in the Activity Log.

Installing Packages

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.

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.

1. Access Package Manager.

2. Open the package details of the package you wish to install from the package list by clicking the package name.

3. Either click the Install button in the item details or the Install link in the package status.

4. A dialog will request confirmation and allow for additional options to be specified.

   • Extract Only - Extract the package only so that no snapshot is created and therefore uninstall will not be possible
   • Save Threshold - Number of transient nodes until automatic saving is triggered (increase if you encounter concurrent modification exceptions)
   • Extract Subpackages - Enable automatic extraction of sub packages
   • Access Control Handling - Specifies how the access control information defined in the package is handled when the package is installed (options are the same as the advanced package settings)
   • Dependencies Handling - Specify how dependencies are handled during installation

5. Click Install.

6. 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

Reinstalling packages performs the same steps on an already installed package that are processed when initially installing the package.

File System Based Upload and Installation

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.

1. 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.

2. In this folder, add your packages. They will automatically be uploaded and installed on your instance.

3. 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 Packages

Uninstalling package reverts the contents of the repository to the snapshot made automatically by Package Manager prior to installation.

1. Access Package Manager.

2. Open the package details of the package you wish to uninstall from the package list by clicking the package name.

3. Click More -> Uninstall, to remove the contents of this package from the repository.

4. A dialog will request confirmation and list all changes being made.

5. The package is removed and the snapshot is applied. Progress of the process is shown in the Activity Log.

Deleting Packages

Deleting a package only deletes its details from Package Manager. If this package was already installed, then the installed content will not be deleted.

1. Access Package Manager.

2. Open the package details of the package you wish to delete from the package list by clicking the package name.

3. Package Manager asks for confirmation that you want to delete the package. Click OK to confirm the deletion.

4. The package information is deleted and details are reported in the Activity Log.

Replicating Packages

Replicate the contents of a package to install it on the publish instance.

1. Access Package Manager.

2. Open the package details of the package you wish to replicate from the package list by clicking the package name.

3. Click More -> Replicate.

4. The package is replicated and details are reported in the Activity Log.

Software Distribution

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.