Fetch records
Note: This task is applicable only to Zoho Creator.
Overview
The fetch record deluge task retrieves records from a specified form, when a given criteria is met.
The criteria is mandatory.
See this page to learn about fetching all values of a field in a collection.
See this page to learn about fetching a specified field's value from the first record in the collection.
Note:
- The fetched records may appear to be sorted based on "added time" (oldest first) system field. However, there is no guarantee to this order and there is no guarantee that the order will remain constant over time. If you are particular about the sequence of the records, it is advisable to use the sort param.
Return
This task returns a collection of records.
Syntax
To fetch records which meet a criteria
<variable> = <form_link_name> [<criteria>];
To fetch records which meet a criteria, and sort them in ascending order based on a field
<variable> = <form_link_name> [<criteria>] sort by <field_link_name>;
To fetch records which meet a criteria, and sort them in descending order based on a field
<variable> = <form_link_name> [<criteria>] sort by <field_link_name> desc;
To fetch records within a specified range, which meet a criteria
<variable> = <form_link_name> [<criteria>] range from <start_index> to <end_index>;
To fetch records within a specified range, which meet a criteria, and sort them in ascending order based on a field
<variable> = <form_link_name> [<criteria>] sort by <field_link_name> range from <start_index> to <end_index>;
To fetch records within a specified range, which meet a criteria, and sort them in descending order based on a field
<variable> = <form_link_name> [<criteria>] sort by <field_link_name> desc range from <start_index> to <end_index>;
Parameter | Description | |||||
---|---|---|---|---|---|---|
<variable> | Collection variable holding the collection of records. | |||||
<form_link_name> | Link name of the form from which the records will be fetched. | |||||
<criteria> | Criteria based on which records will be fetched. | |||||
sort by <field_link_name> | Link name of the field based on which records will be sorted. Note: A lookup field will sort the records based on the record ID. | |||||
range from <start_index> to <end_index> | Records included in the specified index range will be fetched.
Negative index values will result in a runtime error. |
Things to keep in mind
If you wish to fetch all records of the specified form, use the following script as criteria:
[ID != 0]
It is advisable to fetch all records only when absolutely needed. Fetching all records generates a load resulting in performance issues.
- If you wish to use the "sort" and "range" parameters together, the "sort" parameter should be followed by the "range" parameter.
- If specifying the Name or Address field in the criteria, it is mandatory to specify their subfields as shown below:
- Name.first_name
- Name.last_name
- Name.prefix
- Name.suffix
- Address.address_line_1
- Address.address_line_2
- Address.district_city
- Address.state_province
- Address.postal_Code
- Address.country
- Address.longitude
- Address.latitude
If more than one Name fields are present in the form, the link names of the subsequent name sub fields will be appended by a number starting from 1. So, if we take the example of the subfield <field>.prefix, the link name of the first such field will be <field>.prefix, the link name of the second such field will be <field>.prefix1, the link name of the third such field will be <field>.prefix2, and so on. The same logic applies to the Address subfields.
- The Name and Address fields do not work with the sort by param
This task can be used in the following events
When a record is Created | ||
On Load | Yes | |
On Validate | Yes | |
On Success | Yes | |
On User input | Yes | |
Subform on add row | Yes | |
Subform on delete row | Yes | |
When a record is Created or Edited | ||
On Load | Yes | |
On Validate | Yes | |
On Success | Yes | |
On User input | Yes | |
Subform on add row | Yes | |
Subform on delete row | Yes | |
When a record is Edited | ||
On Load | Yes | |
On Validate | Yes | |
On Success | Yes | |
On User input | Yes | |
Subform on add row | Yes | |
Subform on delete row | Yes | |
When a record is Deleted | ||
On Validate | Yes | |
On Success | Yes | |
Other workflow events | ||
On a scheduled date | Yes | |
During approval process | Yes | |
During payment process | Yes | |
In a Custom Function | Yes | |
In an Action item in report | Yes |
Examples
1) The following snippet can be used to extract specified field value from the most recently added record.
info EmployeeDetails.<field_link_name>; // picks up the first record from the collection
2) The following script fetches all records which have the "age" field value as "25", from the Employees form.
3) The following script fetches all records which have the "name" field value as "Edward Thomas" or "Robert Frost", from the Poets_Form form.
Poet_Details = Poets_Form [ name in poets ];
4)The following script fetches all records which have the "name" field value as "Jon Berryman". The name value is then updated to "John Berryman".
for each employee in EmployeeDetails
{
employee.name = "John Berryman" ;
}
5) The following script fetches all records(because no record will have ID as 0) and sorts them by their Names. The Range is specified as 0 to 2, hence only the first 3 records will be fetched.
Limitations due to behavioral updates
The following limitations are applicable to this task. To know about more such limitations, you can check this page.
Sort using multi select fields: Records fetched using this task cannot be sorted using Multi Select, Multi Select lookup, Existing Subform, Inline Subform, or Check Box fields. For example, the below line of code will throw an error.
variable = Form1[ID !=0] sort by checkbox_field ;
Sort using composite fields: Records fetched using this task cannot be sorted using the Name and Address composite fields and Added_Location and Modified_Location composite system fields. For example, the below line of code will throw an error.
variable = Form1[ID !=0] sort by name ;
- Fetch records criteria restriction: The left expression of the fetch records task criteria with the format <parent field>.<child field> cannot contain the following field types i.e., they cannot contain the format as MultiSelect.MultiSelect.
- parent field - Multi Select Lookup, Existing Subform, and Inline Subform
child field - Multi Select field, Multi Select Lookup, Existing Subform, Inline Subform, Multi Select, and Check Box fields.
For example, the below line of code will throw an error.
variable = Form1[multi_select_lookup_field.multiselect_field == {"Choice 1", "Choice 2"}] ;
The following method is the best practice to achieve the use case:
fetchedIDs = Form2[multiselect_field IN {"Choice 1", "Choice 2"}].ID.getAll(); variable = Form1[multi_select_lookup_field in fetchedIDs];
Fetch records criteria restriction (using composite fields): The left and right expressions (operands) of the fetch records task criteria cannot contain the Name and Address composite fields and composite system fields such as Added_Location and Modified_Location. For example, the below lines of code will throw an error during script execution. This restriction applies only when the above-mentioned fields are present in the same form.
variable = Form[ Name == Name ];
variable = Form[ Address == Address ];
- Fetch records criteria restriction (Multi Select and Single Select fields): A Multi Select field type cannot be compared with a single select field type in the left and right expressions (operands) of the fetch records task criteria i.e., the two operands cannot contain the following fields in each of the two field types.
- Multi Select field type - Multi Select Lookup, Existing Subform, Inline Subform, Multi Select, and Check Box fields.
Single Select field type - Radio, Drop Down, Drop Down Lookup, and Radio Lookup fields.
For example, the below lines of code will throw an error during script execution.
variable = Form[ MultiSelect == Radio ];
variable = Form[ MultiSelectLookup == SingleSelectLookup ];
- Fetch records criteria restriction (Multi Select fields): The left and right expressions of the fetch records task criteria cannot contain the following Multi Select field types:
- Lookup (Multi Select)
- Existing Subform
- Inline Subform
Check Box
For example, the below lines of code will throw an error during script execution.
variable = Form[ MultiSelectLookup == MultiSelect ];
variable = Form[ MultSelectField1 == MultSelectField2 ];
variable = Form[ SubForm == SubForm ];
- Operator-based criteria restriction: The left expressions of the fetch records task criteria cannot contain the following Multi Select field types and the right expressions cannot contain more than six elements in the list (here, arguments refer to choices related to the Multi Select fields).
- Multi Select
- Lookup (Multi Select)
- Existing Subform
- Inline Subform
Check Box
For example, the below line of code will throw an error.
rec = Form[ MultiSelect == {"Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5", "Choice 6", "Choice 7"} ];
rec = Form[ MultiSelect IN {"Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5", "Choice 6", "Choice 7"} ];
- contains() function criteria restriction: Records fetched using the fetch records task cannot contain more than one searchString in the contains() function used as a criteria. This restriction is applicable when the criteria are specified for the following Creator fields:
- Multi Select
- Check Box
- Multi Select Lookup
- Subform
SingleSelect_Lookup.MultiSelectField - when you've used a single select lookup field (dropdown or radio) that looks up data from a multi select field in the parent form.
For example, the below line of code will throw an error during script execution since two searchStrings are specified in the criteria.
rec = Form[ MultiSelect.contains({"Choice 1", "Choice 2"}) ];
The following method is the best practice to achieve the use case:
rec = Form[ MultiSelect.contains("Choice 1") && MultiSelect.contains("Choice 2") ];