The Runtime Data Map

In Flux, mapping can be done both in the flow between nodes, and within the node itself between the different variable managers Flux utilizes. This map is referred to as the "runtime data map". Data mapping is essential to making Flux run smoothly, and an improved understanding will dramatically increase the use and efficiency of your Flux workflows.

Variable Managers

There are four variable managers available to map between in Flux:

Action Property Variable Managers - Each node in the Flux framework consists of a set of a fields that are usually specified by the user when created, but can be specified dynamically using the runtime data map. These are static, so no new action properties can be specified, but all existing ones can receive input. An example would be the "Command" action property in a for each collection element action

Runtime Configuration - These are engine wide variables specified in your runtime configuration file. These use the syntax ?/{namespace}/variable=value? where you can specify variables to be available in individual namespaces as well.

Flow Chart Variables - These are variables that are specified on a flow chart to flow chart basis. Flow Chart variables have no configuration file and must be specified directly either in the designer or in code.

Flow Context - The Flow Context is a temporary variable manager that is populated with the results of an action. It can be used to temporarily store data, and is emptied at a transactional break. For a comprehensive list of what the results of a specific node is, refer to Appendix I in the Flux end-user manual.

Usage*In the Designer*

Using the designer, it is simple to specify runtime data mapping. Begin by either right clicking on the flow that you wish to map variables between and selecting "Edit runtime data map", or by clicking the button next to the "Runtime data map" field in a node's action properties. The frame shown in the image below should appear:



Using the runtime data map editing tool is fairly straightforward. To specify a new entry, begin by clicking the "+" button. You will need to input a source variable manager and a destination variable manager to complete the map. The action variable manager is unavailable as a source variable manager, as the action will have already completed before this mapping could take place. Runtime configuration variables will be unavailable as a target in mapping, as they are specified before the engine is started and unable to be changed after. The "Type" specifies the variable manager from which to retrieve a variable, and the "name" is the name of the variable you want to retrieve.

For example, suppose you wanted to use map the results of a file exists trigger to the collection input of a for each collection element action. The type of the source variable manager would be set to "Flow Context" (where the results from nodes are put) and with the name input as RESULT.url_string_matches, RESULT.url_object_matches, RESULT.filename_matches, or RESULT.fileinfo_matches depending on which collection you want to use. The target type would be set to "Action" with "Collection" selected from the drop down box for the name. All possible entries for the type of an "Action" target will always be listed in a drop down box. Refer to the screenshot below for the proper configuration:



In Code
Mapping variables in code is a bit more difficult than in the designer. The basic progression for runtime data mapping is; create a Map object -> make variable manager entries of your choice -> link them in the map -> set runtime configuration for a node or flow using the map. The variable manager entries different for each manager and are modeled with the following classes:

Action properties, only able to be the target in a data map entry, are specified using only the "ActionPropertyTarget" class. This class is manufactured from the flowchart you are currently working on using the makeActionPropertyTarget(String target) method. The target would be the name of property you want to map to, with each word in beginning with an uppercase letter. You will be given an error is the property does not exist for either the target node or the node you are editing the runtime map on; such as when specifying "Collection" when the target or current node is not a for each collection element action. Making this class would look similar to this:

ActionPropertyTarget myTarget = myFlowChart.makeActionPropertyTarget("Simple File Source");

Flow chart variables are specified through one of two methods depending on whether the entry to be mapped is a target or source - FlowChartTarget and FlowChartSource. Instances for both can be made from the flowchart object you are currently working on. They can be made using the following code:

FlowChartSource mySource = myFlowchart.makeFlowChartSource("list");
FlowChartTarget myTarget = myFlowchart.makeFlowChartTarget("newList");

Flow context mapping is similar to flowchart variables as they can be both retrieved from as a source, and mapped to as a destination. The setup for the flow context is almost exactly the same as flow chart sources and destinations with a slight modification in the names of the classes and of the methods to instantiate the classes. Consider the following code:

