Kaizen #181 - Mandating Subform Data for Blueprint Transitions using Widget

Hello Developers!

Welcome back to another week of Kaizen! 

This time, we are tackling a common challenge on how to enforce subform data from a different module before allowing a blueprint transition in Zoho CRM Deals module.

Many CRM workflows require checking and collecting related records' data across modules before advancing a deal, case, or order to the next stage. Zoho CRM Blueprint natively support subforms from Quotes, Sales Orders, and Invoices for the Deals module with the help of Associated Items in the transition settings. 

Let us explore how to mandate custom subforms' data from a different module for a blueprint transition.

Why Mandate Subform Data from a Different Module?

In Zoho CRM, subforms manage multiple data entries under a single parent record. However, certain blueprint transitions may depend on subform data from related modules, such as:  

• A Deal's transition may depend on the document data stored in the associated Contact’s subform.
• A Service Request requiring validation against a subform in the related Account before processing.  
• A Loan Application requiring income proof from the Customer’s subform before approval.  

Since blueprint transition rules only validate fields within the same module, you can use a custom widget to check and update subform data across modules before proceeding.

Business Scenario: Insurance Deals Qualification

Consider Zylker, an insurance company, using Zoho CRM to manage customers and streamline processes. Their sales process follows this blueprint when a deal reaches the Qualification stage:

Insurance Sales Blueprint

Steps to Build a Blueprint Widget

Step 1 - Review Basics

Refer to our earlier Kaizen on CLI Installation, Creating a Widget Project, and Internal hosting of the same.

Step 2 - Develop your Widget

After setting up the widget project using CLI, implement the logic based on your business case.

Here’s the logic for the sample use case we are discussing:

Widget Execution During Transition

• When the user clicks the Collect Requirements transition, the widget loads.
• Using the PageLoad event listener, retrieve the current record's ID and module name.
• Use the GET Records API via its JS SDK to fetch the Contact ID linked to the Deal. 
  

