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

• Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

  Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

• Recent Topics

• Zoho Meeting Android app update - v2.4.0

  Hello everyone! We are excited to announce that we have brought in support for the following features in the latest version of the Zoho Meeting Android app(v2.4.0): 1. Start Personal Meeting Rooms 2. Revamp of the schedule meeting screen and meeting details

• Introducing Zoho Desk integration and a few minor enhancements

  Zoho Desk Integration We've now introduced an integration between Zoho Meeting and Zoho Desk to efficiently manage meeting-related customer inquiries. With this integration, you can track, respond to, and resolve meeting-related tickets directly from

• Zoho Meeting iOS app update: Hearing aid, bluetooth car audio and AirPlay audio support.

  Hello everyone! We are excited to announce the below new features in the latest iOS update(v1.7.4) of the Zoho Meeting app: 1. Hearing aid support: Hearing aid support has been integrated into the application. 2. Bluetooth car Audio, AirPlay audio support:

• Zoho Meeting Android app update: Breakout rooms, noise cancellation

  Hello everyone! In the latest version(v2.6.1) of the Zoho Meeting app update, we have brought in support for the following features: 1. Join Breakout rooms. 2. Noise cancellation Join Breakout rooms. Breakout Rooms are virtual rooms created within a meeting

• iOS 12 update: Introducing autofill passwords and Siri Shortcuts in Zoho Vault

  With this iOS 12 release, Zoho Vault users can now autofill usernames and passwords on Safari and other third-party apps. Users can enjoy a seamless login experience to their everyday apps without compromising security and also access passwords stored in Zoho vault with Siri Shortcuts by adding personalized phrases. How to enable autofill password on your iOS device? First, you need to update your device to iOS 12.  Apple recommends you to take a backup before you update your device to the latest

• Zoho Vault: A look at what's new for iOS, iPadOS, and macOS

  Hi everyone, At Zoho Vault, we constantly aim to improve your security experience. Based on both internal and external feedback, we have recently rolled out updates across our iOS, iPadOS, and support for macOS platforms. Introducing the desktop app for

• Biometric Access Support on Zoho Vault Desktop App

  Is there any plans to add biometric authentication (fingerprint, face recognition) for Vault desktop apps (Windows/macOS) to enhance security and ease of access. I would love to hear other members view on this

• Free webinar: Learn the benefits of migrating to Zoho Vault's new interface

  With remote work becoming more and more common across the globe, productivity and time management are now pivotal concerns for every organization. With the number of business applications employed by companies constantly increasing, a password manager like Zoho Vault saves a lot of productive hours for your team. Vault's new interface has been carefully designed to address these pressing needs, helping users increase their productivity while improving their overall online experience.  This July,

• Free Webinar: An exclusive live Q&A session with the Zoho Vault team

  As 2020 draws to an end, we're closing out a year that has seen drastic changes all around the world. Many businesses have adopted cloud solutions and a remote work culture for the first time, and this has given rise to newer cyber risks and threats that

• Why passwordless authentication should be your top security project for 2021

  Hello users! We know that nobody likes to remember passwords, yet they form an indispensable part of our lives. Many of us working with any kind of technology today manage numerous passwords for personal and business accounts. With the widespread adoption

• Free Webinar: See why Zoho Vault is the best alternative to LastPass

  When LastPass was acquired by LogMeIn in Oct 2015, we expressed our genuine concern about how this would change the LastPass business model and how customer trust would transfer from one company to another. As we suspected, LastPass doubled their pricing

• Managing cyber threats when working remotely | A Customer Survey Report

  The nearly universal adoption of remote work has changed the way businesses function. Globally, enterprises continue to work to find new ways to make life easier for employees working remotely. However, a commonly cited concern has been the lack of cybersecurity

• World Password Day: 5 interesting facts about passwords

  It's World Password Day: that time of the year when we talk about password hygiene and the importance of safe password management. World Password Day is observed on the first Thursday of every May, and this year, we'd like to talk about some of the most

• Free Webinar: Go passwordless in 2022 with Zoho Vault

  Passwords have long been the preferred authentication method, largely due to their universal appeal. While they're easy for people to use and implement, they're also convenient for hackers to exploit. Reports from 2021 state that weak and stolen passwords

• Myki has announced EOL for its services | Learn why Zoho Vault password manager is the best alternative

  Hello Myki users,   Myki has announced end-of-life for its Teams, MSP, and GUARD services, after being acquired by JumpCloud. In their recent announcement, Myki stated that they will be removing their apps and extensions from the respective stores, turning

• Join our exclusive meetup with Zoho's Real Estate community

  Hey there, The Zoho Vault team is conducting a meetup for all real-estate users from Zoho. During this session, we will be discussing the need for secure password management and how Vault can help you and your clients safely protect passwords and other

• Free webinar: A quick walkthrough of Zoho Vault and major updates in 2023

  Managing passwords is crucial for all businesses. You can securely store, share, and manage passwords effectively from anywhere with Zoho Vault. We have introduced several new features in 2023 to offer the best online experience for our users. Join our

• Free webinar: Why a password manager is a “must-have” for everyone in 2024

  In the past decade, we've witnessed numerous cybersecurity breaches globally, with a significant portion resulting from the "it won't happen to me" mindset. Shockingly, in 2023, 86% of breaches involved weak and stolen passwords. Password hygiene is crucial