FlowContextSource myFCSource = myFlowchart.makeFlowContextSource("RESULT.filename_matches");
FlowContextTarget myFCTarget = myFlowChart.makeFlowContextTarget("filename_list");

The runtime configuration variable manager is only available as the source of a flow and cannot be written to. Once again, the flowchart you are working on serves as a factory for making instances of the class that represents a link in the runtime data map - RuntimeConfigurationSource. The following code demonstrates making this class:

RuntimeConfigurationSource myRCSource = myFlowchart.makeRuntimeConfigurationSource("variable");

Now that all the proper classes have been introduced, it is possible to create a working runtime map. First you will need to create a blank Map object and two corresponding links (a source and target) for each entry you want to add to the data map. With your Map object configured, you can link it to a particular node or flow by using the setRuntimeDataMap(Map) method. The following code demonstrates using the runtime data map from start to finish. In the code, the results from a file exists trigger are mapped to the collection of a for each collection element action, and then passed on to a console action.

import flux.*;
import flux.runtimedatamap.FlowContextSource;
import flux.runtimedatamap.ActionPropertyTarget;
import flux.runtimedatamap.FlowContextTarget;
import flux.file.FileFactory;
import flux.file.FileExistTrigger;
import flux.file.FileCriteria;
 
import java.util.Map;
import java.util.HashMap;
 
public class RuntimeMap {
    public RuntimeMap() throws Exception{
        //Create factory, engine, and helper
        Factory factory = Factory.makeInstance();
        EngineHelper helper = factory.makeEngineHelper();
        Engine engine = factory.makeEngine();
 
        //Make flowchart and nodes to be used within the flowchart
        FlowChart myFlowchart = helper.makeFlowChart("Test");
        FileFactory fileFact = myFlowchart.makeFileFactory();
        FileExistTrigger feTrigger = fileFact.makeFileExistTrigger("File Exist");
        FileCriteria fCriteria = fileFact.makeFileCriteria();
        fCriteria.setBaseDirectory("C:\\flux-7-3-1");
        fCriteria.include("*");
        feTrigger.add(fCriteria);
        ForEachCollectionElementAction feca = myFlowchart.makeForEachCollectionElementAction("For each");
 
        ConsoleAction cAction = myFlowchart.makeConsoleAction("Console Action ");
        cAction.setMessage("${i}");
        cAction.println();
 
        ConsoleAction cAction2 = myFlowchart.makeConsoleAction("Complete message");
        cAction2.println("Flow complete: press enter to dispose of engine");
 
        //First runtime data map -- the RESULT.filename_matches pulled form the flow context
        //mapped to the "Collection" property of the target node.  This runtime data map is used in
        //the flow between the file exist trigger and for each collection element action
        Map fExistMap = new HashMap();
        FlowContextSource fContextSource = myFlowchart.makeFlowContextSource("RESULT.filename_matches");
        ActionPropertyTarget apTarget = myFlowchart.makeActionPropertyTarget("Collection");
        fExistMap.put(fContextSource, apTarget);
        Flow flow1 = feTrigger.addFlow(feca);
        flow1.setRuntimeDataMap(fExistMap);
        
        //Second runtime data map -- the current element in a for each collection element action is
        //marked by "i" by default, so we are mapping it back into the flow context for use.
        //This map is used between the for each collection element action and a console action.
        Map feachMap = new HashMap();
        FlowContextSource fcSource = myFlowchart.makeFlowContextSource("i");
        FlowContextTarget fcTarget = myFlowchart.makeFlowContextTarget("i");
        feachMap.put(fcSource, fcTarget);
        Flow flow2 = feca.addFlow(cAction, "RESULT.result");
        flow2.setRuntimeDataMap(feachMap);
        
        //Additional flows
        cAction.addFlow(feca);
        feca.setElseFlow(cAction2);
        
        //Start engine and put in flowchart.
        engine.start();
        engine.put(myFlowchart);
        System.in.read();
        engine.dispose();
    }
 
    public static void main(String[] args) throws Exception{
        new RuntimeMap();
    }
}