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

Hello Developers!

Welcome back to another week of Kaizen! 

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

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

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

Why Mandate Subform Data from a Different Module?

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

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

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

Business Scenario: Insurance Deals Qualification

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

Insurance Sales Blueprint

Steps to Build a Blueprint Widget

Step 1 - Review Basics

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

Step 2 - Develop your Widget

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

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

Widget Execution During Transition

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

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

Check and Collect Required Document Details

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

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

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

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

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

Update the Contact's Subform

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

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

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

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

Step 3 - Validate and Pack the Widget

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

Step 4 - Associate the Widget with the Blueprint

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

Try it Out! 

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

 

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

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

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

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

Until next time, Happy Coding! 

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

Additional Reading

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

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

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

More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog for detailed information on these updates.

• Topic Participants

• Kiruthiga G

  

• Sticky Posts

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

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

• Kaizen #226: Using ZRC in Client Script

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

• Kaizen #222 - Client Script Support for Notes Related List

  Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Recent Topics

• Eventbrite Email Field in Zoho Flow Returns "Info Requested" Instead of Actual Email

  Hi Zoho team, I'm using Zoho Flow to connect Eventbrite with Zoho CRM. My goal is to automatically add event attendees as leads in Zoho CRM. I’ve set up the flow and mapped the ${trigger.profile_email}} field to the Email field in CRM. However, I'm running

• "Invalid value passed for Product ID" Error in Zoho Flow "Create Sales Order" Node

  Hello Zoho Community, I’m facing an issue with Zoho Flow while trying to create a sales order in Zoho Inventory using the "Create Sales Order" node. Here’s a detailed explanation of my setup and the problem: What I’m Trying to Achieve I’m building an

• Associating Project with an Account via Flow

  I'm using flow to create a Project based on a Deal status update using flow. The fields exist to pass the Account Name through properly, but when you view the Projects module in a CRM Account Record it doesn't automatically associate the new Project Record