ZOHO.embeddedApp.on("PageLoad", function(data) {       // Fetch the current page's record details       const recordId = data.EntityId;       const moduleName = data.Entity;       ZOHO.CRM.API.getRecord({Entity: moduleName, RecordID: recordId})         .then(function(response) {           const record = response.data[0];           console.log("Current Record Details:", record);           // Fetch the associated contact ID  contactId = record.Contact_Name.id;

Check and Collect Required Document Details

• Using the Contact ID, run a COQL query using Connection JS SDK to check if each Document Category has at least one entry in the Document Details subform.

Notes
In invoke connection JS SDK, use param type 2 for the API request payload inside the parameter key and param type 1 for regular parameters.

Explore the Working with Connections help page and create a connection with the necessary scopes to invoke the COQL API.

• If all four categories (Address Proof, ID Proof, Income Proof, Medical Report) have at least one entry, the widget allows the transition immediately.
• If any category is missing, the widget prompts the user to enter the details in a table that mirrors the Document Details subform in the Contacts module.
  

// Make a query API call            const query = {             "select_query": `select Document_Category,COUNT(id) from Document_Details where id is not null and Parent_Id='${contactId}' group by Document_Category`           };           ZOHO.CRM.CONNECTION.invoke("crm_oauth_connection", {             method: "POST",             url: "https://www.zohoapis.com/crm/v7/coql",             parameters: query,             param_type: 2,             headers: {               "Content-Type": "application/json"             }  }).then(function(response) {      const data = response.details.statusMessage.data;             if (response.details.statusMessage === "" || (data && data.length < 4)) {               createSubformUI();               document.getElementById('contentContainer').style.display = 'block';             } else if (data && data.length === 4) {               document.getElementById('messageContainer').style.display = 'block';               // Enable the "Move to Next State" button if all files are already updated               const nextStateButton = document.querySelector('.nextStateButton');               nextStateButton.disabled = false;               nextStateButton.style.backgroundColor = '';              }  })

Update the Contact's Subform

• The user enters the document details and clicks the Save button in the widget. 
• Since subform updates act like a PATCH request, any existing record IDs must be included in the update payload to retain them. To get the existing subform record IDs make a  GET Records API call via its JS SDK. 
  

async function getExisitingSubFormRecords(contactId) { let exisitingRecords = []; awaitasync function getExisitingSubFormRecords(contactId) { let exisitingRecords = []; await ZOHO.CRM.API.getRecord({ Entity: "Contacts", RecordID: contactId }) .then(function (response) { const record = response.data[0]; console.log("Current Record Details:", record); if (record.Document_Details) { record.Document_Details.forEach(function (document) { exisitingRecords.push({id: document.id}); }); } }) .catch(function (error) { console.error("Error fetching records:", error); }); return exisitingRecords; } ZOHO.CRM.API.getRecord({ Entity: "Contacts", RecordID: contactId }) .then(function (response) { const record = response.data[0]; console.log("Current Record Details:", record); record.Document_Details.forEach(function (document) { exisitingRecords.push({id: document.id}); }); }) .catch(function (error) { console.error("Error fetching records:", error); }); return exisitingRecords; }

• Clicking the Save button executes the following actions:
  -> Uploads the selected file to Zoho File System (ZFS) using the Upload File API through its JS SDK.
  -> Updates the Document Details subform in the associated Contact record by adding the file ID from the upload response and each row's entry using the Update Records API (via the Update Record JS SDK).
• Once the subform is successfully updated, the widget allows the transition to next Blueprint state.
  

async function updateRecord(event) { event.preventDefault(); // Collect user entries from each row const rows = document.querySelectorAll('#documentsTable tbody tr'); const documentDetails = await Promise.all(Array.from(rows).map(async (row, index) => { const documentCategory = row.querySelector('select[name="documentCategory"]').value; const documentNumber = row.querySelector('input[name="documentNumber"]').value; const documentName = row.querySelector('input[name="documentName"]').value; const documentFile = row.querySelector('input[name="upload"]').files[0]; const fileId = await uploadFile(documentFile); return { Document_Category: documentCategory, Document_Number: documentNumber, Document_Name: documentName, Upload: [ { file_id: fileId } ] }; })); // Get the existing subform records const existingRecords = await getExisitingSubFormRecords(contactId); // Merge the existing records with the new records existingRecords.forEach(record => documentDetails.push(record)); // Prepare the payload for the update API call const payload = { id: contactId, Document_Details: documentDetails }; // Make the update API call ZOHO.CRM.API.updateRecord({ Entity: "Contacts", APIData: payload }).then(function (updateResponse) { console.log("Update response:", updateResponse); const saveButton = document.querySelector('.saveButton'); saveButton.textContent = "Saved"; saveButton.disabled = false; saveButton.style.backgroundColor = 'grey'; // Enable the "Move to Next State" button after saving const nextStateButton = document.querySelector('.nextStateButton'); nextStateButton.disabled = false; nextStateButton.style.backgroundColor = '';  })

Step 3 - Validate and Pack the Widget

• Follow the steps given in the Widget help page to validate and package the widget.
• Go to Zoho CRM > Setup > Developer Hub > Widgets and click Create New Widget.
• Fill in the required details as shown in this image and ensure to select Blueprint as the widget type.
  
  Creating a Blueprint Widget

Step 4 - Associate the Widget with the Blueprint

• Navigate to Setup > Process Management > Blueprint and open the Deals Blueprint created for this use case.
• Click on the Collect Requirements transition.
  
  Associate Widget to a Blueprint Transition
• In the During tab on the left pane, select Widgets and associate the newly created widget.
• Publish the Blueprint to activate the changes.

Try it Out! 

A complete working code sample of this widget is attached at the bottom of this post for reference. 

 

Now, let us see how this Blueprint works from the Deals page:  

1. All required document details are available: The widget validates the Contact’s subform and allows the transition.  
   
   
   
   
2. Missing or incomplete document details: The widget prompts the user to enter the missing details, updates the Contact’s subform, and then enables the transition.  
   
   
   
   

This approach ensures that required subform data from another module is validated and captured before proceeding with a Blueprint transition.  

Would you like us to address any of your pain-points or have a topic to discuss? Let us know in the comments or reach out to us via support@zohocrm.com.

Until next time, Happy Coding! 

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

Additional Reading

1. Blueprint - An Overview, Designing a Blueprint, FAQs
2. Custom Fields - Working with Custom Fields, Building Subform
3. Connections - An Overview, Invoke APIs via Connections
4. Widget - An Overview, CLI Installation, Working with Widgets, JS SDKs, Mobile Compatibility of Widgets, Kaizens
5. Entity APIs - GET Records, Update Records, Upload Files
6. Query API - An Overview, Records through COQL Query, JOINs in COQL, Subquery, Limitations

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

Previous Post: Kaizen #180 - Automating Data Transfer from Zoho Sheets to Zoho CRM Subforms | Kaizen Collection: Directory

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.

• Topic Participants

• Kiruthiga G

  

• Sticky Posts

• Kaizen #198: Using Client Script for Custom Validation in Blueprint

  Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

• Kaizen #226: Using ZRC in Client Script

  Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

• 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

• Recent Topics

• treatment for rehires

        Hello,  we are aware of the fact that Zoho People at the moment does not has a provision for rejoining exited employees. But is there any quick fix or hack to this? It will be appreciated a lot. 

• Zoho Projects Android and iOS app update: Timesheet module is now renamed as 'Time Logs', delete option has been renamed to 'Trash'.

  Hello everyone! We have now renamed the Timesheet module as Time Logs and the delete option as 'Trash' on the Zoho Projects Android and iOS app. Time Logs Android: Time Logs iOS: Trash option Android: Trash option iOS: Please update the app to the latest

• Zoho Mail app update: Manage profile picture, Chinese (Traditional) language support

  Hello everyone! In the latest version (v3.1.9) of the Zoho Mail app update, we have brought in support to manage profile picture. You can now set/ modify the profile picture within the app. To add a new profile picture, please follow the below steps:

• Reminders for Article Approval

  Is there a way to send reminders for approvers to review articles and approve/deny them? I'm not seeing that option anywhere.

• Add Full-Screen Viewing for Quartz Recordings in the Client Interface

  Hi Zoho Team, We would like to request an enhancement to the Zoho Quartz client interface when viewing submitted recordings. Current Limitation: When viewing a Quartz recording from the client (user) interface, there is currently no option to switch the

• 2025 Recap: A Year to Remember | Zoho Inventory

• Important Update : Pipedrive deprecated fields no longer supported in Zoho Analytics

  Dear Pipedrive users, We would like to inform you about a recent update related to your Pipedrive integration with Zoho Analytics. The Pipedrive team has deprecated certain fields from their application. You can find more details in the official Pipedrive

• Product Updates in Zoho Workplace applications | November 2025

  Hello Workplace Community, Let’s take a look at the new features and enhancements that went live across all Workplace applications this November. Zoho Mail Format comments easily using Slash Commands With Slash commands, you can easily format text, insert

• Right-Click Pipeline to Open in New Tab

  Please add the ability to right-click on a pipeline to open it in a new tab

• Adjusting Physical Inventory

  Not getting very far with support on this one, they say they are going to fix it but nothings happened since November. Please give this a thumbs up if you would like to see this feature or comment if you have some insight. Use Case: Inventory set to be

• sync views to sheet

  Im looking to sync my views aka reports in analytics to zoho sheets, when data is updated in analytics it also should be updated in sheets, till now zoho sheets only offer raw data connection and it is not enough as these reports are difficult to re-do

• How to update the Status in a custom module?

  Hi, I have a custom module "cm_payment_registry" in Billing, I am trying to change the status which is "Draft" with: array = {"custom_status":"Approved"}; zoho.billing.update("cm_payment_registry",organization.get("organization_id"), XXXXXXXXXXXXXX, array,"connectionname");

• Replace Zoho Invoice with QuickBooks

  We are implementing Zoho FSM for a cleaning business in the US with 50+ field workers. This business has been using Quickbooks for accounting for decades and will not migrate to Zoho Books. A major issue in the integration is the US sales tax calculation.

• 2025 Highlights: A Year of Steady Progress and Significant Developments

  As we come to the end of 2025, let's take a moment to reflect on the significant progress and developments we've made to improve your travel and expense management. In the Spotlight Introducing Online Booking (US edition only - Early access) Enable online

• Function #42: Show the actual rate of items on invoices

  Hello everyone, and welcome back to our series! In Zoho Books, you have the ability to create Price Lists, wherein you can mark up and mark down the item rates by a specific percentage or set custom rates. Generally, when you apply a price list to an

• Ability to Set Text Direction for Individual Cells in Zoho Sheet

  Dear Zoho Sheet Team, We hope you are doing well. We would like to request an enhancement in Zoho Sheet that allows users to set the text direction (right-to-left or left-to-right) for individual cells, similar to what is available in Google Sheets. Use

• Warehouse fast processing

  Hey guys, would anyone be interested in something like the attached image ? If there's any interest I'd be willing to develop it further for others to use, it's much faster than using Zohos native solutions, it can part pack, pack in full, part ship,

• Can I create a CODE 128 custom field for my items in Zoho Inventory and then use it for generating Sales Orders?

  Can anyone helps me, I don't want to use the SKU code for scanning my products.  ​Because all my products have a CODE-128 label attached.

• Start/Stop Timmer in Chrome Extension

  The chrome extension is great and allows you to do allot however one of the most common things employees working on projects need to do is track their time. Having an easy start/stop timer to track time would be great.

• Invalid collection string

  I haven't changed anything in one of my functions. I'm trying to run it manually and suddenly "Invalid collection string" appears. My code has 6 lines and the error says that the error is on 7th line. Why? What does this error mean? Nothing has been changed

• Zoho Directory 2025: New Features | Security Enhancements | Enriched UI

  Hello everyone, Greetings from the Zoho Directory team! 2025 has been a highly successful year for Zoho Directory. We are delighted to introduce a fresh set of features, an enriched UI, and major product enhancements. These updates aim to deliver a smoother

• zoho people 5 report

  How do I customize my report in Zoho People Report? I understand that I can get the results of multi-table queries through SQL join statements, but I don't know the relationship between each table. I tried to create a report using Attendance User Report

• Leave Report Emailed Weekly

  I am wondering if someone knows how to have a report generated either weekly or monthly or both for department heads and ownership of upcoming employee leave. For instance, it would be nice to get an emailed report on Friday for the upcoming week of who

• Zoho Flow Decision Continuing Despite Not Meeting Conditions

  I have a picklist field called Lead Status in the leads module, with the following lead Statuses: New Lead Attempted Contact - 1 Attempted Contact - 2 Attempted Contact - 3 Attempted Contact - 4 Attempted Contact - 5 Attempted Contact - 6 Attempted Contact

• Tip #55- Accessibility Controls in Zoho Assist: Exploring Vision Settings- 'Insider Insights'

  As we approach the end of the year, it’s a good moment to reflect on how we can make our tools more inclusive and easier to use for everyone. Remote support often involves long hours in front of screens, varied lighting conditions, and users with different

• Zoho Recruit Slow and Freezing on all screens

  We have had an issue with Zoho Recruit for weeks being extremely slow and at times freezing.  We have 100 mega internet, and I went into each computer and updated the virtual memory so there is more available.  Also restarted all computers daily.  Still having the issues.  Almost unable to work.

• Credit Management: #2 Configuring Right Payment Terms for Credit Control

  Think about the last time you ordered something online and saw that little note at the checkout, "Pay on Delivery" or "Pay later". It's simple, but it actually sets the tone. As a business owner, you know exactly when payment is expected. Now, imagine

• Dependent (Conditional) Fields in Zoho Bookings Forms

  Hello Zoho Bookings Team, Greetings, We would like to request the ability to create dependent (conditional) fields in Zoho Bookings registration forms. Current Limitation: There is currently no way to make one field’s available options depend on the value

• Bug Report: Search fails to find existing notes after Evernote import

  Hello, I recently migrated from Evernote (~2600 notes across 23 notebooks), but the search functionality is currently broken. The Issue: I can manually browse to a specific note and see it exists. However, when I type the exact or partial title of that

• Marketing Tip #13: Win repeat customers with post-purchase emails

  The relationship with your customer doesn’t end after the sale; that’s when it begins. A thoughtful post-purchase message shows customers you appreciate them, keeps your brand top of mind, and can even lead to another sale. You can thank them, ask for

• Zoho Form

  I have problem with Zoho Form. One of form i don't received the PDF version. Others okay except this one. W904533

• Create & Update Zoho Vault Passwords via Zoho Flow

  Hi Zoho Flow / Zoho Vault Team, We’d like to request an enhancement to the Zoho Vault integration in Zoho Flow. Current Limitation: At the moment, Zoho Flow supports only the following selected Zoho Vault actions, such as: Fetch passwords, Share passwords

• Custom Related List Inside Zoho Books

  Hello, We can create the Related list inside the zoho books by the deluge code, I am sharing the reference code Please have a look may be it will help you. //..........Get Org Details organizationID = organization.get("organization_id"); Recordid = cm_g_a_data.get("module_record_id");

• Migrate different zoho subscription to zoho one

  Dear We have different zoho subscription we need to migrate it to zoho one. Currently we are paying for zoho email, zoho expense, zoho payroll etc under different admin We need to move it too zoho one flexlible plan for all my employees

• Features, Feedback and Votes

  We’re launching the Feedback Forum for our customers. This is 'THE' place where you can add everything you’d like to see in Zoho Books. If you don't find the specific feature you need, simply add it so others can also vote for it. While we cannot promise

• There Might Be A Glitch in Determining If A String Represents A URL

  I suspect there might be a glitch in determining if a string represents a URL or not. For example, I cannot embed the following URL. Perhaps the exclamation mark or parentheses are the culprit? https://en.wikipedia.org/wiki/How_the_Grinch_Stole_Chri

• Customer Management: #4 Enhance Customer Journey

  When Neha started DefineOps, a growing IT support and consulting firm, most of her work was straightforward. A client would sign up for a free version, decide whether the service works for them, and then either continue or discontinue. Billing was simple,

• Android app sync problem - multiple devices have same problem

  Hello, I am having a problem with synchronization in the Android app. When I create a drawing, the data does not sync correctly—only a blank note is created without the drawing. I tested this on multiple devices, including phones and tablets, and the

• Marketing Tip #1: Optimize item titles for SEO

  Your item title is the first thing both Google and shoppers notice. Instead of a generic “Leather Bag,” go for something detailed like “Handcrafted Leather Laptop Bag – Durable & Stylish.” This helps your items rank better in search results and instantly

• Territory Assignment Issues (Lead to Account + Contact)

  1. Lead → Account & Contact Territory Assignment on Conversion A Lead is automatically assigned one or more territories using a workflow and Lead Assignment Rules. This works as expected, and we are able to assign multiple territories to a Lead automatically.

• Next Page