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

• Cannot connect to imap.zoho.eu on iOS26

  Hey, I recently migrated to another iPhone and since then use iOS26. Every since then, I was not able to connect to "imap.zoho.eu" from Apple Mail. I tried deleting the account and adding it again, did not work. I tried creating an app password, didn't

• Personalize your booking pages with Custom CSS

  Greetings from the Zoho Bookings team! We’re introducing Custom CSS for Zoho Bookings, designed to give you complete control over the look and feel of your booking pages. With this new feature, you can upload your own CSS file to customize colors, fonts,

• Marketer's Space: Plan smarter with Zoho Campaigns' Calendar

  Hello Marketers, Welcome to another post! Today, we'll talk about a discreet yet significant feature that's neatly tucked inside Zoho Campaigns: the calendar. It might look like an optional but somewhat unnecessary feature that you can use occasionally,

• User

  If user is already part of manage engine endpoint central , what hapens when i try to add them to another Zoho org / directory? Are these users added as external users?

• Create static subforms in Zoho CRM: streamline data entry with pre-defined values

  Last modified on (9 July, 2025): This feature was available in early access and is currently being rolled out to customers in phases. Currently available for users in the the AU, CA, and SA DCs. It will be enabled for the remaining DCs in the next couple

• Outlook - Zoho CRM Calendar Integration

  I'm facing an issue integrating Outlook with Zoho CRM. Has anyone successfully connected their Outlook to Zoho, and are all your meetings and emails being captured correctly in the CRM? Any insights or troubleshooting tips would be appreciated

• 【Zoho CRM】ポータル機能のアップデート

  ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中から、ポータル機能のアップデートをご紹介します。 ポータル管理の新機能「自動招待」により、Zoho CRMからポータルへの招待を自動化できるようになりました。これまで必要だった、ユーザーごとの手動設定は不要になります。設定した条件に基づいて、対象ユーザーに自動で招待が送信されます。 ポータルの新機能 条件に基づく自動招待：指定した条件を満たすユーザーに、自動で招待を送信 招待設定：招待メールの言語を選択し、言語ごとに条件を設定可能

• Contact data removes Account data when creating a quote

  Hi, Our customer has address fields in their quote layout which should be the address of the Account. They prefill the information, adding the account name - the address data is populated as per what is in the account - great. However when they then add

• Export all of our manuals from Zoho Learn in one go

  Hi, I know there's a way to export manuals in Zoho Learn, but I want to export everything in one go so it won't take so long. I can't see a way to do this, can I get some assistance or is this a feature in the pipeline? Thanks, Hannah

• Automation#31: Automate Splitting Names for New Contact Records

  Hello Everyone, This week, we present to you a custom function, which allows you to split the first and last names from the user's email ID based on the separator used in the ID. Having grown into a large firm, Zylker Techfix aims to optimize its processes,

• Automatically remove commas

  Team, Please be consistent in Zoho Books. In Payments, you have commas here: But when we copy and paste the amount in the Payments Made field, it does not accept it because the default setting is no commas. Please have Zoho Books remove commas autom

• Project Change Orders and Additions

  We are in the process of migrating from QuickBooks Online to Zoho Books. We have Zoho One and like the ability to sync all of our data across everything. And I like that projects work in a way that's less dumb than QuickBooks. I'm trying to figure out

• ZOHO Desk - Description of slave ticket disappeared after Merge

  Dear Support, On Zoho Desk the description of a ticket disappeared after merging two ticket. The one which was the slave one completely disappeared. The problem that in this description there was an image which i had only on Desk in that ticket. Could

• How do I insert a cross-reference link to a different section within one Knowledge Base article using Zoho Desk?

  I would like to insert a link within a Knowledge Base article to a different section of that same article. The section I want to link to is formatted with the Heading 3 style and is displayed within my TOC. However, I do not see any way to add a link

• Problem Adding Facebook Account

  Hi, I'm new here, I'm having trouble setting up my Facebook account as a social channel. I think the issue is down to how my Facebook is set up, which is pretty confusing. I have a personal Facebook account (let’s called it A) which is my main Facebook

• Zoho Desk Teams App is not loading

  Hi Zoho Desk support. Need an assistance on the Zoho Desk Teams app. Once I click View Ticket, it isn't showing anything. Kindly refer to attached: ZohoDesk Teams App_View Ticket Error.jpg For our Dashboard, we are still experiencing the same issue. Kindly

• 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

• Mapping a new Ticket in Zoho Desk to an Account or Deal in Zoho CRM manually

  Is there any way for me to map an existing ticket in Zoho desk to an account or Deal within Zoho CRM? Sometimes people use different email to put in a ticket than the one that we have in the CRM, but it's still the same person. We would like to be able

• Which WhatsApp API works seamlessly with Zoho CRM?

  I’m exploring WhatsApp API solutions that integrate seamlessly with Zoho CRM for customer communication, lead nurturing, and automation. I would love to hear insights from those who have successfully implemented WhatsApp within Zoho CRM. My Requirements:

