Retrieving Entities with the Fetch Entities Flow Step
  • 19 Jul 2022
  • 5 Minutes to read
  • Dark
  This documentation version is deprecated, please click here for the latest version.

Retrieving Entities with the Fetch Entities Flow Step

  • Dark


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.


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

SettingsSettings Summaries
Type NameThis drop-down list is used to define which Type is being fetched by the Step. This would be a simple or complex Decisions type.
Extension Type NameThis drop-down list is used to define which Extension Data Type is being fetched by the Step, if not a default Type. 
Fetch CriteriaThis window lets the Designer add new Fetch Criteria by using the Field Name to construct a query-like statement for Decisions to interpret automatically within the Step. More than one Fetch Criteria can be configured. To learn more about configuring Fetch Criteria, please see the Fetch Entities Criteria article.
Sort FieldThis drop-down list is used to select which Field the results will be sorted by.
Sort Order FieldThis drop-down list is used to select whether the Sort Order will be ascending or descending.
Fetch Deleted EntitiesEnabling this feature fetches Entities where the "Deleted" criteria is true.
Fast FetchEnabling this feature fetches Entities quickly through indexing. 
Fetch Edit Copy of Entity Retrieves a cached copy of the object for the Flow to manipulate.
Read Uncommitted DataEnabling this feature allows Decisions the ability to read entities in a Database that have been changed, but not saved. 

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.


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. 

About NULL and Additional Resource 
Note that Null results will not be returned should the Fetch Criteria request a specific value. This is because Null represents an unknown or missing value.

The only way to return Null values is to use the Query Match Type IsNull, or a DoesNotEqual value in conjunction with an Input Data Alias value.

For more information on Fetch Entity Criteria and how values such as Null, function, see Fetch Entities Criteria and SQL Equivalence.

Was this article helpful?