> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Release Notes
[localhost link]: http://localhost:3000/docs/4/fusion-ai/release-notes/overview
[mintlify link]: https://doc.lucidworks.com/docs/4/fusion-ai/release-notes/overview
[old doc.lw link]: https://doc.lucidworks.com/fusion/5.9/97
Release notes provide detailed descriptions of the relevant changes included with each Fusion Server release, including new features, improvements, bug fixes, and more.
## Upgrades
Keeping your Fusion deployment upgraded to the latest version enables you to take advantage of the latest features, improvements, bug fixes, and addressed security issues.
### Process
Upgrade to the latest version of Fusion:
## Introduction
This article describes how to perform the following upgrade:
* From version: Fusion `4.2.x`
* To version: Fusion `4.2.y`
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps.
For more information, see Fusion 4.x.
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/4.2.x/var/upgrade` directory (on Unix or MacOS) or the `C:\lucidworks\fusion\4.2.*x\var\upgrade\` directory (on Windows). The file names reference the versions you are upgrading from and to. For example:
* To upgrade `4.2.3` to `4.2.5`, the migrator uses the `4.2.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.
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 later, only a subset of [connectors](/docs/fusion-connectors/connectors/overview) are included by default.
The migrator detects which connectors were used in the older version of Fusion, and installs them automatically in Fusion `4.0.y`. This step requires an Internet connection. If no connection is available, then download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and install them as bootstrap plugins.
If a connector to be upgraded was not 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 are not upgraded.
#### If no Internet connection is available
If no Internet connection is available during an upgrade, the migrator cannot 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 connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) for all existing 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 are not in the old deployment).
Download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and place them in `apps/connectors/bootstrap-plugins` for the new version (on all Fusion nodes).
### Object migrations and transformations
The migrator automatically migrates these Fusion 4.2 object types, transforming them as needed:
* 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
In Fusion Server 4.0 and later, most objects exist in the context of apps. When you upgrade from Fusion Server 4.2.x to 4.2.y, the migrator upgrades app objects, all objects in or linked to objects in apps, and objects that are not linked to apps. You can explore the objects in [Object Explorer](/docs/4/fusion-server/concepts/object-explorer).
### Access control migration
The migrator upgrades all access control configurations:
* Security realms
* Roles
* Users
None of these should require adjustments after migration.
## 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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your *current* 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.x/conf` directory.
### Download and install the newer version of Fusion
**Perform these tasks *on all Fusion nodes*:**
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/fusion-server-4-x-file-download-links).
2. Extract the newer version of Fusion:
```bash theme={"dark"}
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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Unix](https://download.lucidworks.com/fusion-migrator.tar.gz). (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).
```bash theme={"dark"}
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:
```bash theme={"dark"}
export FUSION_OLD="/opt/lucidworks/fusion/4.2.0"
export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
```
3. Create this directory:
```bash theme={"dark"}
mkdir $FUSION_OLD/var/upgrade
```
4. Install the migrator:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
$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:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$FUSION_OLD/bin/zookeeper stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
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
**How 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`):
```bash theme={"dark"}
$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 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`.
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.
**How 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** 
> **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/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:///api/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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your current 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.x\conf` directory.
### Download and install the newer version of Fusion
Perform these tasks *on all Fusion nodes*:
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Windows](https://download.lucidworks.com/fusion-migrator.zip). (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:
```bash theme={"dark"}
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
**Perform these tasks on the indicated nodes:**
1. (*On all Fusion nodes*) Start all Fusion services for the old version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%FUSION_OLD%\bin\zookeeper.cmd stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start Solr for the new Fusion version:
```bash theme={"dark"}
%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):
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
Deleted old plugin blobs from solr
0
246
Old connector plugin blobs were deleted successfully.
```
11. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
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
**How to validate the new version of Fusion**
1. (*On all Fusion nodes*) Restart all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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 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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
This article describes how to perform the following upgrade:
* From version: 4.2.6
* To version: Latest SP
Unlike other Fusion upgrades, 4.2.6 SPs are a patched upgrade that can be applied directly to Fusion 4.2.6. If you are not already using Fusion 4.2.6, complete the upgrade to Fusion 4.2.6 before installing the latest Fusion 4.2.6 SP.
You can view the application files to download at [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/fusion-server-4-x-file-download-links).
This upgrade is available to qualified customers whose Lucidworks plans include extended support.
Consult Upgrade to Fusion 4.x for information on upgrading to a different version of Fusion.
If you require a fresh installation of a Fusion 4.2.6 SP, consult Install Fusion 4.x.
## Preliminary upgrade steps (optional)
If you are upgrading to apply the latest Log4j updates to your existing deployment, please follow the proceeding steps.
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**.
For more information about blobs, see [Blob Storage](/docs/4/fusion-server/concepts/indexing/blob-storage).
## Upgrade an existing Fusion installation (Linux, Windows)
### Linux
To upgrade an existing Fusion installation on 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
To upgrade an existing Fusion installation on 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
Fusion 4.2.6 SPs include [an asynchronous Tika parser service](/docs/4/fusion-server/reference/parser-stages/enable-tika-async-parsing). This service is not automatically enabled upon upgrading. To 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.
```bash theme={"dark"}
# 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:
```bash theme={"dark"}
log-shipper.logs.tika-server = java
```
4. Save the file.
5. Download the [tika-server-log4j2.xml file](https://storage.googleapis.com/docs-downloads/tika-server-log4j2.xml).
6. Add the TikaServer logging configuration to the `fusion/conf` directory.
To automatically start the Tika parser service when starting Fusion, add `tika-server` to the `group.default` line. Otherwise, you can start the Tika parser server with the `$fusion/bin/tika-server` script.
## Introduction
This article describes how to perform the following upgrade:
* From version: Fusion `4.1.x`
* To version: Fusion `4.2.y`
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps.
For more information, see Fusion 4.x.
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/4.1.x/var/upgrade` directory (on Unix or MacOS) or the `C:\lucidworks\fusion\4.1.*x\var\upgrade\` directory (on Windows). The file names reference the versions you are upgrading from and to. For example:
* To upgrade `4.1.3` to `4.2.5`, the migrator uses the `4.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.
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 later, only a subset of [connectors](/docs/fusion-connectors/connectors/overview) are included by default.
The migrator detects which connectors were used in the older version of Fusion, and installs them automatically in Fusion `4.0.y`. This step requires an Internet connection. If no connection is available, then download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and install them as bootstrap plugins.
If a connector to be upgraded was not 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 are not upgraded.
#### If no Internet connection is available
If no Internet connection is available during an upgrade, the migrator cannot 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 connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) for all existing 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 are not in the old deployment).
Download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and place them in `apps/connectors/bootstrap-plugins` for the new version (on all Fusion nodes).
### Object migrations and transformations
The migrator automatically migrates these Fusion 4.1 object types, transforming them as needed:
* 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
In Fusion Server 4.0 and later, most objects exist in the context of apps. When you upgrade from Fusion Server 4.1.x to 4.2.y, the migrator upgrades app objects, all objects in or linked to objects in apps, and objects that are not linked to apps. You can explore the objects in [Object Explorer](/docs/4/fusion-server/concepts/object-explorer).
### Access control migration
The migrator upgrades all access control configurations:
* Security realms
* Roles
* Users
None of these should require adjustments after migration.
### Association of blobs with apps
The association of blobs with apps becomes stronger in Fusion Server 4.1.1. Newly created blobs are only linked to the app to which they are uploaded, and are only shared with other apps when the blobs are directly linked to those apps (added to the apps in [Object Explorer](/docs/4/fusion-server/concepts/object-explorer) or linked using the [Links API](/docs/4/fusion-server/reference/api/links-api)).
When migrating from pre-4.1.1 versions to 4.1.1 or later, the resulting apps might not contain all of the blobs that they contained prior to migration.
It is important to stress that this change *does not break the apps*.
What *might* change is the blobs that are linked to an app. This can be important if you export and re-import apps.
**Recommendation**: After migration from a pre-4.1.1 version to version 4.1.1 or later, we recommend that you use either Object Explorer or the Links API to manually link all blobs to the apps in which they are used.
## 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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your *current* 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.1.x/conf` directory.
### 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
**Perform these tasks *on all Fusion nodes*:**
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/fusion-server-4-x-file-download-links).
2. Extract the newer version of Fusion:
```bash theme={"dark"}
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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Unix](https://download.lucidworks.com/fusion-migrator.tar.gz). (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).
```bash theme={"dark"}
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:
```bash theme={"dark"}
export FUSION_OLD="/opt/lucidworks/fusion/4.1.3"
export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
```
3. Create this directory:
```bash theme={"dark"}
mkdir $FUSION_OLD/var/upgrade
```
4. Install the migrator:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
$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:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$FUSION_OLD/bin/zookeeper stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
After migration, you can find details about the results in the `fusion/4.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
**How 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`):
```bash theme={"dark"}
$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 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`.
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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your current 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.1.x\conf` directory.
### 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
Perform these tasks *on all Fusion nodes*:
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Windows](https://download.lucidworks.com/fusion-migrator.zip). (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:
```bash theme={"dark"}
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
**Perform these tasks on the indicated nodes:**
1. (*On all Fusion nodes*) Start all Fusion services for the old version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%FUSION_OLD%\bin\zookeeper.cmd stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start Solr for the new Fusion version:
```bash theme={"dark"}
%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):
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
Deleted old plugin blobs from solr
0
246
Old connector plugin blobs were deleted successfully.
```
11. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
After migration, you can find details about the results in the `+fusion\+4.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
**How to validate the new version of Fusion**
1. (*On all Fusion nodes*) Restart all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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 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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
## Introduction
This article describes how to perform the following upgrade:
* From version: Fusion `4.0.x`
* To version: Fusion `4.2.y`
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps.
For more information, see Fusion 4.x.
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/4.0.x/var/upgrade` directory (on Unix or MacOS) or the `C:\lucidworks\fusion\4.0.*x\var\upgrade\` directory (on Windows). The file names reference the versions you are upgrading from and to. For example:
* To upgrade `4.0.2` to `4.2.5`, the migrator uses the `4.0.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.
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 later, only a subset of [connectors](/docs/fusion-connectors/connectors/overview) are included by default.
The migrator detects which connectors were used in the older version of Fusion, and installs them automatically in Fusion `4.0.y`. This step requires an Internet connection. If no connection is available, then download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and install them as bootstrap plugins.
If a connector to be upgraded was not 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 are not upgraded.
#### If no Internet connection is available
If no Internet connection is available during an upgrade, the migrator cannot 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 connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) for all existing 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 are not in the old deployment).
Download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and place them in `apps/connectors/bootstrap-plugins` for the new version (on all Fusion nodes).
### Object migrations and transformations
The migrator automatically migrates these Fusion 4.0 object types, transforming them as needed:
* 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
In Fusion Server 4.0 and later, most objects exist in the context of apps. When you upgrade from Fusion Server 4.0.x to 4.2.y, the migrator upgrades app objects, all objects in or linked to objects in apps, and objects that are not linked to apps. You can explore the objects in [Object Explorer](/docs/4/fusion-server/concepts/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.
### Access control migration
The migrator upgrades all access control configurations:
* Security realms
* Roles
* Users
None of these should require adjustments after migration.
### Association of blobs with apps
The association of blobs with apps becomes stronger in Fusion Server 4.1.1. Newly created blobs are only linked to the app to which they are uploaded, and are only shared with other apps when the blobs are directly linked to those apps (added to the apps in [Object Explorer](/docs/4/fusion-server/concepts/object-explorer) or linked using the [Links API](/docs/4/fusion-server/reference/api/links-api)).
When migrating from pre-4.1.1 versions to 4.1.1 or later, the resulting apps might not contain all of the blobs that they contained prior to migration.
It is important to stress that this change *does not break the apps*.
What *might* change is the blobs that are linked to an app. This can be important if you export and re-import apps.
**Recommendation**: After migration from a pre-4.1.1 version to version 4.1.1 or later, we recommend that you use either Object Explorer or the Links API to manually link all blobs to the apps in which they are used.
## 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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your *current* 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.0.x/conf` directory.
### 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
**Perform these tasks *on all Fusion nodes*:**
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/fusion-server-4-x-file-download-links).
2. Extract the newer version of Fusion:
```bash theme={"dark"}
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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Unix](https://download.lucidworks.com/fusion-migrator.tar.gz). (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).
```bash theme={"dark"}
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:
```bash theme={"dark"}
export FUSION_OLD="/opt/lucidworks/fusion/4.0.2"
export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
```
3. Create this directory:
```bash theme={"dark"}
mkdir $FUSION_OLD/var/upgrade
```
4. Install the migrator:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
$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:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$FUSION_OLD/bin/zookeeper stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$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:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
$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:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
After migration, you can find details about the results in the `fusion/4.0.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
**How 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`):
```bash theme={"dark"}
$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 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`.
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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/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`)
* Proxy service (`proxy`)
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 is no special requirement as to which one you pick.
### Ensure that your current version of Fusion has a valid license
Ensure that your current 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.0.x\conf` directory.
### 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
**Perform these tasks *on all Fusion nodes*:**
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Windows](https://download.lucidworks.com/fusion-migrator.zip). (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:
```bash theme={"dark"}
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
**Perform these tasks on the indicated nodes:**
1. (*On all Fusion nodes*) Start all Fusion services for the old version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%FUSION_OLD%\bin\zookeeper.cmd stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
New Fusion Zookeeper import (--zookeeper-import) finished successfully.
```
9. (*On all Fusion nodes*) Start Solr for the new Fusion version:
```bash theme={"dark"}
%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):
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
Deleted old plugin blobs from solr
0
246
Old connector plugin blobs were deleted successfully.
```
11. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
After migration, you can find details about the results in the `+fusion\+4.0.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
**How to validate the new version of Fusion**
1. (*On all Fusion nodes*) Restart all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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 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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
## Introduction
This article describes how to perform the following upgrade:
* From version: Fusion `3.1.x`
* To version: Fusion `4.2.y`
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps.
For more information, see Fusion 4.x.
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.5`, 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.
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 later, only a subset of [connectors](/docs/fusion-connectors/connectors/overview) are included by default.
The migrator detects which connectors were used in the older version of Fusion, and installs them automatically in Fusion `4.0.y`. This step requires an Internet connection. If no connection is available, then download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) and install them as bootstrap plugins.
If a connector to be upgraded was not 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 are not upgraded.
#### If no Internet connection is available
If no Internet connection is available during an upgrade, the migrator cannot 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 connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) for all existing 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 are not in the old deployment).
Download the connectors from [Fusion 4.x Connector Downloads](/docs/fusion-connectors/downloads/fusion-4-x-connector-downloads) 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
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](/docs/4/fusion-server/concepts/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 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.
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 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
This section describes fully automatic parts of migration. You should not 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 do not need to do anything with it.
* It adds these permissions to the role `developer`:
```bash theme={"dark"}
GET:/license
GET,POST,PUT:/appkit
GET,POST,PUT:/apps/**
```
* Updates these permissions for the role `search`:
```bash theme={"dark"}
POST:/apps/*/signals/**
GET:/query/**
GET:/apps/*/query/**
POST:/signals/**
```
* Adds the role `webapps-role` with these permissions:
```bash theme={"dark"}
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.
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:
```bash theme={"dark"}
GET:/license
GET,POST,PUT:/appkit
GET,POST,PUT:/apps/**
```
* If you have created your own search roles, add these permissions to the roles:
```bash theme={"dark"}
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_NAME_signals` collections as `response` signals, instead of indexing them into the `COLLECTION_NAME_logs` collections.
Roughly 90 new fields used by App Insights are added to existing `COLLECTION_NAME_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. 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 will 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`)
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 is 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
**Perform these tasks *on all Fusion nodes*:**
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/fusion-server-4-x-file-download-links).
2. Extract the newer version of Fusion:
```bash theme={"dark"}
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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Unix](https://download.lucidworks.com/fusion-migrator.tar.gz). (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).
```bash theme={"dark"}
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:
```bash theme={"dark"}
export FUSION_OLD="/opt/lucidworks/fusion/3.1.5"
export FUSION_NEW="/opt/lucidworks/fusion/4.2.6"
```
3. Create this directory:
```bash theme={"dark"}
mkdir $FUSION_OLD/var/upgrade
```
4. Install the migrator:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
$FUSION_OLD/bin/ui stop
$FUSION_OLD/bin/connectors stop
$FUSION_OLD/bin/api stop
$FUSION_OLD/bin/solr stop
```
You can see what is running with `$FUSION_OLD/bin/fusion status`.
4\. (*Only on secondary Fusion nodes*) Prepare secondary nodes:
```bash wrap theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$FUSION_OLD/bin/zookeeper stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
$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):
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
Deleted old plugin blobs from solr
0
246
Old connector plugin blobs were deleted successfully.
```
11. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
$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:
```bash theme={"dark"}
java -jar $FUSION_OLD/var/upgrade/migrator.jar --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
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
**How 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`):
```bash theme={"dark"}
$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 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`.
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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/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 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 is 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](/docs/4/fusion-server/reference/system-requirements).
### Download and install the newer version of Fusion
Perform these tasks *on all Fusion nodes*:
1. Select the Fusion release to which you are upgrading from [Fusion Server 4.x File Download Links](/docs/4/fusion-server/reference/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](/docs/fusion-connectors/downloads/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](/docs/fusion-connectors/downloads/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
**Perform these tasks *on all Fusion nodes*:**
1. [Download the latest migrator zip file for Windows](https://download.lucidworks.com/fusion-migrator.zip). (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:
```bash theme={"dark"}
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
**Perform these tasks on the indicated nodes:**
1. (*On all Fusion nodes*) Start all Fusion services for the old version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --export
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
Old Fusion configuration export (--export) finished successfully.
```
3. (*On all Fusion nodes*) Stop the old versions of Fusion services and Solr; but not ZooKeeper:
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --prepare-secondary
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%FUSION_OLD%\bin\zookeeper.cmd stop
```
6. (*Only on the main Fusion node*) Transform configuration data on the main Fusion node:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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*):
```bash theme={"dark"}
%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:
```bash wrap theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --zookeeper-import
```
This message indicates that the step finished successfully:
```bash wrap theme={"dark"}
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:
```bash theme={"dark"}
%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):
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
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:
```bash wrap theme={"dark"}
Deleted old plugin blobs from solr
0
246
Old connector plugin blobs were deleted successfully.
```
11. (*On all Fusion nodes*) Start all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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:
```bash theme={"dark"}
java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" --fusion-import
```
This message indicates that the step finished successfully:
```bash theme={"dark"}
New Fusion object import (--fusion-import) finished successfully.
```
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
**How to validate the new version of Fusion**
1. (*On all Fusion nodes*) Restart all Fusion services for the new version of Fusion:
```bash theme={"dark"}
%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 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.
**How 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** > **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.
**How to import business rule objects**
1. Create an `app-name.txt` file with the following content:
```json theme={"dark"}
{"app.id" : "_name-of-migrated-app_"}
```
For example, for the app `Lucene Revolution`:
```json theme={"dark"}
{"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:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
For example:
```bash wrap theme={"dark"}
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:///api/objects/import?importPolicy=merge"
```
## Deprecations and Removals
Every Fusion release adds or improves Fusion features and functionality. Occasionally, we also remove features and functionality. Before doing so, we “deprecate” them. Deprecated features are no longer officially supported by Lucidworks and will not be updated or maintained. In many cases, new features are introduced which replace and/or improve the functionality of the deprecated feature.
See [Deprecations and Removals](/docs/4/fusion-server/release-notes/deprecations-and-removals) for a list of active deprecations and removals.
How long do I have before the feature is removed?
We give a minimum of one minor release cycle before removing a deprecated feature. For example:
* A feature is deprecated in Fusion 4.1.0, so it will not be removed before Fusion 4.2.0
* A feature is deprecated in Fusion 4.1.1, so it will not be removed before Fusion 4.2.0
Deprecations are typically made in major and minor releases only. Maintenance release deprecations are less common.
## Learn more
Beginning with Fusion 3.1, upgrading Fusion uses a migrator that migrates objects and data from your current version of Fusion to a new version of Fusion or Fusion Server.
The Fusion migrator [log file](#log-file) will help you troubleshoot difficulties while upgrading. If the migrator fails to complete successfully, we explain how to [correct problems and repeat an upgrade](#restarting-an-upgrade).
[Known issues](#known-issues), and workarounds if available, are listed at the bottom of this topic.
## Log file
The log file for the migrator is in:
* `/opt/lucidworks/fusion/_x_._y_._z_/var/upgrade/tmp/migrator.log` (on Unix)
* `C:\lucidworks\var\fusion\_x_._y_._z_\upgrade\tmp\migrator.log` (on Windows).
The `_x_._y_._z_` directory is for the Fusion version that you are migrating *from*.
## Completing an upgrade after an error
If the migrator script produces an error, you will need to correct the problem that the script encountered, and then finish the upgrade as explained here.
### 1. Fix the error
If an upgrade step fails:
1. Examine the [log file](#log-file) and determine what went wrong.
2. Fix what went wrong.
### 2. Repeat the step that failed
After you have fixed the source of the error, repeat the step that failed.
You can repeat the step that failed as many times as needed to correct errors that occur. If the step continues to fail, [restart the upgrade from the beginning](#restarting-an-upgrade).
### 3. Complete the upgrade
Complete the upgrade.
If a *different* step fails, fix that error, repeat that step, and then perform the remainder of the upgrade procedure.
If the upgrade steps produce no additional errors, then you are finished.
### Restarting an upgrade
If an upgrade step continues to fail, then restart the upgrade process from the beginning:
1. Examine the [log file](#log-file) and determine what went wrong.
2. Remove the directory for the new version of Fusion.
3. Reinstall the new version of Fusion, but do not start it.
4. Fix what went wrong.
5. Perform the entire upgrade procedure from the beginning.
## Known issues
Following are known issues with the Fusion migrator.
### 3.1.x to 4.0.y, 4.1.y, and 4.2.y
#### Details
Apps function fine without these links. You only need to create links if you want the JDBC blobs to be visible under the **In Current App** tab in Object Explorer.
#### Actions
After migration, link JDBC blobs to apps manually using either the Fusion UI or the Fusion API.
**Fusion UI**\
Repeat for all apps and all JDBC blobs in each app:
1. In Object Explorer, locate a JDBC blob under **In Any App** or **In No Apps**.
2. Hover over the object, click the App icon, and then click **Add to this app**. 
**Fusion API**
1. Find the blob IDs of JDBC blobs:
```bash wrap theme={"dark"}
curl -u USERNAME:PASSWORD "http://localhost:8764/api/blobs?resourceType=driver:jdbc"
```
2. Repeat for all JDBC blobs. To link a JDBC blob to all apps, run:
```bash theme={"dark"}
curl -u USERNAME:PASSWORD -H "Content-Type:application/json" \
-X PUT -d '{ "subject" : "group:_shared", "object" : "blob:{jdbc-blob-id}", "linkType" : "hasPart", "originator" : "migration" }' \
"http://localhost:8764/api/links"
```
### All upgrades except for 3.1.x to 3.1.y
#### Details
The `managed-schema` data in the Solr configuration cannot exceed 1 MB in size.
This is an example of a failure message:
```text theme={"dark"}
2018-05-07T19:31:00,056 - ERROR
[main:ZKImportExportComponent@276]
- Error writing data to ZK
org.apache.zookeeper.
KeeperException$ConnectionLossException:
KeeperErrorCode = ConnectionLoss for
/lwfusion/3.1.5/solr/configs/rh/managed-schema
```
#### Actions
Remove unneeded elements from the schema, and then restart the upgrade from the beginning.
### 3.1.x and 4.0.x to 4.1.y and 4.2.y
#### Details
Migrated signal-aggregation jobs retain their schedules (by design). To avoid job timeouts, the default schedule for signal-aggregation jobs was increased from every two minutes to every 15 minutes in Fusion 4.1.0.
#### Actions
After migration, consider manually changing the schedule of signal-aggregation jobs to 15 minutes.