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.


      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ




                                ご検討中の方

                                  • Recent Topics

                                  • "Zoho CRM Integration" option is missing in Zoho Social Settings

                                    I am trying to integrate my Zoho Social account with my Zoho CRM account. I am on the Professional Trial plan and my user role is "Brand Admin". However, I cannot find the "Zoho CRM Integration" or "Lead Generation" option anywhere in my Zoho Social settings.

                                  • Error 553

                                    Não estou conseguindo enviar ou receber e-mail, sempre dando o erro 553, sendo que há mais de um mês o domínio está pago e liberado. Preciso de um suporte urgente

                                  • Automate insurance document workflows with Zoho Writer

                                    Insurance companies have to deal with creating and managing complex documents and forms, such as policy applications, explanation of benefits documents, brochures, renewals, and claim forms. Handling all of this manually is hugely time and effort intensive,

                                  • Create PDFs with Text so that we can copy from a generated PDF

                                    Currently, any information that a user enters into a field cannot be highlighted and copied from the PDF that Zoho Sign renders. For example, if someone were to provide a phone number in a Zoho Sign text field, you would not be able to copy the phone

                                  • How To Insert Data into Zoho Table using Api

                                    Hi Community, I have created a table inside zoho tables. How do I insert data into table using API. Please tell the exact endpoint and payload , I just have to insert data into table columns. Also tell how to find tableid, viewid, baseid etc. which are

                                  • How do I delete a folder in Marketing Automation?

                                    Folders are used across contact lists and segments, and email templates. How do I delete a folder once it's been created?

                                  • Portal Approval Process

                                    Hi Zoho team and fellow users, I am seeking a method to establish a multi-step approval process between a Zoho user and a portal user (Custom Portal) to review and approve requests through the Custom Portal. For instance, within this setup, one of the

                                  • Narrative 8: Intelligent in-app support that's instantly available anytime and anywhere

                                    Behind the scenes of a successful ticketing system - BTS Series Narrative 8: Intelligent in-app support that's instantly available anytime and anywhere The App Support Across Platforms (ASAP) add-on for Zoho Desk is an independent application that integrates

                                  • Navigation issue — unable to return to Customer page after opening Receipt from Transactions

                                    Steps to reproduce: Open a Customer record. Go to Transactions tab and open a Receipt by clicking its receipt number. After viewing the receipt, clicking browser Back or closing the receipt does not reliably return me to the original Customer record (I

                                  • Thermal Printer Option Needed for Delivery Challan Templates

                                    Currently in Zoho Books, the Delivery Challan template only supports A4 and A5 page sizes. However, in many businesses (especially retail and hardware), we use thermal printers (like 3-inch or 4-inch rolls) to print delivery challans. It would be very

                                  • Separate Default Payment Modes for Receipts vs. Payments

                                    Right now, when I set a default Payment Mode via a customer invoice or Payments Received screen, that same mode shows up for vendor payments (Purchases → Payments Made). 🔹 Request: We need different default modes for: Customer receipts (e.g., default

                                  • Update/Change GSTIN in GST Settings of zohobooks

                                    We are trying to update our GSTIN under the GST settings section of our Zohobooks account Initially, we had entered a dummy GSTIN (123456789123456) to generate a sample invoice before obtaining our official GST registration. After receiving our actual

                                  • Link Payment Mode and Paid Through Accounts

                                    For most users, it's very difficult for them to understand that the Payment Mode is totally independent of the Paid Through account when paying bills. It seems (and is) redundant for them to have to select what is basically the same thing twice. The current

                                  • Lets enable business to choose the default payment mode

                                    Lets enable business to choose the default payment mode so that we do not have choose payment mode again and again for each and every transsctions

                                  • Add Attachment Support to Zoho Flow Mailhook / Email Trigger Module

                                    Dear Zoho Support Team, We hope you are well. We would like to kindly request a feature enhancement for the Mailhook module in Zoho Flow. Currently, the email trigger in Zoho Flow provides access to the message body, subject, from address, and to address,

                                  • South African Payment Gateways

                                    Since the "Demise" of Wave many South African users have moved over to Zoho and yet for years users have been requesting Integration with a South African Payment Gateway to no avail. Payfast was the most commonly requested gateway as it supports recurring

                                  • Has anyone verified if Zoho is PCI compliant?

                                    We are planning on using Zoho to process payments via Authorize.net. We have everything set up and are attempting to complete the PCI DSS SAQ-A requirement for our merchant account. This requires us to prove Zoho has completed the SAQ-D for Service Providers. We need a way to verify compliance, or a copy of an attestation of compliance signed by the appropriate officer at Zoho. I assume I'm not the first person to use Zoho to process payment, and therefore not the first to require this information

                                  • Bigin Plugin for Outlook

                                    Could we get this added? The Gmail version already exists, and I would like to avoid having to make a switch.

                                  • Date does not fit the field

                                    Hi There. I am having fun learning zoho sign API. Today I noticed the "Signed Date" field does not fit, or alternatively the font is to large for the auto field space. See screenshot below. The signed date field is created by putting {{Signdate}} on the

                                  • Tip of the Week #69 – Automate your Zoho TeamInbox tasks with n8n integration.

                                    Don’t waste time repeating the same tasks—like sending follow-up emails or adding new contacts. Let automation save the day. With n8n, an open-source automation tool, you can connect your favorite apps and let them handle the busywork for you. You don’t

                                  • Multi Page/Step Forms in creator

                                    Greetings i was wondering if it's possible to create multipage/step forms on creator similar to what we have on zoho forms. is that possbile? Thanks

                                  • Package Geometry

                                    how can i add the dimensions and weight capacity of the available boxes to be default in the system everytime we use it ?

                                  • How to create a Master Kanban Board that syncs with Child Projects?

                                    Hello, We're currently using Zoho Sprints for managing our interdepartmental teams, and we're looking to enhance our workflow using Kanban boards as part of a company-wide productivity improvement initiative. Our goal is to implement a project structure

                                  • Writer.. Broken?

                                    Hello,  Writer has been really good to me during the months I've used it, up until now.  I usually launch the app by tapping the icon and I could immediately pick up where I left off.  Now I'm greeted by a loading circle not reaching 100% and I only have the option to create a new account.  By pressing that button it now switches to a login screen and I can access my account. However, it seems (only speculating ofc) to be stuck in cell-phone mode? everything looks scrambled.  I can't access any of

                                  • How to access Recruit Variables in a Deluge function?

                                    I have set up Recruit Variables in Zoho Recruit, and I would like to know how to retrieve these variables from within a Recruit custom function (Deluge). Could someone please explain the correct way to access them? I tried the following code, but it did

                                  • Upon De activate a user what name doe sthe contacts candidates go under?

                                    When deactivating a user, does the user name remain the same, as the candidate owner? If not what/who, does it change to? Do I need to change the user name in contacts and candidates before I deactivate the user?

                                  • Weekly Tips: Customize alerts from your Priority Users

                                    You might receive hundreds of emails daily, but messages from your manager, clients, or team leads often require immediate attention, as they may contain urgent requests or critical updates. How would you ensure you never miss important messages from

                                  • Maximum 100 records in Sheet View is limiting. How can I increase this?

                                    Thanks in advance for any help with this. There was a similar post that showed answered but it did not help with increasing the number of records you see in a Sheet View. Editing in the Sheet View is fast and efficient but I have 3500 records and I need

                                  • Revenue Management: #3 Revenue Recognition Simplified

                                    In continuation of the previous post on how to compute revenue recognition, let's explore a solution that helps businesses handle real-world complexities. While the Accounting Standards provide a clear framework for recognizing revenue, the real challenge

                                  • Tip #40- Strengthen Remote Support with IP-based Restrictions in Zoho Assist– ‘Insider Insights’

                                    Protecting sensitive data and preventing unauthorized access is a top priority for any organization. With IP-based restrictions in Zoho Assist, you can ensure that only users from trusted networks can initiate remote support sessions. Say your IT team

                                  • Push Invoices to Xero Manually

                                    Hi guys, I'm wondering if anyone has wanted to do this and has a workaround or knows of an app that may be able to help with this. I sell B2B and B2C. The customers can purchase on our website or through marketplace, all of which send sales to zoho. The

                                  • OpenAI error code: 1010 in a Zobot

                                    Please see short linked screen recording. Insights welcome. Please and thank you! https://workdrive.zohoexternal.com/external/f3247ba9c872639157b707700c0300c433c7664aea924a034f4da3c3ad2e355f

                                  • Ability to Create Sub-Modules in Zoho CRM

                                    We believe there needs to be a better, more native way to manage related records in Zoho CRM without creating clutter. Ideally, Zoho would support "sub-modules" that we can create and associate under a parent module. Our use case: We have a custom module

                                  • Installing EMAIL Setup in New Domain

                                    Respected Support team, I'm facing an issue with cloudflare in Pakistan, I want to setup Zoho Mail Setup but I Don't know how to enable Zoho mail setup without cloudflare. My Website https://stumbleguymod.com/ is using CF, and I want a different Zoho

                                  • Signature change

                                    I cannot see how to change signature or out of office details easily now in the new format.

                                  • Inventory API - Retrieve all uploaded product / item images

                                    I know that I can get the primary image for each product / item or composite item, by using the /image endpoint.  https://inventory.zoho.com/api/v1/compositeitems/<item-id>/image?authtoken=<TOKEN> This will return only one photo, even if the item has multiple images uploaded. Is there a way to retrieve all images stored for an item via the Zoho Inventory API?

                                  • Ebay Integration malfunction

                                    My eBay integration in Inventory has always worked well. It suddenly malfunctioned. It is creating its own parts in Inventory that are unavailable instead of selling the parts I've always sold. Tech help was unable to resolve this. The latest sale attempt

                                  • Introducing Bin Locations In Zoho Inventory

                                    Hello users, We are excited to let you know that your wait for the Bin Locations feature has now come to an end! Yes, you heard us right! We are here to introduce the much-awaited Bin Locations now in Zoho Inventory. But before we dive into the feature

                                  • how to get all the records in the custom View more than 200 records , Without using the page Concept

                                    how to get all the records in the custom View more than 200 records , Without giveing page as default in the Loop Concept Pls help how We can Achive this void schedule.Lead_Attempt_To_contact_schedule_10_30() { pages = {1,2}; for each pg in pages { query_map

                                  • The way that Users can view the ticket

                                    I have created users. What I would like to achieve is the following: All users under the same company account should be able to view each other’s tickets.

                                  • Next Page