This guide gives an introduction to Fluxnova Run, a pre-packaged, lightweight distribution of Fluxnova. Fluxnova Run is easy to configure and does not require Java knowledge.

Prerequisites and audience

To use this guide, you should at least know what Fluxnova is and what it does. Check out the Get Started guides if you have never used Fluxnova before. The Installation guide is also worth looking at if you are completely new to Fluxnova.

This guide will teach you about Fluxnova Run and how to configure it. It can serve as a reference page for configuration and operation options. It will not give you a step-by-step guide on how to install Fluxnova Run. Head over to the Installation guide for details on how to install and start Fluxnova Run.

What is Fluxnova Run?

Fluxnova Run is a full distribution of Fluxnova. It includes:

• Fluxnova web applications
  • Cockpit
  • Tasklist
  • Admin
• REST API
• An example application

Starting with Fluxnova Run

To start with Fluxnova Run, download the distribution (enterprise) and unpacking it. You will find the following structure:

fluxnova-bpm-run
├── configuration/
│   ├── keystore/
│   │   └── put your SSL key store here if you want to use HTTPS
│   ├── resources/
│   │   └── put your BPMN files, forms and scripts here
│   ├── sql/
│   │   └── necessary SQL scripts to prepare your database system
│   ├── userlib/
│   │   └── put your database driver and other required JARs here
│   ├── default.yml
│   └── production.yml
├── internal/
├── start.bat
└── start.sh
└── shutdown.sh
└── shutdown.bat

Execute one of the two start scripts (start.bat for Windows, start.sh for Linux/Mac). After a few seconds, you can access the Fluxnova web apps via http://localhost:8080/fluxnova/app/, the REST API via http://localhost:8080/engine-rest/.

When executing one of the two start scripts without any arguments, Fluxnova Run will start with a default configuration as a detached process. To shut down Fluxnova Run in “detached” mode, use one of the two shutdown scripts (shutdown.bat for Windows, shutdown.sh for Linux/Mac).

By explicitly passing arguments to one of the two Fluxnova Run start scripts, the default detached mode is disabled and you can configure Fluxnova Run according to your needs. Furthermore, Fluxnova Run will start as a foreground process unless the --detached argument is explicitly passed to the start.bat or start.sh script.

Start script arguments

The start scripts (start.bat for Windows, start.sh for Linux/Mac) accept the following arguments:

Starting Fluxnova Run using Docker

Fluxnova Run is also available as a prebuilt Docker image. Please see the Fluxnova Docker documentation here for instructions on how to pull and start it.

Optional components

By default, Fluxnova Run launches with the web apps, REST API and example modules. If you want to enable only a subset of them, execute the start script through a command-line interface with any of the --webapps, --rest or --example properties to enable the specific modules.

Example application

By default, Fluxnova Run deploys and launches an example application on startup. When launched, this application creates deployments with multiple BPMN and DMN definitions as well as form resources and starts instances of the defined processes.

You can disable the deployment of the example application itself by enabling any combination of the other modules with the --webapps and --rest properties of the start script. That way, the example application will not be launched and its resources will not be present on the classpath of Fluxnova Run.

You can also disable the launch of the example application by setting the application property fluxnova.bpm.run.example.enabled to false or removing it from the application properties. That way, the example application and its resources will be present on the classpath of Fluxnova Run. However, the example application will not be started.

Disabling the example application with any of those mechanisms will NOT delete any deployments or process instances from Fluxnova Run once they are created. You have to delete this data manually through the web apps, the REST API, or by cleaning the database configured in the application properties.

Choose between default and production configuration

Fluxnova Run ships with two different configuration files which are both located in the configuration folder.

• The default.yml configuration only contains necessary configuration like the H2 database, a demo user and CORS for REST calls from a client application.
• The production.yml configuration is intended to provide the recommended properties according to the Security Instructions. When using Fluxnova Run in a production environment, make sure to base your custom configuration on this one and carefully read through the security instructions.

By default, Run launches with the default.yml configuration. To enable the production.yml configuration, execute the start script with the --production property. Using --production disables the example application. It can be enabled by explicitly passing --example to the start script. However, we do not recommended to use the example application in production.

