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:

  1. Open the Package Manager app.

  2. Click + Create package.

    Package Manager app

  3. On the New Package form, type in a package name and description.

    Package Manager - Create Package

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

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

Use case 1: No existing content

You want to install a package into a clean environment.

Result: The new content is installed.

  • Content before/after

  • Rule set

  • Import mode - Replace

Package Manager - Use case 1

  • Workspace: website

  • Root: /travel

  • No filters required

After this package is successfully built, you should use the Replace import mode when installing the package into the clean environment.

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 Careers page is replaced with new content.

  • New pages are installed under the Careers page.

  • Content before/after

  • Rule set

  • Import mode - Replace

Package Manager - Use case 1

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

Travel Demo website - about subtree

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:

  • Careers page is replaced with new content.

  • New pages are installed under the Careers page.

  • The page that should be removed is gone.

  • Content before/after

  • Rule set

  • Import mode - Replace

Package Manager - Use case 3

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

Travel Demo website - about subtree

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 Careers page is left untouched.

  • Pages are installed under the Careers page.

  • Existing pages under Careers are preserved.

  • Content before/after

  • Rule set

  • Import mode - Merge

Package Manager - Use case 4

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

Travel Demo website - about subtree

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.

Import modes

If content exists already on the target instance, the options below allow you to define what happens to it on import. 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.

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

  1. Open the Package Manager app.

  2. 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.
    Package Manager - Build icon

  3. Click Build package.

    Package Manager - 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.binary.storage.rootPath 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).

Package Manager - Build Package

Duplicate packages

If you don’t want to start from scratch when creating a new package, you can save time by duplicating an existing package. This creates a copy of an existing package duplicating content, filters, and import rules. This approach is helpful when you need to create a package that is similar to an existing one but with some variations.

  1. Open the Package Manager app.

  2. Select a package.

  3. Click Duplicate package.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Package Manager module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules