The engine configuration defines both how your engine runs, and how it stores and maintains data from the Flux engine (including flow chart and user data).
The engine configuration settings can be configured in a .properties file, or, if you are starting the engine using Java code, a flux.Configuration object. These configuration settings cannot be changed after the engine has started. For a comprehensive list of static configuration options, see the Javadoc for the flux.Configuration option (Javadocs are located in the /doc/javadoc directory under your Flux installation directory).
Engine behavior is also controlled by the Runtime Configuration. The runtime configuration and the engine configuration are used together to define how the engine operates.
List of Configuration Properties
The following table contains a list of configuration properties that can be set in your engine configuration, along with a description of each, and the default value (if any) that is used if you do not set the configuration property yourself.
Property |
Description |
Default Value |
---|---|---|
AGENT_FAILOVER_TIME_WINDOW |
A time expression that specifies the duration of time between agent connectivity tests. If an agent is busy and cannot be reached during this time period, the process assigned to the unreachable agent will be reassigned to the next available agent in the pool. |
+15m |
AUDIT_TRAIL_EXPIRATION |
A time expression indicating how old individual audit trail, run average, and run history entries must be before they are automatically pruned. Expired entries are automatically deleted from the database. A null audit trail expiration indicates that these entries are never deleted from the database. |
+1H (when using the H2 in-memory database), OR |
AUDIT_TRAIL_FILTER |
A list of audit trail events to record to the audit trail. If this audit trail filter is not set or empty, all audit trail events are recorded to the audit trail. |
none (by default, all audit trail events are recorded) |
AUDIT_TRAIL_LOGGER |
The name of the logger used when logging audit trail information. |
audit_trail |
AUDIT_TRAIL_ROLLBACK_RECORDINGS_ENABLED |
Indicates whether actions that execute in a flow chart that are later rolled back in the current database transaction are still recorded to the audit trail. Useful for knowing what actions led up to an error, before the error caused the current database transaction to be rolled back. |
false |
CACHE_SIZE |
The size of the flow chart cache. The cache size determines the number of flow charts that can be stored in the cache. |
200 |
CACHE_TYPE |
Depending on the kind of Caching used in a Flux engine, performance can be increased dramatically. This configuration property controls how flow charts are cached.
|
NETWORKED |
CLIENT_LOGGER |
The name of the logger used when logging client-side information. |
client |
CLUSTER_NETWORKING_ENABLED |
Indicates whether networking is enabled in the engine instance when it participates in a cluster. Networking is not required for clustering, but networking increases responsiveness among engine instances across the cluster. By disabling cluster networking, the engine instance still participates in a cluster, but all its communication with other engine instances is performed through the database server. |
true |
CONCURRENCY_LEVEL |
The concurrency throttle limit in the root node of the runtime configuration tree. This limit controls the number of flow contexts that may execute at one time across the entire engine. This property is only used if no runtime configuration is available. If a runtime configuration is available, the root throttle of the runtime tree will be used instead. |
10 |
CREATE_REGISTRY |
Indicates whether an RMI registry is created automatically. If this is set to false, Flux will assume that an RMI registry has already been created by another application running in the same JVM, and will attempt to bind to that registry. |
true |
DAILY_MAINTENANCE_TIME |
A time expression specifying the time at which the engine performs once-a-day maintenance on the Flux database tables. For example, to run daily maintenance each morning at 04:30, set this configuration property to the Cron-style time expression "0 0 30 4". The time zone is always the local time zone. Regardless of the exact time expression used, maintenance is performed exactly once per day. |
0 0 0 2 (By default, maintenance is done at 02:00 each morning) |
DASHBOARD_FROM_ADDRESS |
The email address from which business process dashboard notifications emails originate. |
bounce@fix.me |
DASHBOARD_MAIL_SERVER |
The mail server used to send business process dashboard notification emails. |
localhost |
DASHBOARD_URL |
The URL for the business process dashboard. Used when sending business process dashboard notification emails. |
http://localhost:7186\\ |
DATA_SOURCE |
The JNDI name used to lookup an application server's database connection pool. |
none (you must explicitly set this property in order to use a data source) |
DATA_SOURCE_AUTO_COMMIT_CHECK |
Indicates whether to disable auto-commit on database connections obtained through a data source. If this property is enabled, the engine will check every connection retrieved from the data source for an auto-commit value of "false". If the connection has an auto-commit value of "true", the engine will log a warning and automatically attempt to disable auto-commit on the connection. |
true |
DATA_SOURCE_CACHING |
Indicates whether data source objects are saved and re-used later. Such caching of data source objects reduces warning messages emitted by WebSphere 5.0. Unfortunately, this caching may also reduce the ability of an application server to perform clustering. If possible, it is preferred to keep this configuration property at its default setting of false, which means that data source objects are not cached. |
false |
DATA_SOURCE_PASSWORD |
The password used to retrieve a database connection from an application server data source. This property is only used if it is not null and not the empty string, the data source username is not null and is not the empty string, and a data source has been set. |
"" (empty string) |
DATA_SOURCE_USER_TRANSACTION_CLIENT_JNDI_NAME |
The JNDI name of a javax.transaction.UserTransaction object that should be used for client calls into the Engine. User transactions are used to guarantee transaction integrity when the engine's transactions need to be integrated with transactions from other software systems. |
java:comp/UserTransaction |
DATA_SOURCE_USER_TRANSACTION_SERVER_JNDI_NAME |
The JNDI name of a javax.transaction.UserTransaction object that should be used for flow charts and background tasks running on the engine. User transactions are used to guarantee transaction integrity when the engine's transactions need to be integrated with transactions from other software systems. |
java:comp/UserTransaction |
DATA_SOURCE_USER_TRANSACTION_TIMEOUT |
A time expression specifying the timeout for all user transactions that the engine uses. If this property is null, Flux will not set timeouts for user transactions. |
+d (one day) |
DATA_SOURCE_USER_TRANSACTIONS |
Indicates whether a User Transaction object manages database transactions that are retrieved from a data source. If true, a javax.transaction.UserTransaction object is used to manage transactions. If false, Flux manages transactions. |
FALSE |
DATA_SOURCE_USERNAME |
The username used to retrieve a database connection from an application server data source. This property is only used if it is not null and not the empty string and a data source has been set. |
"" (empty string) |
DATABASE_PROPERTIES |
The full path to a database properties file. Database properties allow you to specify how Flux should connect to the database, to rename database tables and columns, to reassign a standard SQL type, and to provide initialization SQL statements to database connections that are created to directly access the database. |
none |
DATABASE_TYPE |
The type of database that the engine should use. |
DERBY |
DRIVER |
The class name of a JDBC driver. If DATABASE_TYPE is DERBY or H2, this property is ignored (as Flux automatically manages drivers for those database types). |
none |
ENGINE_CONTENTS_SUMMARY_FREQUENCY |
A time expression that specifies how often engine contents status audit trail events are generated. The engine contents summary audit trail event provides information on all of the flow charts, messages, and message publishers that exist on the engine. Although this property allows you to adjust the frequency of these events, it is not possible to disable the engine contents summary completely. |
+1d (one day) |
FAILOVER_TIME_WINDOW |
A time expression that specifies how often the engine checks to see whether other engines in the cluster have failed. This is used for failover purposes to determine whether any flow charts have prematurely stopped running and must be restarted on another engine. |
+3m (three minutes) |
FAIRNESS_TIME_WINDOW |
A time expression that specifies how often Flux should temporarily increase flow chart priorities to prevent lower-priority flow charts from being starved (not allowed to run) by higher-priority flow charts. A non-running flow chart's priority will be temporary updated each time Flux performs the fairness check. The flow chart's priority may be temporarily increased several times before it is able to run. Once the flow chart does run, its priority will be reset to its original value and it will begin waiting again for the next opportunity to execute. |
none (fairness checks are not performed by default – setting a value for this property will automatically enable them) |
FILE_TRANSFER_DEBUG |
Indicates whether debugging is enabled for file transfers. If this property is enabled, all interaction between Flux and any remote file hosts will be logged to the Flux system log. When enabled, this property requires the INTERNAL_LOGGER_LEVEL to be set at FINE logging level or greater. |
false |
FLOW_CHART_DEADLINES_ENABLED |
Indicates whether flow chart deadlines (SLAs or Service Level Agreements) are enabled; disabling deadlines reduces database activity. When this property is enabled, you can set deadlines on individual flow charts. If a flow chart exceeds its deadline, it will publish an audit trail event indicating that the deadline has passed. The Operations Console will also graphically indicate any flow charts that are approaching (or have exceeded) their deadlines. |
true |
FLOW_CHART_LOGGER |
The name of the logger used when logging information during flow chart execution. |
flow_chart |
HEARTBEAT_FREQUENCY |
A time expression that specifies the frequency with which heartbeat audit trail events are generated. A heartbeat audit trail event provides information on the health of the engine. Although this property allows you to adjust the frequency of these events, it is not possible to disable heartbeats completely. |
+1H (one hour) |
HOST |
The computer where an RMI engine resides. This property can only be set when using the configuration to look up an engine – it is an error to specify the property when creating an engine. |
none |
ID_DESCRIPTION |
A description of the engine instance intended for human consumption. |
none |
ID_FULL_NAME |
A long, descriptive name of the engine instance, intended for display purposes. |
none |
ID_NAME |
The case-insensitive name of the engine instance. Used to differentiate Flux engine instances in the logs, the audit trail, and Flux security login modules. If the name is not set explicitly in a configuration, the configuration will generate a name using:
|
determined on engine startup (see description column) |
INITIAL_CONTEXT_FACTORY |
The JNDI name of an application server's initial context factory. |
none |
INITIAL_CONTEXT_PASSWORD |
The password used to create an application server initial context when looking up objects in an application server's JNDI tree (like data source, EJB, or JMS information). This property is only used if it is not null and not the empty string and the INITIAL_CONTEXT_USERNAME configuration property is not null and is not the empty string. |
"" (empty string) |
INITIAL_CONTEXT_USERNAME |
The username used to create an application server initial context when looking up objects in an application server's JNDI tree (like data source, EJB, or JMS information). This property is only used if it is not null and not the empty string. |
"" (empty string) |
INTERNAL_LOGGER_FILE_DIRECTORY |
The directory where log files are placed when using the internal logger. |
. (equivalent to the system property "user.dir", typically the directory where the engine or JVM was started) |
INTERNAL_LOGGER_FILE_ROTATION_SIZE |
The maximum size to which a log file for the internal asynchronous and internal synchronous loggers can grow before it is rotated. At most, there are seven log files, which include the current log file and up to six previously rotated log files. The rotation size is specified in bytes. |
10485760 (ten megabytes, 10 * 1024 * 1024) |
INTERNAL_LOGGER_LEVEL |
The logging level used for the internal asynchronous and internal synchronous loggers. This property does not affect the logging level for any other loggers. |
INFO |
JDBC_CONNECTION_RECYCLE_FREQUENCY |
When Flux is configured to obtain database connections directly through JDBC (rather than a data source), it creates a connection pool and periodically recycles connections in the pool. This property is a time expression that indicates how often Flux should recycle database connections. |
+1H (one hour) |
JDBC_ENCRYPTED_PASSWORD |
The encrypted password used to obtain database connections when Flux is configured to obtain database connections directly through JDBC (rather than a data source). This property is only used if it is not null and not the empty string, the JDBC_USERNAME configuration property is not null and is not the empty string, and the JDBC_PASSWORD configuration property is null or the empty string. |
"" (empty string) |
JDBC_PASSWORD |
The password used to obtain database connections when Flux is configured to obtain database connections directly through JDBC (rather than a data source). This property is only used if it is not null and not the empty string and the JDBC_USERNAME configuration property is not null and is not the empty string. |
none |
JDBC_USERNAME |
The username used to obtain database connections when Flux is configured to obtain database connections directly through JDBC (rather than a data source). This property is only used if it is not null and not the empty string. |
sa |
LOG_EXPIRATION |
A time expression indicating how old log entries in the database must be before they are pruned (deleted) from the database. At the DAILY_MAINTENANCE_TIME each day, Flux will find and prune all entries older than this time expression. |
+w (one week). If the DATABASE_TYPE is H2, however, the default value is ?+1H (one hour). |
LOGGER_TYPE |
Indicates which logging system Flux should use. This property should only be set when a single logging system is used on the engine; for multiple loggers, use the LOGGER_TYPES property instead. |
INTERNAL_ASYNCHRONOUS |
LOGGER_TYPES |
Indicates which logging systems Flux should use. This property should only be set when multiple logging systems are to be used on the engine (for example, this could be configured to use both log4j and the internal asynchronous logger to log messages). |
INTERNAL_ASYNCHRONOUS |
MAX_CONNECTIONS |
The maximum number of database connections that the engine should be allowed to have open at once. The Flux engine requires a minimum of two database connections, so this property must be set to a number greater than one |
15 |
ORACLE_LARGE_OBJECT_ADAPTER |
By default, Flux uses standard JDBC APIs for persisting large binary data and characters to the database. Due to an Oracle limitation, however, standard JDBC cannot persist more than 4k bytes of data when communicating with an Oracle database. The Oracle large object adapter works around this limitation using an Oracle-specific API. |
none |
PROVIDER_URL |
The URL to an application server. Used when creating an initial context. |
none |
REGISTRY_PORT |
The port number where the RMI registry that Flux should use is running. If there is no registry running at the specified port (and no other application is using that port) then Flux will open that port and create a new registry. If there is a registry already running on the port number, Flux will bind to that registry. |
1099 |
RMI_PORT |
The TCP/IP port to use when creating RMI objects. A value of 0 indicates that an anonymous port should be used. Java's RMI subsystem multiplexes many RMI objects onto one port, so only a single port need be configured (meaning you can set the RMI_PORT to the same port number as the REGISTRY_PORT with no conflict). |
0 (anonymous port) |
RMI_SERVER |
Indicates whether an engine is created as an RMI server. |
false |
RUN_HISTORY_ENABLED |
Indicates whether flow chart run history information is recorded to the database; disabling run history reduces database activity. Run histories include execution times for flow charts and actions as well as flow chart metrics. These metrics include counts of successful and unsuccessful flow chart runs. |
true |
RUNTIME_CONFIGURATION |
Used to populate the flow chart namespace with configuration properties that apply to one engine only. These configuration properties can change on the fly, that is, dynamically. A union of the cluster-wide runtime configuration properties and the per-engine runtime configuration properties is formed to govern engine behavior. If the union creates a conflict, the per-engine properties take precedence. |
A default runtime configuration that allows at most one flow chart to run at the same time and defines a default error handler that retries failed actions up to five times, with one minute delays after a failure. This default error handler gives up after the fifth failure and places the flow chart in the ERROR super-state and the PAUSED sub-state. |
RUNTIME_CONFIGURATION_FILE |
The path to a runtime configuration file. Used to load a runtime configuration from a file instead of using the appropriate APIs. |
none |
RUNTIME_CONFIGURATION_FILE_REFRESH_FREQUENCY |
A time expression that specifies the frequency with which the runtime configuration file is reloaded automatically. Using this configuration property, if changes are made to the runtime configuration file, they can be imported into the engine automatically. |
+m (one minute) |
SCRIPTING_LANGUAGES |
Specifies the scripting languages that are registered with the Flux engine. Scripting languages are used for pre- and post-processing in triggers and actions. |
null (BeanShell is assumed to be the default language in this case) |
SECURITY_ENABLED |
Indicates whether security is enabled. If security is enabled, standard Java Authentication and Authorization Service (JAAS) security protocols are used. |
false |
SERVER_NAME |
The RMI registry name that is used to bind an RMI engine to an RMI registry. In other words, this is the name of the engine, as used in remote connections to the engine. Any client connecting to the engine will need to know the server name in order to look up the correct engine. |
Flux |
SYSTEM_DELAY |
The maximum amount of time the engine sleeps when it has nothing to do. |
+3m (three minutes) |
SYSTEM_DELAY_MINIMUM |
The minimum amount of time the engine sleeps before polling the database to determine if more work is available. This option is a temporary workaround to reduce database activity until a better solution can be implemented. |
+1s (one second) |
SYSTEM_LOGGER |
The name of the logger used when logging system information. |
system |
SYSTEM_RESOURCE_COMMAND |
Command to obtain system resource information such as CPU and memory usage. Standard output generated by the command is used to update system resource values. The system resource command is executed at the intervals defined by the system resource interval configuration property. |
none (the system resource command is not used by default) |
SYSTEM_RESOURCE_INTERVAL |
A time expression specifying how often the SYSTEM_RESOURCE_COMMAND should be executed. |
"" (not set by default) |
TABLE_PREFIX |
The prefix for all of the Flux database tables. |
FLUX_ |
URL |
A JDBC database URL. If DATABASE_TYPE is DERBY or H2, this property is ignored. |
none |
WORK_MANAGER_RESOURCE_NAME |
The name used to locate a Work Manager resource, to which the engine delegates background processing instead of using threads created directly by the engine. If this property is not defined or does not refer to a valid Work Manager resource, the engine delegates background processing to threads that it creates directly. |
none |
Avoiding Conflicts with REGISTRY_PORT and SERVER_NAME
By default, Flux will attempt to open and bind to the port 1099 on the server where you start the engine. If this port is already in use, you will need to change the REGISTRY_PORT option to use a different port (be sure to select a port number that is not used by any other application on the system).
If you have two engines running on the same machine, it is legal to use the same REGISTRY_PORT for both engines as long as the SERVER_NAME is unique for each (so Flux is able to distinguish between the two different engines for client connection lookups). The reverse is also true: two engines running on the same machine can use the same SERVER_NAME property if the REGISTRY_PORT option is unique for each engine.
It is also legal for two engines running on different machines to use the same REGISTRY_PORT and SERVER_NAME, as long as the host name is unique for each machine.
In short:
- Make sure Flux is using a REGISTRY_PORT setting that is not used by another (non-Flux) application on the machine (the default port is 1099)
- If you are running multiple engines, the combination of the REGISTRY_PORT, SERVER_NAME, and the actual host name of the machine where the engine is running must be unique.
Disabling RMI_SERVER
Disabling the RMI_SERVER option by setting:
RMI_SERVER=false
In your engine configuration allows you to prevent Flux from accepting any remote connections to the engine. This can be useful when the engine needs to be "locked down" and unavailable to end users, or if there are restrictions on the network that require Flux to avoid opening ports for communication.
Note, however, that this property can only be set if your engine is created programmatically (using the Flux Java APIs). If your engine is started from the command line, from a service on the Operating System, or from a batch or shell script, the RMI_SERVER property will always be enabled even if you have explicitly disabled it in the configuration.
The reason for this is that the engine, if created through code, can still be interacted with locally (using the Java API). If the engine is created from a command line, service, or script, however, it will not be able to accept any work or input from a user (since the only way to send work to an engine is to access the engine over the network). Because of this, if you have a need to disable the RMI_SERVER option, you will need to be sure that the engine is created using the Java APIs.
Note also that to completely disable network communications on the engine, you will need to disable cluster networking as well, by setting:
CLUSTER_NETWORKING_ENABLED=false
In your engine configuration.
RMI_SERVER and SECURITY_ENABLED
If you have enabled security on your engine by setting:
SECURITY_ENABLED=true
The engine will automatically be accessible over RMI. It is not necessary to enable the RMI_SERVER property; if you do attempt to set RMI_SERVER=true while security is enabled, the engine will encounter an error on startup and will fail to start until you remove the RMI_SERVER property.
Advanced Users (Java knowledge required)
If you are using the Java APIs, it is possible to enable Security but disable remote communication. See Security and the Java API for more information.
If you set RMI_SERVER=false, but security is enabled, then the RMI_SERVER property is ignored and the engine will automatically enable RMI communication. It is not possible to disable RMI communication with security enabled.
In short, an engine with security enabled will always accept RMI communication, and it is not necessary (or even possible) to specify a value for the RMI_SERVER yourself.
For more information on RMI and security, see Security.
Configuring Flux to Use Your Database
See Configuring Flux to Run with Databases for instructions on setting up the Flux engine to point to your database.
Configuring the System Resource Command
If you have the SYSTEM_RESOURCE_COMMAND property set, Flux can use the output of the command invoked to gather information about the current resources on the system (including memory and CPU statistics) and make scheduling decisions based on that information.
When you invoke the system resource command, it must display the following values to standard output, on a single line, separated by tab characters, in this order:
- Percentage of CPU usage
- Total physical memory
- Free physical memory
- Total virtual memory
- Free virtual memory
The output of the monitor command, therefore, might look something like:
10.000000 1051120 306356 2097024 2065060
To see a sample script you can adapt for your own system resource command, see the examples/software_developers/system_resource_monitoring directory under your Flux installation directory. This directory contains example scripts for both Windows and Unix environments that you can use to quickly configure the command on your own system.
Once you've enabled the system resource monitor, Flux will automatically use the CPU information it retrieves to make scheduling decisions across the cluster. As long as you have two or more engines running in the cluster and all of the engines have the system resource command enabled, Flux can automatically assign flow charts to the engine with the lowest CPU usage (and therefore the engine with the most available resources for running a new flow chart).
Comments
Please sign in to leave a comment.