Upgrade Fusion Server 3.1.x to 4.2.y

Introduction

This article describes how to perform the following upgrade:

  • From version: Fusion 3.1.x

  • To version: Fusion 4.2.y

Important
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps. For more information, see the supported upgrade sequences.

For Fusion 3.1 and later releases, a migrator is available for upgrading Fusion.

During the upgrade process, the migrator uses a properties file. After downloading and installing the migrator, the properties files is in the /opt/lucidworks/fusion/3.1.x/var/upgrade directory (on Unix or MacOS) or the C:\lucidworks\fusion\3.1.x\var\upgrade\ directory (on Windows). The file names reference the versions you are upgrading from and to. For example:

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

Migration entails down time and multiple starts and stops of Fusion services. Plan accordingly, especially in terms of disabling external load balancers or monitors that might react adversely to the starts and stops.

Download the latest migrator immediately before upgrading. This helps ensure that the upgrade goes smoothly.

Important
The newer Fusion instance must be newly untarred and never started.

About the upgrade

This section describes how connectors, object migrations, and signals are migrated during an upgrade.

Connectors

In Fusion 3.1.0 and above, only a subset of connectors are included by default.

The migrator detects which connectors were used in the older version of Fusion, and installs them automatically in Fusion 4.2.y. This step requires an Internet connection. If no connection is available, then you must download connectors at http://lucidworks.com/connectors/ and install them as bootstrap plugins.

If a connector to be upgraded wasn’t available during the upgrade, then a message in /opt/lucidworks/fusion/3.1.x/var/upgrade/tmp/migrator.log (on Unix) or C:\lucidworks\fusion\3.1.x\var\upgrade\tmp\migrator.log (on Windows) indicates this.

Only datasources for connectors that are supported in the new Fusion version are upgraded. Datasources for custom connectors aren’t upgraded.

If no Internet connection is available

If no Internet connection is available during an upgrade, the migrator can’t automatically download the connectors it needs. Using the Fusion UI or API later to install the connectors also might not be an option.

In this case, download the connector zip files for all existing connectors and any connectors that you are adding from http://lucidworks.com/connectors/ and place them in apps/connectors/bootstrap-plugins for the new deployment (on all Fusion nodes). Do so at the time indicated in the procedures that follow.

Adding connectors during an upgrade

You can add connectors during an upgrade (that is, add connectors that aren’t in the old deployment).

Download the connector zip files from http://lucidworks.com/connectors/ and place them in apps/connectors/bootstrap-plugins for the new version (on all Fusion nodes).

Object migrations and transformations

The migrator upgrades all Fusion 3.1 object types:

  • Collections

  • Index pipelines

  • Query pipelines

  • Search cluster configurations

  • Schedules

  • Aggregations

  • Datasources

  • Dashboards

  • Parsing configurations

  • Object groups

  • Links

  • Tasks

  • Jobs

  • Spark objects

The migrator adds these Fusion Server object types:

  • Apps

  • Appkit apps

  • Index profiles

  • Query profiles

  • Blobs

Important
In Fusion Server 4.0 and later, most objects exist in the context of apps. When you upgrade from Fusion 3.1.x to Fusion Server 4.2.y, the migrator creates the app default and places object in that app or links them to it, as needed. Some objects are not linked to apps. You can explore objects in Object Explorer.

Noteworthy transformations

While migrating objects, the migrator makes these 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

In Fusion Server 4.0, index profiles and query profiles are objects. They have capabilities that exceed those of index profiles and query profiles in prior releases.

  • 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.

During migration from 3.1.x to 4.0.y, the migrator upgrades index profiles and query profiles as follows:

  • 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 doesn’t 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 doesn’t 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.

After migration, you might need to adjust the pipeline references of index profiles and query profiles by hand, and/or create new index profiles and query profiles.

Access control migration

The migrator upgrades all access control configurations:

  • Security realms – Security realms don’t require adjustments after migration.

  • Roles – System-created roles don’t require adjustments after migration. User-created roles probably require adjustments after migration.

  • Users – System-created users don’t require adjustments after migration. User-created users probably require adjustments after migration.

Migrations that shouldn’t require adjustments

This section describes fully automatic parts of migration. You shouldn’t have to adjust these items after migration.

The migrator performs these migration tasks:

  • 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 don’t 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

This section describes parts of migration for which you might need to make adjustments after migration.

Important
Following migration, we recommend that you review the API and UI permissions for roles, and the roles and API permissions for users.
  • 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

Fusion Server 4.2.y indexes search log events into the <collection>_signals collections as response signals, instead of indexing them into the <collection>_logs collections.

Roughly 90 new fields used by App Insights are added to existing <collection>_signals collections.

