Choose where you’d like to start

Get Records

Table of Contents

Note: The Creator V1 integration tasks are deprecated and will work until Creator V1 APIs reach their end of life on February 3rd, 2021. Click here for Zoho Creator V2 integration tasks.

Overview

This task is used to fetch records from an application in Zoho Creator.

Syntax

<variable> = zoho.creator.v1.getRecords(<ownerName>, <appLinkName>, <viewLinkName>, <condition>, <fromIndex>, <toIndex>, <connectionlinkName>);

where,

ParameterData TypeDescription

<variable>

LIST

Variable which will hold the returned response.

<ownerName>

TEXT

is the name of the owner of the app from the records will be fetched.

Name of the app owner is present in the url while editing the app: creator.zoho.com/appbuilder/<appOwner>

App owner name can also be fetched using the system variable zoho.adminuser

<appLinkName>

TEXT

is the link name of the application from which the records will be fetched.

Link names of applications, reports, and fields in your account can be viewed here (listed in brackets).

Application Link name can also be fetched using the system variable zoho.appname

<viewLinkName>

TEXT

is the link name of the view (report) from which the records will be fetched.

Link names of applications, reports, and fields in your account can be viewed here (listed in brackets).

<condition>

​
(optional)

TEXT

is the condition based on which records will be fetched.

The condition must be in the following format:
"<fieldLinkName>==<searchValue>"

Lookup fields must be specified in the format <LookupFieldLinkName>.<displayFieldLinkName>

Note: If your search condition contains hard-coded string value, it needs to be enclosed in double quotes escaped with backslashes. For example, the search condition, "Task_Name==Service Task" should be provided as "Task_Name==\"Service Task\"".

<fromIndex>

<toIndex>


(optional)

NUMBER

<fromIndex> is the starting index of the records (which meet the criteria) that will be retrieved.

<toIndex> is the last index of the records (which meet the criteria) that will be retrieved.

Only first 20 records will be fetched if <fromindex> and <toindex> params are not specified. 

You can specify the <fromindex> without specifying <toindex>, in which case 20 records will be fetched starting from the specified <fromindex>.

The <toIndex> param cannot be specified without the <fromIndex> param.

Using <fromindex> and <toindex> params you can fetch upto 200 records. So, if the difference between the <fromindex> and <toindex> exceeds 200, only the first 200 records will be fetched.

<connectionLinkName>

(optional)*

TEXT

is the name of the Zoho Creator connection.

*Note

  • The connectionLinkName is mandatory when executed in Zoho Cliq.
  • The connection should be authtoken based. To create authtoken based connection with Zoho services, choose the default service - Zoho under pick your service in connections page.

Example 1

Let us consider the below example of searching for a record using a condition in Zoho Creator. The record whose task name is ServiceTask is being fetched here.

Assume that we have a form with the two fields - Task_Name (Single Line Field Type) and Task_Description (Single Line Field Type). The arguments - Task_Management (Application Link Name), Create_Task (View Link Name), john (Owner Name) will be supplied to getRecords task in the following example.

response = zoho.creator.v1.getRecords("john","Task_Management","Create_Task","Task_Name == \"ServiceTask\"");

where,

response
is a KEY-VALUE pair that holds the response of the getRecords task
john
is a TEXT value that represents the application owner's name
Task_Management
is a TEXT value that represents the application's link name
Create_Task
is a TEXT value that represents the view's link name
Task_Name == ServiceTask
is a TEXT value that represents the condition to search records

Example 2

Let us consider the below example of searching for records without a condition or the start and end indices in Zoho Creator.

response = zoho.creator.v1.getRecords("SampleApps","Task_Management","Create_Task");

Example 3

Let us consider the below example of searching for a record using a condition in Zoho Creator.

Assume that we have a form with a lookup field - Department (Lookup Field Type) which refers to the Name (single line field type) field in the related form called "Department". The arguments - Employee_Management (Application Link Name), Employees (View Link Name), tony (Owner Name) will be supplied to getRecords task in the following example.

response = zoho.creator.v1.getRecords("tony","Employee_Management","Employees","Department.Name == \"Electrical\"");

where,

response
is a KEY-VALUE pair that holds the response of the getRecords task
tony
is a TEXT value that represents the application owner's name
Employee_Management
is a TEXT value that represents the application's link name
Employees
is a TEXT value that represents the view's link name
Department.Name == Electrical
is a TEXT value that represents the condition to search records

Sample Response

Success Response for Example 1

Following is a successful response received after fetching a record

{
"Task_Description":"I need help installing my air conditioner",
"ID":3605445000000075003,
"Task_Name":"ServiceTask"
}

Success Response for Example 2

Following is a successful response received on fetching records without a condition/index

{"Task_Name":"Priority Task","Task_Description":"I need help installing my air conditioner","ID":"3605445000000075003"},
{"Task_Name":"Support Ticket1","Task_Description":"Toaster Configurations","ID":"3605445000000065010"},
{"Task_Name":"Support Ticket2","Task_Description":"Help me fix it","ID":"3605445000000065003"},
{"Task_Name":"Support Task1","Task_Description":"I need a call back","ID":"3605445000000063122"},
{"Task_Name":"Support Task1","Task_Description":"My new box broke","ID":"3605445000000063115"},
{"Task_Name":"Task1","Task_Description":"I need a technician visit my place","ID":"3605445000000058048"},
{"Task_Name":"Task2","Task_Description":"The water ain't flowing through the hose","ID":"3605445000000058043"},
{"Task_Name":"Tasks1","Task_Description":"Please get my iron box fixed ASAP","ID":"3605445000000058036"}


To get the IDs of the fetched records, execute the following snippet:

for each <loop_variable> in <response_variable>
{
info var.get("ID"); ​
}

Error

Following is an error when the user tries to search for a record with an incorrect application name:

{
"message":"Please verify whether you gave a valid ownerName,appLinkName and viewLinkName or not",
"status":"Failure"
}

Following is an error when the user tries to search for a record with a non-existent or incorrect record ID:

{
"message":"There is no records match for this condition"
}

Related Links

  • To fetch the string value to which the specified key is mapped, use get()
  • To get values from fetched records, use getJSON()
  • To get the Application Owner Name, Application Link Name, Form Link Name and/ or View Link Name, please visit Creator API Link Names

Get Started Now

Execute