• Allow people to sign a zoho form by using esign or scanned signature

  Allow people to sign a zoho form by using esign or scanned signature

• Button to Reapply Filters on Sheet(s)

  I wrote a macro that I attached to a button to reapply the filters on all my sheets and it says it works, but it doesn't actually do anything. What is wrong with it? Is there another way? Or even make it work for one sheet? Sub UniversalFilterRefresh()

• Integrate Multiple ZohoBooks organization with zoho projects

  We have successfully connected our Zoho Books with Zoho Projects for synronizing timesheet data. Our Business specialty is, that the staff of the Main company (A) is working on several projects, but the Clients are sometimes contracted and paying to a

• Zoho OAuth Connector Deprecation and Its Impact on Zoho Desk

  Hello everyone, Zoho believes in continuously refining its integrations to uphold the highest standards of security, reliability, and compliance. As part of this ongoing improvement, the Zoho OAuth default connector will be deprecated for all Zoho services

• How do I add todays date to merge field

  I don't see any selection of todays date when creating a letter. Surely the date option of printing is standard? John

• Tracking Emails sent through Outlook

  All of our sales team have their Outlook 365 accounts setup with IMAP integration. We're trying to track their email activity that occurs outside the CRM. I can see the email exchanges between the sales people and the clients in the contact module. But

• Whats that

  Price?

• The same Contact associated to multiple Companies - Deals

  Hi, I would like to know if there is an option to associate the same contact with multiple companies (two or more) deals, using the same contact details for all. This is because we have contacts who are linked to different companies or branches of the

• Portals-Adjust Column Sizes

  I am trying to adjust the column widths in Portals tabs. Columns that don't need to be wide are wide and longer ones are very short. I thought adding more to the digits box in Edit would widen them, but it doesn't. Anyone know how to adjust these?

• Add link/button to open approved record from approval list and detail views?

  Hi, How do I allow users to click on an approval record and open that submission? For example, userA submits a quotation then userB approves/rejects. They both can see the quotation on "completed task" list & detail views, but there's no way for them

• record submitted from creator and invoice is creating in books , but the workflow of books is not tiggering on create of record in books

  record submitted from creator and invoice is creating in books , but the workflow of books is not tiggering on create of record in books headermap = Map(); headermap.put("X-ZOHO-Execute-CustomFunction","true"); response_inv = invokeurl [ url :"https://www.zohoapis.com/books/v3/invoices/fromsalesorder?salesorder_id="

• Prevent editing of a record after getting approved/rejectedr

  Hi, I'd like to block any user from editing a record after it was approved or rejected, how can I do that?

• Formula Field/Campo de Fórmula

  Hello everyone, I have a purchase requisition form in which each department submits a request, and the request is automatically routed to the person responsible for that department. In this form, I have several fields with the following link names: Quantidade1,

• Formatting Problem | Export to Zoho Sheet View

  When I export data to Zoho Sheet View, ID columns are automatically formatted as scientific notation. Reformatting them to text changes the actual ID values. For example, 6557000335603071 becomes 6557000335603070. I have attached screenshots showing this

• Feature Request - The Ability to Link A Customer with a Vendor

  Hi Finance Suite Team, Many businesses buy and sell products from the same companies or individuals. For example, a car sales business may buy a car from a member of the public, and that member of the public may also buy a new car from us. This makes

• Long table name (sync from Zoho Creator)

  Dears, How can I remove the suffix in parentheses? These tables are synced from Zoho Creator and are treated as system tables, so their names cannot be changed. This issue makes the aggregation formulas look awful.

• [Free Webinar] Learning Table Series - Streamlining incident management process with Zoho Creator

  Hello everyone, We’re excited to invite you to another edition of the Learning Table Series webinar. As you may already know, we've moved to a purpose-based approach in the Learning Table Series this year. Each session now focuses on how a Zoho Creator

• Unattended - Silent

  How can I hide the tray icon / pop up window during unattended remote access for silent unattended remote access?

• Importing into Multiselect Picklist

  Hi, We just completed a trade show and one of the bits of information we collect is tool style. The application supplied by the show set this up as individual questions. For example, if the customer used Thick Turret and Trumpf style but not Thin Turret,

• Text snippet

  There is a nice feature in Zoho Desk called Text Snippet. It allows you to insert a bit of text anywhere in a reply that you are typing. That would be nice to have that option in Zoho CRM as well when we compose an email. Moderation Update: We agree that

• Marketing Tip #18: Make your online store mobile-friendly to improve traffic

  Most online shoppers browse on their phones first. If your store is hard to read, slow to load, or tricky to navigate on mobile, they’ll bounce fast. A mobile-friendly store doesn’t just look nice; it improves engagement, reduces drop-offs, and helps

• Next Page