Retrieving Entities with the Fetch Entities Flow Step

Overview

In the Decisions Flow Designer, the use of a Fetch Entities step allows the Designer to pull the data of any entity within the system to it. The data it can retrieve includes Folders, built-in and custom Data Types, and Database Types. Two additional useful features with this step are its ability to define certain Fetch Criteria using query definitions and its Sort options that are defined in the properties.

Example

This Example will explore the Fetch Entities properties and functionality by using the step to populate a Form Data Grid with the results of the fetched entity list.

In the Designer Studio, select the CREATE FLOW button from the bottom Action Bar in a Designer Folder. When the Create Flow window appears, select the Default template and click CREATE. Provide a name for the Flow, then click CREATE again.

In the Flow Designer, click the orange arrow coming from the Done outcome path of the Start step. When the Quick Add window appears, navigate to Integrations > All Integrations > Entity Framework, select Fetch Entities and click ADD. The Fetch Entities step will now be added to the Flow.

In the Steps tab on the right of the Flow Designer, click and drag a Show Form step from the Favorite Steps section into the workflow. Connect the Results and No Results outcome paths from the Fetch step to the Show Form step. Select the icon for the Show Form step, then select the Pick or Create Form button from the Step Properties on the right. When the Create or Pick window appears, use the left side to enter a new Form name, then click CREATE at the bottom.

In the Form Designer, click and drag a Data Grid and Button from the Favorite Components section into the Form, as shown in the screenshot below. When the Data Grid is inserted into the Form, use the arrows on the outside of the box surrounding it to expand the size. Simply enter "OK" for the Action Outcome Name of the Button.

With the Data Grid component selected, navigate to the properties for this Form Control on the right. Locate the Input Data section and enter Accounts for Data Name. Leave PickTypes set to the default selection. Use the dropdown for Type and select All/Search..., then search for Accounts and select it as the Data Type for this Data Grid. Save and close the Form Designer once complete.

The Form is now created with a Data Grid to show the Fetch Entities results of the Account Type once they are fetched by the Step in the Flow. For this to happen, the Inputs of the Form need to be mapped in the Flow. 

Back in the Flow Designer, select the icon for the Fetch Entities step and locate the Entity Fetch Definition section of the Properties. Please refer to the image and table below for a functional explanation of these settings. Using the All/Search... option in the dropdown list for Type Name, find and select the Account Type. 

Select the Show Form Step in the Flow Designer, then navigate to the Inputs section of the Step Properties. Expand the mapping type list to the right of Accounts and choose Select From Flow. When the Pick Data For Input window appears, choose Entity Results then select DONE. Save and close the Flow Designer once complete.

Alternately, select the Edit Input Mapping button at the top of the Step Properties. Click into the Entity Results box on the left and drag the cursor over to Accounts on the right so that the line connects them, then release. 

While in the Mapping Editor, expand the Entity Results (list of Accounts) to see all of the available data members for the Account type. These data members are available to define input mappings as a list of the item type or as a single object of the item type by expanding the All [Data Member Name] folder.

Debug

Right-click the Flow from the Designer Folder and select Run Flow from the Action Menu. As expected, the Fetch Entities step is pulling in the entire unfiltered and unsorted list of Accounts and showing them on the Form Data Grid where the input was mapped to pass the Entity Results. This can be applied to various types, both system default and user-defined. 

Fetch Edit Copy of Entity 

The Fetch Edit Copy of Entity Property is used to obtain a cached copy of an object (dictated by the Fetch Entities Properties) that a Flow can manipulate. 

This is enabled by checking the Fetch Edit Copy of Entity box under Properties > Entity Fetch Definition on the Fetch Entities step.

The behavior of this Property can be demonstrated by applying a Change Value mapping to a Fetched Folder's Folder Name. Running the same Flow with Fetch Edit Copy of Entity enabled, will not apply this value change. 

Fetch Criteria 

In order to retrieve specific Entities, users may use the Fetch Criteria Property. Fetch Criteria allows the ability to initiate a search Query Match based on the selected Field Name of the retrieved Entities and an optional Input Data Alias; this Alias is can be used to dictate which specific value the user wants the Fetch Entities step to search for.