Skip to end of metadata
Go to start of metadata

To set a script on an action or trigger, you can simply set the Prescript or Postscript. The following sections explain how to use scripting in Flux using prescripts (run before the action/trigger where the script is configured) and postscripts (run after the action/trigger where the script is configured).

NOTE: Scripting in Flux requires some knowledge of the Flux API to operate successfully. It is not recommended to employ prescripts or postscripts in your workflows if you are not familiar with the supported scripting languages in general, or with the Flux API.

Best Practices

Scripting provides a lightweight, easy-to-use alternative to more formal code invocation structures in Flux, like the Java Action and Web Service Action. It is often tempting to use scripting for all code invocation purposes – however, in many cases, this can lead to unforeseen problems or complexity after workflow development is complete. We suggest the following guidelines to make the best use of prescripts and postscripts in your workflows.

  • Prescripts should be used for setting complex data types on your actions that are generated dynamically at runtime, and cannot be access through Variable Substitution or Runtime Data Mapping. In most cases, this would include any data type beyond the basic Java data types or Strings which must be accessed through method invocation (rather than being directly accessible through an existing variable, and therefore available through data mapping).
  • Postscripts should be used for verification (checking the results of actions) and for parsing complex result types into easily parseable / reusable formats. As a general rule, postscripts should not contain methods that can throw exceptions, due to the unique quirks involved in Error Handling for postscripts.
  • When possible, runtime data mapping should be used for moving data between locations, rather than scripting. Runtime data mapping allows data movement and translation to be more immediately visible to operators.
  • Flux scripting uses the BeanShell Framework. BeanShell is dynamic (not strongly-typed) and does not support the use of generics. If you import code from an IDE or external application and the code is written in a strongly-typed language, be sure to remove any generics before importing the code to Flux, as the script will encounter errors if generics are present in the code.

Setting the Scripting Language

Flux uses the Bean Scripting Framework (BSF) environment in prescripts and postscripts. You can configure your Flux engines to use Beanshell and/or Groovy. If you intend to use Groovy, you must download Groovy from http://docs.codehaus.org/display/GROOVY/Download and place the jar file into the Flux Installation lib directory - as well as make the engine-config.properties file change shown below.

If you do not specify a scripting language in the engine configuration, Flux will use BeanShell as the default scripting language.

You can set the scripting languages by adding the following lines to the engine-config.properties file, located in the Flux Installation Directory/config folder.

SCRIPTING_LANGUAGES.0.name=BeanShell
SCRIPTING_LANGUAGES.0.class=bsh.util.BeanShellBSFEngine

SCRIPTING_LANGUAGES.1.name=Groovy
SCRIPTING_LANGUAGES.1.class=org.codehaus.groovy.bsf.GroovyEngine

SCRIPTING_LANGUAGES.<number>.name specifies the name case-insensitive name of a scripting language. SCRIPTING_LANGUAGES.<number>.class specifies the class name for running the language in the BSF.

Using the Script Dialog

Flux scripts are usually snippets of code run using Beanshell. Beanshell can run straight Java code, as well as a dynamic version of Java that is less verbose. A script dialog editor is provided for creating and editing scripts in Flux user interface, The editor is a simple text editor for scripts.

If you write your script in Java, the Verify button submits the script to the Java compiler for review. If the script is Java-compliant code, the verify will display a success message - otherwise a message is displayed detailing the Java issues with the script. Note that if you do use the Java syntax, Beanshell does not support the execution of Java scripts containing generics. 

If you choose to write your script in Beanshell, the script may not verify successfully because Beanshell resolves its variables at runtime - unlike Java which resolves its variables at compile time. If you have a Beanshell script that will not verify but you are reasonably sure it is correct - just use the Save Script button and ignore the verify messages in the script dialog. Flux will execute the Beanshell script and report any errors at runtime if there are issues with the script.

As an example of these differences, this Beanshell script

Beanshell example

will verify with the following details - but it will run just fine if saved. This error is not because the Beanshell script is incorrect but because the Java compiler cannot resolve the method name - since in this case the method name will be resolved by Beanshell at runtime.

