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.

Synchronization using the Command REST API versus the Synchronization REST module

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: 

  • Synchronization using the command REST API is synchronous : the API will no return a result until the synchronization has finished. Synchronizations may take some time to finish depending on the amount of content. 
  • Synchronization using the Synchronization REST API is 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. 
  • Synchronization using the command REST API 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. 
  • Synchronization using the Synchronization REST API uses 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.
  • Synchronization using the command REST API does not check for other running synchronizations: you can launch identical synchronizations to the same instance. You can launch many synchronizations simultaneously. Synchronizations put a certain load on the source Magnolia instance; you can overload the source Magnolia instance by launching too many synchronizations at the same time.
  • Synchronizations using the the Synchronization REST API can be controlled: you can set a synchronization policy to control synchronizations:
    • allow only one synchronization at a time to run
    • allow only one synchronization to a target Magnolia instance to run 
    • allow only one synchronization of a workspace to a target Magnolia instance to run
    • allow all requested synchronizations to run

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

Installing

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.synchronization</groupId>
  <artifactId>magnolia-synchronization-rest</artifactId>
  <version>1.9-beta2</version>
</dependency>

Pre-built JARs are also available for download. See Installing a module for help.

Configuration

The Synchronization module is configured under Configuration > /modules/synchronization-rest/config .

Properties:

policy

optional

The synchronization policy, one of:

  • AllowAll
  • AllowSingle
  • AllowByUrl
  • AllowByUrlRepository

Default is AllowByUrl.

See below for an explanation of each policy.

catalog

optional

Catalog containing the synchronization command.

Default is rest.

command

optional

Synchronization command name invoked when a synchronization is launched.

Default is synchronize.

templates

optional

A list of Receivers to be used for synchronizations.

Default is null.

Synchronization policy

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 synchronize(...) will return HTTP 409 (Conflict) if there is a synchronization currently running.

AllowByUrl

Allow only a single synchronization to a URL to be run. 

Calls to the REST function synchronize(...) will return HTTP 409 (Conflict) if there is a synchronization to the same URL currently running.

AllowByUrlRepository

Allow only a single synchronization to a URL and given workspace to be run. 

Calls to the REST function synchronize(...) will return HTTP 409 (Conflict) if there is a synchronization to the same URL and workspace currently running.

Synchronization command

Synchronization is controlled by the RestSynchronizationCommand (extends BaseActivationCommand ) registered in /modules/synchronization-rest/commands/rest :

Node nameValue

 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.

class

required

SilentXASyndicator performs synchronization of content without update to metadata.

recursive

optional, default is false

Executes recursively when set to true.

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.

Synchronization REST API

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

GET

Get synchronization status

Returns the status of a specified synchronization request.

Request URL

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

Parameters

Parameter

Description

Parameter type

Data type

synchId

required

Specify the  synchronization request ID. 

Note: 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 synchronization jobs

Clears the status of all synchronization jobs.

Important

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

Request URL

/.rest/synchronization/v1/reset

POST

Synchronize a workspace on a Magnolia instance

Launch a synchronization of designated workspace on a Magnolia instance.

Request URL

/.rest/synchronization/v1/synchronize

Parameters

Parameter

Description

Parameter type

Data type

url

required

The URL of the Magnolia instance.

queryString
repository

required

The workspace to be synchronized.

queryString
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 recursive parameter. 

queryString
recursive

optional,  default is false

Indicates if subnodes of path should also be synchronized. 

queryboolean
fromDate

optional,  default is null

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.

querylong
fromPath

optional,  default is null

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

queryString
toPath

optional,  default is null

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.

queryString

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

Synchronize a workspace on a Magnolia instance with a Receiver template.

Launch 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-

Request URL

/.rest/synchronization/v1/synchronizeWith

Parameters

Parameter

Description

Parameter type

Data type

url

required

The URL of the Magnolia instance.

queryString
repository

required

The workspace to be synchronized.

queryString
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 recursive parameter. 

queryString
recursive

optional, default is false

Indicates if subnodes of path should also be synchronized. 

queryboolean
fromDate

optional, default is null

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.

querylong
template

required

Specifies a receiver template configured in the module configuration.

queryString

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
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))