The Synchronization Add-On is meant to be used during upgrades to help you keep the content freeze period to a minimum. By content freeze period, we mean the period of time authors, editors, and webmasters should stop working in the CMS. During the upgrade they can continue to work in the old environment until you are ready to flip the switch to the new environment. At that moment you can send the changes made in the old environment during the upgrade to the new environment. The process will be as follows:
- Before you start the upgrade process, write down the current journal revision of the repository. The synchronization add-on supplies a REST end-point to query the current journal revision at http://host:port/cms/ws/synchronization/revision. This will be the revision from which changes are synchronized later.
- Make a copy of the database backing the repository.
- Perform the upgrade on the copy of the database.
- Download the synchronization package from the old environment that contains all the changes since the revision recorded earlier by GETting it at http://host:port/cms/ws/synchronization/export?startRevision=yourStartRevision
- Upload it to the new environment by POSTing it to http://host:port/cms/ws/synchronization-target
See our blog entry on the subject for an architectural overview of this feature.
Enabling the Synchronization Add-On
The synchronization add-on must be installed on the source (old) environment before the upgrade process can be started. As mentioned, this is a Hippo DX feature so you must use the enterprise release pom as a parent:
<parent> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-cms7-enterprise-release</artifactId> <version>[VERSION]</version> </parent>
Add the following dependencies to the cms/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>
If you are using relevance you must also add the following dependency here:
<dependency> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-addon-targeting-synchronization</artifactId> </dependency>
The synchronization add-on must be installed on the target (new) environment as well. Add the following dependencies to the cms/pom.xml:
<dependency> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-addon-synchronization-target</artifactId> </dependency>
Note that the synchronization addon relies on the availability of a repository journal to read changes made during the period you want to bridge so you need to have set up the source environment with cluster configuration.
Configure the RepositoryJaxrsServlet
Add the following servlet definition to both source and target cms/src/main/webapp/WEB-INF/web.xml:
(this will by default already be configured for new projects created with hippo-project-archetype >= 2.00.10+)
<servlet> <servlet-name>RepositoryJaxrsServlet</servlet-name> <servlet-class>org.onehippo.repository.jaxrs.RepositoryJaxrsServlet</servlet-class> <load-on-startup>6</load-on-startup> </servlet>
Along with the following servlet mapping:
<servlet-mapping> <servlet-name>RepositoryJaxrsServlet</servlet-name> <url-pattern>/ws/*</url-pattern> </servlet-mapping>
Curl calls for using the synchronization add-on
To get the current repository revision:
curl -u username:password http://host:port/cms/ws/synchronization/revision > sync_revision.txt
To get the synchronization package from the source:
curl -u username:password http://host:port/cms/ws/synchronization/export?startRevision=??? > sync.zip
To post the synchronization package to the target:
curl -u username:password -X POST -F "firstname.lastname@example.org" http://host:port/cms/ws/synchronization-target > sync_result_log.xml
Username and password should be of a valid repository user, who is also authorized with the restuser role for the /hippo:configuration/hippo:domains/synchronization-rest domain (by default all users from the admin group are already authorized).
The synchronization feature is built on the replication feature therefore the same customizations are available. See replication extensions and filters for details. The only difference is you need to configure these at /hippo:configuration/hippo:modules/synchronization/hippo:moduleconfig/metadata .