You are encouraged to adopt the new signal fields, but you can continue using the old dynamic field names, such as user_id_s, until Fusion 5.0. If you adopt the new signals schema, then you must update any Spark jobs that rely on the old field names.

Fusion Server 4.2.y replaces the _signals_ingest index pipeline with a new version that works with the new signals schema.

If you made changes to the _signals_ingest pipeline, then you’ll need to manually add those changes to the new configuration after migration.

The migrator preserves legacy-style aggregation jobs. Optionally, you can manually convert these to SQL-based aggregation jobs.

Fusion Server 4.2.y adds a new session rollup job for each collection with signals enabled. The session rollup job creates session signals that contain aggregated information about user activity in a session.

Fusion Server 4.2.y adds a new head/tail analysis job for each collection with signals enabled. The head/tail analysis job uses signals to compute interesting metrics for head-and-tail queries.

Review known issues

Before upgrading, review the known issues to see whether any of them apply to the circumstances of your upgrade. Some known issues might require actions before upgrading.

That article also contains instructions regarding what to do if an upgrade step fails.

Upgrade on Unix

Use this procedure to upgrade Fusion on a single Unix node or on multiple Unix nodes.

Perform the steps in this procedure on the indicated nodes on which Fusion is running ("Fusion nodes"). To perform an upgrade, Fusion nodes must have at least these services running:

  • API service (api)

  • Fusion UI service (ui)

If Solr and/or ZooKeeper instances are also running on other nodes (without Fusion), you don’t need to do anything with the external Solr and/or ZooKeeper instances.

Important
For every step on multiple nodes, ensure that the step completes on all Fusion nodes before going to the next step. There is the notion of a "main node" during the migration process. This node will be used for certain centralized migration activities that do not need to be done on every node, such as downloading connectors that are then uploaded to blob storage that is shared by all, etc. Just pick one of your Fusion nodes to be the "main node"; there’s no special requirement as to which one you pick.

Install the Java JDK

Before upgrading to Fusion Server 4.2 or later, you must install the Java JDK on all nodes that will run Fusion Server. Prior versions of Fusion Server could use either the JRE or the JDK.

For more information, see Java requirements.

Download and install the newer version of Fusion

Perform these tasks on all Fusion nodes:
  1. Download the version of Fusion to which you are upgrading.

  2. Extract the newer version of Fusion:

    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. Don’t 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 can’t download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from http://lucidworks.com/connectors/ 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 http://lucidworks.com/connectors/ 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 isn’t sufficient disc space, free up space before proceeding.

Download and install the Fusion migrator

Perform these tasks on all Fusion nodes:
  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).

    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.2:

    export FUSION_OLD="/opt/lucidworks/fusion/3.1.5"
    export FUSION_NEW="/opt/lucidworks/fusion/4.2.2"
  3. Create this directory:

    mkdir $FUSION_OLD/var/upgrade
  4. Install the migrator:

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

Run the migrator

Perform these tasks on the indicated nodes:
  1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:

    $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:

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

    This message indicates that the step finished successfully:

    Old Fusion configuration export (--export) finished successfully.
  3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:

    $FUSION_OLD/bin/ui stop
    $FUSION_OLD/bin/connectors stop
    $FUSION_OLD/bin/api stop
    $FUSION_OLD/bin/solr stop
    Tip
    You can see what is running with $FUSION_OLD/bin/fusion status.
  4. (Only on secondary Fusion nodes) Prepare secondary nodes:

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

    This message indicates that the step finished successfully:

    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):

    $FUSION_OLD/bin/zookeeper stop
  6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar --main-transform
    Note
    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:

    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):

    $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:

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

    This message indicates that the step finished successfully:

    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:

    $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):

    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:

    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:

    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:

    $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:

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

    This message indicates that the step finished successfully:

    New Fusion object import (--fusion-import) finished successfully.
    Tip
    After migration, you can find details about the results in the fusion/3.1.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

To 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):

    $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. 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.

  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 AI 4.2 introduces functionality for using business rules, that is, manually created formulas for rewriting queries and responses.

You can add support for business rules to apps that were created in versions of Fusion AI prior to version 4.2. To do so, perform the steps in this section.

The add-rule-objects-xyz.zip file (where xyz is a version number) specifies the objects to add to an app. It is supplied in the Fusion migrator zip file at the top level. After installing the migrator, the location is $FUSION_OLD/var/upgrade/import-files.

Note
Adding support for business rules has a costs. Additional collections and objects are created. Only add support for business rules to apps in which you plan to use them.

You have a choice. You can update each app using the Fusion UI or the Fusion API.

Fusion UI

For each app in which you plan to use business rules, import the objects in the add-rule-objects-xyz.zip file into the app.

