Configuring jCustomer features

November 14, 2023

This topic shows you how to configure the main features in jCustomer.

Changing the default configuration

Before perform other modifications, ensure that you set your own cluster name. For more information, see Installing jCustomer in Installing Elasticsearch, jCustomer, and jExperience.

If you want to change the default configuration, you can perform any modification you want in the <cxs-install-dir>/etc directory by creating your own custom configuration in the configuration file. You can find default values for the properties in the file.

For example, you defines the addresses and ports where jCustomer can be found:${env:UNOMI_CLUSTER_GROUP:-default}
# To simplify testing we set the public address to use HTTP, but for production environments it is highly recommended
# to switch to using HTTPS with a proper SSL certificate installed.

Installing the MaxMind GeoIPLite2 IP lookup database

jCustomer requires an IP database to resolve IP addresses to user location. The GeoLite2 database can be downloaded at MaxMind from the following location:

Simply download the GeoLite2-City.mmdb file and copy it into the <cxs-install-dir>/etc directory.

Installing Geonames database

jCustomer includes a geocoding service based on the geonames database ( You can use it to create conditions based on countries or cities. To use it, you need to install the Geonames database. Get the "" database from here:

Download it and put it in the <cxs-install-dir>/etc directory, without unzipping it.

Edit the <cxs-install-dir>/etc/ file and set the org.apache.unomi.geonames.forceImport property to true. The data import should start right away. Otherwise, the import should start at the next startup. The import runs in background, but can take about 15 minutes.

At the end, you should have about 4 million entries in the "geonames" ElasticSearch index.

jExperience and remote publication

jExperience is fully compatible with a remote publishing architecture. Though a precise method must be applied. Here are the steps:

  1. Start ElasticSearch.
  2. Start jCustomer.
  3. Start Jahia (ensure that contribution server operating mode is defined as "production" and remote server operating mode is defined as "distantPublicationServer", using
  4. On the contribution server:
    Note: The remote site must have the same name/sitekey as original site, as all goals/conditions are based on node paths. Different site names are not supported for now.
    1. Create the desired site (for example, ACME SPORT).
    2. Install and enable the jExperience-modules.
    3. Configure jExperience in Site Settings. On the remote server:
    4. Create a new site with the same template set.
  5. Install jExperience-modules.
  6. Then set up the remote publication on the contribution node and execute (check logs / should be good).
    1. Stop both Jahia-server.
    2. Set contribution node to "operationMode=production" (
    3. Set remote server has to be set to "operatingMode=distantPublicationServer" (
    4. Restart.
    5. Open remote site in a new private window and browse the page.
    6. In Site Settings>jExperience (contribution mode) check that the profile was created.
    7. Click OK.

Configuring the email action

In jExperience Rules, an action is available to send email. Emails are sent using an SMTP server that needs to be configured in the following jCustomer file: /etc/ 

org.apache.unomi.mail.server.hostname=<smtp server host name>
org.apache.unomi.mail.server.port=<smtp server port>
org.apache.unomi.mail.server.username=<smtp server username>
org.apache.unomi.mail.server.password=<smtp server password>
org.apache.unomimail.server.sslOnConnect=<use ssl>

In the email template, you can use the following pattern to display any profile property value in the email that will be sent: $"propertyId")$ 

This feature should never be used to send very large emails or for marketing campaign purposes. To integrate with email marketing or marketing automation tools, please contact your account manager.