Skip to end of metadata
Go to start of metadata

Upgrading Flux allows you take advantage of the latest improvements, bug fixes, and new features that Flux has to offer. We recommend always running Flux on the newest version possible, both to take advantage of the increase stability offered as new bug fixes are added, and to provide easier to new features in the future (the more up-to-date your Flux installation is, the easier it will be to upgrade to newer versions of Flux down the line).

This guide documents the steps required to upgrade your Flux installation.

If you're upgrading from a prior release of Flux 8.0 (drop-in replacement of flux.jar, flux.war files) please review our Upgrade Notes related to the Sigar library for this release to complete the upgrade


Changes from Releases Prior to Flux 8

  • BPM support removed.
  • Supervisor() APIs removed from
  • Desktop designer removed.
  • RMI (1099) replaced with HTTPS (7520) for remote communication.
    • Configurations removed: createRegistry, registryPort, rmiPort, rmiServer, serverName
    • Configurations added: port, server, ssl
    • flux.Control, flux.NonStreamable, flux.Transactable APIs merged with flux.Engine API.
  • EngineHelper is a static helper utility. Used directly without creating from Factory.
  • BusinessInterval stored in repository.
  • setActiveWindow(aBusinessInterval) has been deprecated and replaced with setActiveWindowNamespace(aBusinessIntervalNamespaceInTheRepository).
  • RemoteSecurity and LocalSecurity concepts are merged to Engine interface.
  •      engine.login("admin", "admin");
  • flux.transform APIs removed.
  • flux.xml APIs removed.
  • flux.Cluster API removed.
  • SubFlowChartAction removed. Added support to update existing SubFlowChartAction to a FlowChartAction.
  • CacheType.NETWORKED removed.
  • File API Changes.
    • ForEachDelimitedTextFileAction, ForEachFileAction, SimpleFileSource, ZipFileCriteria APIs removed.
    • FileCriteriaPair replaced with IncludesFileCriteria, SingleFileCriteria, TargetFileCriteria, RenameableDoubleFileParameter.
  • Agents do not require a port. Agents poll Engine for tasks.
    • Agent pool property removed from ProcessAction. Moved to a super-interface AgentAction.
    • In 8.0, FileCopyAction, FileExistTrigger, FileMoveAction can be executed on an Agent in addition to ProcessAction.
  • DB schema changes:
    • Cluster table changes: Removed BIND_NAME column and added IS_SSL column.

Getting Started

To install your Flux upgrade, you will first need a little information about your existing Flux environment and the version you plan to upgrade to.

To different between version numbers, each Flux release has three identifiers: the major version, the minor version, and the maintenance version. These are arranged like so:

Flux <major version>.<minor version>.<maintenance version>

For example, your Flux version may be "Flux 7.9.13", "Flux 7.8.4", or similar.

There are two types of Flux upgrades:

  • Major or minor upgrades. These upgrades contain considerable changes from previous Flux versions (UI updates or major functionality changes) and may require database schema changes, API changes, or engine configuration changes.
  • Maintenance upgrades. These upgrades only contain bug fixes and minor improvements. Maintenance upgrades do not require database schema changes, API changes, or engine configuration changes.

If your existing Flux installation and the version you are upgrading to share both a major and minor version, but the maintenance version is different, then this is a maintenance upgrade. Follow the maintenance upgrade instructions below to upgrade your Flux installation.

If your existing Flux installation and the version you are upgrading to have a different major or minor version, this is a major or minor upgrade. Follow the major or minor upgrade instructions below to upgrade your Flux installation.

Maintenance Upgrades

To install a maintenance upgrade:

0. Backup your existing environment prior to upgrading. Make sure you backup the existing flux.jar, flux.war, the contents of the /lib folder, any batch or shell scripts (*.bat and *.sh), the service configuration files in <flux_home>/service, and your Flux license key. Also create a backup of your Flux database.



The database schema for the FLUX_CLUSTER table has been modified. A new column named SCHEDULING has been added to improve the performance of Flux scheduling. Update scripts for each database (except Derby) are located in the docs directory. Apply the appropriate update script to your database before updating Flux.

