Release Notes

​

Introduction

• From version: Fusion 4.2.x
• To version: Fusion 4.2.y

• To upgrade 4.2.3 to 4.2.5, the migrator uses the 4.2.x-4.2.x.properties file.

​

About the upgrade

​

Connectors

​

If no Internet connection is available

​

Adding connectors during an upgrade

​

Object migrations and transformations

• Collections
• Index pipelines
• Query pipelines
• Search cluster configurations
• Datasources
• Parsing configurations
• Object groups
• Links
• Tasks
• Jobs
• Spark objects
• Apps
• Appkit apps
• Index profiles
• Query profiles
• Blobs

​

Access control migration

• Security realms
• Roles
• Users

​

Review known issues

​

Upgrade on Unix

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Extract the newer version of Fusion:
   Copy

   cd /opt/lucidworks
   mv ~/Downloads/fusion-4.2.y.tar.gz ./
   tar -xf fusion-4.2.y.tar.gz
   

   For example, if Fusion is currently installed in /opt/lucidworks/fusion/4.2.x, then change your working directory to /opt/lucidworks/ and extract the file there. do not run the new version of Fusion yet.
3. Ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the /opt/lucidworks/fusion/4.2.y/conf directory.
4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
5. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
6. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
7. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/4.2.x/data/solr. If there is not sufficient disk space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/4.2.x"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.y"
   

   For example, when upgrading from Fusion 4.2.0 to 4.2.6:
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/4.2.0"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
   

3. Create this directory:
   Copy

   mkdir $FUSION_OLD/var/upgrade
   

4. Install the migrator:
   Copy

   tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
   

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   $FUSION_OLD/bin/fusion start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   $FUSION_OLD/bin/log-shipper stop
   $FUSION_OLD/bin/sql stop
   $FUSION_OLD/bin/admin-ui stop
   $FUSION_OLD/bin/webapps stop
   $FUSION_OLD/bin/proxy stop
   $FUSION_OLD/bin/connectors-rpc stop
   $FUSION_OLD/bin/connectors-classic stop
   $FUSION_OLD/bin/api stop
   $FUSION_OLD/bin/solr stop
   

   If Spark services are running, also stop those:
   Copy

   $FUSION_OLD/bin/spark-master stop
   $FUSION_OLD/bin/spark-worker stop
   

   You can see what is running with $FUSION_OLD/bin/fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

   Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_OLD/bin/zookeeper stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_NEW/bin/zookeeper start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
   Copy

   $FUSION_NEW/bin/fusion start
   

10. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

    After migration, you can find details about the results in the fusion/4.2.x/var/upgrade/tmp directory. If the migration produces unexpected results, the files in this directory are helpful for troubleshooting.

​

Validate the new version of Fusion

