The jCustomer official and nightly builds are distributed as packages (ZIP or TAR/GZ), which contain the Apache Karaf server with all the jCustomer services bundled and pre-configured. A second distributable is the jExperience Package itself (JAR file), which includes modules to be deployed on the Jahia instance. The next sections describe the installation of both parts.
jCustomer requires Elasticsearch. When you use jExperience and jCustomer together, you must install a standalone version of Elasticsearch.
To install a standalone Elasticsearch:
<elasticsearch-install-dir>.<elasticsearch-install-dir>/config/elasticsearch.yml file replace the cluster.name parameter with your own cluster name.
# ---------------------------------- Cluster -----------------------------------
#
# Use a descriptive name for your cluster:
#
cluster.name: YourOwnClusterName
#
Record the cluster name and configure your jCustomer instance to point on it later.
bin/elasticsearch on Mac or Linux and bin\elasticsearch.bat on Windows.Navigate to the <elasticsearch-install-dir>/bin directory and launch Elasticsearch using the following command:
./elasticsearch
You can then stop the server simply by issuing a CTRL+C inside the console where you launch the Elasticsearch server. Leave it running for now as you will need it running before starting jCustomer.
If you want to install Elasticsearch as a background service on a specific operating system, you may use other packages. You can find documentation on how to do this here: https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html
Depending on the jExperience version that you deploy on your Jahia Instance, you must get the compatible corresponding jCustomer version. You can find the correct version on the jExperience download page.
As a reminder, you can find the Jahia supported version of jCustomer in the Customer Center. The jCustomer install consists of one unique step, which requires uncompressing the content of the jcustomer-X.X.X.tar.gz (Linux, Solaris, or Mac OSX) or jcustomer-X.X.X.zip into your target installation folder. This creates the jcustomer-X.X.X folder, which is referenced later in this document as <jcustomer-install-dir>.
Whether you’re installing jCustomer and Elasticsearch locally, remotely, or in a cluster you must to specify an Elasticsearch cluster name. It is recommended to do this before you start the server for the first time. Otherwise you will lose all the data you have stored previously. You can also change the host and port if they need to be modified from the default values.
To change these settings, you must create or modify for each cluster node a file called <jcustomer-install-dir>/etc/unomi.custom.system.properties with the following contents:
org.apache.unomi.elasticsearch.cluster.name=YourOwnClusterName
# The elasticSearchAddresses may be a comma separated list of host names and ports such as
# hostA:9200,hostB:9200
# Note: the port number must be repeated for each host
org.apache.unomi.elasticsearch.addresses=localhost:9200
The directory layout of an installed jCustomer (after first startup) is as follows:
/bin/data/cache/generated-bundles/log/deploy/etc/instances/lib/ext/endorsed/system<elasticsearch-install-dir>/data directory if you want to purge the stored data.The first time you start jCustomer is unique. By default the Apache Karaf (OSGi) server will start, but jCustomer's packages will not start automatically. Previous versions started automatically, but Jahia has since then introduced a new migration tool. To start jCustomer, you must first start the Apache Karaf server in any mode (see below), and then start the packages using a shell command.
jCustomer supports the following start modes:
For Linux, Solaris, or Mac OSX:
./bin/karaf
For Windows:
bin\karaf.bat
This starts Apache Karaf as a foreground process and displays the shell console. Note that closing the console or shell window will cause jCustomer and Apache Karaf to terminate. In regular mode, you can type 'system:shutdown' or 'logout' in the console to shutdown Apache Karaf.
For Linux, Solaris, or Mac OSX:
./bin/start
For Windows:
bin\start.bat
You can connect to the shell console using SSH or client (see the next section).
Even if you start Apache Karaf without the console (using server or background modes), you can connect to the console. This connection can be local or remote. It means that you can access the jCustomer console remotely. To connect to the console, you can use the bin/client Unix script (bin\client.bat on Windows). To connect to a local process you should use Linux, Solaris, or Mac OSX:
./bin/client –h localhost –u karaf
For Windows:
bin\client.bat –h localhost –u karaf
The first time you start Apache Karaf, the jCustomer packages will not automatically start. You must start the packages using the following Apache Karaf shell command:
unomi:start
This step is only required once, the next time Apache Karaf starts it will automatically start the jCustomer packages.
Note that you can start jCustomer without this command. To do so you will need to modify the setenv.sh file and add the following line:
export KARAF_OPTS="-Dunomi.autoStart=true"
When you start jCustomer in regular mode, the logout command or CTRL-D key binding helps you logout from the console and shutdown the jCustomer instance. When you start jCustomer in background mode, you can use the bin/stop Unix script (bin\stop.bat on Windows). More generally, you can use the shutdown command (on the CXS console) that works in any case.
karaf@root()> shutdown -h
Confirm: halt instance root (yes/no):
The shutdown command asks for a confirmation. If you want to bypass the confirmation step, you can use the -f (--force) option:
karaf@root()> shutdown -f
You can also use directly halt which is an alias to shutdown -f -h.
jCustomer uses a mechanism to prevent unauthorized servers and clients to send some specific events. Events such as logins, or properties updates should only be allowed from whitelisted servers. To do that jCustomer uses a combination of a unique key and an IP address to check if a server may send restricted events to jCustomer. This is configured in the etc/org.apache.unomi.thirdparty.cfg file that is created after the initial start of jCustomer. jCustomer must be restarted for the settings from this file to take effect.
Edit the etc/unomi.custom.system.properties file to add a jCustomer key. This key may be any unique string (there is a default one, but it should only be used for testing, never for production). We recommend using something obscure such as a UUID (generate one here) or a SHA checksum (generate one here).
You will also need to configure the IP addresses that will be allowed to send some secure events. Warning: If these requests will go through proxies, you must use the IP address of the last proxy in the chain. For example if your deployment is setup this way: Jahia>Public jCustomer IP>Apache HTTP server>jCustomer, the IP address must be the last IP that is used to connect to jCustomer, in this case the IP address of the HTTP server. Here we call the various IP addresses of the Jahia nodes Jahia_NODE_1, Jahia_NODE_2. Of course if you have more than two nodes you will also need to add them here.
org.apache.unomi.thirdparty.provider1.key=<generated-unomi-key>
org.apache.unomi.thirdparty.provider1.ipAddresses=127.0.0.1,::1,DX_NODE_1,DX_NODE_2
org.apache.unomi.thirdparty.provider1.allowedEvents=login,updateProperties
The jCustomer key will then be required in the jExperience connection setup. Note that the allowedEvents must contain the updateProperties event, as it is now required by jExperience to perform any updates on profile or persona properties. Make sure this value is present especially if you are migrating from previous versions of jCustomer.
The jExperience Package is delivered as a JAR named EnterpriseDistribution-jExperience-version-number.jar, where version-number is the version you are installing, for example 1.11.2. The JAR must be deployed on your Jahia server. While your Jahia server is running, in the Server Administration UI>System components>Modules, click the Upload action and choose the EnterpriseDistribution-jExperience-version-number.jar file to install the package.
jExperience’s configuration for the connection to the jCustomer server is setup using OSGi configuration files. These files are located in the /digital-factory-data/karaf/etc directory as is the case for other OSGi configuration files. We also provide a sample configuration file.
Configuration files can be created and edited while Jahia is running. They will be automatically refreshed at a regular interval.
Multiple configuration instances may be deployed by following naming convention:
/digital-factory-data/karaf/etc/org.jahia.modules.jexperience.settings-[CONFIG_NAME].cfg
where [CONFIG_NAME] can be anything you want to identify your configuration
You can use a global jExperience configuration for all the sites or keep configuration per sites. To have the configuration apply only to a given site the following property must be set:
jexperience.siteKey=mySite
Using the siteKey could be useful to override a global configuration to customize it for a given site. If no siteKey provided, the configuration will be considered global.
For information about permissions included with jExperience, see About jExperience permissions.