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

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



Hello Developers!

Welcome back to another week of Kaizen! 

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

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

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

Why Mandate Subform Data from a Different Module?

In Zoho CRM, subforms manage multiple data entries under a single parent record. However, certain blueprint transitions may depend on subform data from related modules, such as:  
  • A Deal's transition may depend on the document data stored in the associated Contact’s subform.
  • A Service Request requiring validation against a subform in the related Account before processing.  
  • A Loan Application requiring income proof from the Customer’s subform before approval.  
Since blueprint transition rules only validate fields within the same module, you can use a custom widget to check and update subform data across modules before proceeding.

Business Scenario: Insurance Deals Qualification

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

Steps to Build a Blueprint Widget

Step 1 - Review Basics

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

Step 2 - Develop your Widget

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

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

Widget Execution During Transition
  • When the user clicks the Collect Requirements transition, the widget loads.
  • Using the PageLoad event listener, retrieve the current record's ID and module name.
  • Use the GET Records API via its JS SDK to fetch the Contact ID linked to the Deal. 
ZOHO.embeddedApp.on("PageLoad", function(data) {
      // Fetch the current page's record details
      const recordId = data.EntityId;
      const moduleName = data.Entity;
      ZOHO.CRM.API.getRecord({Entity: moduleName, RecordID: recordId})
        .then(function(response) {
          const record = response.data[0];
          console.log("Current Record Details:", record);
          // Fetch the associated contact ID
 contactId = record.Contact_Name.id;

Check and Collect Required Document Details
  • Using the Contact ID, run a COQL query using Connection JS SDK to check if each Document Category has at least one entry in the Document Details subform.
Notes
Notes
In invoke connection JS SDK, use param type 2 for the API request payload inside the parameter key and param type 1 for regular parameters.

Explore the Working with Connections help page and create a connection with the necessary scopes to invoke the COQL API.
  • If all four categories (Address Proof, ID Proof, Income Proof, Medical Report) have at least one entry, the widget allows the transition immediately.
  • If any category is missing, the widget prompts the user to enter the details in a table that mirrors the Document Details subform in the Contacts module.
// Make a query API call 
          const query = {
            "select_query": `select Document_Category,COUNT(id) from Document_Details where id is not null and Parent_Id='${contactId}' group by Document_Category`
          };
          ZOHO.CRM.CONNECTION.invoke("crm_oauth_connection", {
            method: "POST",
            url: "https://www.zohoapis.com/crm/v7/coql",
            parameters: query,
            param_type: 2,
            headers: {
              "Content-Type": "application/json"
            }
 }).then(function(response) {
     const data = response.details.statusMessage.data;
            if (response.details.statusMessage === "" || (data && data.length < 4)) {
              createSubformUI();
              document.getElementById('contentContainer').style.display = 'block';
            } else if (data && data.length === 4) {
              document.getElementById('messageContainer').style.display = 'block';
              // Enable the "Move to Next State" button if all files are already updated
              const nextStateButton = document.querySelector('.nextStateButton');
              nextStateButton.disabled = false;
              nextStateButton.style.backgroundColor = ''; 
            }
 })

Update the Contact's Subform
  • The user enters the document details and clicks the Save button in the widget. 
  • Since subform updates act like a PATCH request, any existing record IDs must be included in the update payload to retain them. To get the existing subform record IDs make a  GET Records API call via its JS SDK. 
async function getExisitingSubFormRecords(contactId) {
let exisitingRecords = [];
awaitasync function getExisitingSubFormRecords(contactId) {
let exisitingRecords = [];
await ZOHO.CRM.API.getRecord({ Entity: "Contacts", RecordID: contactId })
.then(function (response) {
const record = response.data[0];
console.log("Current Record Details:", record);

if (record.Document_Details)
{
record.Document_Details.forEach(function (document) {
exisitingRecords.push({id: document.id});
});
}
})
.catch(function (error) {
console.error("Error fetching records:", error);
});
return exisitingRecords;
} ZOHO.CRM.API.getRecord({ Entity: "Contacts", RecordID: contactId })
.then(function (response) {
const record = response.data[0];
console.log("Current Record Details:", record);
record.Document_Details.forEach(function (document) {
exisitingRecords.push({id: document.id});
});
})
.catch(function (error) {
console.error("Error fetching records:", error);
});
return exisitingRecords;
}
  • Clicking the Save button executes the following actions:
    -> Uploads the selected file to Zoho File System (ZFS) using the Upload File API through its JS SDK.
    -> Updates the Document Details subform in the associated Contact record by adding the file ID from the upload response and each row's entry using the Update Records API (via the Update Record JS SDK).
  • Once the subform is successfully updated, the widget allows the transition to next Blueprint state.
async function updateRecord(event) {
event.preventDefault();
// Collect user entries from each row
const rows = document.querySelectorAll('#documentsTable tbody tr');
const documentDetails = await Promise.all(Array.from(rows).map(async (row, index) => {
const documentCategory = row.querySelector('select[name="documentCategory"]').value;
const documentNumber = row.querySelector('input[name="documentNumber"]').value;
const documentName = row.querySelector('input[name="documentName"]').value;
const documentFile = row.querySelector('input[name="upload"]').files[0];
const fileId = await uploadFile(documentFile);
return {
Document_Category: documentCategory,
Document_Number: documentNumber,
Document_Name: documentName,
Upload: [
{
file_id: fileId
}
]
};
}));
// Get the existing subform records
const existingRecords = await getExisitingSubFormRecords(contactId);
// Merge the existing records with the new records
existingRecords.forEach(record => documentDetails.push(record));
// Prepare the payload for the update API call
const payload = {
id: contactId,
Document_Details: documentDetails
};
// Make the update API call
ZOHO.CRM.API.updateRecord({
Entity: "Contacts",
APIData: payload
}).then(function (updateResponse) {
console.log("Update response:", updateResponse);
const saveButton = document.querySelector('.saveButton');
saveButton.textContent = "Saved";
saveButton.disabled = false;
saveButton.style.backgroundColor = 'grey';
// Enable the "Move to Next State" button after saving
const nextStateButton = document.querySelector('.nextStateButton');
nextStateButton.disabled = false;
nextStateButton.style.backgroundColor = ''; 
})

Step 3 - Validate and Pack the Widget

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

Step 4 - Associate the Widget with the Blueprint

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

Try it Out! 

A complete working code sample of this widget is attached at the bottom of this post for reference. 
 
Now, let us see how this Blueprint works from the Deals page:  
  1. All required document details are available: The widget validates the Contact’s subform and allows the transition.  



  2. Missing or incomplete document details: The widget prompts the user to enter the missing details, updates the Contact’s subform, and then enables the transition.  



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

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

Until next time, Happy Coding! 

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

Additional Reading

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


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



      • Sticky Posts

      • Kaizen #197: Frequently Asked Questions on GraphQL APIs

        🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.

      • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

        Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

      • Kaizen #193: Creating different fields in Zoho CRM through API

        🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.

      • Client Script | Update - Introducing Commands in Client Script!

        Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

        • Recent Topics

        • Uploading Files from uploads api

          I tried uploading the image from the API call but its giving me unauthorized error even i have given valid token in header. After uploading i need that id to pass in create ticket api uploads but its not uploading that file. Please help me out in th

        • Categorize Items with Item Headers

          Hello customers, Did you ever want to classify items based on specific categories to help your customers understand your invoice better? With the new Item Header feature, you can easily categorize items in your invoices and estimates and give them a common title.  Item Headers are available in the Invoices, the Recurring Invoices and the Estimates module. It can be carried forward from estimates to invoices at the time of converting the estimates.  To add an item header: Go to the Estimates, Invoices

        • URLs being masked despite disabling tracking

          Hey, We had disabled click tracking from an email update we are sharing with our users. Despite this, the URL the end user is receiving is masked, and looks like "https://qksyl-cmpzourl.maillist-manage.net/click/1d8e72714515cda6/1d8e72714515ca70" instead

        • Change format of quantity format

          Hi,  I would like to change the qunatity format from 1,00 to 1.  Is this possible?   thanks!

        • square up and Zoho books

          Since we set up the app connection between square up and Zoho books we have realised that when the amounts are getting transferred Zoho is adding VAT again making the numbers 20% more than they should be. We have checked our settings and they VAT/ Tax

        • How to provide Access rights to specific Bank accounts

          We have several bank accounts. I want to provide certain members access to only 2-3 accounts. It appears that when I give permissions, they are for ALL bank accounts. How do I do that?

        • Errors Getting a Bank Transaction

          Using Postman(for testing), I am receiving errors when attempting to get a single bank transaction. I am able to receive the list of bank transactions with https://www.zohoapis.com/books/v3/banktransactions/?organization_id={org_id} but when I try to

        • Subscriptions Plans and CRM Products Integration?

          Is there any way to set up plans and pricing in Zoho Subscriptions and have those available as Products in the CRM? We are trying to set up the CRM and the Products seem to be more geared toward selling products that are not subscription based.  So if we sell annual or monthly contracts which are $10/seat/month, I can set this up as a plan in Subscriptions, but how can I set the same thing up in the CRM for the salespeople to sell/quote? What is the best practice for setting up the CRM Products to

        • Mapping Zoho Subscription Plans and Products to CRM and Books

          We have products that are one time products and subscription products.   1) We would like to have the ability to create an opportunity in CRM that includes both one-time charge products and subscription products.  Currently the only way of creating a subscription product is by defining a "Product->Plan" hierarchy in Zoho Subscription.  It appears that the only SYNC between Subscription and CRM is around contacts and the Product->Plan hierarchy doesn't sync to CRM, thus, you would need a duplicate

        • Zoho People Attendance Module - Split Shifts

          Hello, Our business employs a number of college students who often split their workdays between work hours and class schedules, resulting in split shifts. For example: Employee 1 works 9am to 11:30am and then leaves for class, returning to work at 3pm

        • Bulk update fields based on date

          Hi! I need all the quotes with "Quote Stage" set to "Next Year" to update to "Draft" every January 8 (every year). Can you help?

        • Target for a campaign

          Hi, Hope you can help me. I need to create a report (for a marketing campaign) that combines Deals and Contacts to export all the contacts with closed deals. I can easily do that, what I cannot do is to remove from the target the contacts that have more

        • Zoho Desk + Jira integration - Email notifications and comments posted by administrator instead of real user

          Dear All, I set up the integration under my admin account, and now when users leave comments in Jira (to created tickets in Zoho Desk), the email notifications show that the ‘Administrator’ left a comment, not a real user. The same happens in the ticket

        • Celebrating the power of visuals

          On World Photography Day, we would like to highlight the power of visuals in customer service. Visuals promote learning and understanding in less time. A photograph can rekindle a memory, convey more than words, and give a fresh perspective. How does

        • Customer address in Zoho Bookings

          Hello,  Is it possible to add customer address information to the Zoho bookings appointment screen? Or have it pull that information automatically from the CRM? We are wanting to use this as a field management software but it is difficult to pull the address from multiple sources when it would be ideal to have a clickable address on the appointment screen that opens up the user's maps.  It would also be advantageous for the "list view" to show appointment times instead of just duration and booking

        • Blocking / black listing customers

          Hi, We have a situation, we observed that certain customers are blocking multiple appointments with our advsiors but not showing up. Some of these are repeat offenders. This leads to those service hours getting blocked and not available for genuine customers.

        • Option to block bookings from specific email address or ip adresss in zoho booking

          Sometime few of our client keep booking irrelevant booking service just to resolve their queries and they keep booking it again and again whenever they have queries. Currently its disturbing our current communication process and hierarchy which we have

        • Feature Request: Email Templates for notifications accross all services

          Currently in Zoho Bookings, email notifications (such as booking confirmations, reminders, and cancellations) must be customized individually for each service. This becomes time-consuming and error-prone when managing multiple services that require consistent

        • Allow customers to choose meeting venue and meeting duration on booking page

          My business primarily involves one-to-one meetings with my clients. Given the hybrid-work world we now find ourselves in, these meetings can take several forms (which I think of as the meeting "venue"): In-person Zoom Phone call I currently handle these

        • Approval-based booking with Zoho Creator and Zoho Bookings

          Hi community members, We have developed a workaround for approval-based booking using Zoho Creator and Zoho Bookings! This provides a temporary solution as we work on the native feature, and it's useful for anyone needing an approval workflow when confirming

        • Member Accounts in Related List

          Hi Team, Currently, when a parent account is associated with an account in FSM, there is no related list displaying the associated member accounts under the parent account’s related list section. To view member accounts, I have to manually search using

        • how do i remove a specific Zoho Service from my account

          I no longer need Zoho CRM, ZRM Assist nor ZRM BugTracker. How do I remove them from the list of apps for my account?

        • I Want migarte all invoice details to zoho sheets

          I want to migrate all existing invoice details to Zoho Sheet, and automatically update the sheet whenever a new invoice is created.

        • were can i find my invoices i need this for my accountant

          were can i find my invoices i need this for my accountant, how can i get id direct to my email?

        • ONLY email field not populating Writer fillable document (randomly)

          I have a Zoho Writer fillable document that has pulled all my data from my Zoho Sheets file, EXCEPT the email column. It pulled every data before and after that column with no issues. Screenshots attached. It's not my first time using the app or the feature,

        • My number is marked as spam

          Hello Zoho Mail Support, My phone number was incorrectly flagged as “spam” during sign-up. This is my personal number, and I have not engaged in any spam activities. Kindly review and verify my account so I can proceed with my email setup. Thanks.

        • Personnalisation des paramètres dans Zoho Mail

          Pourquoi cela compte-t-il ? La personnalisation des paramètres dans Zoho Mail permet aux administrateurs de configurer l’environnement de messagerie en fonction des besoins spécifiques de leur organisation. Que ce soit pour alléger l’interface pour certaines

        • How To Save Data Into Zoho CRM Sandbox

          Hi Community, I want to save data into my zoho sandbox , for this I am using this api endpoint - https://www.zohoapis.com/crm/v8/Patients but I am getting this error - { "success": false, "message": "Zoho API request failed", "error": { "code": "INVALID_MODULE",

        • Automate pushing Zoho CRM backups into Zoho WorkDrive

          Through our Zoho One subscription we have both Zoho CRM and Zoho WorkDrive. We have regular backups setup in Zoho CRM. Once the backup is created, we are notified. Since we want to keep these backups for more than 7 days, we manually download them. They

        • Question about retrieving unsubscribed contacts (outside of lists) via API

          Hello, I am currently using Zoho Marketing Automation and would like to integrate it with our company’s core system. For this purpose, I am exploring the API options available to retrieve contact information. Specifically, I would like to know if there

        • Getting “mandatory field missing: Service_Line_Items” When Creating Work Order via Zoho Flow Deluge

          Hi Team, I’m trying to create a Work Order in Zoho FSM with only a Service Line Item (no Parts). However, I keep getting this error: Work Order Response: {"code":"MANDATORY_NOT_FOUND","details":{"api_name":"Service_Line_Items"},"message":"required field

        • How to customize the colors of the Client Portal login screen and add the company logo?

          As title, how to customize the colors of the Client Portal login screen and add the company logo?

        • Daily updates/fixes and how to see what was changed?

          When I receive the notification that zoho was updated and I need to refresh it. How can I see what was changed or fixed? Sometimes they change things that effect my books and I need to know what they did. For example over this past weekend something was

        • Upcoming Change: Snowflake Username/Password Authentication Deprecation – Action Required

          Hello Users, Snowflake has officially announced that username and password-based authentication will be deprecated by November 2025. You can find the official announcement [here]. If you're using a Snowflake connection in Zoho Analytics to import data,

        • Why should I choose Zoho Inventory vs Odoo?

          Hello there! I have used Zoho in different companies I've worked in, and I have a positive perception of it. I am starting a new import business for pipes, tubes, fittings, valves, elbows, etc., which all have serial numbers, cast numbers, etc., so I

        • Product Updates in Zoho Workplace applications | July 2025

          Hello Workplace Community, Let’s take a look at the new features and enhancements that went live across all Workplace applications this July. Zoho Mail Import bookmarks from Pocket Worried about losing your Pocket bookmarks? Don't worry we have got you.

        • PLEASE FIX YOR BUGS

          PICTURES ARE BEING REJECTED DESPITE THEM FOLLOWING THE GUIDELINES ON DIMENTIONS.

        • Kaizen# 204 - Answering Your Questions | Perform Field Updates before Blueprint transition via Client Script

          Hello everyone! Welcome back to another exciting Kaizen post. One of the questions we received through your Kaizen feedback was: “How can I update fields before Blueprint transition and how to prevent a transition based on a condition using Client Script?”

        • Create online meetings for Booking Pages with Zoho Meetings and Zoom

          Greetings, We hope you're all doing well. We're excited to share some recent enhancements to Bigin's Booking Pages. As you know, Booking Pages let you create public pages to share your availability so that your customers can easily book time slots with

        • Filters in audit logs

          Greetings, I hope all of you are doing well. We're happy to announce a few recent enhancements we've made to Bigin. We'll go over each one in detail. Previously, there were no filters available to narrow down data in audit logs. Now, we've introduced

        • Next Page