Upgrading from jCustomer 1.4.x to jCustomer 1.5.4

November 14, 2023

In this document you will see the migration step from jCustomer 1.4.x to jCustomer 1.5.4 or more recent versions of jCustomer (1.5.6, 1.5.7). To migrate to jCustomer 1.5.7 (or similar), just apply the steps below but use the download of jCustomer 1.5.7 instead of 1.5.4 (jCustomer downloads can be found under tab "Downloads" here). 

The assumed starting configuration is Jahia 7.3.x +, jExperience 1.11.3, jCustomer 1.4.x, Elasticsearch 5.6.3. Please note that you do need to update to jExperience 1.11.3 before applying these instructions.

Read all of the instructions on this page carefully before proceeding with the upgrade process.
Custom scripting and security:
jCustomer 1.5.4 introduces a new allow-listing system that only executes expressions and scripts that have been previously vetted. For compatibility reasons, jCustomer comes packaged with default allow-lists of expressions that should cover all the built-in use cases. If you are using custom plugins/extensions that include rules that use expressions (MVEL or OGNL), please refer to the scripting security instructions in chapter 3.8 of the Unomi documentation. In case you are not sure if these instructions apply to your installation, feel free to contact our support team.
It is HIGHLY RECOMMENDED to:
Apply the instructions on a preproduction environment first
Perform a full cluster backup/snapshot of the source clusters (including Elasticsearch and Unomi clusters). You can refer to the Elasticsearch 5.6 documentation on backups if needed.

Prepare the configuration

If you customized jCustomer configuration, you will need to port over your custom configuration to the migrated instance.

Starting from your existing 1.4.x configuration, compare its values with the content of the new "custom.system.properties" file. In the top-left corner of GitHub, select the "git tag" corresponding to the jCustomer version you are upgrading to. 

Start the migration

Before starting the migration, stop all jExperience modules on your Jahia instance from the interface Administration/Modules. Also stop all existing jCustomer instances and all existing Elasticsearch instances.

You can confirm that no jCustomer process is still running with this command:

>  ps aux | grep jcustomer

You can confirm no ElasticSearch process is still running with this command:

>  ps aux | grep elasticsearch

In the ElasticSearch 5.6.3 folder, edit the config/elasticsearch.yml file, modify the default ports to:

transport.tcp.port: 9310

http.port: 9210

Make SURE you change the ports out of the default 9200-9205 and 9300-9305 range (or whatever your cluster uses) otherwise both clusters will attempt to merge!

Download jCustomer 1.5.4+ and Elasticsearch 7.4.2 in .zip file or in .tar.gz file, extract them but do not start them yet.

In the ElasticSearch 7.4.2 folder, edit the config/elasticsearch.yml you will need to add the following line

reindex.remote.whitelist: "localhost:9210"

You can then start ElasticSearch 5.6.3 then ElasticSearch 7.4.2. When both are started, open the new jCustomer folder 1.5.4+, then start Karaf using:

>  ./bin/karaf

Once in the Karaf console is launched, start the migration using the following command:

>  migrate 1.4.0

Answer the questions with your values. At the end you should have the following message:

Migration to version 1.5.0 is done successfully

Please note that the version mentioned in the console will always indicate 1.5.0, even if you're updating to 1.5.4+. 

If you are using custom plugins/extensions that include rules that use expressions (MVEL or OGNL), please refer to the scripting security instructions in chapter 3.8 of the Unomi documentation. In case you are not sure if these instructions apply to your installation, feel free to contact our support team.

Still from the Karaf console, start Unomi.

>  unomi:start

Stop ElasticSearch 5.6.3, keep ElasticSearch 7.4.2 running. In your Jahia administration, restart all jExperience modules and check JExperience is still working.