Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
The Synchronization module synchronizes a target Magnolia instance with a source instance. The module allows you to publish a large amount of content selectively. Only previously published content is transferred to the target instance. You can use the module to add content to new public instances without shutting down existing instances and impacting their ability to serve content.
The module traverses the node tree and publishes only previously published content. Content that was never published is not published during synchronization either. If content was versioned when it was published (Magnolia default behavior), the module publishes the last known version, making it possible to recover modified content.
The Synchronization module installs the Sync Instance app that allows you to manually synchronize content between author and one public instance.
<dependency> <groupId>info.magnolia.synchronization</groupId> <artifactId>magnolia-synchronization</artifactId> <version>2.0.1</version> </dependency>
To be able to use the Sync Instance app, add also the following module:
<dependency> <groupId>info.magnolia.synchronization</groupId> <artifactId>magnolia-synchronization-app</artifactId> <version>2.0.1</version> </dependency>
If you intend to use the Synchronization module together with the Activation and Transactional Activation modules, representing an older implementation of publishing, you must also install the legacy module:
<dependency> <groupId>info.magnolia.synchronization</groupId> <artifactId>magnolia-synchronization-legacy</artifactId> <version>1.8.3</version> </dependency>
This legacy module:
magnolia-module-activation
and magnolia-module-exchange-transactional
modules.magnolia-synchronization-compatibility
, magnolia-synchronization-app
).Imagine that you have two public Magnolia instances. Due to hardware failure, one of them is out of operation. As you try to publish content during the outage, transactional publishing tells you that the content cannot be published because one of the public instances is down.
Since you really need to publish new content to the remaining public instance, you make a conscious decision to switch off the receiver that suffered the hardware failure. Now you can publish the content while waiting for the failed hardware to be replaced.
A few days later hardware on the failed public instance has been replaced and the server is up again. You re-enable the receiver so that all new content is published to both public instances. But you still have a problem with what to do with all the content that was published while the instance was down. Your options are:
All public instances are corrupted, broken or compromised. No instances exist to serve content. A small site can deal with this by creating a new public instance and publishing all content to it. This is difficult in large deployments that have many editors, where content has already been modified since the blackout took effect, and where some pages are not yet ready to be published across the site. Use the Synchronization module to publish any previously published versions of content, even if the content was modified further, and skip any pages that were not previously published.
You have a sudden high load on your site. You need to add a new public instance to deal with the load.
The solution is to create a new empty public instance and use the Synchronization module to publish content only to that instance while the existing public instances keep serving content.
The Synchronization module is configured at Configuration > /modules/synchronization-core
.
Note that the mgnlSystem
and mgnlVersion
workspaces cannot be synchronized using the Synchronization module or Sync Instance tool.
Synchronization is controlled by the SynchronizationCommand (extends BaseActivationCommand
) registered in /modules/synchronization-core/commands/synchronization
:
Node name | Value |
---|---|
modules | |
synchronization-core | |
commands | |
synchronization | |
synchronize | |
syndicator | |
class | info.magnolia.module.synchronization.SilentXASyndicator |
recursive | true |
receivers | |
class | info.magnolia.synchronization.commands.SynchronizationCommand |
Properties:
syndicator | optional Registers the syndicator class. |
| required
|
| optional, default is Executes recursively when set to |
receivers | required Synchronization receivers configurations (see below). |
Configure the target instance as a receiver with subscriptions under it in /modules/synchronization-core/commands/synchronization/synchronize/receivers
.
Node name | Value |
---|---|
commands | |
synchronization | |
synchronize | |
receivers | |
subscriptions | |
extends | /modules/publishing-core/config/receivers |
class | info.magnolia.synchronization.commands.SynchronizationCommand |
recursive |
And /modules/publishing-core/config/receivers
looks like this:
Node name | Value |
---|---|
receivers | |
magnoliaPublic8080 | |
enabled | true |
url | http://localhost:8080/magnoliaPublic |
The Sync Instance tool allows you to manually synchronize content between author and a single public instance. The operation is performed asynchronously.
To perform a manual synchronization:
Click Start. Synchronization starts within one minute of execution.
You must wait for the job to start before starting another one. Otherwise you will overwrite the previous job.
Path examples:
Path | Repository | Recursive | Synchronizes |
| website | Yes | All website pages. |
| website | No |
|
| website | Yes | All pages under |
| users | No | User |
| users | Yes | All admin level users. |
You can schedule synchronization jobs using the Scheduler module. The purpose of scheduling is not to synchronize an instance repeatedly, because this leads to unnecessary flushing of the cache and increases load. The aim is to schedule the sync to occur at a convenient later time such as during low traffic volume.
To configure a synchronization receiver, copy the /modules/scheduler/config/jobs/demo
node and edit its properties.
Node name | Value |
---|---|
modules | |
scheduler | |
config | |
jobs | |
demo | |
params | |
path | /demo-project/about |
repository | website |
catalog | synchronization |
command | synchronize |
cron | 0 0 * * * * |
description | Synchronize /demo-project/about every hour |
enabled | true |
Properties:
<job name>
| required Name of the job, |
| optional Parameters passes to the command. SynchronizationCommand expects/allows the following parameters: |
| required Path to the content, for example |
| optional, default is Set to |
| required Workspace where the content resides, for example |
| required Name of the catalog where the command resides. The SynchronizationCommand resides in the |
| required Name of the command definition node, |
| optional Schedule that indicates the execution time, written as a CRON expression. In our example |
| optional Job description. |
| optional, default is Enables and disables the job. |
Test the synchronize command un-scheduled first. If it runs correctly, schedule it to publish to a new public instance after one minute (CRON expression: 0 * * * * ?
). If this works correctly too, point the receiver configuration to the out-of-sync target instance and modify the CRON schedule as required.