1. (Only on the main Fusion node) Restart the new version of Fusion (all services defined in fusion.properties):
   Copy

   $FUSION_NEW/bin/fusion restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   • For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   • For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. When you are satisfied with the migration and you have backed up the fusion/4.2.x/ directory, you can rm -fr fusion/4.2.*x/ to remove the older version of Fusion (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects.
   The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects.
   The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is $FUSION_OLD/var/upgrade/import-files.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects.
   Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the $HOME environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file/app-name.txt' -F "importData=path-to-zip-file/add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=$HOME/Lucene_Revolution.txt' -F "importData=$FUSION_OLD/var/upgrade/import-files/add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Upgrade on Windows

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Move the fusion-4.2.y.zip file to the directory that contains the fusion\ directory.
   For example, if Fusion is installed in C:\lucidworks\fusion\4.2.x, then move the file to C:\lucidworks.
3. Unzip the fusion-4.2.y.zip file. do not run the new version of Fusion yet.
4. For Fusion 4.x, ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the C:\lucidworks\fusion\4.2.y\conf directory.
5. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
6. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
7. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
8. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion\4.2.x\data\solr. If there is not sufficient disk space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Windows. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Open a Command Prompt window and create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively. For example:
   Copy

   set FUSION_OLD=C:\lucidworks\fusion\4.2.0
   set FUSION_NEW=C:\lucidworks\fusion\4.2.6
   

3. Create a fusion\4.2.x\var\upgrade directory.
4. Unzip the migrator zip file, and move the contents of the extracted folder to +fusion\+4.2.x\var\upgrade.

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   %FUSION_OLD%\bin\fusion.cmd start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   %FUSION_OLD%\bin\log-shipper.cmd stop
   %FUSION_OLD%\bin\sql.cmd stop
   %FUSION_OLD%\bin\admin-ui.cmd stop
   %FUSION_OLD%\bin\webapps.cmd stop
   %FUSION_OLD%\bin\proxy.cmd stop
   %FUSION_OLD%\bin\connectors-rpc.cmd stop
   %FUSION_OLD%\bin\connectors-classic.cmd stop
   %FUSION_OLD%\bin\api.cmd stop
   %FUSION_OLD%\bin\solr.cmd stop
   

   If Spark and SQL services are running, also stop those:
   Copy

   %FUSION_OLD%\bin\spark-master.cmd stop
   %FUSION_OLD%\bin\spark-worker.cmd stop
   

   You can see what is running with %FUSION_OLD%\bin\fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

   Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_OLD%\bin\zookeeper.cmd stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are only using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_NEW%\bin\zookeeper.cmd start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start Solr for the new Fusion version:
   Copy

   %FUSION_NEW%\bin\solr.cmd start
   

10. (Only on the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port
    

    For example:
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983
    

    This message indicates that plugins were deleted successfully:
    Copy

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
    

11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
    Copy

    %FUSION_NEW%\bin\fusion.cmd start
    

12. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (On all Fusion nodes) Restart all Fusion services for the new version of Fusion:
   Copy

   %FUSION_NEW%\bin\fusion.cmd restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   1. For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   2. For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. When you are satisfied with the migration and you have backed up the +fusion\+4.2.x directory, you can remove the older version of Fusion by removing that directory (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is %FUSION_OLD%\var\upgrade\import-files\.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the %HOMEPATH% environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file\app-name.txt' -F "importData=path-to-zip-file\add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=%HOMEPATH%\Lucene_Revolution.txt' -F "importData=%FUSION_OLD%\import-files\add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

• From version: 4.2.6
• To version: Latest SP

​

Preliminary upgrade steps (optional)

1. Log in to the Fusion Admin UI with an administrator account.
2. Select System -> blobs
3. Open webapp-admin-war → admin-webapps
4. Delete the admin.war, insights.war, app-studio.war WAR by selecting each entry and clicking Delete Blob.

​

Upgrade an existing Fusion installation (Linux, Windows)

​

Linux

1. Place the fusion-4.2.6-service-pack-patch.jar and fusion-4.2.6-sp3.tar.gz on each server hosting Fusion services.
   The script does not update external Solr and Zookeeper installations.
2. Shut down all Fusion services on each server that will receive the patched upgrade.
3. Run the fusion-4.2.6-service-pack-patch.jar jar (java -jar fusion-4.2.6-service-pack-patch.jar) and follow the prompts.
4. Start the Fusion services.

​

Windows

1. Place the fusion-4.2.6-service-pack-patch.jar and fusion-4.2.6-sp3.zip on each server hosting Fusion services. The script does not update external Solr and Zookeeper installations.
2. Shut down all Fusion services on each server that will receive the patched upgrade.
3. Run the fusion-4.2.6-service-pack-patch.jar jar (java -jar fusion-4.2.6-service-pack-patch.jar) and follow the prompts.
4. Start the Fusion services.

​

Enable the Tika parser service

1. Open fusion/conf/fusion.properties in a text editor.
2. Add the following Tika entry to the end of the file.
   Copy

   # Tika parser service
   tika-server.port = 8889
   
   # If your tika server is properly secured behind a firewall, then you can then set the
   # -Dtika.server.allowLocalFileOptimization=true to allow you to use the "local file optimization" which reduces
   # http overhead during local tika parses.
   tika-server.jvmOptions = -Dtika.MAX_HEAP_MB=1000 -Dtika.NUM_PROCESSES=2 -Dtika.ALLOW_LOCAL_FILE_OPTIMIZATION=true
   

3. In the log-shipper section of the file, add the following in a new line:
   Copy

   log-shipper.logs.tika-server = java
   

4. Save the file.
5. Download the tika-server-log4j2.xml file.
6. Add the TikaServer logging configuration to the fusion/conf directory.

​

Introduction

• From version: Fusion 4.1.x
• To version: Fusion 4.2.y

• To upgrade 4.1.3 to 4.2.5, the migrator uses the 4.1.x-4.2.x.properties file.

​

About the upgrade

​

Connectors

​

If no Internet connection is available

​

Adding connectors during an upgrade

​

Object migrations and transformations

• Collections
• Index pipelines
• Query pipelines
• Search cluster configurations
• Datasources
• Parsing configurations
• Object groups
• Links
• Tasks
• Jobs
• Spark objects
• Apps
• Appkit apps
• Index profiles
• Query profiles
• Blobs

​

Access control migration

• Security realms
• Roles
• Users

​

Association of blobs with apps

​

Review known issues

​

Upgrade on Unix

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Extract the newer version of Fusion:
   Copy

       cd /opt/lucidworks
       mv ~/Downloads/fusion-4.2.y.tar.gz ./
       tar -xf fusion-4.2.y.tar.gz
   

   For example, if Fusion is currently installed in /opt/lucidworks/fusion/4.1.x, then change your working directory to /opt/lucidworks/ and extract the file there. do not run the new version of Fusion yet.
3. Ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the /opt/lucidworks/fusion/4.2.y/conf directory.
4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
5. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
6. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
7. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/4.1.x/data/solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/4.1.x"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.y"
   

   For example, when upgrading from Fusion 4.1.3 to 4.2.6:
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/4.1.3"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
   

3. Create this directory:
   Copy

   mkdir $FUSION_OLD/var/upgrade
   

4. Install the migrator:
   Copy

   tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
   

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   $FUSION_OLD/bin/fusion start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   $FUSION_OLD/bin/log-shipper stop
   $FUSION_OLD/bin/admin-ui stop
   $FUSION_OLD/bin/webapps stop
   $FUSION_OLD/bin/proxy stop
   $FUSION_OLD/bin/connectors-rpc stop
   $FUSION_OLD/bin/connectors-classic stop
   $FUSION_OLD/bin/api stop
   $FUSION_OLD/bin/solr stop
   

   If Spark and SQL services are running, also stop those:
   Copy

   $FUSION_OLD/bin/spark-master stop
   $FUSION_OLD/bin/spark-worker stop
   $FUSION_OLD/bin/sql stop
   

   You can see what is running with $FUSION_OLD/bin/fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

   Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_OLD/bin/zookeeper stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_NEW/bin/zookeeper start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
   Copy

   $FUSION_NEW/bin/fusion start
   

10. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (Only on the main Fusion node) Restart the new version of Fusion (all services defined in fusion.properties):
   Copy

   $FUSION_NEW/bin/fusion restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   • For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   • For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 4.1.0 to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the fusion/4.1.x/ directory, you can rm -fr fusion/4.1.*x/ to remove the older version of Fusion (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is $FUSION_OLD/var/upgrade/import-files.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the $HOME environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file/app-name.txt' -F "importData=path-to-zip-file/add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=$HOME/Lucene_Revolution.txt' -F "importData=$FUSION_OLD/var/upgrade/import-files/add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Upgrade on Windows

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Move the fusion-4.2.y.zip file to the directory that contains the fusion\ directory. For example, if Fusion is installed in C:\lucidworks\fusion\4.1.x, then move the file to C:\lucidworks.
3. Unzip the fusion-4.2.y.zip file. do not run the new version of Fusion yet.
4. For Fusion 4.x, ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the C:\lucidworks\fusion\4.2.y\conf directory.
5. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
6. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
7. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
8. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion\4.1.x\data\solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Windows. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Open a Command Prompt window and create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively. For example:
   Copy

   set FUSION_OLD=C:\lucidworks\fusion\4.1.3
   set FUSION_NEW=C:\lucidworks\fusion\4.2.6
   

3. Create a fusion\4.1.x\var\upgrade directory.
4. Unzip the migrator zip file, and move the contents of the extracted folder to +fusion\+4.1.x\var\upgrade.

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   %FUSION_OLD%\bin\fusion.cmd start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   %FUSION_OLD%\bin\log-shipper.cmd stop
   %FUSION_OLD%\bin\admin-ui.cmd stop
   %FUSION_OLD%\bin\webapps.cmd stop
   %FUSION_OLD%\bin\proxy.cmd stop
   %FUSION_OLD%\bin\connectors-rpc.cmd stop
   %FUSION_OLD%\bin\connectors-classic.cmd stop
   %FUSION_OLD%\bin\api.cmd stop
   %FUSION_OLD%\bin\solr.cmd stop
   

   If Spark and SQL services are running, also stop those:
   Copy

   %FUSION_OLD%\bin\spark-master.cmd stop
   %FUSION_OLD%\bin\spark-worker.cmd stop
   %FUSION_OLD%\bin\sql.cmd stop
   

   You can see what is running with %FUSION_OLD%\bin\fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

   Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_OLD%\bin\zookeeper.cmd stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are only using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_NEW%\bin\zookeeper.cmd start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start Solr for the new Fusion version:
   Copy

   %FUSION_NEW%\bin\solr.cmd start
   

10. (Only on the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port
    

    For example:
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983
    

    This message indicates that plugins were deleted successfully:
    Copy

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
    

11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
    Copy

    %FUSION_NEW%\bin\fusion.cmd start
    

12. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (On all Fusion nodes) Restart all Fusion services for the new version of Fusion:
   Copy

   %FUSION_NEW%\bin\fusion.cmd restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   1. For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   2. For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 4.1.0 to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the +fusion\+4.1.x directory, you can remove the older version of Fusion by removing that directory (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is %FUSION_OLD%\var\upgrade\import-files\.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the %HOMEPATH% environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file\app-name.txt' -F "importData=path-to-zip-file\add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=%HOMEPATH%\Lucene_Revolution.txt' -F "importData=%FUSION_OLD%\import-files\add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Introduction

• From version: Fusion 4.0.x
• To version: Fusion 4.2.y

• To upgrade 4.0.2 to 4.2.5, the migrator uses the 4.0.x-4.2.x.properties file.

​

About the upgrade

​

Connectors

​

If no Internet connection is available

​

Adding connectors during an upgrade

​

Object migrations and transformations

• Collections
• Index pipelines
• Query pipelines
• Search cluster configurations
• Datasources
• Parsing configurations
• Object groups
• Links
• Tasks
• Jobs
• Spark objects
• Apps
• Appkit apps
• Index profiles
• Query profiles
• Blobs

​

Noteworthy transformations

• It adds the new log-shipper service to fusion.properties.
• It removes obsolete log-cleanup tasks.
• It converts the format of job history records.

​

Access control migration

• Security realms
• Roles
• Users

​

Association of blobs with apps

​

Review known issues

​

Upgrade on Unix

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Extract the newer version of Fusion:
   Copy

     cd /opt/lucidworks
     mv ~/Downloads/fusion-4.2.y.tar.gz ./
     tar -xf fusion-4.2.y.tar.gz
   

   For example, if Fusion is currently installed in /opt/lucidworks/fusion/4.0.x, then change your working directory to /opt/lucidworks/ and extract the file there. do not run the new version of Fusion yet.
3. Ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the /opt/lucidworks/fusion/4.2.y/conf directory.
4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
5. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
6. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
7. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/4.0.x/data/solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).
   Copy

     export FUSION_OLD="/opt/lucidworks/fusion/4.0.x"
     export FUSION_NEW="/opt/lucidworks/fusion/4.2.y"
   

   For example, when upgrading from Fusion 4.0.2 to 4.2.6:
   Copy

     export FUSION_OLD="/opt/lucidworks/fusion/4.0.2"
     export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
   

3. Create this directory:
   Copy

     mkdir $FUSION_OLD/var/upgrade
   

4. Install the migrator:
   Copy

     tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
   

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

     $FUSION_OLD/bin/fusion start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

     java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
   

   This message indicates that the step finished successfully:
   Copy

     Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

     $FUSION_OLD/bin/webapps stop
     $FUSION_OLD/bin/admin-ui stop
     $FUSION_OLD/bin/proxy stop
     $FUSION_OLD/bin/connectors-classic stop
     $FUSION_OLD/bin/connectors-rpc stop
     $FUSION_OLD/bin/api stop
     $FUSION_OLD/bin/solr stop
   

   If Spark and SQL services are running, also stop those:
   Copy

     $FUSION_OLD/bin/spark-master stop
     $FUSION_OLD/bin/spark-worker stop
     $FUSION_OLD/bin/sql stop
   

   You can see what is running with $FUSION_OLD/bin/fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

     java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

     Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

     $FUSION_OLD/bin/zookeeper stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

     java -jar $FUSION_OLD/var/upgrade/migrator.jar --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

     Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

     $FUSION_NEW/bin/zookeeper start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

     java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

     New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
   Copy

     $FUSION_NEW/bin/fusion start
   

10. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

        java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

        New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (Only on the main Fusion node) Restart the new version of Fusion (all services defined in fusion.properties):
   Copy

     $FUSION_NEW/bin/fusion restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   • For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   • For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 4.0.x to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the fusion/4.0.x/ directory, you can rm -fr fusion/4.0.*x/ to remove the older version of Fusion (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is $FUSION_OLD/var/upgrade/import-files.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

     {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

     {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the $HOME environment variable is defined.
2. Import the business rule objects:
   Copy

     curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file/app-name.txt' -F "importData=path-to-zip-file/add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

     curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=$HOME/Lucene_Revolution.txt' -F "importData=$FUSION_OLD/var/upgrade/import-files/add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Upgrade on Windows

• API service (api)
• Proxy service (proxy)

​

Ensure that your current version of Fusion has a valid license

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Move the fusion-4.2.y.zip file to the directory that contains the fusion\ directory. For example, if Fusion is installed in C:\lucidworks\fusion\4.0.x, then move the file to C:\lucidworks.
3. Unzip the fusion-4.2.y.zip file. do not run the new version of Fusion yet.
4. For Fusion 4.x, ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the C:\lucidworks\fusion\4.2.y\conf directory.
5. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
6. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
7. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
8. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion\4.0.x\data\solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Windows. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Open a Command Prompt window and create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively. For example:
   Copy

     set FUSION_OLD=C:\lucidworks\fusion\4.0.2
     set FUSION_NEW=C:\lucidworks\fusion\4.2.6
   

3. Create a fusion\4.0.x\var\upgrade directory.
4. Unzip the migrator zip file, and move the contents of the extracted folder to +fusion\+4.0.x\var\upgrade.

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

     %FUSION_OLD%\bin\fusion.cmd start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

     java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
   

   This message indicates that the step finished successfully:
   Copy

     Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

     %FUSION_OLD%\bin\webapps.cmd stop
     %FUSION_OLD%\bin\admin-ui.cmd stop
     %FUSION_OLD%\bin\proxy.cmd stop
     %FUSION_OLD%\bin\connectors-classic.cmd stop
     %FUSION_OLD%\bin\connectors-rpc.cmd stop
     %FUSION_OLD%\bin\api.cmd stop
     %FUSION_OLD%\bin\solr.cmd stop
   

   If Spark and SQL services are running, also stop those:
   Copy

     %FUSION_OLD%\bin\spark-master.cmd stop
     %FUSION_OLD%\bin\spark-worker.cmd stop
     %FUSION_OLD%\bin\sql.cmd stop
   

   You can see what is running with %FUSION_OLD%\bin\fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

     java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

     Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

     %FUSION_OLD%\bin\zookeeper.cmd stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

     java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

     Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are only using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

     %FUSION_NEW%\bin\zookeeper.cmd start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

     java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

     New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (On all Fusion nodes) Start Solr for the new Fusion version:
   Copy

     %FUSION_NEW%\bin\solr.cmd start
   

10. (Only on the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):
    Copy

        java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port
    

    For example:
    Copy

        java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983
    

    This message indicates that plugins were deleted successfully:
    Copy

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
    

11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
    Copy

    %FUSION_NEW%\bin\fusion.cmd start
    

12. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (On all Fusion nodes) Restart all Fusion services for the new version of Fusion:
   Copy

   %FUSION_NEW%\bin\fusion.cmd restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   1. For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   2. For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 4.0.x to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the +fusion\+4.0.x directory, you can remove the older version of Fusion by removing that directory (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is %FUSION_OLD%\var\upgrade\import-files\.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

     {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

     {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the %HOMEPATH% environment variable is defined.
2. Import the business rule objects:
   Copy

     curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file\app-name.txt' -F "importData=path-to-zip-file\add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

     curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=%HOMEPATH%\Lucene_Revolution.txt' -F "importData=%FUSION_OLD%\import-files\add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Introduction

• From version: Fusion 3.1.x
• To version: Fusion 4.2.y

• To upgrade 3.1.5 to 4.2.5, the migrator uses the 3.1.x-4.2.x.properties file.

​

About the upgrade

​

Connectors

​

If no Internet connection is available

​

Adding connectors during an upgrade

​

Object migrations and transformations

• Collections
• Index pipelines
• Query pipelines
• Search cluster configurations
• Schedules
• Aggregations
• Datasources
• Dashboards
• Parsing configurations
• Object groups
• Links
• Tasks
• Jobs
• Spark objects

• Apps
• Appkit apps
• Index profiles
• Query profiles
• Blobs

​

Noteworthy transformations

• It adds the new log-shipper service to fusion.properties.
• It removes obsolete log-cleanup tasks.
• It converts the format of job history records.

​

Migration of index profiles and query profiles

• Prior to Fusion 4.0. A single index profile could reference multiple index pipelines. A single query profile could reference multiple query pipelines.
• In Fusion 4.0 and later. A single index profile can reference a single index pipeline. A single query profile can reference a single query pipeline.

• Index profiles.
  • If a 3.1.x index profile contains a reference to the index pipeline default, then the migrated profile retains that single reference.
  • If a 3.1.x index profile does not contain a reference to the index pipeline default, then the migrated profile references an index pipeline that has the same name as the index profile.
• Query profiles.
  • If a 3.1.x query profile contains a reference to the query pipeline default, then the migrated profile retains that single reference.
  • If a 3.1.x query profile does not contain a reference to the query pipeline default, then the migrated profile references a query pipeline that has the same name as the query profile.

​

Access control migration

• Security realms. Security realms do not require adjustments after migration.
• Roles. System-created roles do not require adjustments after migration. User-created roles probably require adjustments after migration.
• Users. System-created users do not require adjustments after migration. User-created users probably require adjustments after migration.

​

Migrations that should not require adjustments

• It migrates encrypted passwords, so users can log in with the same credentials they used on the older version of Fusion or Fusion Server.
• It adds the user webapps-system-account. Fusion Server uses this account. You do not need to do anything with it.
• It adds these permissions to the role developer:

  GET:/license
  GET,POST,PUT:/appkit
  GET,POST,PUT:/apps/**

• Updates these permissions for the role search:

  POST:/apps/*/signals/**
  GET:/query/**
  GET:/apps/*/query/**
  POST:/signals/**

• Adds the role webapps-role with these permissions:

  GET,HEAD:/webapps/**
  GET,HEAD:/license

​

Migrations that might require adjustments

• If you have created your own developer roles, add these permissions to the roles:

  GET:/license
  GET,POST,PUT:/appkit
  GET,POST,PUT:/apps/**

• If you have created your own search roles, add these permissions to the roles:

  POST:/apps/*/signals/**
  GET:/query/**
  GET:/apps/*/query/**
  POST:/signals/**

​

Signals and Spark jobs

​

Review known issues

​

Upgrade on Unix

• API service (api)
• Fusion UI service (ui)

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Extract the newer version of Fusion:
   Copy

      cd /opt/lucidworks
      mv ~/Downloads/fusion-4.2.y.tar.gz ./
      tar -xf fusion-4.2.y.tar.gz
   

   For example, if Fusion is currently installed in /opt/lucidworks/fusion/3.1.x, then change your working directory to /opt/lucidworks/ and extract the file there. do not run the new version of Fusion yet.
3. Ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the /opt/lucidworks/fusion/4.2.y/conf directory.
4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
5. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
6. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps/connectors/bootstrap-plugins for the new deployment.
7. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/3.1.x/data/solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/3.1.x"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.y"
   

   For example, when upgrading from Fusion 3.1.5 to 4.2.6:
   Copy

   export FUSION_OLD="/opt/lucidworks/fusion/3.1.5"
   export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
   

3. Create this directory:
   Copy

   mkdir $FUSION_OLD/var/upgrade
   

4. Install the migrator:
   Copy

   tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
   

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   $FUSION_OLD/bin/fusion start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   $FUSION_OLD/bin/ui stop
   $FUSION_OLD/bin/connectors stop
   $FUSION_OLD/bin/api stop
   $FUSION_OLD/bin/solr stop
   

java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary

Prepare secondary nodes (--prepare-secondary) finished successfully.

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_OLD/bin/zookeeper stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   $FUSION_NEW/bin/zookeeper start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (If upgrading from Fusion 3.1.0 through 3.1.3; On all Fusion nodes) Start Solr for the new Fusion version:
   Copy

   $FUSION_NEW/bin/solr start
   

10. (If upgrading from Fusion 3.1.0 through 3.1.3; Only on the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):
    Copy

    java -cp "$FUSION_OLD/var/upgrade/jython-standalone-2.7.1.jar:$FUSION_OLD/var/upgrade/migrator.jar" org.python.util.jython "$FUSION_OLD/var/upgrade/transformations/manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port
    

    For example:
    Copy

    java -cp "$FUSION_OLD/var/upgrade/jython-standalone-2.7.1.jar:$FUSION_OLD/var/upgrade/migrator.jar" org.python.util.jython "$FUSION_OLD/var/upgrade/transformations/manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983
    

    This message indicates that plugins were deleted successfully:
    Copy

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
    

11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
    Copy

    $FUSION_NEW/bin/fusion start
    

12. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (Only on the main Fusion node) Restart the new version of Fusion (all services defined in fusion.properties):
   Copy

   $FUSION_NEW/bin/fusion restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   • For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   • For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 3.1.x to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the fusion/3.1.x/ directory, you can rm -fr fusion/3.1.*x/ to remove the older version of Fusion (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is $FUSION_OLD/var/upgrade/import-files.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the $HOME environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file/app-name.txt' -F "importData=path-to-zip-file/add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=$HOME/Lucene_Revolution.txt' -F "importData=$FUSION_OLD/var/upgrade/import-files/add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

​

Upgrade on Windows

• API service (api)
• Fusion UI service (ui)

​

Install the Java JDK

​

Download and install the newer version of Fusion

1. Select the Fusion release to which you are upgrading from Fusion Server 4.x File Download Links.
2. Move the fusion-4.2.y.zip file to the directory that contains the fusion\ directory. For example, if Fusion is installed in C:\lucidworks\fusion\3.1.x, then move the file to C:\lucidworks.
3. Unzip the fusion-4.2.y.zip file. do not run the new version of Fusion yet.
4. For Fusion 4.x, ensure that the new version of Fusion has a valid permanent Fusion license before proceeding with the upgrade. Place a valid license.properties file in the C:\lucidworks\fusion\4.2.y\conf directory.
5. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.
6. (If you are performing an upgrade without Internet access) Without Internet access, the migrator cannot download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
7. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from Fusion 4.x Connector Downloads and place them in apps\connectors\bootstrap-plugins for the new deployment.
8. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion\3.1.x\data\solr. If there is not sufficient disc space, free up space before proceeding.

​

Download and install the Fusion migrator

1. Download the latest migrator zip file for Windows. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)
2. Open a Command Prompt window and create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively. For example:
   Copy

   set FUSION_OLD=C:\lucidworks\fusion\3.1.5
   set FUSION_NEW=C:\lucidworks\fusion\4.2.6
   

3. Create a fusion\3.1.x\var\upgrade directory.
4. Unzip the migrator zip file, and move the contents of the extracted folder to +fusion\+3.1.x\var\upgrade.

​

Run the migrator

1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:
   Copy

   %FUSION_OLD%\bin\fusion.cmd start
   

2. (Only on the main Fusion node) Run the migrator to export the configuration data from the old version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
   

   This message indicates that the step finished successfully:
   Copy

   Old Fusion configuration export (--export) finished successfully.
   

3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
   Copy

   %FUSION_OLD%\bin\ui.cmd stop
   %FUSION_OLD%\bin\connectors.cmd stop
   %FUSION_OLD%\bin\api.cmd stop
   %FUSION_OLD%\bin\solr.cmd stop
   

   You can see what is running with %FUSION_OLD%\bin\fusion status.
4. (Only on secondary Fusion nodes) Prepare secondary nodes:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
   

   This message indicates that the step finished successfully:
   Copy

   Prepare secondary nodes (--prepare-secondary) finished successfully.
   

5. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_OLD%\bin\zookeeper.cmd stop
   

6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --main-transform
   

   Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).
   This message indicates that the step finished successfully:
   Copy

   Fusion data transformations on main node (--main-transform) finished successfully.
   

7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are only using an external ZooKeeper instance, in which case you can ignore this step):
   Copy

   %FUSION_NEW%\bin\zookeeper.cmd start
   

8. (Only on the main Fusion node) Import the first part of configuration data into the new version of Fusion:
   Copy

   java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
   

   This message indicates that the step finished successfully:
   Copy

   New Fusion Zookeeper import (--zookeeper-import) finished successfully.
   

9. (If upgrading from Fusion 3.1.0 through 3.1.3; On all Fusion nodes) Start Solr for the new Fusion version:
   Copy

   %FUSION_NEW%\bin\solr.cmd start
   

10. (If upgrading from Fusion 3.1.0 through 3.1.3; Only on the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port
    

    For example:
    Copy

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-2.7.1.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983
    

    This message indicates that plugins were deleted successfully:
    Copy

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
    

11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:
    Copy

    %FUSION_NEW%\bin\fusion.cmd start
    

12. (Only on the main Fusion node) Import the second part of configuration data into the new version of Fusion:
    Copy

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
    

    This message indicates that the step finished successfully:
    Copy

    New Fusion object import (--fusion-import) finished successfully.
    

​

Validate the new version of Fusion

1. (On all Fusion nodes) Restart all Fusion services for the new version of Fusion:
   Copy

   %FUSION_NEW%\bin\fusion.cmd restart
   

2. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:
   1. Clear your browser’s cache.
      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.
   2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).
   3. Log in.
   4. Navigate to Admin > About Fusion.
      The About Fusion panel should display the newer Fusion release number.
3. Ensure that all connectors were installed automatically during the upgrade.
   1. For Fusion 4.x from the Fusion launcher, click the tile for a migrated app. Click System > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
   2. For Fusion 3.x from the Fusion launcher, click Devops > Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.
4. Ensure that all customizations you made in the former version of Fusion are present in the new one.
5. If you migrated from version 3.1.x to version 4.2.0 or later, confirm associations between blobs and apps and make adjustments if necessary.
6. When you are satisfied with the migration and you have backed up the +fusion\+3.1.x directory, you can remove the older version of Fusion by removing that directory (on all Fusion nodes).

​

Add support for business rules to existing apps

​

Fusion UI

1. In the Fusion launcher, click the app into which you want to import objects. The Fusion workspace appears.
2. In the upper left, click System > Import Fusion Objects. The Import Fusion Objects window opens.
3. For the data file, select add-rule-objects-xyz.zip from your local filesystem. The location in the extracted migrator files is %FUSION_OLD%\var\upgrade\import-files\.
4. Click Import.
5. Edit the Application ID parameter value to use the app name. If the app name contains spaces, replace those with underscore characters. For example, Lucene Revolution would become Lucene_Revolution.
6. Click Import.
7. If there are conflicts, Fusion prompts you to specify an import policy. Click Merge to skip all conflicting objects and import only the non-conflicting objects. Fusion confirms that the import was successful.
8. Click Close to close the Import Fusion Objects window.

​

Fusion API

1. Create an app-name.txt file with the following content:
   Copy

   {"app.id" : "_name-of-migrated-app_"}
   

   For example, for the app Lucene Revolution:
   Copy

   {"app.id" : "Lucene_Revolution"}
   

   Here, we assume that you create the files in your home directory, for which the %HOMEPATH% environment variable is defined.
2. Import the business rule objects:
   Copy

   curl -u USERNAME:PASSWORD -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=path-to-txt-file\app-name.txt' -F "importData=path-to-zip-file\add-rule-objects-xyz.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"
   

   For example:
   Copy

   curl -u admin:Very-SecurePW8 -H "Content-Type:multipart/form-data" -X POST -F 'variableValues=%HOMEPATH%\Lucene_Revolution.txt' -F "importData=%FUSION_OLD%\import-files\add-rule-objects-001.zip" "http://<FUSION_HOST>/api/objects/import?importPolicy=merge"