Connect to a Database

Fluxnova Run is pre-configured to use a file-based H2 database for testing. The database schema and all required tables are automatically created when the engine starts up for the first time. If you want to use a custom standalone database, follow these steps:

1. Make sure your database is among the supported database systems.
2. Create a database schema for Fluxnova yourself.
3. Install the database schema to create all required tables and default indices using our database schema installation guide.
4. Drop a JDBC driver jar for your database system in the configuration/userlib folder.
5. Add the JDBC URL and login credentials to the configuration file like described below.
6. Restart Fluxnova Run

Deploy BPMN Models

In the unpacked distro, you will find a resources folder. All files (including BPMN, DMN, CMMN, form, and script files) will be deployed when you start Fluxnova Run.

You can reference forms and scripts in the BPMN diagram with embedded:deployment:/my-form.html, fluxnova-forms:deployment:/myform.form, or deployment:/my-script.js. The deployment requires adding an extra / as a prefix to the filename.

Deployments via the REST API are still possible.

Configure Fluxnova Run

Just like all the other distros, you can tailor Fluxnova Run to your needs. To do this, you only have to edit one of the configuration files that you can find in the configuration folder.

Database

The distro comes with a file-based h2 database for testing. It is recommended to connect to a standalone database system for use in production.

Authentication

To add authentication to requests against the REST API, you can enable authentication at runtime, without having to rebuild Fluxnova Run. Both basic and JWT/OIDC authentication are supported, and you select between them with the fluxnova.bpm.run.auth.authentication property.

Basic Authentication

With basic authentication, requests are authenticated against the configured identity source, for example the built-in admin user:

fluxnova:
  bpm:
    run:
      auth:
        enabled: true
        authentication: basic

Basic authentication has no additional required dependencies.

JWT Authentication

With jwt authentication, incoming requests are authenticated using a bearer token validated against an OIDC-compliant identity provider (for example Microsoft Entra ID/Azure AD, Okta, or Keycloak).

fluxnova:
  bpm:
    run:
      auth:
        enabled: true
        authentication: jwt
    jwt:
      jwks-url: https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys
      issuer: https://login.microsoftonline.com/<tenant>/v2.0
      audience: api://your-client-id

The nimbus-jose-jwt library, required for JWT token validation, is only pulled in when JWT authentication is used; it remains an optional dependency otherwise.

The same fluxnova.bpm.jwt.* properties and JWT support are also available for Spring Boot applications using the fluxnova-bpm-spring-boot-starter-rest starter, where authentication is instead configured with fluxnova.bpm.auth.enabled and fluxnova.bpm.auth.type. See the REST API documentation for details.

Cross-Origin Resource Sharing

If you want to allow cross-origin requests to the REST API, you need to enable CORS.

REST

Fluxnova Run can be configured to disable the REST endpoint which exposes the WADL file via a property.

Deployment

Fluxnova Run also supports configuration options for customizing the deployment.

LDAP Identity Service

Fluxnova can manage users and authorizations on its own, but if you want to use an existing LDAP authentication database you can enable the LDAP Identity Service Plugin which provides read-only access to the LDAP repository.

Find all available configuration properties in the LDAP Plugin Guide

LDAP Administrator Authorization

You can also use the Administrator Authorization plugin to ensure the appropriate LDAP user or group gains administrative access. Review all the available configuration options in the Administrator Authorization plugin section of our documentation.

In the table below, observe the Fluxnova Run-specific properties for the Administrator Authorization plugin.

Plugin registration

Fluxnova Run supports two types of plugins.

• Process engine plugins can be used to extend the process engine configuration to add more functionality.
• Webapp plugins are used to extend one of the Fluxnova webapps (i.e. Cockpit, Tasklist, Admin, Welcome).

Both types of plugins are supported in Fluxnova Run but have to be registered differently.

Process engine plugin registration

Fluxnova provides a process engine plugin mechanism to enable users to add and adjust process engine features by extending the process engine configuration. You can use plugins developed by Fluxnova, or by third-party developers.

Get more details on how process engine plugins work on the dedicated process engine plugins documentation section.

