Synchronization REST module

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.

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.

Command REST vs Sync REST

You could launch a synchronization with the command API of the REST module. However, using the Synchronization REST API to synchronize has several advantages over the command REST API.

Command REST

Synchronous

The API will not return a result until the synchronization has finished. Synchronizations may take some time to finish depending on the amount of content.

Fixed configuration

Must be configured before launching a synchronization. The synchronization command uses a receiver defined in the Synchronization module’s configuration. The receiver defines the target Magnolia instance to send content to and can’t be passed to the synchronization command.

Uncontrolled execution

It is possible to launch identical synchronizations to the same instance if not carefully orchestrated. You can launch many synchronizations simultaneously. Synchronizations adds load on the source Magnolia instance; you can overload the source Magnolia instance by launching too many synchronizations at the same time.

Sync REST

Asynchronous

A synchronization launched with the Synchronization REST API returns immediately with a job ID and provides calls to check on the status of the synchronization job (waiting for execution, running, finished successfully and finished with errors).
In addition, if you need to define a site specific receiver using workspace path mappings, you can define a template receiver in the configuration of the Synchronization REST module and use the mappings in the template to perform the synchronization.

No configuration

You can specify all the details of the synchronization (URL for the Magnolia instance, workspace, path and more) when launching the synchronization. No configuration is needed to start a synchronization.

Controlled execution

Using these policies, you can avoid overloading the source Magnolia instance and prevent duplicate synchronizations of the same content to a Magnolia instance.

The synchronization policy can be set to control synchronizations:
- Allow only one synchronization at a time
- Allow only one synchronization to a target Magnolia instance
- Allow only one synchronization of a workspace to a target Magnolia instance
- Allow all requested synchronizations

Installing with Maven

Bundled modules are automatically installed for you.

If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement> section and your webapp’s <dependencies> section. If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies> section.

<dependency>
  <groupId>info.magnolia.synchronization</groupId>
  <artifactId>magnolia-synchronization-rest</artifactId>
  <version>2.0.1</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Synchronization REST API

This page describes the synchronization endpoint, which can be used to launch synchronization and check on their status.

GET

Get status

Returns the status of a specified synchronization request.

Request URL

/.rest/synchronization/v1/status/{synchId}

Parameters

Parameter Description Parameter type Data type

synchId

required

Specify the synchronization request ID.

the synchronization request ID is returned by synchronize or synchronizeWith.

path

String

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 execution
- RUNNING - currently executing
- DONE - completed successfully without errors
- FAILED - completed unsuccessfully due to an error
- CANCELLED - synchronization was cancelled before execution
- ERROR - synchronization was completed but was unable to determine results

Clear jobs

Clears the status of all synchronization jobs.

This call will not stop running synchronization jobs or synchronization jobs awaiting execution.

Request URL

/.rest/synchronization/v1/reset

Returns an HTTP status of:

204 - the reset was successful

POST

Trigger synchronization

Launch a synchronization of designated workspace on a Magnolia instance.

Request URL

/.rest/synchronization/v1/trigger

Parameters

Parameter Description Parameter type Data type

Parameter	Description	Parameter type	Data type
`url`	required The URL of the Magnolia instance.	`query`	`String`
`workspace`	required The workspace to be synchronized.	`query`	`String`
`recursive`	optional, default is `true` Indicates if subnodes of path should also be synchronized.	`query`	`boolean`
`fromDate`	optional Specifies a Unix epoch timestamp in milliseconds. Nodes modified since `fromDate` will be synchronized, nodes older than `fromDate` will be skipped. If `null`, all node specified by `path` and `recursive` will be synchronized.	`query`	`long`
`fromPath`	required Workspace path on the author instance from which content is published.	`query`	`String`
`toPath`	optional Workspace path on the public instance to which the content is published. Nodes at or below `fromPath` will be synchronized on the target Magnolia instance at `toPath`.	`query`	`String`

url

required

The URL of the Magnolia instance.

query

String

workspace

required

The workspace to be synchronized.

query

String

recursive

optional, default is true

Indicates if subnodes of path should also be synchronized.

query

boolean

fromDate

optional

Specifies a Unix epoch timestamp in milliseconds.

Nodes modified since fromDate will be synchronized, nodes older than fromDate will be skipped.

If null, all node specified by path and recursive will be synchronized.

query

long

fromPath

required

Workspace path on the author instance from which content is published.

query

String

toPath

optional

Workspace path on the public instance to which the content is published.

Nodes at or below fromPath will be synchronized on the target Magnolia instance at toPath.

query

String

Returns an HTTP status of:

200 - the synchronization request was launched and awaiting execution
409 - another synchronization request is running and the request cannot be launched at this time
500 - an error occurred and the synchronization request was not launched

If 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 execution
- RUNNING - currently executing
- DONE - completed successfully without errors
- FAILED - completed unsuccessfully due to an error
- CANCELLED - synchronization was cancelled before execution
- ERROR - synchronization was completed but was unable to determine results

Example

Here is an example call for triggering a synchronization

curl -u superuser:superuser http://localhost:8080/magnoliaAuthor/.rest/synchronization/v1/trigger --data '
{"url" : "http://localhost:8080/magnoliaPublic", "workspace": "website", "fromPath" : "/", "fromDate" : "2012-03-29T10:05:45-06:00"}
' --header "Content-Type: application/json"

Known Issues

Due to the fact that update/install tasks are not run from beta to final versions there will be some manual steps if you were using one of the beta releases.

Import manager config

The following configuration will have to be imported manually. (See config.modules.synchronization-core.config.manager.xml).

Remove command config

RestSynchronizationCommand removed from final module. This is harmless but the command node configuration will have to be removed manually from the JCR configuration. (i.e. /modules/synchronization-rest/commands)

2020-06-25 15:10:19,851 WARN magnolia.transformer.ClassPropertyBasedTypeResolver: Encountered the 'class' property but failed to resolved the type from its value: [info.magnolia.synchronization.commands.RestSynchronizationCommand]

Remove sender config

In case 1.9-beta3 was installed, the synchronization sender node will have to be removed manually from JCR configuration. (i.e. /modules/synchronization-core/commands/synchronization/synchronize/synchronizationSenderClass).

Feedback

DX Core

Synchronization REST module

Command REST vs Sync REST

Command REST

Sync REST

Installing with Maven

Synchronization REST API

GET

Get status

Request URL

Parameters

Clear jobs

Request URL

POST

Trigger synchronization

Request URL

Parameters

Example

Known Issues

Import manager config

Remove command config

Remove sender config

Location

Main doc sections