Package Manager
- Topics:
- Administering
CREATED FOR:
- Admin
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.
NOTEPackage 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
CAUTIONAccessing Package Manager
You can access Package Manager in three ways:
- From the AEM main menu > Tools > Deployment > Packages
- From CRXDE Lite using the top switcher bar
- 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 lets you 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 and 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.
Further actions are available beneath the More button.
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 a package and then the Edit button to view the details of a package including the following settings.
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 rules, you define a regular expression (also known as regex, regexp or rational 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.
TIPTIPDependencies
6.5groupId:name:versiongroupId:name:versionAdvanced Settings
WKND Media Grouphttps://wknd.sitehttps://wknd.site/package/Restart - AEM must be restarted after installing the package
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
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
-
Click Create Package.
TIPIf your instance has many 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.
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.
-
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.
Editing a Package
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.
Rewrapping a Package
Once a package has been built, it can be rewrapped. Rewrapping changes the package information without such as thumbnail, description, and so on, 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.
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.
-
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.
Viewing Package Contents and Testing Installation
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.
Downloading Packages to Your File System
-
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.
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
-
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.
- 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.
-
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:
Validate OSGi Package Imports
What is 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 is 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 is 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 is eported
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.
NOTEValidate ACLs
What is 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 is 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.
CAUTIONPerforming Validation
Validation of packages can be done in two different ways:
Validation should always occur after uploading the package but before installing it.
Package Validation Via Package Manager
-
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.
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:
osgiPackageImportsoverlaysacls
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.
-
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.
Installing Packages
Uploading a package only adds the package content to the repository, but it is not accessible. Install the uploaded package to use the package’s content.
CAUTIONPrior 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.
CAUTION- If you are installing digital assets, you must:
First, deactivate the WorkflowLauncher.
Use the Components menu option of the OSGi console to deactivatecom.day.cq.workflow.launcher.impl.WorkflowLauncherImpl. - Next, when installation is complete, reactivate the WorkflowLauncher.
-
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.
- 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
-
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
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.
-
Under the AEM installation folder, there is a
crx-quicksartfolder alongside the jar andlicense.propertiesfile. Create a folder namedinstallundercrx-quickstartresulting 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 Packages
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 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.
-
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.
Replicating Packages
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.
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, see the Software Distribution documentation.
NOTE