In the table below, observe the Fluxnova Run-specific properties for registering process engine plugins.

Perform the following steps in Fluxnova Run to register process engine plugins:

1. Find and read the process engine plugin documentation.

• Find the canonical name of the process engine plugin Java class that implements the ProcessEnginePlugin interface.
• Find out if the process engine plugin provides any configuration parameters. You will be able to configure your plugin using those parameters. If the plugin does not provide any properties, skip this step.

1. Download the process engine plugin .jar file and place it to the ${RUN_HOME}/configuration/userlib/ directory.
2. In your Fluxnova Run configuration file, add the process engine plugin class and any configuration parameters as list items under the process-engine-plugins YAML property.

Once complete, your YAML configuration file should look similar to the following:

  fluxnova.bpm.run.process-engine-plugins:
    - plugin-class: canonical.name.of.the.PluginClass

Example process engine plugin registration

Let’s say that you want to register a process engine plugin called TestPlugin. The following information is available:

• The plugin is provided in a .jar archive called fluxnova-bpm-test-plugin.jar.
• The name of the Java class that implements the ProcessEnginePlugin interface is TestPlugin. The canonical name of this class is org.finos.fluxnova.bpm.run.test.plugins.TestPlugin.
• The TestPlugin exposes the following two configuration parameters:
  • parameterOne - a String value
  • parameterTwo - a Boolean value

We’ll take the following steps:

1. Place the fluxnova-bpm-test-first-plugin.jar archive in the ${RUN_HOME}/configuration/userlib/ directory.

2. Add the following content to your Fluxnova Run YAML configuration file.

fluxnova.bpm.run.process-engine-plugins:
  - plugin-class: org.finos.fluxnova.bpm.run.test.plugins.TestPlugin
    plugin-parameters:
      parameterOne: valueOne
      parameterTwo: true

In the example above, we use the TestPlugin canonical name as a YAML key. The YAML value consists of a collection of key-value pairs that represent the configuration parameters for the TestPlugin and their values. Some process engine plugins don’t have configuration parameters. For these, you only need to define the plugin-class YAML property, like so:

fluxnova.bpm.run.process-engine-plugins:
  - plugin-class: org.finos.fluxnova.bpm.run.test.plugins.TestPlugin
  - plugin-class: org.finos.fluxnova.bpm.run.test.plugins.AnotherPlugin

3. Start Fluxnova Run. The TestPlugin will be read from the YAML configuration and registered with the process engine.

Webapp plugin registration

Fluxnova provides a mechanism to extend the Fluxnova Webapps with your own functionality. You can add plugins at various plugin points. For example, the processes dashboard in Cockpit.

A webapp plugin is a maven jar project that provides a server-side and a client-side extension to the webapp. You can find more information about how to structure your plugins here.

To register a webapp plugin, simply drop the jar file into the configuration/userlib folder. See the Starting with Fluxnova Run section of this guide to find out how to navigate the directories of Fluxnova Run.

Example application launch

Fluxnova Run comes with a demo application that deploys resources and starts process instances. You can disable the start of that application so it does not create deployments and process instances. The resources of the application are however still accessible on the classpath of Fluxnova Run. Consult the example application section for further details.

HTTPS

Fluxnova Run supports HTTPS over SSL. To enable it, you will need a valid SSL certificate signed by a trusted provider and stored in a key store file (either .jks or .p12). For testing, we included a self-signed certificate. You should not use this in production. To enable it, add the following properties to your configuration file.

server:
  ssl:
    key-store: classpath:keystore.p12
    key-store-password: fluxnova
    key-store-type: pkcs12
    key-alias: fluxnova
    key-password: fluxnova
  port: 8443

After starting Fluxnova Run, you can access the webapps via https://localhost:8443/fluxnova/app/ and the REST API via https://localhost:8443/engine-rest/.

Logging

Fluxnova provides fine-grained and customizable logging. An overview of the available logging categories can be found in the Logging User Guide. To configure the logging behavior in Fluxnova Run, customize your configuration file with the following properties.

For more information on logging configuration visit the Spring Boot Logging Guide.