Written by The Jahia Team
   Estimated reading time:

To upgrade from Marketing Factory 1.7.x to 1.8.0:

Prerequisites

1. Delete MF settings on all sites

2. In DX administration > modules > Stop Marketing Factory Core 1.7.x and associated modules (e.g: MF Components, MF FF Bridge, MF OAuth Data Mapper, etc...)

3. Stop Apache Unomi 1.1.3

ElasticSearch migration (from 5.1.2 to 5.6.3)

1. Backup your Elasticsearch database using Elasticsearch snapshots (see documentation here). You can find an example of a snapshot / restore procedure at the end of this document.

2. Stop your Elasticsearch (cluster)

3. Download and install Elasticsearch version 5.6.3

4. Update the /path/to/your/ES/config/elasticsearch.yml with your own value (should be pretty similar to the previous one but, WE STRONGLY RECOMMEND YOU DO NOT COPY THE FILE but instead re-apply only the required changes such as the cluster.name). Warning: if you intend to use the following setting: action.auto_create_index: false you MUST change it to: action.auto_create_index: +context*,-* instead, since we now use index templates for automatic index creation.

5. Start your ElasticSearch (cluster)

6. Import your ElasticSearch database using Elasticsearch restore, check your ES cluster health before starting Apache Unomi migration, import can take a little while

Apache Unomi migration

1. Download and install Apache Unomi 1.2.1 from the Jahia Customer Extranet page.

2. Apply any custom changes that you made in the configuration of Apache Unomi 1.1.3 (files in the <unomi-install-dir>/etc folder) to Apache Unomi 1.2.1

WE STRONGLY RECOMMEND YOU DO NOT COPY THE FILES and instead re-apply any changes only if you really need them. For example, the file org.apache.unomi.cluster.cfg must contain the following two  lines:
contextserver.publicAddress=<publicProtocol>://<publicHost>:<publicPort>
contextserver.internalAddress=<internalProtocol>:<internalHost>:<internalPort>
 
The following lines that are also no longer required:
contextserver.address=<host>
contextserver.port=<port>
contextserver.secureAddress=<secureHost>
contextserver.securePort=<securePort>
jmxUsername=karaf
jmxPassword=karaf
jmxPort=1099
 
4. Start Apache Unomi 1.2.1 using ./karaf
 
5. If you used ./start then connect to the Apache Unomi Karaf SSH Shell using an SSH client such as in the following example (default password karaf):
ssh -p 8102 karaf@localhost
 
6. Migrate your ElasticSearch database using Apache Unomi command tools:
unomi:migrate 1.2.0
 
7. Answer yes at the question:
[WARNING] You are about to execute a migration, this a very sensitive operation, are you sure? (yes/no):
 
8. Answer yes or no at the question
We need to initialize a HttpClient, do we need to trust all certificates? (yes/no):
 
9. Enter your ElasticSearch address at the question:
Host address (default = http://localhost:9200):
 
10. Answer 2 at the question:
How to manage tags?
1. copy: will duplicate tags in systemTags property
2. move: will move tags in systemTags property
[1 - 2]:
 
11. Answer yes to the question:
As we will copy/move the tags, do you wish to remove existing namespace on tags before copy/move to systemTags? (e.g: hidden.) (yes/no)
 
12. Wait a little bit and if everything goes well you should see:
Migration to version 1.3.0 done successfully

13. It is now required to use Unomi keys, so you will have to open the following file (created at karaf first start) : <unomi-install-dir>/etc/org.apache.unomi.thirdparty.cfg that contains the following lines:

thirdparty.provider1.key=<generateYourOwnKey>
thirdparty.provider1.ipAddresses=<your.dx.IP.address>,<your.dx.alt.IP.address>
thirdparty.provider1.allowedEvents=login,updateProperties
 
Although you could use the provided key for testing purposes, we recommend you create your own (especially for production). This may be any string, we recommend something as cryptic and as long as possible. You will need to add this key to your Apache Unomi settings in the Marketing Factory connection settings.
 
You will also need to adjust the ipAddresses setting, that controls which IPs may send restricted events directly to Apache Unomi (listed in the allowedEvents setting). In most cases (unless a specific integration has been added) you shouldn’t need to change the allowedEvents values.
 

End

1. Update Marketing Factory core to 1.8.0 and if you are using them the associate modules (e.g: MF Components, MF FF Bridge, MF OAuth Data Mapper, etc...)

2. Undeploy previous version of the modules

3. Start unomi using the command in the Karaf SSH shell:

unomi:start

4. Exit Apache Unomi Karaf SSH Shell, if you started with ./karaf then enter shutdown then ./start to start you Apache Unomi, otherwise just leave the console.

5. Start Marketing Factory

6. If some of your users meet problems after the migrations, ask them to clean their browser's cache

 

Example of a ElasticSearch snapshot/restore

Snapshot Steps

Add to the elasticsearch.yml file:

path.repo: [“/home/elasticsearch/my_backup”]

Setup the backup with the following command:

    curl -XPUT ’http://localhost:9200/_snapshot/my_backup' -H ‘Content-Type: application/json’ -d ‘{
        “type”: “fs”,
        “settings”: {
            “location”: “/home/elasticsearch/my_backup”,
            “compress”: true
        }
    }’
Launch the snapshot using something like this :
curl -XPUT "http://10.100.0.126:9200/_snapshot/my_backup/snapshot_2?wait_for_completion=true&pretty"  -H 'Content-Type: application/json' -d '{"indices": "context*"}'

Restore Steps

If you are restoring to the same cluster, make sure you delete all old indices first before restoring them. If not, you will need to setup the backup using steps 1 & 2 of the snapshot procedure in your new ElasticSearch cluster.

You can then restore it with: 
curl -XPOST “localhost:9200/_snapshot/my_backup/snapshot_2/_restore” -d ‘{
    “indices”: “context*”
}’