Upgrade to Translations Add-on from 1.03 to 2.x, with LiveWords
Introduction | Install | Configure | Release Notes | Upgrade to 2.x
This document describes how to upgrade from a Hippo 11.2 project with Translations Addon 1.03 to a Hippo 11.2 project with Translations Addon 2.x, with the LiveWords connector.
Steps
Upgrade the project code base
1. Undo the 1.03 installation as documented at the 1.03 installation guide
- Remove dependencies on com.onehippo.cms7:translations-addon-bom
- Remove dependencies on org.apache.activemq:activemq-client
- From the CMS's web.xml, remove the <resource-ref> elements named "jms/ConnectionFactory", "jms/TRANSLATION.OUTBOUND" and "jms/TRANSLATION.INBOUND".
- From the local context.xml, remove the same JNDI resources.
- Remove any leftovers on ActiveMQ and translations-addon
2. Do the 2.x installation as documented at the 2.x installation guide
- Add dependencies to the BOM (bill of materials), livewords connector (repository and webhook), settings-frontend and editor-frontend dependencies.
- Set up the Livewords TranslationResource in the site's Spring configuration.
3. If desired, remove mixins translationsaddon:translatable and translationsaddon:translated from any local documents manually. Alternatively, use Groovy scripts 'TranslationsAddonRemoveTranslatable' and 'TranslationsAddonRemoveTranslated' available for that after startup (see below).
4. Remove any occurrence on livewords-connector.war (documentation): the connector is now a configured class.
5. For local testing, you may want to set log level of "com.bloomreach.cms.translations" to INFO, normally in conf/log4j-dev.xml
Set up configuration on a local instance
Build and run the local project, preferably on a storage from before the upgrade, to test the upgrade path. Running on a clean storage is also possible of course, then any feedback on upgrade path will come later.
1. Run the installed Groovy scripts
If mixins translationsaddon:translatable and translationsaddon:translated still are present on local document, run Groovy scripts 'TranslationsAddonRemoveTranslatable' and 'TranslationsAddonRemoveTranslated'.
2. Check and set the configurations
There is a Groovy script 'TranslationsAddonUpgradeConfiguration' that runs automatically on startup. Please check its loggings in the CMS's Updater Editor and the resulting configuration in the CMS's Settings Management.
Run by all configurations as documented at the configuration page and adjust if necessary.
This includes the LiveWords connector configuration and web hook. Export any changes to local configuration and content files (perhaps using Auto Export).
--
Configuration changes can be propagated from the local development environment to the various standing environments (staging, production), using the normal bootstrapping mechanism, but its not recommended to do that for sensitive infomation like connector properties "livewords.api.user" and "livewords.api.key".
Installation on environments
When satisfied on the local environment, create a release and distribution, to be installed on a container, assumed Tomcat.
1. Before installation
- Remove the livewords-connector.war (and its exploded directory) from Tomcat webapps.
- From the context.xml, remove the <resource-ref> elements named "jms/ConnectionFactory", "jms/TRANSLATION.OUTBOUND" and "jms/TRANSLATION.INBOUND".
2. After installation and startup
- Check what Groovy script 'TranslationsAddonUpgradeConfiguration' did and adjust the resulting configuration if necessary.
- Run Groovy scripts 'TranslationsAddonRemoveTranslatable' and 'TranslationsAddonRemoveTranslated'.
- Choose a URL for the Livewords web hook on that environment and configure if accordingly in the HST hosts, again see the LiveWords web hook documentation.
The URL has to be exposed to the outside world (or at least the LiveWords system) using your webserver (Apache, nginx).