Synchronization Add-On

Info: The Synchronization Add-On requires a standard or premium Bloomreach Content license. Contact Bloomreach for details.

The Replication and Synchronization add-ons are not compatible with the Relevance Module. Before starting the synchronization process, clean the revision journal to avoid out-of-memory (OOM) issues.

The Synchronization Add-On is designed to minimize the content freeze period during upgrades. The content freeze period is the time when authors, editors, and webmasters must pause work in the CMS. With this add-on, users can continue working in the old environment during the upgrade. After the upgrade, you can transfer changes made in the old environment to the new environment.

The synchronization workflow is as follows:

1. Before starting the upgrade, record the current journal revision of the repository. Use the synchronization add-on's REST endpoint at http://host:port/cms/ws/synchronization/revision to retrieve the current revision. This revision will be the starting point for later synchronization.
2. Create a copy of the database that backs the repository.
3. Perform the upgrade on the database copy.
4. Download the synchronization package from the old environment. This package contains all changes since the recorded revision. Retrieve it by sending a GET request to http://host:port/cms/ws/synchronization/export?startRevision=yourStartRevision.
5. Upload the synchronization package to the new environment by sending a POST request to http://host:port/cms/ws/synchronization-target.

Enabling the Synchronization Add-On

You must install the synchronization add-on on the source (old) environment before starting the upgrade. Ensure your project is configured as an enterprise project.

Add the following dependencies to cms-dependencies/pom.xml:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-synchronization-source-engine</artifactId>
</dependency>
<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-synchronization-source-config</artifactId>
</dependency>
copy

If your project uses relevance, also add:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-targeting-synchronization</artifactId>
</dependency>
copy

Install the synchronization add-on on the target (new) environment as well. Add the following dependency to cms-dependencies/pom.xml:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-synchronization-target</artifactId>
</dependency>
copy

The synchronization add-on requires a repository journal to track changes made during the upgrade window. Ensure the source environment is configured as a cluster.

Configure the RepositoryJaxrsServlet

Add the following servlet definition to both the source and target environments in cms/src/main/webapp/WEB-INF/web.xml:

(This configuration is included by default in projects created with hippo-project-archetype version 2.00.10 or later.)

<servlet>
  <servlet-name>RepositoryJaxrsServlet</servlet-name>
  <servlet-class>org.onehippo.repository.jaxrs.RepositoryJaxrsServlet</servlet-class>
  <load-on-startup>6</load-on-startup>
</servlet>
copy

Add the corresponding servlet mapping:

<servlet-mapping>
  <servlet-name>RepositoryJaxrsServlet</servlet-name>
  <url-pattern>/ws/*</url-pattern>
</servlet-mapping>
copy

Using the Synchronization Add-On with curl

Retrieve the current repository revision:

curl -u username:password http://host:port/cms/ws/synchronization/revision > sync_revision.txt
copy

Download the synchronization package from the source environment:

curl -u username:password http://host:port/cms/ws/synchronization/export?startRevision=??? > sync.zip
copy

Upload the synchronization package to the target environment:

curl -u username:password -X POST -F "[email protected]" http://host:port/cms/ws/synchronization-target > sync_result_log.xml
copy

Use credentials for a valid repository user who is authorized with the restuser role for the /hippo:configuration/hippo:domains/synchronization-rest domain. By default, all users in the admin group have this authorization.

Customization

The synchronization feature is built on the replication framework and supports the same customizations. For details, see the documentation on replication extensions and filters. For synchronization, configure these options at /hippo:configuration/hippo:modules/synchronization/hippo:moduleconfig/metadata.