To import business rule objects
  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 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

For each app in which you plan to use business rules, import the objects in the add-rule-objects-xyz.zip file into the app.

To import business rule objects
  1. Create an app-name.txt file with the following content:

    {"app.id" : "name-of-migrated-app"}

    For example, for the app Lucene Revolution:

    {"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:

    curl -u admin: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://localhost:8765/api/v1/objects/import?importPolicy=merge"

    For example:

    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://localhost:8765/api/v1/objects/import?importPolicy=merge"

Upgrade on Windows

Use this procedure to upgrade Fusion on a single Windows node or multiple Windows nodes.

Perform the steps in this procedure on the indicated nodes on which Fusion is running ("Fusion nodes"). To perform an upgrade, Fusion nodes must have at least these services running:

  • API service (api)

  • Fusion UI service (ui)

If Solr and/or ZooKeeper instances are also running on other nodes (without Fusion), you don’t need to do anything with the external Solr and/or ZooKeeper instances.

Important
If you are upgrading Fusion on multiple nodes, then, for every step on multiple nodes, ensure that the step completes on all Fusion nodes before going to the next step. There is the notion of a "main node" during the migration process. This node will be used for certain centralized migration activities that do not need to be done on every node, such as downloading connectors that are then uploaded to blob storage that is shared by all, etc. Just pick one of your Fusion nodes to be the "main node"; there’s no special requirement as to which one you pick.

Install the Java JDK

Before upgrading to Fusion Server 4.2 or later, you must install the Java JDK on all nodes that will run Fusion Server. Prior versions of Fusion Server could use either the JRE or the JDK.

For more information, see Java requirements.

Download and install the newer version of Fusion

Perform these tasks on all Fusion nodes:
  1. Download the version of Fusion to which you are upgrading.

  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. Don’t run the new version of Fusion yet.

  4. 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 can’t download new versions of connectors automatically. Download the new versions of connector zip files for your current connectors from http://lucidworks.com/connectors/ 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 http://lucidworks.com/connectors/ 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 isn’t sufficient disc space, free up space before proceeding.

Download and install the Fusion migrator

Perform these tasks on all Fusion nodes:
  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:

    set FUSION_OLD=C:\lucidworks\fusion\3.1.5
    set FUSION_NEW=C:\lucidworks\fusion\4.2.2
  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

Perform these tasks on the indicated nodes:
  1. (On all Fusion nodes) Start all Fusion services for the old version of Fusion:

    %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:

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

    This message indicates that the step finished successfully:

    Old Fusion configuration export (--export) finished successfully.
  3. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:

    %FUSION_OLD%\bin\ui.cmd stop
    %FUSION_OLD%\bin\connectors.cmd stop
    %FUSION_OLD%\bin\api.cmd stop
    %FUSION_OLD%\bin\solr.cmd stop
    Tip
    You can see what is running with %FUSION_OLD%\bin\fusion status.
  4. (Only on secondary Fusion nodes) Prepare secondary nodes:

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

    This message indicates that the step finished successfully:

    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):

    %FUSION_OLD%\bin\zookeeper.cmd stop
  6. (Only on the main Fusion node) Transform configuration data on the main Fusion node:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --main-transform
    Note
    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:

    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):

    %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:

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

    This message indicates that the step finished successfully:

    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:

    %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):

    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:

    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:

    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:

    %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:

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

    This message indicates that the step finished successfully:

    New Fusion object import (--fusion-import) finished successfully.
    Tip
    After migration, you can find details about the results in the fusion\3.1.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

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

    %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. 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.

  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 AI 4.2 introduces functionality for using business rules, that is, manually created formulas for rewriting queries and responses.

You can add support for business rules to apps that were created in versions of Fusion AI prior to version 4.2. To do so, perform the steps in this section.

The add-rule-objects-xyz.zip file (where xyz is a version number) specifies the objects to add to an app. It is supplied in the Fusion migrator zip file at the top level. After installing the migrator, the location is %FUSION_OLD%\var\upgrade\import-files\.

You have a choice. You can update each app using the Fusion UI or the Fusion API.

Fusion UI

For each app in which you plan to use business rules, import the objects in the add-rule-objects-xyz.zip file into the app.

To import business rule objects
  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 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

For each app in which you plan to use business rules, import the objects in the add-rule-objects-xyz.zip file into the app.

To import business rule objects
  1. Create an app-name.txt file with the following content:

    {"app.id" : "name-of-migrated-app"}

    For example, for the app Lucene Revolution:

    {"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:

    curl -u admin: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://localhost:8765/api/v1/objects/import?importPolicy=merge"

    For example:

    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://localhost:8765/api/v1/objects/import?importPolicy=merge"