Publishing overview

Publishing handles how content gets published from an author instance to a public instance. Publishing is installed by the Publishing module and extended by the Publishing Transactional module (in DX Core).

The publishing implementation also allows you to define and use custom publishing operations with which you can publish content to something that’s not a Magnolia public instance, for example to a custom API or a Content Delivery Network.

How publishing works

On the author instance

Collecting

The PublishingCommand collects the content that needs to be (un)published. It then creates a new instance of Sender containing the collected content. The Sender component is responsible for content packaging. By default, only modified nodes are published.

Node collection for different publishing scenarios is outlined below.

  • Publication is recursive:

    • itemsPerRequest is set and if the number of child nodes is less than 1000: nodes are batched into chunks to improve publication speed (however, this does not work with versions).

    • Publishing versions: node versions are collected, and nodes are ordered bottom-up for publishing.

  • Publication isn’t recursive (Default):

    • The current node is taken.

    • Publishing a version: the node’s current version is taken.

Large flat content repositories can negatively impact overall performance, particularly search. For this reason, you must organize pages into a folder hierarchy to ensure optimal performance. Also, features that constantly create content (such as messages, tasks, and versions) should be checked regularly to clean up old content.

Versioning

Upon publication, all nodes are copied to the magnolia-mgnlVersion workspace on the author instance. Depending on how the publication command chain is configured, the content is usually copied before packaging and sending. If no version command is present in the publication command chain, no versions are created. The maxVersionIndex, which defines version limits, is configured in /server/versions and affects the number of versions stored in the mgnlVersion workspace.

Packaging

A Package consists of properties and files that will be sent to the public instance. Packages are only used with a publication and are created by the Packager, which adds the properties and XML exports of the content to a Package.

Sending

The Sender creates an instance of SenderOperation and passes either a Package or a Node to the instance, together with a ReceiverDefinition. Whether a package or node is passed depends on the action involved.

  • Package upon publication

  • Node when unpublishing content

The SendOperation executes the transfer to the public instance.

On the public instance

Receiving

The PublicationFilter receives a sender’s request. The request is then sent to the Dispatcher which decides what to do with the request depending on the request headers. The Dispatcher extracts the data from the request and creates a ReceiveOperation responsible for creating/updating/deleting the content.

Ordering of siblings

Published nodes are included before the nearest next sibling existing on all author and public instances. The order of siblings of the published node on public instances isn’t otherwise affected.

Go to the optimize ordering section for more information on adapting the ordering to fulfill your needs.

This default behavior doesn’t take into account the order at any other point in time (such as the time of creating the published version).

Rollback

The magnolia-mgnlSystem workspace is used on public instances in case rollback is necessary if publication failure occurs. Existing published content is copied there before new content is published to the target workspace (for example, website). In case of failure, rollback is initiated, copying content from mgnlSystem back to the target workspace.

Other aspects

Authentication and security

Publishing is authenticated using public-key cryptography. The authentication configuration for publishing is stored in /server/activation; see Publishing security for more on this.

Locking

Each publishing request executes a lock for either a path or node where content is to be published.

Path-based locking has been introduced as the default way of locking with version 1.2.6 of the Publishing module. Node-based locking is available for compatibility reasons. See the lockManagerMode property on the module page for configuration details.

If two users publish to the same (sub)tree, the locking mechanism waits a predefined amount of time and tries to obtain a lock for the operation. If the operation receives the lock, it can proceed with content (un)publishing. If not, publishing is considered unsuccessful and the respective status code is returned to the sender.

Content publishing and content synchronization

Always wait with content publishing actions until all content synchronization tasks have been finished.

If you attempt to publish a page while the Synchronization module is mid-sync and hasn’t yet synchronized the page’s parent, the publishing process will fail.

Recursive and non-recursive publishing

Magnolia supports two methods of publishing content:

  • Non-recursive, which publishes only the selected node and its properties.

  • Recursive, which publishes the selected node, its properties, and its children.

Items that are marked for deletion are permanently deleted if their parent node is published recursively.

You can’t publish the root node programmatically, but you can recursively publish its subnodes using the publishing command. You also can’t unpublish the root node or its subnodes. Instead, you must unpublish subnodes under the root node one by one.

Transactional publishing

Transactional publishing provides a way to publish content-managed transactions. Content is:

  • commited if all receivers respond with success status.

  • rollbacked if at least one of the receivers respond with error status.

The transactional publishing receiver uses mgnlSystem workspace to store the backups of the published content. If content is to be commited, the backup is removed. If content is to be rollbacked, the backup is restored to the workspace it belongs to.

Transport layer

By default Magnolia uses the HTTP transport layer.

Workspaces are publishable by default

The Publishing module makes all workspaces publishable by default.

Disable the publishing workflow in the Pages app

Magnolia ships with publishing approval and rejection workflows. By default, they are only enabled in the Pages app.

Disabling the workflow in the Pages app may be appropriate for a simple site workflow where there are no separate editor and publisher roles.

There are several options to disable the publishing workflow for the Pages app.

  1. Create a DX Core webapp that excludes the Workflow and Personalization modules.

  2. Decorate the pages-app and add a dependency to workflow-pages. The dependency is necessary so that the light module decoration isn’t overridden again.

    Click to see the decorations

    /light-modules/my-module/decorations/pages-app/apps/pages-app.subApps.yaml
    browser:
  actions:
    publish: !override
      icon: icon-publish
      $type: jcrCommandAction
      command: personalizationActivation
      availability:
        writePermissionRequired: true
        rules:
          isPublishable:
            $type: jcrPublishableRule
    publishRecursive: !override
      icon: icon-publish-incl-sub
      $type: jcrCommandAction
      command: personalizationActivation
      params:
        recursive: true
      availability:
        writePermissionRequired: true
        rules:
          isPublishable:
            $type: jcrPublishableRule
    light-modules/my-module/module.yaml
    version: 1.0.2
displayName: Shareable
dependencies:
  workflow-pages:
    version: 6.0/*

    Removing a decoration?

    The only way to remove an existing decoration is to either override it with another decoration or remove the whole module with the original decoration.

  3. Delete the content of the workflow-pages decoration. This approach doesn’t persist the changes when an instance is upgraded and involves extra configuration steps.

    Click to see more details

    Editing a resource in the Resources files app creates a copy of the recourse in JCR. This isn’t recommended for deployment and maintenance. For productive environments, you should use a decorator, as described above.


    Resource Files app

    1. Go to the Resource Files app.

    2. Search for pages-app.

    3. Select the file /workflow-pages/decorations/pages-app/apps/pages-app/pages-app.subApps.yaml.

    4. Click Edit file.

      Make a copy of the contents if you need to restore the four-eye workflow actions later.

    5. Delete its contents and Save changes.

    Configuration app

    1. Add the itemTypes property on the /modules/publishing-core/commands/default/publish/publish node as shown below.

      /modules/publishing-core/commands/default/publish/publish
      Node name Value

      ⸬ publish

           ⸬ publish

               ⬩ class

      info.magnolia.publishing.command.PublicationCommand

               ⬩ itemTypes

      mgnl:contentNode,mgnl:componentVariants
Feedback

DX Core

×

Location

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

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules