Triggers and Actions

Flux comes with a large number of built-in triggers and actions to provide really helpful functionality, such as scheduling, watching for files on secure FTP servers, and transferring files.

Triggers wait for an event to occur. Actions perform some task.

The section below describes properties that are universally shared across all triggers and actions in Flux.

Individual triggers and actions are also described in greater detail in the subsequent pages.

List of Built-in Triggers and Actions

Action	Description
Audit Trail Trigger	Fires when an audit trail event that matches certain criteria is reported to the audit trail. Useful when one workflow needs to wait for other workflows to reach milestones or for other workflows to finish.
Console Action	Prints a message to the console, that is, stdout or stderr. The print() and println() methods are taken from java.io.PrintWriter.
Database Condition Action	Executes an SQL query and then, using the first row of JDBC result set information returned from the query, evaluates a condition expression to see if it is satisfied. Useful for determining when the data in a database meets certain conditions and satisfies certain criteria.
Database Condition Trigger	According to a certain frequency, executes an SQL SELECT statement and then, using the first row of JDBC result set information returned from the query, evaluates a condition expression to see if it is satisfied. Useful for determining when the data in a database meets certain conditions and satisfies certain criteria.
Database Query Action	Executes an SQL query in the engine’s database and makes the resulting JDBC result set available to workflow actions.
Database Stored Procedure Action	Calls a stored procedure and makes the results of the stored procedure, if any, available to the flow context.
Database Update Action	Executes SQL statements in a database. For this purpose, the database connection available to the flow context can be used, or alternately, database connection information can be provided to connect to a data source or use a direct JDBC connection.
Delay Trigger	This delay trigger pauses, or sleeps, for a while after an execution flow reaches this trigger. The difference between this trigger and the timer trigger is that timer triggers fire on a set schedule. For example, it attempts to fire every 15 seconds, regardless of whether an execution flow has returned to the timer trigger. On the other hand, this trigger begins sleeping at the moment an execution flow reaches this trigger, not on a pre-determined schedule.
Error Action	Throws an exception and forces error processing to occur.
Flow Chart Action	Exports a new workflow to an engine. The workflow can be loaded from a workflow XML file or the repository. The newly created workflow can be populated with flow chart variables. The newly created workflow overwrites any existing workflow with the same name that may already exist.
Flow Chart Trigger	Watches a given namespace until there are no more workflows in that namespace.
Manual Trigger	Fires only when this trigger is expedited. Useful for situations where a running workflow must wait for explicit permission to continue executing.
Process Action	Executes a native process or command-line program. By default, this process action blocks until the process finishes. The process’s exit code is returned in the flow context using a ProcessActionResult object.
Regular Expression Action	Searches for strings in a file or an input string that match a regular expression. Optionally, within the search results, the first or all of those matching strings can be replaced with a different string. The file contents and the input string are not modified. The result lists the matching strings, optionally replaced by different strings. If both the replaceFirst and replaceAll properties have been set on this action, the first matching string is replaced by the replaceFirst property and the remaining matching strings are replaced by the replaceAll property.
Rest Action	Invokes a REST service with support for SSL encryption, security certificates, multipart messages, and other REST capabilities.
Timer Trigger	Fires triggers at scheduled dates and times. Unlike some other triggers, a timer trigger can be expedited. When being expedited, a timer trigger does not update its internal state, such as decrementing the running count. When being expedited, a timer trigger simply fires without decrementing the running count or updating any other state.
Web Service Action	Invokes an operation on a Web service. The operation name and input arguments to the Web service are specified using the DynamicMethod interface.
Decision	A special node that makes an explicit decision, also known as a conditional branch. The result that is passed to a Decision node from the previous action is copied to this Decision node’s result, so that conditional branches can take place properly from the Decision node.
For Each Collection Element Action	Makes each element in a collection available for individual processing in a workflow. The collection can be an array, List, Map, or Set.
For Each Number Action	Iterates over an inclusive range of numbers. The numbers can be integers or floating point numbers. The range can progress in a positive or negative direction. Each number in the sequence is returned to the flow context.
Join	A special node that performs an explicit join. It is not permitted to add more than one outgoing flow to this Join. Note that to perform a join, it is not necessary to use a Join node. A join point can be defined on any action. The Join node exists for convenience.
Null Action	Performs no action. Useful for inserting a transaction break.
Split	A special node that makes an explicit split, also known as a fork. It is not permitted to set a join point on this Split. Note that to make a split, it is not necessary to use a Split node. Any action can make a split. The Split node exists for convenience.
Dynamic Java Action	Creates a Java object from a class, then invokes a method on the newly created object. The class does not need to implement any specific interface. When the job executes this action, the object returned by the listener is added to the flow context.
Dynamic RMI Action	Invokes a method on an existing RMI server object that does not implement any specific interface.
Java Action	Creates a Java object from a class, then invokes a method on the newly created object. The class must implement the flux.ActionListener interface. When the job executes this action, the object returned by the listener is added to the flow context.
RMI Action	Invokes a method on an existing RMI server object. The RMI server object must implement the flux.RemoteActionListener interface. When the job executes this action, the object returned by the RMI server object is added to the flow context.
File Copy Action	Copies a group of source files and directories to a group of targets. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
File Create Action	Creates a group of files and directories. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
File Delete Action	Deletes a group of files and directories. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
File Exist Trigger	Fires when specified files and directories exist. The file exist trigger periodically scans, as defined by setPollingDelay(), the appropriate file system, and returns all files and directories that exist and match the file criteria.
File Modified Trigger	Fires when specified files and directories are modified. The file modified trigger periodically scans, as defined by setPollingDelay(), the appropriate file system and returns all files and directories that have been modified and match the file criteria.
File Move Action	Moves (renames) a group of source files and directories to a group of targets. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
File Not Exist Trigger	Fires when specified files and directories do not exist. The file not exist trigger periodically scans, as defined by setPollingDelay(), the appropriate file system and fires when no files or directories on the file system match the file criteria. In other words, the trigger fires when all files specified by the file criteria are non-existent.
File Rename Action	The exact same behavior as FileMoveAction. Here to avoid confusion if it is not obvious that a move action is the same thing as a rename action. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
For Each File Action	For each file in the group of specified files, returns the file name to the flow context. At workflow execution time, if at least one error occurs, a FileActionException is thrown.
FTP Command Action	Executes a sequence of commands on an FTP, SFTP, or FTPS host.
File Transform Action	Transforms, that is, changes files from one form into another form.
Dynamic EJB Entity Action	Invokes a method on an EJB entity bean home interface, which is responsible for returning one or more remote references. Afterwards, an optional method on each remote reference is invoked. These EJB entity bean remote references do not need to implement any specific interface. The result objects returned by each invocation of this optional method are returned as a java.util.List to the flow context. This list may be empty, but it is not null.
Dynamic EJB Session Action	Creates and invokes a method on an EJB session bean. The default create() method is used to instantiate the session bean. The EJB session bean does not need to implement any specific interface. After the session bean is created and invoked, it is removed.
EJB Entity Action	Invokes a method on an EJB entity bean home interface, which is responsible for returning one or more remote references. Afterwards, a method on each remote reference is invoked. The result objects returned by each invocation of this method are returned as a java.util.List to the flow context. This list may be empty, but it is not null.
EJB Session Action	Creates and invokes a method on an EJB session bean. The default create() method is used to instantiate the session bean. After the session bean is created and invoked, it is removed afterwards.
JMS Action	Publishes a JMS message to a JMS queue or JMS topic.
Mail Action	Using an email template at workflow construction time, constructs and sends a concrete email at runtime. The mail action sends email through an SMTP mail server.
Mail Trigger	Monitors an email server for incoming mail and fires when email arrives.

Properties Shared by All Triggers and Actions

Name

The name of the action or trigger.

The special character ‘ is reserved in Flux and cannot be used in trigger and action names.

Skippable

A boolean (true/false) value indicates whether this action can be skipped if it generates an error that causes the flow context to enter the FAILED state. Setting an action as skippable allows you to determine whether you want to skip the action when recovering the flow context from the FAILED state.

When the flow context enters the FAILED state, it will remain in that state until it is recovered. When you recover the flow context, if the action that caused the error was skippable, the Operations Console will prompt you to select whether that action should be skipped or re-executed.

Once you have chosen to skip the offending action, Flux will roll back the flow context to the last transaction break, then begin executing again from there. When it reaches the skippable action that caused the error, it will skip that action and continue on in the workflow as normal.

Any flow context variables (including result values) that would normally have been passed to the skippable action will instead be passed to the next action (or actions, in the case of a split) when the action is skipped.

Timeout Expression

A time expression that specifies how much time may pass before the trigger or action times out. If an action has been running (or a trigger waiting for a condition) for an amount of time that meets or exceeds the timeout expression, the Flux engine considers the action to have timed out.

For example, if a timeout expression is set to “+20m”, then an action will time out 20 minutes after it begins running, and a trigger will time out 20 minutes after it begins waiting for its condition (that is, after the flow of execution reaches the trigger). If the timeout expression is null or empty, the action will never time out. By default, triggers and actions will never time out.

