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

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
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

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


Info
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.

    Access your files securely from anywhere

        All-in-one knowledge management and training platform for your employees and customers.








                              Zoho Developer Community



                                  Bootcamp
                                  Community
                                  Pricing
                                  Webinars
                                  What's New
                                  Integrations
                                  Contact Support
                                  Contact Sales
                                    Zoho Survey Resources
                                      Features
                                      Survey Templates
                                      Integrations
                                      Community
                                      iOS Mobile Surveys
                                      Pricing
                                      Android Mobile Surveys
                                      Insurvey Blogs
                                      Insight Blogs
                                      Tips & Tricks





                                                  Latest Feature Updates

                                                    • Desk Community Learning Series


                                                    • Digest


                                                    • Functions


                                                    • Meetups


                                                    • Kbase


                                                    • Resources


                                                    • Glossary


                                                    • Desk Marketplace


                                                    • MVP Corner


                                                    • Word of the Day


                                                    • Ask the Experts




                                                        Zoho SalesIQ Resources

                                                              • 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


                                                              Manage your brands on social media
                                                              Access Zoho Social

                                                                Zoho Pagesense Resources


                                                                    Zoho TeamInbox Resources

                                                                      Zoho DataPrep Resources


                                                                        Zoho CRM Plus Resources

                                                                          Zoho Books Resources


                                                                            Zoho Subscriptions Resources

                                                                              Zoho Projects Resources


                                                                                Zoho Sprints Resources


                                                                                  Qntrl Resources


                                                                                    Zoho Creator Resources



                                                                                        Zoho CRM Resources

                                                                                        • CRM Community Learning Series

                                                                                          CRM Community Learning Series


                                                                                        • Kaizen

                                                                                          Kaizen

                                                                                        • Functions

                                                                                          Functions

                                                                                        • Meetups

                                                                                          Meetups

                                                                                        • Kbase

                                                                                          Kbase

                                                                                        • Resources

                                                                                          Resources

                                                                                        • Digest

                                                                                          Digest

                                                                                        • CRM Marketplace

                                                                                          CRM Marketplace

                                                                                        • MVP Corner

                                                                                          MVP Corner









                                                                                            Design. Discuss. Deliver.

                                                                                            Create visually engaging stories with Zoho Show.

                                                                                            Get Started Now


                                                                                              Zoho Show Resources

                                                                                                Zoho Writer

                                                                                                Get Started. Write Away!

                                                                                                Writer is a powerful online word processor, designed for collaborative work.

                                                                                                  Zoho CRM コンテンツ




                                                                                                    Nederlandse Hulpbronnen


                                                                                                        ご検討中の方




                                                                                                                • Recent Topics

                                                                                                                • Set Warehouse based on Vendor

                                                                                                                  Greetings. I would like to set automaticaly the Warehouse based on the Vendor. Context: I am working on an adaptation of a Purchase Order to be used as a Quotation. I have defined that when a user has to raise a quote the Vendor will be "PROCUREMENT" I would like to set the Warehouse to a predefined value when "PROCUREMENT" is set as Vendor. I have tried to do with the Automation feature using the Field Update option, but Warehouse does not is listed as a field. Can you help? Thanks in advance.

                                                                                                                • Auto tagging

                                                                                                                  Some of the articles I enter into Notebook get there when I enter them in Raindrop.io and IFTTT copies the articles in Notebook. When this happens the notes are tagged but instead of useful one word tags with topic the tag pertains to the specific article

                                                                                                                • How do I save audio files to my PC that I record into Zoho Notebook from my phone?

                                                                                                                  I was thinking of using Zoho Notebook as a way to store composition ideas, as well as for other things if it can handle this. For this to be useful for me though, I need to be able to have an easy way to download those audio files to my PC, either individually

                                                                                                                • Search mails in shared mailbox

                                                                                                                  Hi everyone, is there a way to search mails in shared mailbox's? Search in streams or mail doesn't return anything from mails in shared mailboxes. Thanks! Rafal

                                                                                                                • Kaizen #186 : Client Script Support for Subforms

                                                                                                                  Hello everyone! Welcome back to another exciting Kaizen post on Client Script! In this edition, we’re taking a closer look at Client Script Support for Subforms with the help of the following scenario. " Zylker, a manufacturing company, uses the "Orders"

                                                                                                                • Writing SQL Queries - After Comma Auto Suggesting Column

                                                                                                                  When writing SQL Queries, does anyone else get super annoyed that after you type a comma and try to return to a new line it is automatically suggest a new column, so hitting return just inputs this suggested column instead of going to a new line? Anyone

                                                                                                                • Convert invoice from zoho to xml with all details

                                                                                                                  How to convert an Invoice to XML format with all details

                                                                                                                • Sync your Products Module for better context.

                                                                                                                  In customer support, context is everything. The integration between Zoho Desk and Zoho CRM helps your sales and support teams function as one, delivering better customer experiences. With the latest update to this integration, you can now sync the Product module in your Zoho CRM with your Zoho Desk portal. This feature enables products from Zoho CRM to reflect in the "product" field in Zoho Desk. This can save your support team valuable time and effort.    Some things to note when syncing the two:

                                                                                                                • Where is the desktop app for Zoho Projects???

                                                                                                                  As a project manager, I need a desktop app for the projects I manage. Yes, there's the web app, which is AWESOME for cross browser and platform compatibility... but I need a real desktop app for Projects that allow me to enter offline information where

                                                                                                                • CRM verify details pop-up

                                                                                                                  Was there a UI change recently that involves the Verify Details pop-up when changing the Stage of a Deal to certain things? I can't for the life of me find a workflow or function, blueprint, validation rule, layout rule ect that would randomly make it

                                                                                                                • Does Zoho Writer have Dropdowns

                                                                                                                  I want to add a drop down field in Zoho writer. Is this possible?

                                                                                                                • Multiple header in the quote table???

                                                                                                                  Hello, Is it possible in Zoho CRM to add multiple headers or sections within the Quote product table, so that when the quote is printed it shows separate sections (for example “Products” and “Services”)? To clarify, I’m asking because: This does not appear

                                                                                                                • openUrl in blueprints

                                                                                                                  My customer wants to open a URL at the end of a blueprint transition. Seems this isn't possible right now but it would be very useful. In this thread, https://help.zoho.com/portal/en/community/topic/openurl-not-working the Zoho agent said that it's logically

                                                                                                                • Dropshipping Address - Does Not Show on Invoice Correctly

                                                                                                                  When a dropshipping address is used for a customer, the correct ship-to address does not seem to show on the Invoice. It shows correctly on the Sales Order, Shipment Order, and Package, just not the Invoice. This is a problem, because the company being

                                                                                                                • Prepayment of a sales order

                                                                                                                  How does everyone handle this common (at least it is common for us!) situation? We require all our orders to be fully prepaid before shipment since we manufacture made to order, custom products. Since ZOHO does not allow a sales order to be prepaid, we are forced to create an invoice at the time an order is placed to allow the customer to pay it. Our sales category is therefore skewed, since the sale was actually booked at the time an order was placed, rather then at the time it is shipped, which

                                                                                                                • Access to Specific Zoho Desk layout for external parties

                                                                                                                  Hi, We have a partner who handles for us sales requests from specific markets. He is not a Zoho Desk user. But we want him to b part of a specific Zoho Desk layout to handle inquiries.  How to achieve it in the easiest way possible?

                                                                                                                • Deposit on a Sales Order

                                                                                                                  Good day, 100% of my business is preorders, no inventory. I am trying to run away from QB for one of my businesses, but I require two options that I don't seem to find with Zoho Books. 1 - If there is a way to apply a deposit on a sales order, as with

                                                                                                                • How Does Knowledge Base Search and Article Recommendation Work?

                                                                                                                  Hello, I would like to understand how the Knowledge Base search engine works. Specifically, does it search based on: The article title only? The full article content? Both, the article and the content? Keywords? Tags? Also, how does the system determine

                                                                                                                • Bulk Delete Attachments

                                                                                                                  Is there a way to bulk delete attachments on the form entries? our storage is full and deleting files one by one is pain taking process.

                                                                                                                • How do I sync multiple Google calendars?

                                                                                                                  I'm brand new to Zoho and I figured out how to sync my business Google calendar but I would also like to sync my personal Google calendar. How can I do this so that, at the very least, when I have personal engagements like doctor's appointments, I can

                                                                                                                • Ability to Disable System Banner Messages in Chat Flow Control

                                                                                                                  Dear Zoho SalesIQ Team, Greetings, We would like to request an enhancement related to the system banner messages in Zoho SalesIQ chat flow control. Current Behavior: SalesIQ allows configuring various automatic banner/system messages such as: Waiting

                                                                                                                • How do you do ticket add ons in Backstage?

                                                                                                                  Hi Everyone, If you wanted to have general admin tickets and allow for add ons, like camping, or car or Carbon offset. What would you do? Peace Robin

                                                                                                                • Idle Chat Reminders for Agent-Handled Conversations

                                                                                                                  Dear Zoho SalesIQ Team, Greetings, We would like to request an enhancement to the Idle Chat Handling functionality in Zoho SalesIQ—specifically for chats that are handled by human agents after a bot-to-agent transfer. Current Behavior: In Zobot settings,

                                                                                                                • Snapchat

                                                                                                                  Are there any plans to add Snapchat to Zoho Social or is there any API that we can use to integrate into Zoho.

                                                                                                                • Zoho Sign "An unexpected error occured" when clients trying to sign documents

                                                                                                                  We are unable to have clients sign our documents. When attempting to complete the process an error appears saying "an unexpected error occured" and in the document history just shows "signing failure." We are at a complete standstill with no response

                                                                                                                • ¡Vuelven los Workshops Certificados de Zoho a España!

                                                                                                                  ¡Hola usuarios de Español Zoho Community! Hace ya unos días que hemos dado la bienvenida al 2026, y promete ser un año de lo más emocionante. Y es que nos gustaría haceros nuestro particular regalo de Reyes, aunque lleguemos un poco tarde. 🎁 ¡Nos gustaría

                                                                                                                • Cancel Subscription

                                                                                                                  Hi , Im want to cancel my account but without success please help me to do it

                                                                                                                • How to list services on quote instead of products

                                                                                                                  I need to create a customer facing estimate that displays our services. The default quote layout only allows products to be listed. Is there a way to correct this?

                                                                                                                • Making an email campaign into a Template

                                                                                                                  I used a Zoho Campaign Template to create an email. Now I want to use this email and make it a new template, but this seems to be not possible. Am I missing something?

                                                                                                                • Syncing calendar with Google Calendar doesn't work when events are sent to auto repeat

                                                                                                                  Hi... The ZOHO CRM -- GOOGLE CALENDAR sync is broken. If I create a single event on either side, sync works, but if I create an event with auto repeat on either side it doesn't work. Furthermore, events created before the sync don't show up in the calendar.

                                                                                                                • Invoice status on write-off is "Paid" - how do I change this to "Written off"

                                                                                                                  HI guys, I want to write off a couple of outstanding invoices, but when I do this, the status of the invoices shows as "Paid". Clearly this is not the case and I need to be able to see that they are written off in the customer's history. Is there a way

                                                                                                                • Zoho Books - France

                                                                                                                  L’équipe de Zoho France reçoit régulièrement des questions sur la conformité de ses applications de finances (Zoho Books/ Zoho Invoice) pour le marché français. Voici quelques points pour clarifier la question : Zoho Books est un logiciel de comptabilité

                                                                                                                • Creating meetings from an email

                                                                                                                  Hi. Similar to Outlook, it would be helpful if a meeting can be scheduled from an email so that the attendees need not be manually entered every time it's created.

                                                                                                                • 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

                                                                                                                • ZohoSalesIQ.Chat cannot send messages

                                                                                                                  Chat cannot send messages. Our app implements the customer service chat window functionality by integrating the Mobilisten SDK. Recently, we encountered an issue: after successful SDK initialization and visitor registration, when the `startWithQuestion`

                                                                                                                • Missed chats on WhatsApp closing after one minute

                                                                                                                  Hi, we have added WhatsApp as a channel. However, if a chat is not picked up within 2mins, the chat is marked as missed and is closed within a minute. Why are they not staying in our "missed" queue for 24 hours as per our WhatsApp preference settings?

                                                                                                                • Feature Request: Add Tax ID Display on Event Tickets

                                                                                                                  Hello Backstage Team, I’ve had several clients bring up an issue regarding tax compliance when creating events. For tax purposes, they are required to show their Tax ID on the event tickets. Currently, this isn’t an option, so they have to manually generate

                                                                                                                • Release Notes | January 2026

                                                                                                                  We have rolled out a set of powerful new enhancements across Zoho Vertical Studio that bring several long-awaited capabilities to your applications. These updates focus on deeper customization, smarter automation, better reporting, and improved usability

                                                                                                                • Email Alias: To keep emails flowing without disruption

                                                                                                                  Email Alias acts like a nickname for a user’s primary email address, allowing multiple email addresses to deliver messages into the same mailbox. Consider the scenario where an employee manages multiple responsibilities, such as responding to sales inquiries,

                                                                                                                • Zoho Sites - General Feedback

                                                                                                                  Hi Everyone-- Quick question for discussion: is it me or is working with Zoho Sites like entering the Twilight Zone? I've built many sites over the years, but this platform seems impossible. I've spent an entire day and a half trying to get a simple one-color

                                                                                                                • Next Page