To update an existing Derby database, do the following:

  • Make sure the Flux engine is stopped before performing this update.
  • Download and extract the Derby database utility from Download the version.
  • Extract the zip file into a directory, e.g., derby. Open a command line and change into the bin directory, (e.g., cd /derby/bin).
  • From the command line, enter the command ij. This will start the interactive Derby command utility.
  • from ij> enter the command connect 'jdbc:derby:/<YourFluxInstallationDirectory>/derbydb'; This will connect to the Flux Derby database.
  • from ij> enter the command EXIT;
  • You may now start your Flux engine.
  • The upgrade scripts for other database are provided below.

This new column can be left in the Flux database even if you need to fall back to a prior release of Flux 8.


  1. Shut down any engine and Operations Console instances that are running.
  2. Download and extract the new Flux version from the Flux Support Portal. Download the .zip version of the release from 
  3. Unzip the downloaded zip file to a temporary directory.
  4. Delete the directory named 'flux' in the existing Flux webapps directory.
  5. Copy the flux.jar and flux.war files from the new release over your existing ones (i.e., <flux home>/flux.jar and <flux home>/webapp/flux.war).
  6. Copy all of the files from the <flux directory>/lib folder of the new release into the <flux home>/lib folder of the existing installation. Select "Yes" if prompted to replace any existing files.
  7. [If this is not an evaluation version of Flux] Ensure your Flux license key file is in the <flux home> directory and run the configure script located there to install the Flux license key.
  8. If you run Flux using the provided .bat or .sh scripts, backup all your scripts before starting. This is only necessary if any changes were introduced, such as bumping up the JVM memory, setting a custom classpath or any other system property. Once that's done, place all the .bat / .sh files from the new version in <flux home>.
  9. If you run Flux using the Windows services, backup all your service configuration files before placing the copies from the new version in <flux home>/service/windows .
  10. Restart your engine(s) and web application(s).
  11. Edit the fluxConfig.js file in <flux home>/webapps/javascript/mx to match your engine and opsconsole host names and ports.
  12. Clear your browser cache and access the Flux Operations Console or Flux Cockpit.

That's it! Your new Flux version is now installed and ready to run.

Major or Minor Upgrades

To upgrade to Flux 8.0, you must be using a 7.11.x release. If you're using Flux 7.9, go to Upgrading Flux 7.9 to Flux 7.11.

If you are not sure which Flux release you are using or you need assistance upgrading to Flux 7.11, contact for more information.

If you are running Flux 8.0, first download the Flux converter tool using this link:

Once you have downloaded the tool, unzip the archive to a new folder, then follow the instructions below (for your convenience, these instructions are also included in the README.txt contained in the tool's home directory).

Actions Removed in Flux 8.0

Review the information below before upgrading. This information and accompanying table contains important information about actions that have been removed in Flux 8.0.

The following table contains a list of all actions that have been removed in Flux 8.0, as well as the suggested replacement for each:

Sub Flow Chart ActionFlow Chart Action
File Transform ActionNo equivalent action in Flux 8.0
For Each File Action

File Exist Trigger + For Each Collection Element Action

For Each Delimited Text File ActionRegular Expression Action
Business Process TriggerNo equivalent trigger in Flux 8.0. Flux 8.0 no longer supports BPM functionality.
Cognos ActionNo equivalent action in Flux 8.0

If any of your workflows contain one or more of these actions, it will not be possibly to complete the upgrade process until the workflows have been updated (in Flux 7.11) to remove the actions. This can usually be accomplished by replacing these actions with their suggested alternative in the table above, typically using the same settings as the existing action. For questions or assistance in redesigning your workflows, contact

Flux 7.11 and 8.0 License Keys Required

You will need your Flux 7.11 and Flux 8.0 license keys for this upgrade. If you do not have these license keys, you can request them by mailing

To complete the Flux 7.11 to Flux 8.0 migration:

  1. Unzip the migration zip file to a directory. Save your Flux 7.11 and 8.0 license keys to this directory.
  2. Add/update your Flux database / data source configuration information to the file, using the included default settings as a template.
  3. Add your JDBC driver and any custom classes (custom actions, triggers, or action listener classes, and any additional classes your workflows depend on) to the classpath variable in export.bat (Windows) or (*nix).
  4. Copy flux.jar from your Flux 7.11 directory to this directory and rename it to flux711.jar.
  5. Open a command prompt and run the following command (replace "admin admin" with the username and password for your Flux 7.11 installation and, if you are using a *nix system, replace "export.bat" with ""):

    export.bat admin admin

    This script outputs the Flux 7.11 workflows to 2 directories: jobs and repository.

  6. [If any of your workflows contain custom actions or Java Actions] Migrate your Flux 7.11 workflow code to Flux 8.0 by compiling it against the Flux 8.0 JAR file. You may need to modify the code for deprecated or removed APIs (see the JDIFF documentation at for a complete accounting of these APIs). This includes not only custom code used in Java actions, but any code that uses Flux's APIs (custom actions, code used for running Flux and exporting workflows, etc.).
  7. Create a new set of tables for Flux 8.0, following the instructions in Configuring Flux to run with Databases. If your Flux 8.0 installation will use the same database as your previous 7.11 instance, make sure to modify the .sql script to change the table prefix (You can simply replace all occurrences of "FLUX_" with any value you choose).
  8. Add/update your Flux database / data source configuration information to the file, using the included default settings as a template
  9. [If you chose a new table prefix in step 7] Add the line "TABLE_PREFIX=MY_TABLE_PREFIX_" to, where "MY_TABLE_PREFIX_" is the new table prefix you chose. Once the migration is complete, copy this configuration setting to your final Flux 8.0 engine configuration as well – you'll need this to allow your Flux 8.0 engine to start correctly.
  10. Copy flux.jar from your Flux 8.0 directory to this directory. Repeat step 3 for import.bat (Windows) or (*nix), making sure to use any updated classes or JARs you generated in step 6. Since the import needs to run on a local engine, comment out the following line in the engine configuration file you are using for the import like so:


    If you're using the built-in Derby database, make sure to delete the 'derbydb' folder that is created upon export inside the Flux converter tool folder.

  11. Open a command prompt and run the following command (this time, make sure not to edit "admin admin", as these will be the default settings for your Flux 8.0 install – if you are using a *nix system, replace "export.bat" with ""):

    import.bat admin admin

    This will import all of your running workflows and your repository from the Flux 7.11 installation.

    Congratulations! You have successfully upgraded to Flux 8.0.

Software Developers

API-level changes may be introduced in major / minor Flux versions. These API changes may cause errors like the following to appear after performing a major or minor upgrade, if code is executed without recompiling against the newer Flux version:

java.lang.IncompatibleClassChangeError: Found class flux.Configuration, but interface was expected

To avoid these errors, be sure to recompile all code that uses Flux libraries after each major or minor upgrade.

  • No labels


  1. Anonymous

    The Flux converter tool is ok, but it cleans the database, so if you have workflows with the "run as user" option, they don't work because the Flux converter tool when cleans the database also remove the users.

    1. Hello,

      The "Run As User" option is preserved within the workflow XML and should be maintained when running the converter tool.

      If you are seeing this value cleared, could you email a copy of the XML to so we can further investigate why this occurs for you?

      Kind regards,


  2. Anonymous

    Hi Nick,

    That is correct, the "Run As User" option is preserved if the users already exists in the database, but if they don't an error appears:

    Importing workflows from jobs.ffc
    The flow chart "/ASDF" failed to import.
    Reason The value of the "Run As User" property of this workflow, "user_asdf", does not exist in the Flux user database. Either change the property to correspond to an existing user, or add this user to the Flux user database.

    To correct this is easy to create the users and re execute the procedure, but sadly the import procedure cleans the database before importing the xml. I was hurry so I decompile and the "toeight-1.0.jar" and modifiy the "" in the line 192 where the Flux converter tool cleans in the pre processing:

    protected void preProcessing(Engine engine)
    throws Exception
    System.out.println("Stopping engine.");
    System.out.println("Clearing engine.");

    Corrected this line, I recreate the users and the import process was flawless.


    1. Thank you for clarifying! I've filed an improvement request to have this updated for future use. I'm glad to hear you were able to find a workaround.

      We'll update this comment when that fix is available!

      Kind regards,