• How to follow up a member in a meeting?

  Hello, I make weekly meeting online with a lot of people. I want(I've been using calendly to do it). I want to do a follow-up to it. I want to send messages via Zoho-flow to all the member that participated in the meeting. How can I do it?

• Setting Delays in Invoice Reminder Flow

  I am currently working on a flow that sends reminders for unpaid invoices. The flow is designed to delay actions until specific intervals before the due date: A reminder should be sent 7 days before the due date. A second reminder should be sent 3 days

• Get Sales Orders Related to Inventory Item

  Dear Team, I'm just wondering if there is a way to get a list of all Sales Orders related to a specific Inventory Item. I did search all articles but couldn't find any article that could help.

• Endpoint Central Cloud Asset Update from Fresh Service

  All, Does anyone use the asset management feature in Fresh Service? I'd like some help on building a flow to update asset attributes in Endpoint Central Cloud based off of an update to that same asset in Fresh Service. The trigger is "asset is updated"

• Zoho Flow Export to Deluge

  It would be great to take a user built zoho flow and export the entire flow as a deluge script including having multiple connected applications (showing the API connections and webhooks) and different functionality in the other applications interacting

• Action Iteration/Loop using Zoho Flow

  Trying to use Zoho Flow for automating following Context - A zoho form entry which has image upload field with upto 5 images setting and files are saved into Workdrive. After form is submitted need to create folder based on some fields and move files

• Zoho Flow - Unable to evaluate formatDate with Zoho Invoice Date Field for Calendar Integration

  Hello Community, I'm trying to automate the creation of all-day events in Zoho Calendar whenever a new invoice is created in Zoho Invoice. I'm using Zoho Flow for this automation. My Goal: When an invoice is created with a specific "Event Date," I want

• Zoho Inventory Sales Order Items

  I'm trying to build automation using Zoho Flow to add items to a Sales Order. In the automation options for both "create sales order" and "update sales order", The item ID is required. However, when I update the Sales Order, it's just replacing the item

• Permissions for Azure Devops connection

  I am trying to set up a connection with our Azure DevOps org but it keeps giving me this error. On Azure I should be able to have admin-level access to everything. Can you please point me to which permission this is checking for so I can enable it?

• Marketing Tip #1: Optimize item titles for SEO

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

• My IMAP mail suddenly stopped working

  On my iPhone and iPad, IMAP stopped working for my Zoho account with the error "User name or password incorrect" and "Invalid credentials failure" however I was able to access via web with the same credentials. Also stopped working on Apple Mail client.

• Confused by the distiction between matched and categorized when reconciling a bank statement an how to

  I used to use quickbooks. In quickbooks, it was possible to use the check writing feature to add an expense that was on the bank statement that did not go through the AP and check writing process. I would write a check, assign it a number like etf (for

• Not Receiving OTP • https://voters.eci.gov.in/home/family

  Hello Customer, Greetings from Zoho Mail. Upon a detailed review of our delivery logs, we can confirm that other Zoho Mail users are successfully receiving OTP emails from eci.gov.in. However, in your specific case, it appears that the OTP emails are

• WorkDrive for Excel Add on

  Dear Sir/Madam Have installed Workdrive for Microsoft add on But unable to view the same added in Excel

• Splitting Transactions in Zoho Books

  I have read in past forum posts that the ability to split bank transactions would likely be implemented - it's definitely a typical accounting program feature.  I'm new to Zoho and thought I'd found nirvana until I realized this feature doesn't seem to

• Zoho Calendar s’enrichit avec une intégration à Zoho People et Zoho Cliq

  Les journées de travail ne se déroulent jamais exactement comme prévu. Une conversation informelle devient une séance d’échange d'idées, une absence modifie un planning, et votre agenda se retrouve vite décalé par rapport à la réalité. Chez Zoho Calendar,

• Zoho public comments are confusing and unnecessary

  Hi, we use zoho desk and have issues with public comments. We started using them because the "Reply" option just seemed very clumsy because of the following reasons: - the top "Reply" button starts what seems to be a regular email, showing the entire

• Zoho API - ticket creation - Validation failed for the condition : Ticket Status Info should not be empty

  Hi ! I'm trying to create ticket through Zoho API, and I'm getting a 422 response : "Validation failed for the condition : Ticket Status Info should not be empty" My request looks like this : curl --location 'https://desk.zoho.eu/api/v1/tickets' \ --header

• Deleting unwanted ticket replies

  Hello, In a Zoho Desk Ticket thread, sometimes one of the recipients has auto-reply activated. This creates a new message in the Ticket thread that not only pollutes the thread, but most importantly cannot be replied properly because usually auto-reply e-mails don't do "reply all", so the other recipients are not included. I want to delete such a message in the Ticket thread. I searched the help of Zoho Desk, but only found a way to mark as Spam (https://help.zoho.com/portal/kb/articles/marking-support-tickets-as-spam)

• System-generated support email added in CC on “Reply All”

  Hi, I recently set up Zoho Desk for a client and we are trying to prevent the Zoho Desk system-generated support email address (not the mailbox used as the department’s "From address") from being automatically added in CC when agents use “Reply All” on

• Convenience Fees

  I use Zoho Invoice for invoicing my billboard customers.  I have a few customers that want to pay using credit cards and ACH.  As a result, I have integrated an Online Payment Gateway (Stripe) for these customers.  I currently charge these customers a "Convenience Fee" of 3% for using this service as I typically only take checks as payment (and the gateway charges 2.9% + $0.30 per transaction).  I do this by creating a separate line item on the invoice and adding 3% to it.  I would like to offer

• HTML Tags added to Reports with Notes

  Recently Zoho added the ability to markup text within notes. That way, users can change font size, colors, etc. It's a great change. However, since the change, reports that include a column for "Note Content" are printing HTML tags within the report.

• Restrict Payment Methods

  Allow us to restrict certain payment methods specific for each customer.

• Emails Getting Delay Error Messages - Status: 451

  Hi. Hoping someone can help. I've been using Zoho for over a year now with no problems at all. Today, the majority of my emails I send out or reply to are getting this error: This message was created automatically by mail delivery system. THIS IS A WARNING MESSAGE ONLY. YOU DO NOT NEED TO RESEND YOUR MESSAGE. The original message was received at Sun, 22 Dec 2019 18:20:19 -0800 from wazza@amninjas.com [wazza@amninjas.com] ----- The following addresses had fatal errors ----- [Status: ERROR, Address:

• Add Domain

  Hello Zoho Support, My Zoho Sites project accidentally auto-added domains with http:// prefix and duplicated domain entries. Current domains list shows: http://www.kinhtethethao.com.vn (Primary – cannot be removed) http://www.kinhtethethao.com.vn (verification

• Kaizen #221: Workflow & Actions Reports APIs

  Over the last few weeks, we have joined Zylker Cloud Services as they restructured their automation ecosystem using Workflow APIs and Actions APIs. Along the way, we discovered how to audit workflows, update old rules, create new ones, and manage associated

• Having an Issue with the Entity ID

  I'm having an issue when trying to use Zoho Flow and the notes function. I currently have it set up when a new response comes into a particular form, all of their responses will go into the notes section of their contact on the CRM. I'm currently mapping

• For Each Loop in Zoho Flow

  I am using Zoho flow to create rows in an google sheets for every new order in Shopify but the issue is that it is creating one row per order and all line items are comma separated values but I want separate rows for each line item. Is there a way to

• Debug and Test not receiving updates

  Hello, I've been trying to debug two of my simple flows between Zoho Projects and Clockify but it seems like the Debug and Test feature is not working for me. When I click the Play button on any of the flows and then perform the trigger actions nothing

• Attendance, Reimagined: Smarter Views for Teams and Individuals

  Tracking attendance shouldn’t feel like a chore. With the revamped Attendance module UI, Zoho FSM makes it easier than ever to monitor work hours, check-in activity, and team availability—whether you’re managing an entire workforce or just keeping an

• Logistics Industry: Learn to create amazing appointment scheduling sites

  In the logistics industry, the quality of service is something that cannot be shown to others unless they experience it.  Sure, there are metrics that show how you fare when compared to your competition, but then, it only communicates little with respect to quality. The usual route which firms in logistics took are advertisements, to which the internet has opened alternatives in today’s digital age like websites and appointment scheduling sites. A great online presence can help you communicate with

• Customer Management: # 1 Pick a Convenient Way to Onboard Customer

  When Meera opened her bookstore, onboarding customers was effortless. A customer walked in, picked a book and left with a handwritten bill. As the store gained popularity, things changed. " Can I place an order over the phone?" a customer asked one day.

• Fetch ALL items from Inventory and send to Google Sheet using Flow

  The title says it all -- I want to fetch the Item name, SKU, Purchase rate, and Sales rate for ALL items in Zoho Inventory and have them populate a tab in an existing Google Sheet. I have already successfully made this work for one item, so the flow is

• Why Document Integrity Matters at Every Stage of the Contract Lifecycle

  Contracts are legal records that must stay authentic and traceable from creation to expiry or termination. In Zoho Contracts, several design decisions focus on protecting the integrity of every document. These measures ensure that no important details

• affichage pièces jointes impossible

  Bonjour, aujourd'hui je n'arrive pas à afficher ni à télécharger les pièces jointes dans ZOHO CRM. J'utilise Chrome, j'ai vidé les caches et les cookies. Mais cela ne change rien. Merci de votre aide

• Reminder to renew subscription.

  Whenever I try to add to one of my notes a " renew your subscription" window pops out and won't Close disallowing me to edit. Why should I renew my subscription on an application with at best such bugs and at worse such underhanded ways to force ren

• Fields not coming through, not pulling data

  Forgive the noviceness of my vocabulary. I am in Zoho flow connecting CRM and Projects. When an opportunity hits a certain stage, it will create the project in Projects, and bring in data from the opportunity. Everything is working, except for two fields

• Next Page