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.

    • 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

    • Detect and ignore bots in visitors

      The SalesIQ visitor numbers are basically useless to us because there is no bot detection. We get the same bots coming in from the same countries looking at the same pages every day. It can't be that difficult to tell the difference between an actual

    • Add Real-Time Microphone Audio-Level Indicator During Screen Recording

      Hi Zoho WorkDrive Team, Hope you are doing well. We would like to request an important enhancement to the Zoho WorkDrive screen-recording experience. Current Limitation: During a recording session, there is no visual indication that the microphone is

    • Zero Personalization of the File Sharing Experience

      By now (2025) this is the maximum level of personalization available for a Zoho sharing link. We gently asked Zoho if we could modify at least the background, and they replied that it cannot be customized. We're truly disappointed – and surprised every

    • Two factor authentication for helpdesk users

      The company i work for wants use the helpdesk site in Zoho desk, as a place for their distribution partners to ask question and look for information about our product. The things there is suppose to go up there is somewhat confidential between my company

    • Kiosk can't merge picklist or multiselect

      There is no ability to load a multiselect or picklikst field into a kiosk with the values that have been previously selected. So, I essentially have 3 unacceptable options: 1.)Load the value into a text string and include instructions like this: "Picklist

    • AGE field from DATE OF BIRTH Field.

      HI! I have a field called date of birth in my CRM (LEADS, CONTACT etc…)     How can I know the AGE today   I would like to create a field AGE. I now how to create a field but I don´t which calculation (CUSTOM FUCTION) to make ¿ANY HELP?

    • How to update/remove file in zoho creator widgets using javascript API

      Hi Team, I have developed a widget which allows inserting and updating records I have file upload field with multiple file upload. Now while doing insert form record, I am using uploadFile API to upload files for that record. I am using updateRecord API

    • Announcing new features in Trident for Windows (v.1.34.4.0)

      Hello Community! Trident for Windows just got better! With this update we have features that make your daily work easier and more efficient. We've added some features that are exclusive to our app and we're sure you'll find them useful. Let’s dive into

    • Report Hover Setting

      Would be great if we will able to show information to the user while hovering a record in a report.

    • Vertical images displayed as horizontal

      Some pictures that originally are in vertical position are displayed in horizontal after the upload. It seems that system rotates them by 90 degrees. How can I fix this issue?

    • Zoho Desk iOS app update: Saved filters and sort options

      Hello everyone! Saved filters created on the web(desk.zoho.com) for tickets are now accessible on the Zoho Desk iOS app. You can easily rename, delete, or clear filters on the go. We have also introduced Sort options on the ticket listing screen, allowing

    • Big Things Just Dropped in the SalesIQ Universe: Top Upgrades You’ll Love in Nova’25

      Nova'25 has landed, and it’s packed with meaningful upgrades to help you engage smarter, work faster, and scale with ease. Whether you're into proactive messaging, smarter automation, or better admin control, there's something here for everyone. Here's

    • Time Entries in Analytics

      I am trying to import a zoho sheet into zoho analytics. In my sheets one of the columns has "time Entries" in this "format HH:MM am/pm" example 11:00 PM. After import, i noticed that analytics converted the time to "00 Jan 1900 23:00:00".. how do i maintain

    • Amazon invoice in Zoho Books

      I have just made my first few sales on Amazon India. Amazon Seller account generates invoices for the sales made on Amazon. These invoices are sent to customers also. Now when I was only making offline sales, I used to create Invoices in Zoho Book. Now

    • Zoho Creator Upcoming Updates - November 2025

      Hello everyone, Welcome to your monthly roundup of new features and enhancements! We hope you've already taken a look at Release Projection 2—it details the features coming your way for the rest of the year. And this month, we're excited to start rolling

    • Zoho Webinar + HubSpot : Simplifiez la gestion de vos données de webinaires

      Les webinaires sont aujourd’hui essentiels pour interagir avec vos prospects et vos clients. Cependant, la gestion des données entre plusieurs plateformes peut vite devenir complexe. Grâce à la nouvelle intégration entre Zoho Webinar et HubSpot, vos outils

    • I am trying to give access to one of our educators access to 3 forms in Zoho and she is not able to view the data - Access issue

      Hi Team, When I try to provide read access to one of our educators on Zoho for Pre-training , post training and Impact survey forms submit form access which also allows them to read , it does not show them data

    • How to book GST paid in zoho books

      hi, i am a new user to Zoho books and not able to book GST paid in books, kindly suggest how i can book it in books. thanks, siddharth

    • PUNJAB NATIONAL BANK (CORPORATE) INDIA - NOT AVAILABLE IN BANKING

      Dear sir, Kindly fix it. PUNJAB NATIONAL BANK (INDIA) is available but PUNJAB NATIONAL BANK (CORPORATE) is not available. Kindly enable this banking since we need to categorize the entries. Regards, Sanjay Jena email id/ user id : travewithmerchant@

    • Is it possible to create a word cloud chart in ZoHo Analystics?

      Hi there, I have a volume of transaction text that I would like to analyse using word cloud (or other approcah to detect and present word frequency in a dataset). For example, I have 50,000 records describing menu items in restaurants. I want to be able

    • 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

    • Facturation électronique 2026 - obligation dès le 1er septembre 2026

      Bonjour, Je me permets de réagir à divers posts publiés ici et là concernant le projet de E-Invoicing, dans le cadre de la facturation électronique prévue très prochainement. Dans le cadre du passage à la facturation électronique pour les entreprises,

    • Your bot just got smarter: AI-Powered routing that reads between the lines

      What if your bot could tell the difference? Between a visitor who just needs a quick answer, someone actively comparing options, and a frustrated customer one click away from leaving? Most bots can't. They deliver the same response to everyone, missing

    • Weekly Tips : Master Keyboard Shortcuts in Zoho Mail

      If you spend a lot of time managing emails, switching between your mouse and keyboard can slow you down. Whether you are replying to clients, organizing your inbox, or searching for messages, every second counts. So, how can you streamline your email

    • Introducing custom lookup fields in the Tickets, Contacts, and Accounts modules

      Hello all, We are excited to announce a new enhancement that will empower you to further customize the Tickets, Contacts, and Accounts modules. Now, you will be able to create custom lookup fields in your Tickets, Contacts, and Accounts layouts for more

    • DKIM cannot be enabled for the domain as no verified default selector present

      Can't get the DKIM working. May you please check my account (nksy.us) to see what's wrong?

    • Contacts per department

      Hello, Is it possible to limit Contacts to a Department? Thanks

    • Collections Management: #3 Tackling Payment Failures

      Sam refreshed the dashboard. "Payment failed". Same customer. Same subscription. This is happening for the third time. He sends a usual email: "Your renewal payment failed again. Could you please check and retry?" A couple of days passed, and there was

    • How do I increase the email attachment size in Zoho CRM ?

      It looks like I'm limited to 10MB when sending an attachment using the email widget on a record in Zoho CRM. Is there a way to increase the size? Or can I use some other tool? From what I'm reading online, I'm maxed out at 10MB. Any insight would be greatly

    • WhatsApp Channels in Zoho Campaigns

      Now that Meta has opened WhatsApp Channels globally, will you add it to Zoho Campaigns? It's another top channel for marketing communications as email and SMS. Thanks.

    • Zoho sign and creator error message {"code":9043,"error_param":"Checked by","message":"Extra key found","status":"failure"}

      Good day, I receive the error message: {"code":9043,"error_param":"Checked by","message":"Extra key found","status":"failure"} when running below code from creator to sign, void TestForSign(int ID) { //Fetch Template Details (Optional, for dynamic mapping)

    • Download a writer template as .docx instead of .pdf.

      I have been trying to implement a feature to download a writer template as a .docx and got it working partly but it isn't good. Earlier I checked our code and I saw openurl("https://crm.zoho.com/crm/org121314/specific/Template.do?action=print&step=pdfPreview&id="

    • Allow the usage of Multi-Select fields as the primary field on "Layout Rules"

      We want to force our users to enter some explanation strings when a multi-select field has been utilized. I can't understand the reason for the usage restriction of Multi-Select fields as a primary field. This is a simple "Display hidden mandatory field

    • Extract Archived Projects using Zoho Projects API

      In my organization we archive the projects when they are already completed, charged, invoiced, so that only those that are still pending process remain active. I need to access all projects (active and archived) from an external system, but the API v3

    • Ask the Experts: Five-hour live Q&A session with Zoho WorkDrive product experts

      Have questions about WorkDrive 5.0? Let’s talk! We recently launched Zoho WorkDrive 5.0, packed with powerful updates to help your team work smarter, stay secure, and get more value from your business content. From content-centric workflows and AI-powered

    • File upload support for subforms

      Dear All, Subforms help you add and track data related to your CRM records. We've always supported most of the commonly used field types in subforms, so as to cater to your business requirements. Now we're happy to extend support to file upload fields.

    • Circular record relationship in CRM

      Given there is a lookup in custom module Transactions creating a related list on the chosen Contact record. I. e. a lookup field on Transactions module points to Contacts. The related list on a Contact record can thus have have many transaction records.

    • Is it possible to pull the Zoho desk data into Zoho analytics in real time

      Hi - I am looking to add more dashboards and reports of Zoho Desk in analytics. I see there is a schedule to pull the data into analytics, but I'm wondering if there is an option to pull the data in real time instead of a specific interval?

    • Enhance productivity with the revamped Zoho Sheet View

      Hello folks, For some time now, you've been able to use the Zoho Sheet View to quickly edit multiple records or to insert a batch of new records. Its tabular interface allows users to engage in these tasks productively. Despite this, the existing Sheet

    • How to set value of dropdown field to variable

      For the life of me, I can't figure out why the following code won't set input.status to the previousSelection. Steps to reproduce: 1. Click input.complete 2. input.status dropdown updates from '1-Backlog' to '4-Done' 3. Click input.complete again to deselect

    • Next Page