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

• Bookings duration - days

  Hi team, Is there any way to setup services/bookings that span multiple days? I am using Zoho Bookings for meeting room bookings. Clients may wish to book a room for more than one day, for up to a month.  If not, is there a plan to allow services to be setup with durations of Days as well as hours and minutes? Many thanks, Anna.

• big 5 accounts

  how do you find what accounts are listed as Big 5 ?

• Zoho recruit's blueprint configuration is not functioning as mapped

  Current Status: Zoho Blueprint is not functioning as configured. Issue: We are moving a Candidate status in Zoho Recruit "for active file" but we encountered: "Status cannot be changed for records involved in Blueprint." This happens to various client

• Actual vs Minimum

  Hi all, I am sure I am not the only one having this need. We are implementing billing on a 30-minute increment, with a minimum of 30 minutes per ticket. My question is, is there a way to create a formula or function to track both the minimum bill vs the

• Delay in rendering Zoho Recruit - Careers in the ZappyWorks

  I click on the Careers link (https://zappyworks.zohorecruit.com/jobs/Careers) on the ZappyWorks website expecting to see the job openings. The site redirects me to Zoho Recruit, but after the redirect, the page just stays blank for several seconds. I'm

• How to add interviews through API

  I'm trying to add an interview without much luck. The documentation gives examples of adding just about everything except an interview. However, the issue might be the way I'm formatting it, because the documentation is unclear to me. It seems as if the xml should be passed in the url, which seems unusual. I've tried the data as both plain and character escaped, but nothing seems to work, nor do I even get an error response. https://recruit.zoho.com/recruit/private/xml/Interviews/addRecords?authtoken=***&scope=recruitapi&version=2&xmlData=<Interviews> <row

• Offer already made- but I withdrew it

  I made an offer letter, but made a mistake on it. I withdrew the offer but now I can't recreate the correct offer. Zoho keeps saying that "A same offer has already been made". I look in the "offers" and there are NO offers (this is the first time I've

• Control the precision of answer bot responses

  Hello everyone, Admins can control the precision with which the Answer bot analyzes and generates a response by adjusting the threshold levels. Based on predefined threshold values, Zia analyzes how closely the query matches with the available KB articles.

• Rebrand your CRM with the all-new custom domain mapping setup

  UPDATES TO THIS FEATURE! 19th Jan, 2024 — Custom domain mapping has been made available for portal users in Zoho One and CRM Plus. 23rd June, 2023 — Custom domain mapping has been made available for all users, in all DCs. Hello everyone! We are elated

• Add Israel & Jewish Holidays to Zoho People Holidays Gallery

  Greetings, We hope you are doing well. We are writing to request an enhancement to the Holidays Gallery in Zoho People. Currently, there are several holidays available, but none for Israel and none for Jewish holidays (which are not necessarily the same

• Sender Email ID is duplicate

  My sender id "automate@erplaunchpad.com" is coming as duplicate but I have not used it anywhere else please help

• CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

  Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

• Building Toppings #6 - Install and uninstall actions

  Hello Biginners! In our previous forum post, we explored creating connections - specifically, custom service connections in the Bigin Developer Console. In this post, we'll focus on another feature that can be used in every topping: install actions. We'll

• New UI in Zoho One CRM

  Hello, Just switched to the new UI for Zoho One CRM, do not like it, especially the search functions. What are the steps to backstep to the previous UI? UPDATE: I found it.

• App like Miro

  Hi all, is there a way to have a interactive whiteboard like in Miro? We want to visualize our processes and workflows in an easy way.

• Important updates to your connectors

  Hello everyone, Greeting from Zoho Creator! We're excited to announce that we'll be rolling out significant backend updates to Zoho Creator's built-in connectors to enhance security by following the latest frameworks. The existing version of some of the

• Product Request: Send email to Secondary email

  Guys, we should be able to send the campaign to the secondary email too.  Is this on the plans for Zoho Campaign? It looks like I can map the secondary email from the CRM to the Campaigs, but can not send the message.  

• Logic for sending to a non-primary email address

  Hi, I have a scenario where contacts are able to sign up for emails with 2 different email addresses (example: work, personal). I've mapped both to Campaigns from Zoho CRM, but when I go to target an email only the primary email addresses are pulling in. How can I update this to look at both of the email addresses - or specifically the secondary email address in Campaigns? Thanks, Jenny

• How Do Mutliple Sales People Prospect in the "LEADS" module without calling the same leads?

  We have 4 sales reps and the Leads module does not have real time intuitive knowlodge to make the sales rteps dont call the same people at the same time. How can we crate a fluent prospecting sytem where the salres reps can go out bound without calling

• Keeping track of project expenses

  I have talked to a few support techs and it is very hard for me to believe that Zoho's project accounting software can't keep accounts for my projects. I must not understand what they're saying. We get a contract to build something. So the project revenue

• Mailbox delegation - A secure way to enable collaboration

  Admins often encounter scenarios where a user needs another team member to access and manage their mailbox during extended leave, role transitions, or while handling high email volumes. In such situations, ensuring business continuity without sharing

• Canvas View bug

  I would like to report a bug. When clone a canvas view from an existing canvas view, if the original canvas view have canvas button with client script. Then the new create canvas view will have canvas button, it is make sense. But when I try to delete

• Export blueprint as a high-resolution PDF or image file

  This would be a good feature for organizations that want to share the blueprint process with their employees but don't want them to have access to the blueprint in the system settings. At the moment all that users can do is screenshot the blueprint or

• Zoho Recruit Community Meetup - London 🇬🇧 (Venue Finalised)

  Hello Recruiters! We’re excited to announce that the Zoho Recruit team is coming to the UK for an in-person Zoho User Group (ZUG) Meetup in London! This is your chance to connect with fellow Zoho users, learn from experts, and walk away with actionable

• Users may not pick the fields to be shown as columns in the Choose Account window when creating a new Deal record

  Hi there, by talking with other users I found out that I, as an Admin, am the only one who can pick fields to be shown as columns in the Choose Account window when creating a new Deal record. In fact, if other users click on the "Add Column" symbol on

• 【参加無料】東京 Zoho ユーザ交流会 NEXUS ー AI エージェント (Zia Agents)の活用事例 / CRMで実現するマーケティング業務効率化

  ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で「東京 Zoho ユーザー交流会 NEXUS」を開催します！ ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー ✒️申し込みはこちらから：https://www.zohomeetups.com/tokyo2026vol1#/?affl=communityforumpost2 ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー ★参加のおすすめポイント ✅ AIエージェント（Zia）のリアルに使える実例を知る

• Error AS101 when adding new email alias

  Hi, I am trying to add apple@(mydomain).com The error AS101 is shown while I try to add the alias.

• ZOHO.CRM.UI.Record.open not working properly

  I have a Zoho CRM Widget and in it I have a block where it will open the blocks Meeting like below block.addEventListener("click", () => { ZOHO.CRM.UI.Record.open({ Entity: "Events", RecordID: meeting.id }).catch(err => { console.error("Open record failed:",

• Python - code studio

  Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

• 🚀 WorkDrive 6.0 (Phase 1): Empowering Teams with Content Intelligence, Automation, Accessibility, and Control

  Hello, everyone! WorkDrive continues to evolve from a robust file management solution into an intelligent, secure, and connected content collaboration platform for modern businesses. Our goal remains unchanged: to simplify teamwork, strengthen data security,

• Introducing Workqueue: your all-in-one view to manage daily work

  Hello all, We’re excited to introduce a major productivity boost to your CRM experience: Workqueue, a dynamic, all-in-one workspace that brings every important sales activity, approval, and follow-up right to your fingertips. What is Workqueue? Sales

• Support Custom Background in Zoho Cliq Video Calls and Meetings

  Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement to the video background capabilities in Zoho Cliq, specifically the ability to upload and use custom backgrounds. Current Limitation At present, Zoho Cliq allows

• Upload own Background Image and set Camera to 16:9

  Hi, in all known online meeting tools, I can set up a background image reflecting our corporate design. This doesn't work in Cliq. Additionally, Cliq detects our cameras as 4:3, showing black bars on the right and left sides during the meeting. Where

• ISO 27001 Compliance

  What are people doing to ensure ISO 27001 compliance for their Zoho environments? It would make sense for Log360 Cloud to integrate natively with the Zoho suite, but that is not the case. It requires a gateway cluster, which is not an option for a fully

• Zoho People - Retrieve the Leave Details - get("LeaveCount")

  Hi, Zoho People I need to collect all of an employee's leave requests for the calendar year and check how many half-days they have taken. If I run the script on the query he just modified, I can retrieve the information related to that query and use the

• What's new in Zoho Sheet: Simplify data entry and collaboration

  Hello, Zoho Sheet community! Last year, our team was focused on research and development so we could deliver updates that enhance your spreadsheet experience. This year, we’re excited to deliver those enhancements—but we'll be rolling them out incrementally

• Marketer's Space: New to Campaigns? Some common early mistakes that might occur

  Hello Marketers, Welcome back to another post in Marketer's Space. If you're just getting started with Zoho Campaigns, things can feel exciting and slightly confusing at the same time. You're not alone. Most early frustrations come from setup gaps rather

• This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details

  Hello, Just signed up to ZOHO on a friend's recommendation. Got the TXT part (verified my domain), but whenever I try to add ANY user, I get the error: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details I have emailed as well and writing here as well because when I searched, I saw many people faced the same issue and instead of email, they got a faster response here. My domain is: raisingreaderspk . com Hope this can be resolved.  Thank you

• Workflow Rule - Field Updates: Ability to use Placeholders

  It will be great if you can use placeholder tags to update fields. For example if we want to update a custom field with the client name we can use ${CONTACT.CONTACT_FIRSTNAME}${CONTACT.CONTACT_LASTNAME}, etc

• Need a Universal Search Option in Zohobooks

  Hello Zoho, Need a Universal Search Option in Zohobooks to search across all transactions in our books of accounts. Please do the needful Thanks

• Next Page