-
Notifications
You must be signed in to change notification settings - Fork 39
Configuration
Dima Osipov edited this page Oct 10, 2024
·
48 revisions
nFlow is mainly configured through Spring properties. The default values can be overridden by means provided by Spring Framework: e.g. redefine a property in your own PropertySource or in system properties (-Dname=value).
Properties whose name ends to .ms define milliseconds. The default value is in parenthesis after the property name.
| Property name | Description |
|---|---|
| nflow.executor.group (nflow) |
nFlow Instances that process same workflows have same executor group name. |
| nflow.dispatcher.sleep.ms (1000) |
Polling frequency for new workflow activations, when no new activations are found |
| nflow.db.driver (autoselect between h2, mysql or postgresql DataSource) |
Fully qualified class name of datasource |
| nflow.db.url (autoselect between jdbc: h2:mem:test mysql://localhost/nflow postgresql://localhost/nflow sqlserver://localhost;databaseName=nflow oracle:thin:@//localhost:1521/XE db2://localhost:50000/nflow mariadb://localhost/nflow) |
nFlow database JDBC URL |
| nflow.db.user (sa) |
nFlow database user |
| nflow.db.password (empty) |
nFlow database user password |
| nflow.db.max_pool_size (4) |
Maximum size of database connection pool |
| nflow.db.create_on_startup (true) |
Automatically create missing database structures (note: cannot manage nflow version updates) |
| nflow.db.disable_batch_updates (false) |
Disables batch updates even if they are supported by the database thus degrading performance. Needed to be set to true especially when using Galera to make sure it notices deadlocks reliably. |
| nflow.non_spring_workflows_filename (empty) |
Filename in classpath that contains fully qualified class name of non-Spring bean WorkflowDefinitions |
| nflow.executor.thread.count (2 x number of CPU cores) |
Maximum amount of concurrent nFlow execution threads |
| nflow.workflow.instance.query.max.results (10000) |
Maximum number of workflow instances to be returned by the workflow instance query. The maxResults parameter value provided by user will be limited to this value. |
| nflow.workflow.instance.query.max.results.default (100) |
The maximum number of workflow instances to be returned when the user does not provide the maxResults parameter for the workflow instance query. |
| nflow.workflow.instance.query.max.actions (10000) |
Maximum number of actions to be returned for workflow instance. The maxActions parameter value provided by user will be limited to this value. |
| nflow.workflow.instance.query.max.actions.default (100) |
The maximum number of actions to be returned when the user does not provide the maxActions parameter. |
| nflow.dispatcher.await.termination.seconds (60) |
Time to wait for dispatcher to terminate gracefully on shutdown before interrupting it. |
| nflow.dispatcher.executor.queue.size (2 x nflow.executor.thread.count) |
Workflow dispatcher queue size. |
| nflow.dispatcher.executor.queue.wait_until_threshold (nflow.dispatcher.executor.queue.size / 2) |
The dispatcher will wait as long as the queue size is above this limit before dispatching more workflows to be processed. |
| nflow.dispatcher.executor.thread.keepalive.seconds (0) |
The time before idle executor threads are terminated from the pool. 0 means that the threads are never terminated. |
| nflow.autoinit (true) |
Controls whether workflow definitions should be stored to the database when they are registered (nflow.autoinit=true) or when the dispatcher is started (nflow.autoinit=false). This setting has no effect when nflow.definition.persist=false. |
| nflow.autostart (true) |
Controls whether the workflow dispatcher is automatically started when the Spring application starts up. |
| nflow.executor.timeout.seconds (900) |
The time after which the executor is considered as terminated unless it updates it's active timestamp in the database. If the timeout happens, other executors in the same executor group can start recovering the workflow instances of the terminated executor. |
| nflow.executor.keepalive.seconds (60) |
Interval of executor activity updates to the database. This defines the minimum value, the actual interval may be longer depending on how long it takes to dispatch the workflows for processing from the database. |
| nflow.executor.stuckThreadThreshold.seconds (60) |
The time after which a stack trace is logged for executor threads that may be stuck, e.g. when executor has been processing the same workflow state method. The number of potentially stuck executor threads is also logged. |
| nflow.db.h2.tcp.port (8043) |
Server port for the H2 database. |
| nflow.db.h2.console.port (8044) |
Port for the H2 database console. |
| nflow.db.idle_timeout_seconds (600) |
Database connection pool idle timeout. |
| nflow.definition.persist (true) |
True if workflow definitions should be stored to the database when they are registered (nflow.autoinit=true) or when the dispatcher is started (nflow.autoinit=false). |
| nflow.illegal.state.change.action (log) |
Action to take when executing a state change that has not been explicitly permitted for the workflow. Value can be "ignore" (do nothing), "log" (default, log a warning) or "fail" (move workflow instance to error state). |
| nflow.unknown.workflow.type.retry.delay.minutes (60) |
Time to wait in minutes until trying to retry a workflow that has an unknown type. |
| nflow.unknown.workflow.state.retry.delay.minutes (60) |
Time to wait in minutes until trying to retry a workflow that is in unknown state. |
| nflow.executor.stateSaveRetryDelay.seconds (60) |
Retry delay after failure in new workflow instance state saving |
| nflow.executor.stateVariableValueTooLongRetryDelay.minutes (60) |
Retry delay after failing to save too long state variable value to database, when not handled by the state method. Added in 6.1.0. |
| nflow.db.workflowInstanceType.cacheSize (10000) |
Cache size for mapping workflow instance id to workflow type. Added in 6.2.0. |
| nflow.executor.fetchChildWorkflowIds (true) |
If set to false, executor will not read child workflow IDs from database when starting to process a workflow instance. Reading child workflow IDs is usually unnecessary and setting this to false will increase performance, default is true for backwards compatibility only. Child workflows can be accessed when needed with via StateExecution methods. Added in 6.2.0, will be removed in 7.0.0. |
| nflow.maintenance.insertWorkflowIfMissing (true) |
Insert default MaintenanceWorkflow to nFlow database on startup if it does not already exist. Added in 7.0.0. |
| nflow.maintenance.initial.cron (4 4 4 * * *) |
Default cron schedule for default MaintenanceWorkflow. After the MaintenanceWorkflow instance has been added to the database, changing this has no effect. Change the value of state variable "cron" to change the scheduling. Added in 7.0.0. |
| nflow.maintenance.initial.delete.olderThan | Default time period (in ISO8601 format) after which passive workflow instances should be deleted from the production tables. After the MaintenanceWorkflow instance has been added to the database, changing this has no effect. Change the value of state variable "config" to change the configuration. Added in 7.0.0. |
| nflow.maintenance.initial.archive.olderThan (P45D) |
Default time period (in ISO8601 format) after which passive workflow instances should be archived. After the MaintenanceWorkflow instance has been added to the database, changing this has no effect. Change the value of state variable "config" to change the configuration. Added in 7.0.0. |
| nflow.maintenance.initial.deleteArchived.olderThan (P1Y) |
Default time period (in ISO8601 format) after which passive workflow instances should be deleted from the archive tables. After the MaintenanceWorkflow instance has been added to the database, changing this has no effect. Change the value of state variable "config" to change the configuration. Added in 7.0.0. |
| Property name | Description |
|---|---|
| nflow.executor.host.length (-1) |
The length of the host field in the nflow_executor table in the nFlow database, only needed if then dynamic field length calculation does not work |
| nflow.workflow.instance.state.text.length (-1) |
The length of the state_text field in the nflow_workflow_instance table in the nFlow database, only needed if then dynamic field length calculation does not work |
| nflow.workflow.action.state.text.length (-1) |
The length of the state_text field in the nflow_workflow_action table in the nFlow database, only needed if then dynamic field length calculation does not work |
| Property name | Description |
|---|---|
| nflow.rest.allow.origin (*) |
The value for the Access-Control-Allow-Origin header in the HTTP response. |
| nflow.rest.cors.enabled (true) |
Controls whether CORS headers are added to nFlow REST API HTTP responses. |
| nflow.rest.allow.headers (X-Requested-With, Content-Type, Origin, Referer, User-Agent, Accept) |
The value for the Access-Control-Allow-Headers header in the HTTP response. |
| nflow.rest.path.prefix (nflow/api) |
Base path for nFlow REST API. |
| Profile | Description |
|---|---|
| jmx | Enables JMX statistics. |
| Property name | Description |
|---|---|
| host (localhost) |
The network interface nFlow server is bind to as an IP address or a host name. If 0.0.0.0, bind to all interfaces. |
| port (7500) |
The port nFlow server listens to. If 0, uses a random port. |
| spring.profiles.active (not set) |
Comma separated list of profiles to enable. See nflow-engine and nflow-jetty spring profiles |
| terminate.timeout (30) |
Time to wait (in seconds) for previous process using the same port to terminate gracefully before killing it. |
| extra.resource.directories (not set) |
Additional directories that Jetty will use as source for static resources. |
| nflow.jetty.accesslog.directory ("log") |
Directory where accesslogs are stored. Since 3.0.0 |
| nflow.swagger.basepath ("/api") |
Swagger basepath for REST services. Must point to path to which services from nflow-rest-api are installed. Since 3.0.0, removed in 5.0.0. |
| nflow.external.config (not set) |
Location for external configuration properties. Examples: classpath:/com/myco/foo.properties or file:/path/to/foo.properties. Since 3.0.0 |
| nflow.api.basepath ("/") |
JAXRS server address. Since 4.2.0, removed in 5.0.0. |
| nflow.swagger.packages ("io.nflow.rest") |
A list of comma separated package names where resources will be scanned for Swagger annotations. Since 5.0.0. |
nFlow can be used with any database listed below. The following versions have been tested to work:
| Database | Tested versions |
|---|---|
| PostgreSQL | 11 and 15 |
| MySQL | 5.7 and 8.0 |
| MariaDB | 10.3 and 10.10 |
| H2 | 2.1 |
| Microsoft SQL Server | 2017 and 2022 |
| Oracle | 18 and 21 |
| DB2 | 11.5.0 and 11.5.7 |
Note! Galera is not tested, but works if you set nflow.db.disable_batch_updates=true and specify in the Galera configuration wsrep_sync_wait=7, because the default value 0 causes stale reads)
You can either create a dedicated database for nFlow or reuse your existing DataSource when you embed nFlow into your application as a library. You also need to decide how nFlow database structures are created, see below for instructions.
First you need to create a database for nFlow, unless you are using a memory-based H2, which is suitable for development and testing.
MySQL, MariaDB
Execute the following commands:
sudo mysql -e "create database nflow character set utf8mb4;"
sudo mysql -e "create user 'nflow'@'%' identified by 'nflow';"
sudo mysql -e "grant create,drop,delete,insert,update,index,select on nflow.* TO 'nflow'@'%';"
sudo mysql -e "flush privileges;"
PostgreSQL
Add following line before other host lines in /var/lib/pgsql/data/pg_hba.conf:
host nflow nflow samenet scram-sha-256
Execute the following commands:
sudo -u postgres createuser --echo --pwprompt nflow
sudo -u postgres createdb --echo --owner nflow nflow
sudo systemctl reload postgresql.service
After creating nFlow database, override the default nFlow database properties whose name is prefixed by nflow.db (see nflow-engine properties). Also set the Spring profile that matches your database (e.g. -Dspring.profiles.active=nflow.db.mysql for MySQL).
| Profile | Description |
|---|---|
| nflow.db.mysql | Enables MySQL database support |
| nflow.db.postgresql | Enables PostgreSQL database support |
| nflow.db.mariadb | Enables MariaDB database support |
| nflow.db.sqlserver | Enables Microsoft SQL Server database support |
| nflow.db.db2 | Enables DB2 database support |
| nflow.db.oracle | Enables Oracle database support |
The exact solution depends on your configuration, but this section provides hints and guidelines.
Basically you need to tell nFlow which DataSource and which database vendor is used. This can be achieved through Spring configuration (see below).
@Configuration // 1.
@DependsOn("flyway") // 2.
public class NflowDatabaseConfiguration extends PgDatabaseConfiguration { // 3.
@Override //
@Bean // 4.
@NFlow //
public DataSource nflowDatasource(Environment env, BeanFactory appCtx) {
return appCtx.getBean("hikariDatasource", DataSource.class); // 5.
}
}Comments
- A standard Spring annotation for configurations.
- In this case, Flyway manages the database schema, so it needs to be initialized before nFlow. If you're not using Flyway, you need to setup the dependency to your
DataSourcebean so that it is created before the configuration uses it. - The database vendor (here: PostgreSQL) specific configuration is extended, which tells nFlow which database optimizations are used.
- Method
nflowDatasourceis overridden to return a reference to your existingDataSourceinstead of creating a new one. -
appCtxcontains the existingDataSourceas bean namedhikariDatasource, so we'll get and return it.
There're two options for creating nFlow database structures:
- Start nFlow with nflow.db.create_on_startup property set to true: missing database objects will be created automatically.
- Connect to the database using your favourite client and execute the database specific DDL in nflow-engine/src/main/resources/scripts/db directory.
Currently nFlow does not come with any security framework. You can add your own layer of security e.g. through Spring Security if you wish.
nFlow implements logging via SLF4J API. nflow-jetty uses Logback as the logging implementation.
You can specify location of logback.xml file using -Dlogback.configurationFile=/path/to/config.xml command line parameter.