Magnolia 6.1 reached end of life on March 31, 2021. This branch is no longer supported, see End-of-life policy.
BETA
The Synchronization REST module provides a convenient REST API for publishing content from a source Magnolia instance (typically an author instance) to a target Magnolia instance (typically a public instance). It provides another way to synchronize content using the Synchronization module and start synchronization, monitor synchronizations and stop synchronizations remotely through via a REST service.
You can use the module to add content to new public instances without shutting down existing instances and impacting their ability to serve content.
You could launch a launch a synchronization with the command API of the REST module, however, synchronizing using the Synchronization REST API has several advantages compared to the command REST API:
Using these policies, you can avoid overloading the source Magnolia instance and prevent duplicate synchronizations of the same content to a Magnolia instance.
<dependency> <groupId>info.magnolia.synchronization</groupId> <artifactId>magnolia-synchronization-rest</artifactId> <version>1.9-beta2</version> </dependency>
The Synchronization module is configured under Configuration > /modules/synchronization-rest/config
.
Properties:
policy | optional The synchronization policy, one of:
Default is See below for an explanation of each policy. |
catalog | optional Catalog containing the synchronization command. Default is |
command | optional Synchronization command name invoked when a synchronization is launched. Default is |
templates | optional A list of Receivers to be used for synchronizations. Default is |
You can control when synchronizations are performed with the synchronization policy. Synchronizations can put a significant load on the source Magnolia instance (usually your author instance) and can overload the source Magnolia instance and make it unresponsive. The synchronization policy controls how many synchronizations can be run simultaneously.
Synchronization policies:
AllowAll | Allow any requested synchronization. |
AllowSingle | Allow only a single synchronization to be run. Calls to the REST function |
AllowByUrl | Allow only a single synchronization to a URL to be run. Calls to the REST function |
AllowByUrlRepository | Allow only a single synchronization to a URL and given workspace to be run. Calls to the REST function |
Synchronization is controlled by the RestSynchronizationCommand (extends BaseActivationCommand
) registered in /modules/synchronization-rest/commands/rest
:
Node name | Value |
---|---|
modules | |
synchronization-rest | |
commands | |
rest | |
synchronize | |
syndicator | |
class | info.magnolia.module.synchronization.SilentXASyndicator |
recursive | true |
receivers | |
class | info.magnolia.synchronization.commands.RestSynchronizationCommand |
Properties:
syndicator | optional Registers the syndicator class. |
| required
|
| optional, default is Executes recursively when set to |
receivers | required Synchronization receivers configurations (see below). |
Note: info.magnolia.synchronization.commands.RestSynchronizationCommand is functionally identical to the Synchronization module's info.magnolia.synchronization.commands.SynchronizationCommand. However, SynchronizationCommand does not correctly return the status of a synchronization job. Please use RestSynchronizationCommand instead.
This page describes the synchronization endpoint, which can be used to launch synchronization and check on their status.
Returns the status of a specified synchronization request.
/.rest/synchronization/v1/synchronize/{synchId}
Parameter | Description | Parameter type | Data type |
---|---|---|---|
| required Specify the synchronization request ID. Note: the synchronization request ID is returned by |
|
|
Returns the status of a synchronization request with:
jobId
- the ID of the synchronization request (same as synchId)status
- the synchronization request status, one of: WAITING
- waiting for executionRUNNING
- currently executingDONE
- completed successfully without errorsFAILED
- completed unsuccessfully due to an errorCANCELLED
- synchronization was cancelled before executionERROR
- synchronization was completed but was unable to determine resultsClears the status of all synchronization jobs.
Important
This call will not stop running synchronization jobs or synchronization jobs awaiting execution.
/.rest/synchronization/v1/reset
Launch a synchronization of designated workspace on a Magnolia instance.
/.rest/synchronization/v1/synchronize
Parameter | Description | Parameter type | Data type |
---|---|---|---|
url | required The URL of the Magnolia instance. | query | String |
repository | required The workspace to be synchronized. | query | String |
path | optional, default is " /" The path of a node within the workspace to be synchronized. Note: subnodes of the path may synchronized depending on the setting of the | query | String |
recursive | optional, default is Indicates if subnodes of path should also be synchronized. | query | boolean |
fromDate | optional, default is Specifies a Unix epoch timestamp in milliseconds. Nodes modified since If | query | long |
fromPath | optional, default is Workspace path on the author instance from which content is published. | query | String |
toPath | optional, default is Workspace path on the public instance to which the content is published. Nodes at or below | query | String |
Returns an HTTP status of:
200
- the synchronization request was launched and awaiting execution409
- another synchronization request is running and the request cannot be launched at this time500
- an error occurred and the synchronization request was not launchedIf the request was launched, the status of a synchronization request is returned with:
jobId
- the ID of the synchronization request (same as synchId)status
- the synchronization request status, one of: WAITING
- waiting for executionRUNNING
- currently executingDONE
- completed successfully without errorsFAILED
- completed unsuccessfully due to an errorCANCELLED
- synchronization was cancelled before executionERROR
- synchronization was completed but was unable to determine resultsLaunch a synchronization of designated workspace on a Magnolia instance using a Receiver template.
The receiver template will specify the source path and destination path of synchronized nodes as well as other details of the synchronization-
/.rest/synchronization/v1/synchronizeWith
Parameter | Description | Parameter type | Data type |
---|---|---|---|
url | required The URL of the Magnolia instance. | query | String |
repository | required The workspace to be synchronized. | query | String |
path | optional, default is "/" The path of a node within the workspace to be synchronized. Note: subnodes of the path may synchronized depending on the setting of the | query | String |
recursive | optional, default is Indicates if subnodes of path should also be synchronized. | query | boolean |
fromDate | optional, default is Specifies a Unix epoch timestamp in milliseconds. Nodes modified since If | query | long |
template | required Specifies a receiver template configured in the module configuration. | query | String |
Returns an HTTP status of:
200
- the synchronization request was launched and awaiting execution409
- another synchronization request is running and the request cannot be launched at this time500
- an error occurred and the synchronization request was not launchedIf the request was launched, the status of a synchronization request is returned with:
jobId
- the ID of the synchronization request (same as synchId)status
- the synchronization request status, one of: WAITING
- waiting for executionRUNNING
- currently executingDONE
- completed successfully without errorsFAILED
- completed unsuccessfully due to an errorCANCELLED
- synchronization was cancelled before executionERROR
- synchronization was completed but was unable to determine results