Using a Data Flow in a Form – Advanced ExampleLast Updated: 12/06/2018 Introduced in Version:
A Data Flow is a flow used in a form to dynamically calculate or fetch data without leaving the form. Data Flows are triggered by certain events on a form (e.g., a user changing a value in text box).
A Data Flow behaves exactly like a typical flow in Decisions but with a few limitations (e.g. it must have at least one piece of output data and it cannot contain a form itself). The Data Flow is triggered by an event in the form such as user input into a field or clicking a button.
Use a Data Flow when you want to create a form that updates dynamically while the user interacts with it.
This advanced example will demonstrate how to use a Data Flow to create a simple invoice form that updates dynamically as the user enters data. The Data Flow will calculate a “Total Due” field by adding up the cost of multiple line items.
For a simple example see Using Data Flow in Form.
We begin by creating the flow that will include our invoice form. In the Decisions Designer Studio, we begin by creating a Designer Folder called “Data Flow – Invoice”. For information on creating a Designer Folder, see Creating a Designer Folder.
In our new Designer Folder we create a new flow by clicking the Flow icon.
In the New Flow dialog we name our flow “Data Flow – Invoice” and click OK (leaving all other settings default).
In the workspace there is already a green Start step and a red End step. We want to add a new step that will become our invoice form. To do this, click the arrow coming out of the green Start step. This opens the Quick Add for Step dialog. On the right side under Favorite Steps we click Show Form and click ADD.
The Show Form step is added to the workspace and the Default Editor for Step dialog opens. We name our form “Invoice” and click Create (leaving other settings default).
Building the Invoice Form
The Form Editor opens. This is the design screen we will now use to create our invoice form. In the Form Controls tab on the right side, under Favorite Components, we click the Label component and drag it to the top of the form (when prompted we set the text to “Invoice” and click Enter).
(As a best practice step we enlarge and center the Label text. These properties are changed in the Properties tab on the right under View > Use Form Font > […]. The alignment is set in View > Alignment.)
Next, we want to create fields for the user to input the names and prices of two line items. From the Form Controls tab on the right, we click and drag over two Text Box controls in which the user will enter the names of the items and two Masked Text Box controls in which the user will enter the price for each item as shown in the screen shot below. When prompted by the Set Data Name dialog, we name the output data for the Text Box controls “Item1” and “Item2” respectively. For the Masked Text Box controls we name the output data “Item1Price” and “Item2Price” respectively. We also add a Label for each as shown below:
(Note, in this example we’re giving the user fields to input only two line items. In the real world we would want to let the user enter more line items to create their invoices. To do this we would design the form using a Repeater Control. For more information on Repeater Controls, see Creating a Repeater Form Control.)
We configure the properties for the Masked Text Box controls to expect a currency entry. This will ensure the user enters a valid monetary value. To do this, click on the control to select it, then in the Properties tab on the right under Value Type select Currency.
Next, we want to create a “Total Due” box that will display the calculated total. From the Form Controls tab on the right we click and drag over two Label components as shown in the screen shot below. (Notice also we’ve added Cancel and OK buttons.)
We set the top Label to display “TOTAL DUE”. We will return later to configure the bottom Label. After we configure it with the Data Flow we will later create, the bottom Label will contain the dynamically calculated total of items 1 and 2.
This concludes our basic form design. At the top left we click Save Form and Close Form. Next we will create the Data Flow that will add the prices of the items and create the “TotalDue” value.
Building the Data Flow
Back in our Designer Folder, click Create Flow. In the New Flow dialog, name the flow “Data Flow” and leave the other settings default, then click OK.
The Flow Designer opens and shows a default flow layout with a start and end step. Click the green start step and, in the Properties tab on the right under Flow Data, click Show Editor.
Create two input values named “Item1Price” and “Item2Price” and set them to String. For each value, under Mapping Type, click Select Value [From Flow] from the drop down list, click Pick, then select the corresponding value for each. Then click Close.
At this point we have mapped the price values for each item into our Data Flow. Now we need to add the values together. There’s a problem: our values are currently String type data and need to be converted into Decimal type. To make this conversion we add a Convert String to Decimal step from the Steps tab on the right – one for each value. (These are subflow steps, meaning they behave like steps in your flow but each contain their own discrete flow.)
In the Properties tab on the right, we configure each Convert String to Decimal step as shown below. Notice the names we have given to the converted data (“Item1PriceConverted” and “Item2PriceConverted”).
Now can add these two converted values.
From the Steps tab on the right, under Data > Numbers, click and drag an Add step onto the workspace.
Click the Add step to select it, then in the Properties tab on the right set the two values to “Item1PriceConverted” and “Item2PriceConverted”.
Under Outputs set the Mapping Type to Rename and the name to “PriceSum”.
Next we need to configure output data that our Data Flow will pass back to the form. Click the red end step to select it, then in the Properties tab on the right under Data, click Show Editor.
Create an output value called “PriceSum”, configure it as follows then click Close.
In the upper left corner, save and close the flow.
Open the form again. In the Form Designer, click in the blank checkered space then click on the Properties tab on the right to open the form properties. Under Form Rules > Data Flows, click Add New.
Name the flow “Data Flow” then click Pick and choose Data Flow, then click OK.
(Note: if you see an error warning about invalid inputs, click the pencil edit icon for each input and manually set them to Form Component and the appropriate value. If you see no values under Flow Inputs or Flow Outputs, click Update Inputs.)
(If you are seeing these errors, configure each input as shown below and click OK.)
Next, click the bottom “Total Due” label to select it. In the Properties tab on the right under Common Properties, click the Text from Data Name checkbox. Click Pick From Data, click Flow: PriceSum, and click OK.
(Note: the term “Flow:” is prefixed to the data to indicate that it is coming from the Data Flow.)
In the upper left corner, save and close the form.
Back in the main flow, your form step may show error warning because of the input mapping type. Click this step to select it, then in the Properties tab on the right under Inputs, set the mapping types to Ignore. (This tells the step not to expect any value for these data because they will receive input value from the user.)
We are now finished building the invoice form and its Data Flow.
The final step is testing. Above the main flow workspace, click Debug Flow.
Click the start arrow to begin the test. The “Invoice” form will appear with blanks for items and their prices. Fill these fields with test values.
The “TOTAL DUE” field should automatically display the summed values.
Notice on the left how the Data Flow is running multiple times. This is because the Data Flow runs each time the user changes the values in either price field.
If you encounter errors, the most likely cause is improperly configured input or output data from the Data Flow. To troubleshoot, on the left side of the debugger expand the instances of the Data Flow and click on an instance to open it. Right-click on any of the steps, click Execution 1 > View Input/Output Data. This lets you see exactly what data the step was doing with the data and may help you pinpoint the problem.