Configure packages
You can do the following configuration steps on an author instance.
Once you have created and built a package, it can be downloaded, uploaded, deleted, and imported on both author and public instances. See Use packages for more details.
Create packages
You can create packages containing content from workspaces in Magnolia. One or more rule sets within a package definition define a package’s content. From the create package page, you can also build the package content once defined and download it to install it on another environment.
Follow the steps below to create a package:
-
Open the Package Manager app.
-
Click + Create package.
-
On the New Package form, type in a package name and description.
-
Click + Rule set to add package definitions to the new package.
When packaging content from the website workspace, remember to also package any assets from the assets workspace that are used on those pages. -
Click Create Package.
You’re notified of the creation progress in the bottom left corner. It’s added to the top of the list of packages on the package browser tab.
Example package definitions
This section explains package definitions through examples of content before installation, package rule sets, and final content results. All rule sets in these examples generate packages from the original Travel Demo website. The outcome of installing these packages is determined by the instance content prior to installation, package contents, and the chosen import mode.
See also the FileVault Workspace Filter documentation for more details.
Filters are evaluated relative to a rule set’s Root path.
Only nodes that match both the root and the filter are traversed.
This mirrors the behavior described in FileVault Usage for Export.
|
Use case 1: No existing content
You want to install a package into a clean environment.
Result: The new content is installed.
Use case 2: Insert new content
You want to install a package with the Careers pages into an existing environment that doesn’t have these pages yet.
Also, you need to omit marketing-associate from those pages because that page isn’t ready yet.
Results:
-
The
Careerspage is replaced with new content. -
New pages are installed under the
Careerspage.
-
Workspace:
website -
Root:
/travel/about/careers -
Exclude filter:
/travel/about/careers/marketing-associate
In this example, you apply this rule set to the Travel Demo website on the author instance when creating the package.
After this package is successfully built, you should use the Replace import mode when installing the package into the clean environment.
If you use the merge import mode, the existing Careers page is left untouched.
|
Use case 3: Insert new content and remove existing content
You want to Install a package with the Careers pages into an existing environment that includes a subpage which should to be removed.
Also you need to omit marketing-associate from those pages because that page isn’t ready yet.
Results:
-
Careerspage is replaced with new content. -
New pages are installed under the
Careerspage. -
The page that should be removed is gone.
-
Workspace:
website -
Root:
/travel/about/careers -
Exclude filter:
/travel/about/careers/marketing-associate
In this example, you apply this rule set to the Travel Demo website on the author instance when creating the package.
After this package is successfully built, you should use the Replace import mode when installing the package into the clean environment.
| Neither merge nor update removes the page that should be removed, as only replace removes existing pages that aren’t in the package. |
Use case 4: Insert new content and preserve existing content
You want to install a package with the Careers pages into an existing environment that doesn’t have these pages yet.
Also, you need to omit marketing-associate from those pages because that page isn’t ready yet.
Finally, you want to preserve whatever is under the Careers page.
Results:
-
The
Careerspage is left untouched. -
Pages are installed under the
Careerspage. -
Existing pages under
Careersare preserved.
-
Workspace:
website -
Root:
/travel/about/careers -
Exclude filter:
/travel/about/careers/marketing-associate
In this example, you apply this rule set to the Travel Demo website on the author instance when creating the package.
After this package is successfully built, you should use the Merge import mode when installing the package into the existing environment.
If you want to keep the page keep-this-page, for example, and install a package that includes the same page but with a new title, but-add-this-title, the merge import mode keeps the page and adds the new title, which didn’t exist in the workspace already.
|
Use case 5: Single pages, page areas, and assets
This use case presents some typical rule sets that you might need when creating packages.
-
A single page under a parent path, excluding all other subpages.
-
Content for specific pages, but only including their areas (for example,
main,header,footer) and their components. -
A single asset, including its binary data.
The exclude filter below excludes the subpages company, what-we-believe, and careers under /travel/about.
-
Workspace:
website -
Root:
/travel/about -
Exclude filter:
/travel/about/(company|what-we-believe|careers)
Use multiple rule sets, one per page.
Each rule set targets the page root and includes only the area nodes and their descendants.
The include filter below includes the areas and their components of the /travel/about/company page, including keywords and metatags.
-
Workspace:
website -
Root:
/travel/about/company -
Include filter:
/travel/about/company/(main|header|footer|keywords|metaTags)(/.*)?
You can repeat this analogically for any remaining pages.
For example, the include filter below includes the areas and their components of the /travel/about/what-we-believe page, including keywords and metatags.
-
Workspace:
website -
Root:
/travel/about/what-we-believe -
Include filter:
/travel/about/what-we-believe/(main|header|footer|keywords|metaTags)(/.*)?
Assets store their binary data under a jcr:content node, so point the rule set root directly to the asset’s root path to include the binary.
-
Workspace:
dam -
Root:
/twitter.png -
No filters required
Installation modes
If content exists already on the target instance, the options below allow you to define what happens to it on install. See the FileVault Import Mode documentation for more details.
-
Replace: Content from the package replaces any content found in the same path on the current instance. Use this option if you want to replace any content on the current instance with the content present in the package. This means that existing content is overridden or deleted as necessary. -
Merge: This option installs content from the package only to paths that don’t already exist on the current instance. It’s ideal for incorporating new package content while safeguarding existing content on the instance. -
Update: Existing content on the current instance is updated with package content, and new package content is added. Any existing content on the server not included in the package remains untouched.When installing content, the order of content on the target instance may differ from the order on the source instance. Be careful when choosing the installation mode if the target already contains content created by a different import mechanism (for example, Magnolia’s Export/Import, not Package Manager). Those nodes may have UUIDs different from those in your package. Using MergeorUpdatein such cases can lead to node collisions (for example, “node exists with a different UUID”). For an initial install to a target that already has content at the same paths, preferReplace, or delete the existing subtree before installing the package. Avoid mixing import mechanisms for the same paths.
FileVault: ImportMode
Package Manager uses FileVault’s import modes to install packages. The table on their FileVault API: ImportMode documentation page summarizes how imported content is applied to existing content in the repository based on FileVault method descriptions.
Publication metadata
When a package is built, publication-related metadata is excluded from the package.
This exclusion causes all installed nodes to be set to the DRAFT status when you install a package with the Replace installation mode.
With Merge and Update installation modes, publication metadata on the target remains untouched.
An overview of the publication status for each installation mode:
| Scenario | Replace | Merge | Update |
|---|---|---|---|
Existing published page, untouched on the instance. |
|
|
|
Component added to a page; you publish the page before building the package. |
|
|
|
Component modified on the page; you publish the page after building the package. |
|
|
|
Page doesn’t exist on the instance. |
|
|
|
Edit packages
Editing a built or live package discards any built content. The package then returns to a draft state, and you must rebuild the package if you want to push it to an instance.
Build or rebuild packages
Once you’ve defined a package with its workspace(s), root nodes, and filters, you can proceed to build it. Building a package generates a .zip file containing your content. The build process can be initiated either from the browser view or while editing the package. After a successful build, the package can then be pushed to an instance.
Build while editing a package
-
Open the Package Manager app.
-
Edit a package in the browser view.
If you edit a package, you must rebuild it before you can download or import its contents. You can’t cancel a build process once it has started. 
-
Click Build package.
Want to look at built packages in the JCR?
Packages are created and built, then stored in the packages workspace in JCR.
The magnolia.packagemanager.storage.binaries.path property defines the storage location for binaries when a package is built.
By default, this is the instance’s root folder (for example, /apache-tomcat/webapps/magnoliaAuthor/packmanBinaries).
