Upgrading to jExperience 1.11

November 14, 2023

General information

  • It is possible to update from Marketing Factory 1.10.3 or 1.10.4 to jExperience 1.11
  • jExperience 1.11 is compatible with jCustomer 1.4.1 or jCustomer 1.5.1 and DX 7.2.3.2+
  • Please read first these instructions entirely before you take any action.
  • Please run this migration in a sandbox environment first, then move to pre-production and production.
  • Ensure that a backup exists for both jCustomer/Apache Unomi data and Jahia data 
  • Check the Jahia logs at every steps
  • If Jahia is running as a cluster, these operations have to be done only on processing server.

Step by step instructions:

  1. Ensure that Marketing Factory core is running on your server
  2. Download, install and start the module "jExperience migrator" from Jahia store
    • Ensure this module is started and running on all Jahia nodes of the cluster
    • The module migrator will automatically migrate your content, nodetypes and also the configuration files (it will automatically rename the configuration file and also the properties inside the configuration file to match the new jExperience naming) More info about configuration file renaming
  3. Install the module jExperience, but make sure to uncheck "start automatically" jExperience, DO NOT START the module yet. Also install (DO NOT START) the module jexperience-components and other renamed marketing factory modules like : 

     

    • jExperience-google-analytics
    • jExperience-oauth-data-mapper
    • jExperience-queries-components
    • jExperience-forms-bridge
  4. You must have all of your old custom Marketing Factory modules updated and ready to be deployed with dependencies to:
    • <dependency>
          <groupId>org.jahia.modules</groupId>
          <artifactId>jexperience</artifactId>
          <version>1.11.0</version>
          <scope>provided</scope>
      </dependency>

      To find all the modules installed on your platform with dependencies on Marketing Factory, here is a script that needs to be executed with the JCR Console tool (to be found in the JCR Data section of the support tools).

      def rows = session.getWorkspace().getQueryManager().createQuery("SELECT [j:title] FROM [jnt:moduleVersion] where [j:dependencies] = 'marketing-factory-core'",javax.jcr.query.Query.JCR_SQL2).execute().getRows();
      rows.each({row -> log.info(row.getValue('j:title').getString())})

      When executed it will print the list of dependent modules, like the following example plus/minus the modules you have installed on your platform:

      marketing-factory-components
      marketing-factory-google-analytics
      marketing-factory-oauth-data-mapper
      marketing-factory-queries-components
      marketing-factory-forms-bridge
      ...
      
      
  5. Stop and uninstall all previous Marketing factory modules
    • Ensure they are uninstalled on all Jahia nodes of the cluster
    • It's important that at this step all the Marketing factory modules are uninstalled, even previous version if you have some.
  6. Start new jExperience-core and other jExperience modules that you might use (jexperience-components and others as identified on Step 4) 
    • Make sure they are started on all Jahia nodes of the cluster
  7. The migration of jExperience is now complete. You should now procede with upgrading your Unomi installation to jCustomer 1.4.1 or jCustomer 1.5.1.
  8. If you have any issue with the migration, inspect the server logs to see what the module migrator has logged. But if you followed the previous steps everything should be fine.

Upgrading Jahia Unomi 1.3.3 to jCustomer 1.4.1.

Important note: jCustomer is based on Apache Unomi, but is also the product that is fully supported and maintained by Jahia. We do not support customers that are directly using Apache Unomi distributions downloaded from the Apache website. This procedure is assuming you are upgrading from Unomi 1.3.3 which is a version provided by Jahia on our website.

Migration steps:

  1. Stop the existing instance of Unomi 1.3.3
  2. Download and install jCustomer 1.4.1 by uncompressing it into a new directory
  3. Make sure you copy the configuration over to the new instance of jCustomer 1.4.1 from Unomi 1.3.3
  4. Start jCustomer 1.4.1 using ./start command in the operating system shell.
  5. 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
  6. Start jCustomer (only needed when running jCustomer 1.4.1 for the first time).
    unomi:start
  7. Optional: In case you want to use jCustomer 1.5.1 you can follow this migration procedure: Upgrading from jCustomer 1.4.1 to jCustomer 1.5.1

You should now test your migrated jExperience and check that everythings is OK. Also you may now stop and uninstall the "jExperience migrator" module.