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.

    • Recent Topics

    • Zoho Desk Limit for Comma Separated Queries

      Hi, I have just discovered a limit that I believed is not mentioned in any of Zoho's documentations. My search query looks like so: "query: {"accountId":"786050000091629966,786050000163589273,786050000163589427,786050000162753705,786050000162112971,786050000161987643,786050000160752868,786050000167089504,786050000167089378,786050000167089024,786050000167070005,786050000166295256,786050000128153693,786050000110560021,786050000046594575,786050000039106461,786050000002225356,786050000076889093,786050000047895103,786050000043365354,786050000044765191,786050000041790249,786050000040359116,786050000037945198,786050000024605077,786050000000525015,786050000155333895,786050000157741437,786050000000718125,786050000011574353,","departmentId":"786050000042648070","status":"Finished","sortBy":"createdTime","customField2":"cf_completion_date:2025-01-28T03:00:00.000Z,2025-10-28T03:00:00.000Z","customField3":"cf_billed:false"}"

    • Module Name doesn't exist

      I am trying to create a module named Activity, with plural Activities, but I have an error that module name already exists. This module is doesn't exist, and I don't have a single field called Activity or Activities.

    • Send mass email using my secondary email

      Hello, When I send an email to just one person from Zoho CRM, a complete email editor appears, where I can choose which of my email addresses I want to use in the From field. When I send a mass email, there is not such option. I can only select the email template. When I configure an email template, I can choose who is in the From field, but I can't set it to use my secondary address. The only way to send a mass email using my secondary address that I can think of is swapping my two addresses in

    • How to next stage blueprint in Zoho Creator

      Hello, I have question, its possible to next stage blueprint? in case, Start - (first stage) Leader 1 (with condition 1) - (second stage) Leader 2 (with condition 2) - (third stage) Leader 3 (with condition 3) - (fourth stage) After first stage, i want

    • Zoho Desk iOS and Android app update: AI powered: Reply Assistance and Refine Messages on IM module.

      Hello everyone! We are excited to introduce new AI powered features on the IM module of the Zoho Desk app. Reply Assistance: Reply Assistance generates suggested responses for incoming chat messages, which you can directly insert into the conversation

    • Unify All Zoho Video Meeting Experiences into One Standardized Platform

      Hi Zoho Team, We would like to share an important user experience concern regarding the current state of video meeting functionality across the Zoho ecosystem. The Problem Within Zoho, there are multiple ways to initiate or schedule a video meeting: Zoho

    • Is it possible to embed Youtube shorts?

      Hi Zoho desk support, This is Ryan from Accuver America. While I'm trying to create a knowledge base article with embed video, I ran into this issue. "www.youtube.com refuse to connect" A little bit background is that because this video is recorded on

    • Zoho Inventory - Move Orders

      Quick question about Move Orders... Why is there no status to say something like "Draft", "In Progress" and "Completed", similar to Transfer Orders? I'm assuming that when something needs to be moved it should be planned in Inventory, executed and then

    • Multi-select Lookup does not have Advanced filter options in CRM

      With much fanfare Zoho announced the advanced filter options for CRM lookup fields which was a nice addition. This feature is not available for Multi-Select lookup fields. Will it be rolled out in the next 3-6 months, considering the standard lookup filter

    • Kaizen #8 - Handling Recurrence and Participants in the Events Module via API

      Hello everyone! We are back this week with an exciting post—Handling recurrence and participants in the Events module through API. First things first—What is the Events module? "Events" is a part of the Activities module in Zoho CRM.  An event is an activity that happens at a given place and time. You can find Events on the user's Zoho CRM's home page, Activities home page, Calendar, and in other related records. What are the types of Events? Events are of two types—Recurring and non-recurring events.

    • Split functionality - Admins need ability to do this

      Admins should be able to split an expense at any point of the process prior to approval. The split is very helpful for our account coding, but to have to go back to a user and ask them to split an invoice that they simply want paid is a bit of an in

    • Delegates - Access to approved reports

      We realized that delegates do not have access to reports after they are approved. Many users ask questions of their delegates about past expense reports and the delegates can't see this information. Please allow delegates see all expense report activity,

    • How to include total km for multiple trips in expense report.

      Whenever I create a mileage report it only shows the total dollar amount to be reimbursed. The mileage for each individual trip is included but I also need to see the total distance for all trips in a report? How do I do this?

    • Get logged in user ID in Deluge script

      Hello all, How do I get the id of the logged-in user in a deluge script? the "zoho.loginuserid" function actually returns the users email address or whatever the user id they use to login to zoho with and not the id of the user record, and given that

    • Item Details Field - New Barcode / Document option?

      Is this a new feature??? its in both books and inventory.

    • Super Admin Logging in as another User

      How can a Super Admin login as another user. For example, I have a sales rep that is having issues with their Accounts and I want to view their Zoho Account with out having to do a GTM and sharing screens. Moderation Update (8th Aug 2025): We are working

    • Shared Mailbox - Mark as read for all users

      Hi all, Maybe someone can help me out. At the moment we have a shared mailbox without streams. When a users reads an mail or marks it as read other users will not see this. How can we resolve this? We now archive the mails when read and followed up. However

    • 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

    • Prevent new Record Association

      Hello all, We have a small sales organization therefore, it's helpful for everyone on the sales team to be able to view the full list of accounts to assist in preventing duplicate accounts from being created. However we want to prevent people from creating

    • Add the same FROM email to multiple department

      Hi, We have several agents who work with multiple departments and we'd like to be able to select their names on the FROM field (sender), but apparently it's not possible to add a FROM address to multiple departments. Is there any way around this? Thanks. Jordanne

    • Unified customer portal login

      As I'm a Zoho One subscriber I can provide my customers with portal access to many of the Zoho apps. However, the customer must have a separate login for each app, which may be difficult for them to manage and frustrating as all they understand is that

    • Can I export to PDF in Zoho Learn

      I have seen help pages where export to pdf options are available but I do not see that option available from the application. I see that exprt is available in my free trial version but that is only to html pages. I need to be able to export my manuals

    • Zoho Analytics & SQL Server - Live connect

      Below are the steps I did Created a fresh database and table in my own virtual server Created a new data source connection with live connect I was able to select the tables and created the data source successfully I am getting the error when I try to

    • Zoho Sites "pages" management page

      I have 80 plus pages on zoho sites. When I go to the "pages" link to view and edit pages, They are not in any kind of order, so I spend lots of time searching for pages when I need to edit or create new. How can I change the view order of all my pages

    • Staff rules

      Hi! Do you people know what are the default staff rules when a new booking is created? We have two staff members in my team (me as the admin, and my employee). As we share the same services, I'm wondering how Zoho will pick the staff for new apointments.

    • Add Image Upload Field to Zoho Bookings Registration Form

      Hi, We would like to request the addition of an image upload field to the Zoho Bookings registration form. Currently, Zoho Bookings only supports text-based fields (e.g., Single Line, Multi-Line, Email, Checkbox, Dropdown, Radio Button, and Date), but

    • New Field in CRM Product Module Not Visible in Zoho Creator for Mapping

      I created a new single-line field in the Products module in Zoho CRM. Zoho CRM and Zoho Creator are integrated, but the newly created field in CRM is not visible in Zoho Creator when I try to map fields.

    • Merge Tags Output Incorrect Placeholder Text After CRM Sync

      Hi everyone, I’m experiencing an issue with merge tags in Zoho Campaigns after last sync of contacts and leads from Zoho CRM (days before everything worked perfectly). Here’s the situation (seems like a default configuration in Campaigns) : My leads have

    • UI Improvement - Ability to Collapse Flow

      The UI for Flow is generally pretty good. However, when multiple decision trees are used, the layout can get pretty convoluted and hard-to-follow (see one of my Flows below): In these cases, even the auto-arrange fails to make this something that a normal

    • Windows agent 2025_M02 release notes

      Agent Version: 111.0.3.300 Release date: 24 February, 2025 Various Major enhancements to improve overall performance and optimize the user experience. Squashed a few bugs to improve overall product quality.

    • Windows agent 2025_M01 release notes

      Agent Version: 111.0.3.299 Release date: 05 February, 2025 Major Enhancement: Live Monitor feature compatibility released. Major Enhancement: Updated Scaling for multi technician cases with Android and Web based viewers. Various other bug fixes and performance

    • Disable Buttons for Users with Profiles without permission

      Hey, I've noticed that users without permission of setting up things in the marketplace, can still see the icon: On a click, you see this: It would be way better, if they couldn't see this menu icon at all. (Aside from the fact that it completely misplaced

    • how to record deferred revenue?

      Dear Zoho Team, We issue invoices relating to 12-month web hosting service. When we issue the invoice, we should record the entire amount of the invoice as DEFERRED REVENUE (ie. $10 x 12 mths = $120, balance sheet item). After the particular month of the hosting service, $10 of revenue has been earned and deferred revenue amount will be $110. We must keep adjusting the balance sheet and income statement over the course of the service until the company has fulfilled its obligation of services and

    • Narrative 13: Importing your data

      Behind the scenes of a successful ticketing system: BTS Series Narrative 13: Importing your data When importing data into an application, it is crucial to prevent data loss or duplication. These types of errors can hinder the development of a clean and

    • Blueprint Not Triggering When Lead Status Is Updated by Workflow (IndiaMART Integration)

      I have set up a blueprint that triggers when a lead’s status is “New Lead.” Our CRM is integrated with IndiaMART, and when leads are created from IndiaMART, their Lead Status is initially set to None. To handle this, I created a workflow that automatically

    • Update Subform in specific field(Status) without affecting other fields in Zoho CRM using Deluge?

      Scenario: PRODUCT Module(change name Plot) in any product status change From Available to Booked then on PROJECT Custom Module have Subform So, Subform name is Property Details now in that Subform 1 field is STATUS that update according to  product status

    • Experience effortless record management in CRM For Everyone with the all-new Grid View!

      Hello Everyone, Hope you are well! As part of our ongoing series of feature announcements for Zoho CRM For Everyone, we’re excited to bring you another type of module view : Grid View. In addition to Kanban view, List view, Canvas view, Chart view and

    • YouTube Live #2: Agreement Intelligence with Zoho Sign's eSign AI assistant

      Hi there, We're back again with our YouTube live series and this time, we'll take you through our holistic agreement intelligence powered signature workflows. Struggling to draft an agreement? Need help double-checking clauses and going through complicated

    • Can I Build a POS using ZOHO creator and integrate it with ZOHO Books?

      Hello,  I have a Zoho Books account and I was wondering if I can have a POS system that integrates with it. Primarily with Inventory, Customers and Payment and ofcourse Create invoices and credit notes.   So, would Zoho creator provide me with this solution?  Thank you, 

    • An important update for Zoho Cliq desktop users

      The latest version of the Zoho Cliq desktop app (v1.8.0) will no longer be supported on macOS 10.15 Catalina and earlier versions. This is because the framework we use (Electron) no longer supports some older macOS versions. If you’re using macOS 10.15

    • Next Page