Upgrading to jCustomer 2.2.0

• Read all of the instructions on this page carefully before proceeding with the upgrade process.
• Review the migration procedure in Apache Unomi 2.0.0 documentation,
• Run a pre-production test first.
• Upgrade jCustomer to 1.5.7+

The upgrade procedure has been described in detail in the Apache Unomi 2.0.0 documentation, please review this documentation in detail before proceeding.

Custom JSON Schemas

Any event submitted to jCustomer 2.2.0 public endpoints will be rejected except if they comply with an existing JSON Schema.

By default, jCustomer and jExperience are provided with all the schema needed to support their own functionalities, but it might be necessary to create additional schemas for custom events you created.

If you are new to JSON Schemas in jCustomer (or Apache Unomi) 2.2.0, please review the First steps with Apache Unomi. This page contains step-by-step instructions to create your first JSON Schema.

Before beginning with the migration, please create any JSON Schemas necessary to handle your events.

It is advised to verify if your previous events have a matching JSON Schema by following this documentation, in general, you should not proceed with the migration if there are still rejected events.

You can also verify events individually by submitting a POST request to an admin endpoint dedicated to schema validation: /cxs/jsonSchema/validateEvent, which will provide default about schema errors (if the event does not match a schema).

Prepare data migration

jCustomer 2.2.0 introduces breaking changes in its data model, it includes a set of migration scripts to transform the existing data from jCustomer 1.5.7+ data model to jCustomer 2.2.0 data model.

But since jCustomer can only migrate objects it knows about, some custom events you created might require to create migration scripts and inject those into the migration process.

Before starting its migration, jCustomer will create a list of all of the migration scripts located in its internal codebase and scripts placed by users in data/migration/scripts, it will then sort that list and execute the scripts sequentially. This allows you to specify, by following a naming pattern, in which order your own scripts should be executed.

The Apache Unomi 2.2.0 documentation contains a dedicated section to explain how to create additional migrations scripts.

Migrating from jCustomer 1.5.7+ to jCustomer 2.2.0

Please note that during the migration and as long as the jExperience module is started, the fallback variants are displayed by personalizations/optimizations on the site.

To migrate you platform, please follow these steps carefully:

1. Backup your jCustomer-1.5.7+ instance (in case you run jCustomer in cluster, backup the whole cluster)
   For a detailed description to backup jCustomer please follow the section How to backup jCustomer on this page
2. Stop jCustomer-1.5.7+
3. Download jCustomer-2.2.0 from jExperience customer center and install it
4. If you're handling custom events, make sure you created the corresponding migration scripts and placed those in jCustomer: data/migration/scripts
5. Start a single jCustomer 2.2.0 migration node following instructions from Apache Unomi 2.0.0 documentation. This node will be handling all of the data transformation.
6. Apply all your custom configurations to the new jCustomer-2.2.0 instance
7. Updgrade and start jExperience in version 3.1.0 on your Jahia instance.
8. Start jCustomer-2.2.0 ./start command in the operating system shell.
9. Connect to the jCustomer Karaf SSH shell using an SSH client such as in the following example (default password karaf):
   ssh -p 8102 karaf@localhost
10. Start jCustomer (only needed when running jCustomer 2.2.0 for the first time).
    unomi:start
11. Submit custom JSON Schemas via the API