Verify Details

The same script written in Java is more verbose, and it will verify successfully.

Java example for above Beanshell code

Depending upon your comfort with Java or Beanshell, feel free to use either language.

Creating a Flow Context Variable Using Scripts

To create a Flow Context variable and assign a value to it just call the following from any Prescript or Postscript:

This will create a variable named "Variable_Name" and assign the value "Variable_value" to it.

Retrieving Variables Using Scripts

Just like the line below creates and assigns a value to a Flow Context variable (or assigns a new value if the variable already exists):

If you wish to retrieve the value of a Flow Context variable, you can call:

Where "Variable_Name" is the name of the variable you are trying to retrieve. 

If you need to retrieve a Runtime Variable or a Workflow Variable, you will need to call the following instead:

The '${}' syntax is used across Flux for Variable Substitution.

Overriding Action Results with Postscripts

A postscript can be used to override the result of an action or trigger. For example, a postscript can replace the standard result returned from a Java Action with a new value. Similarly, a postscript can replace trigger results with new results.

To override the result of an action or trigger, simply create a postscript on a particular action that contains the following line of script code:

The argument "resultOverride" is simply the value that you provide that replaces and overrides the result from the action or trigger itself.

The result of every action or trigger is place into the flow context under the reserved name "result". By placing your own value into that "result", you can override and replace the result, if any, returned by the action or trigger.

For example, suppose a Java Action returns the string "my result value". To override that result with the number 23, create a postscript on that Java Action that contains the following line of code:

Similarly, to override the old string result "my result value" with a new string result "a new value", create a postscript that contains this line of code:

Alternatively, you can manipulate and replace the action results by first retrieving the result from the flow context, and then reinserting it. The code below demonstrates multiplying the current number in a For Each Number Action by four and returning it into the flow context:

Predefined Variables and Classes

When you use a pre- or post-script, there are several variables and classes that are automatically available to you.

Variables

The predefined variables are:

  • flowChart - the workflow that is being executed.
  • action - the trigger or action that the script is executing from.
  • vm -  the workflow's variable manager.
  • flowContext - the current flow context.

Classes

When using BeanShell (the default scripting language), all of the flux.* classes (classes from the flux package) are available by default. If you need to use any other classes (for example, a flux.file.* class), you will need to import them at the top of the script, like so:

Real-World Examples from our Technical Support Department

Create a flow context variable containing the name of the current action (the action where the script executes)

You can use the predefined object "action" to access the current action. You can call any method on this object that you could call on the action using the Flux API; so to get the action name, you would simply call action.getName().

You would then place the action in the flow context using the predefined object "flowContext". flowContext.put(String, Object) adds an object to the flow context.

A prescript to add the action name to the flow context, therefore, would look something like:

You can then access the action's name from the flow context using standard API or variable substitution techniques.

Show a message in the Operations Console

A prescript to show a message to the Operations Console would look something like:

Such an approach is often used to provide status messages to operators during the processing of actions.

Escape Double Quotes in String Variables

Use the following syntax to escape the double quote character ("):

Get the Average Run Time for a Flowchart and Display it in the Operations Console

Output the Runtime Configuration to the Console

Upload a workflow from a file to the Repository

You can upload the workflow files to the Repository using the curl command to login in to the engine and upload the files:

Output the list of Repository workflows

Get the last modification date of a Repository workflow

To get the last modified info from a workflow you'll need to query the FLUX_REPOSITORY table, get:

Output all running workflows and their status

Terminate a running workflow

Copy a repository workflow and rename

Start all repository workflows for a given namespace

 

Output the Variable Manager from a Flow

 

 

// Dump the flow’s Variable Manager to the form

Set names = vm.getNames();

Iterator iter = names.iterator();

StringBuffer formContents = new StringBuffer();

while (iter.hasNext()) {

  String name = (String)iter.next();

  String value = (String) vm.get(name).toString();

  formContents.append(name);

  formContents.append(":\”");

  formContents.append(value);

  formContents.append("\”");

  formContents.append(",");

}

action.setForm(formContents.substring(0,formContents.length() -1 ));

  • No labels