Kaizen #172 - Leveraging the 'crmAPIResponse' Object in Queries

Hello everyone!

Welcome back to another week of Kaizen!

We released the Queries feature sometime back and hope you have tried it out.

A little gist about this feature before we move on to our post.

Zoho CRM's Queries feature enables dynamic data retrieval from both CRM modules and external services, facilitating seamless integration and informed decision-making.

Key Components

• Sources: Pre-configured sources like Modules and COQL are available, with the option to add custom sources via REST APIs.
  
• Queries: Fetch data by selecting modules, writing COQL statements, or specifying REST API endpoints, headers, and parameters.
  
• Variables: Incorporate variables in criteria, COQL statements, and endpoints to pass dynamic values during execution.
  
• Schema: Auto-generated schemas define the structure of query responses, with editable paths, field types, and labels for customization.
  
• Serializer: Utilize JavaScript to manipulate and customize query responses, ensuring data is in the desired format for further processing.
  

Types of Queries

• Modules: Retrieve records by selecting specific modules and fields, applying conditions to filter data as needed.
  
• COQL (CRM Object Query Language): Write SQL-like queries to fetch data, supporting complex operations like joins and aggregations.
  
• REST API: Fetch data from external services by specifying endpoints, headers, parameters, and connections.
  

With the Queries feature, you can efficiently access and display relevant data within Zoho CRM, enhancing workflow efficiency and decision-making capabilities.

A little insight into Functions before we dive into today's Kaizen!

Functions, Queries, you get the connection, right? Read on!

Many of us use Functions in Zoho CRM extensively to perform our business logic and customize the way things work in Zoho CRM. You can use Functions in blueprints, workflows, Circuits etc.

Let's say you have a function that gets the employee records from the Employees module. Technically, the function executes an API call or an integration task, and gives a response.

The response can be a string or map(JSON), depending on how the function is written and where it is used. Since functions can be used in many places, the same response format may not be the right one to be used in a circuit or a workflow.

This is where the genie 'crmAPIResponse' object comes into picture!

The power of the 'crmAPIResponse' object

The crmAPIResponse object to be returned in the CRM function should encapsulate the response in a way that it can be used in Queries, Circuit, workflow etc. The details needed are encapsulated as a map. It should include details like crmStatusCode, status, message, body in order to construct the desired format for handling data and customizing the error handling logic.

Let's consider the following example function where we use the getRecordByID integration task.

The response of the integration task contains all the fields in that module, but we want only certain parts of the response JSON and also add custom error messages, to be used in other components like Queries, Circuits, etc,.

Here is the code.