• Zoho Vault - Webinars 2023 - Video Recordings and Slide Decks

  Hello, We wanted to offer a consolidated list of Zoho Vault webinar resources from 2023. Therefore, we're putting together a list that includes links to our webinar recordings and slide decks for easy access. Webinar Video recording Slide deck Getting

• Free webinar: ‌Focal point: Building a financial ecosystem with Zoho Vault and Zoho Workplace

  Hi everyone! Cyber threats against the financial sector are escalating. In the last two decades, nearly one-fifth of reported incidents targeted financial institutions, causing $12 billion in direct losses. Cybercriminals are becoming more sophisticated,

• New features in Zoho Vault

  We’re thrilled to introduce a wave of powerful updates in Zoho Vault, designed to enhance security, streamline workflows, and improve your overall experience. Let’s dive into what’s new! Folder creation restrictions Limit who can create folders in your

• Join our World Password and Passkey Day expert Q&A 2025

  Hey everyone! World Password and Passkey Day is almost here, and there's no better time to talk about something we all rely on daily—secure authentication. Did you know that a staggering 60% of hacking-related breaches are tied to weak or stolen passwords?

• Dashlane discontinued its free plan: Here's why Zoho Vault's free plan is worth the switch

  Hey everyone, Dashlane password manager has officially announced that its free plan will be discontinued starting September 16, 2025. This change means that current free users will need to either upgrade to a paid subscription or export their data and

• Introducing SecureForms in Zoho Vault

  Hey everyone, Let’s face it—asking someone to send over a password or other sensitive data is rarely straightforward. You wait. You nudge. You follow up once, twice—maybe more. And when the information finally arrives, it shows up in the worst possible

• Clickjacking: Zoho Vault's Response

  Issue: Password manager browser extensions are found to be vulnerable to clickjacking security vulnerabilities that could allow attackers to steal account credentials, TFA codes, and card details under certain conditions. Reported by: Marek Toth, Independent

• Free webinar: Security that works: Building resilience for the AI-powered workforce

  Hello there, Did you know that more than 51% of organizations worldwide have experienced one or more security breaches, each costing over $1 million in losses or incident response? In today’s threat landscape, simply playing defense is no longer enough.

• Free webinar—Redefining workforce security with Zoho Vault: Passwords, passkeys, and multi-factor authentication

  Hi everyone! Did you know that in Q2 alone, 94 million data records were leaked globally? Behind every breach is a combination of poor password habits, phishing attacks, privilege misuse, and simple human error. The fallout—including reputational damage,

• Fill Colors

  Hello, Just curious, is it possible to manage the Used and standard colors in the fill drop down menu ? I would like to change/edit them is possible to colors I frequently use. Thanks for you reply, Bruce

• Is there a way to generate a virtual meeting for a group service in Zoho Bookings?

  Are virtual meetings not supported for group services/meetings? I have integrated Zoom with one-on-one services, but I need a way to create an online group meeting. Thanks

• Client scripts for Zoho Books ?

  Good day everyone, I am looking for a way to be able to interact with the Quotes and Invoices as they are being created. Think of it like Zoho client script in Zoho CRM. But for the life of me I dont see a way to do this. The issue with having function

• Fillable template with dynamic tables?

  Is there a way to build a fillable template so that users can add rows to a table? To describe what I'm trying to accomplish the table has 3 sections; a header row, some number of rows with custom information, and a summary row with totals. I can't figure

• Invoicing multiple expense items as a single line item

        My client would like me to invoice them for multiple expense items on a single line item on an invoice.  Can this be done?  I know I can import billable expenses to an invoice, but I don't know how to show them as a single line item or have them

• Tables improvement ideas / features

  Heya, I've been using Zoho Tables for a few months now and wanted to post some features that I think will be greatly beneficial for the tool: 1. Ability to delete a record in automation or move a record in automation. - Usecase: I move a record from one

• Announcing offline payment modes for event tickets

  Hello everyone,   Collecting ticket payments from prospective attendees can be a tricky part of event planning. While Zoho Backstage has always allowed you to collect payments online as people buy tickets from your event microsite, we have now enabled

• Gmail is ramping up its email sender policy from November 2025

  Hello marketers, As you may be aware, Gmail introduced a guideline for bulk senders starting February 2024. If not, here's a quick refresher straight from Google: After this policy was announced first in 2023 and soft-implemented in February 2024, we

• Deluge Error Code 1002 - "Resource does not exist."

  I am using the following script in a Custom Button on a Sales Return. Basically, the function takes the information in the sales return (plus the arguments that are entered by the user when the button is pushed) and creates a return shipping label via

• Is there a list of Zoho Icons?

  Is there a list of Zoho Icons you can reference: i.e. business-gold is <image marginRight='7px' color='#2A70E7' bgColor='#FFFFFF' width='52px' height='52px' type='icon' value='business-gold' size='24px' cornerRadius='26px' iconType='solid' /> Thanks!

• Item images

  Can we get an "On hover" expanded image for items please ?

• Ability to Create and Manage YouTube Video Chapters in Zoho Social

  Hi Zoho Social Team, How are you? We would like to request an enhancement to Zoho Social that would allow users to create and manage YouTube video chapters directly within the platform. Currently, Zoho Social does not support manually adding chapters

• What happens to my current site SEO if i opt for zoho creator?

  I have an existing website and I need to use Zoho creators for the rapid creation of my webpage creation. Currently, my IT team is creating the web pages, but I am concerned about the SEO of my current website if I shift to zoho will i loose it all?

• Next Page