After the trigger or action times out, the flow of control will follow any outgoing conditional flows with the “timeout” condition. If there are no outgoing timeout flows, the flow will stop executing at that point.

If an action times out while it is running, the engine must allow the action to run to completion as it is not possible to safely interrupt a running action. Once the action finishes as normal, the standard timeout behavior is invoked.

If you are using a Java Action, you can use the API method FlowContext.isTimedOut() to check whether an action has timed out. You can then perform appropriate steps within your Java Action listener (like exiting if a timeout occurs).

Timing Out an Action Using Signals

As mentioned above, when an action times out, the engine must still allow it to run to completion before the flow can move forward. This can be problematic if an action is “stuck” or in a position that it can never finish since it is impossible for the flow to move on from that point.

If your flow contains an action that may become stuck, it is best to use signals to separate the timeout logic from the action that becomes stuck. This allows you to simulate a Flux timeout, with the added advantage that your flow can continue without waiting for a stalled action to finish.

A typical scenario might be something like:

1. Create a Delay Trigger that starts at the same time as the action you need to time out. Give the Delay Trigger a “delay time expression” that matches the expected timeout value (for example, if the other action should time out after 10 minutes, the Delay Trigger will have the delay time expression “+10m”).
2. Create a flow from the Delay Trigger to the next action that should be taken after the timeout occurs (the action that your “stuck” action would normally flow into after it timed out).
3. On the flow created in step 2, raise a signal to kill the “stuck” action.
4. On the “stuck” action, set the “signals to monitor” to include the signal raised in step 3.
5. Repeat steps 3 and 4 for any flows coming out of the “stuck” action, to kill the Delay Trigger. This will prevent the Delay Trigger from firing unnecessarily and raising a signal that is no longer required (there is any need to time out if the action has already been completed normally).

This scenario is also covered more broadly by the “abort” scenario, which can be used to cancel an action that no longer needs to run. For a complete working example of this scenario, see the examples/end_users/abort directory under your Flux installation directory.

Timeout Business Interval

A business interval that can be used, in conjunction with the timeout expression, to calculate if and when an action or trigger should time out.

The business interval is applied to the timeout expression to determine when an action or trigger should be considered to have timed out.

Using Trigger and Action Results

Almost every trigger and action in Flux returns a result. The result is returned as the flow context variable “RESULT”.

A result will typically have several properties that contain some information about the result. For example, a Process Action’s result has separate properties for the exit code of the process it ran, the standard output that was generated, and the standard error that was generated.

You can use trigger and action results in any of the following ways:

1. Use a prescript or postscript to access the result using Flux APIs (or use the same APIs within a Java Action). You can access the result object using the code:

   flowContext.get("RESULT");
   

   You can then use the returned object to access the result properties. Results and their properties are described in greater detail in the Flux Javadoc. To find the result properties for a particular action, simply view that action’s entry in the Javadoc, then select its result object (which will be displayed on the action’s Javadoc page).

2. Use a runtime data map to access a particular result property, then map it to an action property or to another variable. To use this method, you can create a runtime data map with a flow context source. You can access a result property from the flow context source using the syntax RESULT.<property name>, where <property name> is the name of the result property you are attempting to access.
3. In a conditional flow. You can use the syntax RESULT.<property name> in your conditional flow, where <property name> is the name of the property you are attempting to access. For example, to create a conditional flow that would only be followed if a Process Action’s stderr result property (the standard error from the process) contained the text “error”, you could set the following flow condition on a flow from the Process Action:

   RESULT.stderr LIKE '%error%'
   

The subsequent pages for individual triggers and actions describe all of the available result properties for each trigger or action.