{ leadId = "3652397000018025772"; // Replace with a valid Lead ID // Initialize customAPIResponse map customAPIResponse = map(); // Fetch lead details crmResponse = zoho.crm.getRecordById("Leads", leadId); // Log the raw response for debugging info "CRM API Raw Response: " + crmResponse; // Validate and process the response to include only the required fields if (crmResponse != null && crmResponse.containsKey("id")) { // Extract required fields filteredData = map(); filteredData.put("id", crmResponse.get("id")); filteredData.put("Last_Name", crmResponse.get("Last_Name")); filteredData.put("Email", crmResponse.get("Email")); customAPIResponse.put("crmStatusCode", 200); customAPIResponse.put("status", "success"); customAPIResponse.put("message", "Lead data retrieved successfully."); customAPIResponse.put("body", filteredData); // Include only filtered data } else { customAPIResponse.put("crmStatusCode", null); customAPIResponse.put("status", "error"); customAPIResponse.put("message", "Invalid or null response from Zoho CRM API."); customAPIResponse.put("body", null); } // Return the customAPIResponse return {"crmAPIResponse": customAPIResponse}; }

Here, you can see that we have parsed the response of the integration task to get the Last_Name, Email, and record ID using the crmResponse.get("field_API_name") statement and constructed the customAPIresponse object using the customAPIResponse.put("key", "value") statement.

The statement return {"crmAPIResponse": customAPIResponse}; returns the response body as depicted in the previous statements.

Response to the info "CRM API Raw Response: " + crmResponse; statement

"CRM API Raw Response: {"Owner":{"name":"Patricia Boyle","id":"3652397000000186017","email":"p.boyle@zylker.com"},"$field_states":null,..}}}

Response of the return {"crmAPIResponse": customAPIResponse}; statement

{     "crmAPIResponse": {         "crmStatusCode": 200,         "status": "success",         "message": "Lead data retrieved successfully.",         "body": {             "id": "3652397000018025772",             "Last_Name": "Math",             "Email": "math@gmail.com"         }     } }

Error response

{     "crmAPIResponse": {         "crmStatusCode": null,         "status": "error",         "message": "Invalid or null response from Zoho CRM API.",         "body": null     } }

You can see that we have used the crmAPIResponse object to get only the required keys from the response and constructed a much simpler response.

Refer to our help page on Response Object for more details.

Finally, to today's Kaizen!

We've established that you can use the crmAPIResponse object to construct responses in a way that's suitable to be consumed at another place like a circuit or a workflow.

We also know that Queries allows you to have sources of the REST API type to fetch data from various sources. This means that you can have a standalone function that is enabled as a REST API as a source in Queries.

Let's see an example.

There is a simple function that uses the getRecords integration task to get the records from the Employees module.

I have used the crmAPIresponse object to construct a response as shown in the following code.

string standalone.getRecords() { result = zoho.crm.getRecords("Employees"); response = Map(); response.put("status_code",200); response.put("body",{"code":"success","details":result,"message":"function executed successfully"}); return {"crmAPIResponse":response}; }

The response of this function is a string in the crmAPIResponse object as shown in this image.

1. Save this function and enable REST API.
   
   
2. You can see that the domain is https://www.zohoapis.com. To be able to use this in a Query, register this domain in Trusted Domain.
   
   
3. To create a REST API type source, you must add the source. Go to Setup > Developer Hub > Queries > Sources tab.
4. Click Add Source and give the details like the name, base URL, headers, and parameters under the Information section.
   
   
5. Click Save.
6. Go to the Queries tab and click Add Query.
   
7. For Source, choose the source you just added.
   
8. Under Information, enter the name, API name of the query.
   
9. For the endpoint, enter the API Key URL of the function.
   
   
10. Enter the parameter name and values in the Parameter field.
    
11. Click Add Serializer if you want to serialize the response. In this example, I have serialized the response to include only the Name, Email, and Position fields in the output. The result contains the 'body' object that we returned in the crmAPIResponse object of the function.
    
    
    
    
12. Click Save to save the serialization.
    
13. Click Next to view the schema of the query. Make changes as required.
    
14. Save the query.
    

You can now use this query in Canvas or associate it with Kiosk to solve your business needs.

Let us see how the crmAPIResponse object in the function affects the response of the query.

Query with the function without crmAPIResponse:

Let's consider that the function getRecords() does not use the crmAPIResponse object. In that case, the function returns a response that is a string. This response string cannot be serialized or used elsewhere.

Schema of the query without crmAPIResponse:

Query with the function with crmAPIResponse and serialization:

The same getRecords() function that uses the crmAPIResponse object allows you to construct the response as JSON. You can serialize this response easily and use it in a circuit, query, workflow etc.

You can see here that the response is now a JSON.

Schema of the query with crmAPIResponse:

In conclusion, you can use the crmAPIResponse object in Functions to construct the desired response and use the REST API-enabled function as a source in Queries.

Leveraging the advantage of the crmAPIResponse object in functions and using it in Queries increases the prospect of solving many more business cases easily and customize more efficiently.

We hope you liked this post and found it useful. Let us know your thoughts in the comments.

If you'd like us to cover any other topic in this series, feel free to comment or reach us at support@zohocrm.com.

Cheers!

------------------------------------------------------------------------------------------------------------------------------------------------

More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog for detailed information on these updates.

See Also

• Related Kaizen - Handling Variables in Queries, Serialization and Schema Management in Queries 
• Queries in Zoho CRM
  
• Functions in Zoho CRM
  
• Response Object in Zoho CRM
  
• Previous Kaizen - FAQs on COQL API
  
• Kaizen Directory
  

• Topic Participants

• Shylaja S

  

• Zsolt Simon self-employed

• Sticky Posts

• Kaizen #222 - Client Script Support for Notes Related List

  Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Kaizen #152 - Client Script Support for the new Canvas Record Forms

  Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

• Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

  Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

• Recent Topics

• Inventory batch details

  Hi there, I'm trying to get the batch details of an item, here's what I've done so far. I've sent cUrl request to the below endpoint and I get a successful response. Within in the response I find the "warehouses" property which correctly lists all the

• Auto check out after shift complete

  i'm just stuck here right now, i wanna know how to do this thing, now tell me, how can i configure a custom function that runs after complete shift time if employee forget to check-out ?

• How to create a flow that creates tickets automaticaly everyday based on specific times

  Hi guys Does anyone know how to create a flow that will create tickets automaticaly in ZOHO Desk when a certain time is reached. Im havin a hard time configuring a flow that will create tickets automaticaly everyday during specific hours of the day For

• ZOHO FLOW - ZOHO CREATOR - ZOHO WRITER : Get Related records

  Bonjour, J'ai besoin que vous m'ajoutiez la solution "Get related Records" dans la liste de choix de zoho creator (sous Zoho flow). En effet, j'ai besoin de récupérer les champs d'un sous formulaire pour l'ajouter à l'impression de mon document. Mer

• Will zoho thrive be integrated with Zoho Books?

  title

• Connecting email for each department in ZohoDesk

  Hi! Could someone help me to go through connecting emails for each department?

• How do I trigger a Flow based on a campaign response?

  Is there a way to trgiider a Zoho Flow based upon a lead opening an email sent via Zoho Campaigns? I see that the data is recorded in the 'Campaigns' section of Zoho CRM under 'Member Status' and I want to trgigger a flow based upon that record changing.

• All Zoho Flows are filtered

  My two flows operate perfectly when I run them as a test, but when they're activated each run ends with a status of neither success, nor fail, but filtered. I haven't set up any filters. I don't see where to turn off filters. When I test run on a sequence

• Creating Multiple Items on Sales Order

  Hi, I’m trying to automate some processes using Zoho Flow, specifically the creation of sales orders in my Zoho Inventory. However, Zoho Flow's Create Sales Order function can only add one item. I would like to include multiple items in a single sales

• Problem Connection from Zoho Flow and Gravity Form

  I obtained my API key from Gravity Forms via WordPress. However, when I enter my Zoho Flow, it states: Gravity Forms says, 'You are not authorised to access the API." I tried recreating a new API key, but it is still not working.

• Eventbrite Email Field in Zoho Flow Returns "Info Requested" Instead of Actual Email

  Hi Zoho team, I'm using Zoho Flow to connect Eventbrite with Zoho CRM. My goal is to automatically add event attendees as leads in Zoho CRM. I’ve set up the flow and mapped the ${trigger.profile_email}} field to the Email field in CRM. However, I'm running

• "Invalid value passed for Product ID" Error in Zoho Flow "Create Sales Order" Node

  Hello Zoho Community, I’m facing an issue with Zoho Flow while trying to create a sales order in Zoho Inventory using the "Create Sales Order" node. Here’s a detailed explanation of my setup and the problem: What I’m Trying to Achieve I’m building an

• Associating Project with an Account via Flow

  I'm using flow to create a Project based on a Deal status update using flow. The fields exist to pass the Account Name through properly, but when you view the Projects module in a CRM Account Record it doesn't automatically associate the new Project Record

• How to follow up a member in a meeting?

  Hello, I make weekly meeting online with a lot of people. I want(I've been using calendly to do it). I want to do a follow-up to it. I want to send messages via Zoho-flow to all the member that participated in the meeting. How can I do it?

• Setting Delays in Invoice Reminder Flow

  I am currently working on a flow that sends reminders for unpaid invoices. The flow is designed to delay actions until specific intervals before the due date: A reminder should be sent 7 days before the due date. A second reminder should be sent 3 days

• Get Sales Orders Related to Inventory Item

  Dear Team, I'm just wondering if there is a way to get a list of all Sales Orders related to a specific Inventory Item. I did search all articles but couldn't find any article that could help.

• Endpoint Central Cloud Asset Update from Fresh Service

  All, Does anyone use the asset management feature in Fresh Service? I'd like some help on building a flow to update asset attributes in Endpoint Central Cloud based off of an update to that same asset in Fresh Service. The trigger is "asset is updated"

• Zoho Flow Export to Deluge

  It would be great to take a user built zoho flow and export the entire flow as a deluge script including having multiple connected applications (showing the API connections and webhooks) and different functionality in the other applications interacting

• Action Iteration/Loop using Zoho Flow

  Trying to use Zoho Flow for automating following Context - A zoho form entry which has image upload field with upto 5 images setting and files are saved into Workdrive. After form is submitted need to create folder based on some fields and move files

• Zoho Flow - Unable to evaluate formatDate with Zoho Invoice Date Field for Calendar Integration

  Hello Community, I'm trying to automate the creation of all-day events in Zoho Calendar whenever a new invoice is created in Zoho Invoice. I'm using Zoho Flow for this automation. My Goal: When an invoice is created with a specific "Event Date," I want

• Zoho Inventory Sales Order Items

  I'm trying to build automation using Zoho Flow to add items to a Sales Order. In the automation options for both "create sales order" and "update sales order", The item ID is required. However, when I update the Sales Order, it's just replacing the item

• Permissions for Azure Devops connection

  I am trying to set up a connection with our Azure DevOps org but it keeps giving me this error. On Azure I should be able to have admin-level access to everything. Can you please point me to which permission this is checking for so I can enable it?

• Best way to start zoho inventory with bulk openning stock

  We are already using zoho book since long time for cars trading company. Now to streamline more, would like to import the excel data of closing stock of inventory to zoho inventory and to start on. Since we need to track each VIN (unique vehicle id number)

• My IMAP mail suddenly stopped working

  On my iPhone and iPad, IMAP stopped working for my Zoho account with the error "User name or password incorrect" and "Invalid credentials failure" however I was able to access via web with the same credentials. Also stopped working on Apple Mail client.

• Confused by the distiction between matched and categorized when reconciling a bank statement an how to

  I used to use quickbooks. In quickbooks, it was possible to use the check writing feature to add an expense that was on the bank statement that did not go through the AP and check writing process. I would write a check, assign it a number like etf (for

• Not Receiving OTP • https://voters.eci.gov.in/home/family

  Hello Customer, Greetings from Zoho Mail. Upon a detailed review of our delivery logs, we can confirm that other Zoho Mail users are successfully receiving OTP emails from eci.gov.in. However, in your specific case, it appears that the OTP emails are

• WorkDrive for Excel Add on

  Dear Sir/Madam Have installed Workdrive for Microsoft add on But unable to view the same added in Excel

• Zoho Calendar s’enrichit avec une intégration à Zoho People et Zoho Cliq

  Les journées de travail ne se déroulent jamais exactement comme prévu. Une conversation informelle devient une séance d’échange d'idées, une absence modifie un planning, et votre agenda se retrouve vite décalé par rapport à la réalité. Chez Zoho Calendar,

• Holidays

  Hi; For defining Holidays, you need to add logic to handle the year as well as the month & day. We need to be able to enter Holidays for the next year. I need to add a holiday for January 2, 2017, but I can't until January 1st, which is a Sunday and we

• Zoho public comments are confusing and unnecessary

  Hi, we use zoho desk and have issues with public comments. We started using them because the "Reply" option just seemed very clumsy because of the following reasons: - the top "Reply" button starts what seems to be a regular email, showing the entire

• Introducing parent-child ticketing in Zoho Desk [Early access]

  Hello Zoho Desk users! We have introduced the parent-child ticketing system to help customer service teams ensure efficient resolution of issues involving multiple, related tickets. You can now combine repetitive and interconnected tickets into parent-child

• Zoho API - ticket creation - Validation failed for the condition : Ticket Status Info should not be empty

  Hi ! I'm trying to create ticket through Zoho API, and I'm getting a 422 response : "Validation failed for the condition : Ticket Status Info should not be empty" My request looks like this : curl --location 'https://desk.zoho.eu/api/v1/tickets' \ --header

• Deleting unwanted ticket replies

  Hello, In a Zoho Desk Ticket thread, sometimes one of the recipients has auto-reply activated. This creates a new message in the Ticket thread that not only pollutes the thread, but most importantly cannot be replied properly because usually auto-reply e-mails don't do "reply all", so the other recipients are not included. I want to delete such a message in the Ticket thread. I searched the help of Zoho Desk, but only found a way to mark as Spam (https://help.zoho.com/portal/kb/articles/marking-support-tickets-as-spam)

• Desk DMARC forwarding failure for some senders

  I am not receiving important emails into Desk, because of DMARC errors. Here's what's happening: 1. email is sent from customer e.g. john@doe.com, to my email address, e.g info@acme.com 2. email is delivered successfully to info@acme.com (a shared inbox

• System-generated support email added in CC on “Reply All”

  Hi, I recently set up Zoho Desk for a client and we are trying to prevent the Zoho Desk system-generated support email address (not the mailbox used as the department’s "From address") from being automatically added in CC when agents use “Reply All” on

• Applying Excess Payments & Conflict Invoices Due to Cancelled Items

  I’m running into several issues that appear to stem from deeper-than-expected overlap between Zoho Finance (Books/Inventory) and Zoho POS. The level of coupling between these systems seems greater than what was originally communicated, and it’s leading

• Please, make writer into a content creation tool

  I'm tired of relying on Google Docs. I'm actually considering moving to ClickUp, but if Writer were a good content creation tool instead of just a word processor, I would finally be able to move all my development within the Zoho ecosystem, rather than

• Zoho Sheet - Desktop App or Offline

  Since Zoho Docs is now available as a desktop app and offline, when is a realistic ETA for Sheet to have the same functionality?I am surprised this was not laucned at the same time as Docs.

• Convenience Fees

  I use Zoho Invoice for invoicing my billboard customers.  I have a few customers that want to pay using credit cards and ACH.  As a result, I have integrated an Online Payment Gateway (Stripe) for these customers.  I currently charge these customers a "Convenience Fee" of 3% for using this service as I typically only take checks as payment (and the gateway charges 2.9% + $0.30 per transaction).  I do this by creating a separate line item on the invoice and adding 3% to it.  I would like to offer

• HTML Tags added to Reports with Notes

  Recently Zoho added the ability to markup text within notes. That way, users can change font size, colors, etc. It's a great change. However, since the change, reports that include a column for "Note Content" are printing HTML tags within the report.

• Next Page