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 #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

        • Limit maximum entries for subform - depending on fields entry

          Hi Zoho! I have a form with a subform in it. I'd like to have limitation for the row number depending on an entry in a drop-down field in the main form (If the field in the main form is marked "Answer1" - Limit the entries to 1 row, if the field is "Answer2" to have 2 rows limitation, "Answer3" = no limitation at all) Can this be done? Thanks Ravid

        • Save HTML Snippet Page as PDF with Dynamic Data in Zoho Creator (Working Solution)

          Hi Zoho Creator Community 👋, I faced a common challenge while working with HTML Snippet Pages — I needed to generate a PDF with dynamic data and save it back into the record automatically. Here’s the working solution that might help others. Use Case

        • Make Camera Overlay & Recording Controls Visible in All Screen-Sharing Options

          Hi Zoho WorkDrive Team, Hope you are doing well. We would like to request an improvement to the screen-recording experience in Zoho WorkDrive. Current Limitation: At the moment the recording controls are visible only inside the Zoho WorkDrive tab. When

        • Rebranding Options for Zoho One

          We need the addition of rebranding and white-labeling settings directly within the Zoho One Admin Panel. This feature should allow organizations to customize the unified portal with their own logo, brand colors, and custom domain mapping (e.g., portal.company.com).

        • Tip #57- Accessibility Controls in Zoho Assist: Mobility- 'Insider Insights'

          Remote support should be easy to navigate for everyone. For users with mobility-related accessibility needs, long sessions and complex navigation can be challenging. Zoho Assist’s Mobility Accessibility Controls simplify interaction through keyboard-based

        • Total Cost in reports showing zero

          The image below shows my issue. The column Total Cost should show the cost to our company based on hours logged and the employee's rate. For instance, if the person working on Subtask 1 is paid 20/hr, then Total Cost should display $160 ($20x8 logged

        • To print Multiple delivery notes in batches

          In Zoho Books, we can print a Delivery Note from an Invoice using the Print Delivery Note option, but it is non-editable and always prints all line items from the invoice. Our requirement is to deliver invoiced items in batches and print delivery notes

        • Invoices not arriving and mail server settings

          I am having an issue where some clients are not receiving invoices. I have configured Zoho Books to send on my behalf and configured the appropriate SPF, DKIM and DMARC settings on my mail server and tested these as working. I get the CC'd copies so I

        • UPLOAD A CREATED PDF AUTOMATICALLY

          Using the html header pdf+print button, I have managed to find a way to have a user create a pdf using entered form data. Using the schedule button, I can have a "file uploaded" pdf mailed to someone as an attachment. The missing piece is to be able to add the pdf, created in that html page to a file upload field automatically? Right now one has to save it to computer and then upload it in a FILE UPLOAD FIELD. Any help would appreciated !  

        • Consolidated Department-wise Payroll Cost Summary Report

          Hello Zoho Payroll Team and Community, I am writing to discuss a reporting requirement regarding department-level expense tracking within Zoho Payroll. As we scale and manage salary distribution for employees across multiple departments, such as Accounts,

        • How to remove chat icon from knowledge base?

          I have set up a knowledge base to hold FAQs and documentation. It is currently standalone, and not integrated into our website. On every page there is a chat button in the bottom left corner that says "We're offline, please leave a message." How can I

        • [ZohoDesk] Improve Status View with a new editeble kanban view

          A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to edit

        • Automated Dismissal of Specific Notifications and Centralized Control of Toast Notification Settings

          Dear Zoho Team, I hope this message finds you well. We would like to request two enhancements related to notification handling within Zoho Desk: Automatic Dismissal of Specific Notifications: Currently, when certain actions are taken in the ticket list

        • Show field in spreadsheet view depending on other field value

          Hello. Not sure if this is possible but let's say i have spreadsheet view in Creator with four different fields Field A, B, C and D Then i have a field named Response which for one record could contain only one of the pre-definde choices below A, B, C

        • Intergrating multi location Square account with Zoho Books

          Hi, I have one Square account but has multiple locations. I would like to integrate that account and show aggregated sales in zoho books. How can I do that? thanks.

        • Zoho Learn Zapier Integration

          Hello all, Is there any plan to integrate Zoho Learn with Zapier? It seems almost all Zoho products are in Zapier, with the exception of Learn and Marketing Automation.

        • Notice: SalesIQ integration paused on Zoho Sites

          I have this notice on my Zoho Sites in the SalesIQ integration setup. Can someone assist? "This integration has been temporarily paused for users. Reconnecting SalesIQ after disconnection will not be possible until we provide further updates." thank

        • Differences between Zoho Books and Zoho Billing

          Without a long drawn out process to compare these. If you were looking at these Books and Billing, what made you opt for one and not the other. Thanks

        • New Feature : Copying tickets with all the contents such as conversations/history/attachments etc

          Sometimes our customers and distributors do create tickets (or send emails) which contain more than one incident in them and then also some of the further conversations which are either created by incorrect new tickets or replies to old tickets are being created as combined tickets. In such cases we require to "COPY" the contents of the tickets into separate tickets and merge them into their corresponding original tickets. The "CLONE" feature doesn't copy the contents (especially the conversations

        • Como se agregan los empleados

          Necesito saber si para agregar empleados los mismos necesitan tener licencias

        • Deluge Error Code 1002 - "Resource does not exist."

          I am using the following script in a Custom Button on a Sales Return. Basically, the function takes the information in the sales return (plus the arguments that are entered by the user when the button is pushed) and creates a return shipping label via

        • Adding multiple Attendee email addresses when adding a Zoho Calendar event in Zoho Flow

          I am trying to integrate Notion and Zoho Calendar via Zoho Flow. However, the Attendee email address supported by Zoho Calendar - Create event only supports one email address, so I am having difficulty implementing automation to automatically register

        • Graceful Handling of Exceeded Option Limits

          Hi Zoho SalesIQ team. I would like to submit a feature request to deal with a bug in salesIQ Current Behavior (Bug): When a dynamic list passed to the Single Select Option Card contains more than 20 options, the Zobot stops responding (freezes/hangs)

        • System default SLA descriptions can't be modified

          The system default SLAs have identical descriptions for all SLA levels, but their settings differ. However, I am facing an issue where I cannot modify these descriptions and save the changes. The content of the description box can be edited but the changes

        • Adding non-Indian billing address for my Zoho subscription

          Hey Need help with adding a non-Indian billing address for my Zoho subscription, trying to edit the address to my Singapore registered company. Won't let me change the country. Would appreciate the help. Regards, Rishabh

        • How to create one ZohoCRM organisation out of a multi-organization?

          Hi, we have a multi-org including two different Zoho CRM organizations for two companies using respectively EUR and USD as default currency. I was wondering if there is any easy way to merge the two organizations into just one, so that users may access

        • Gray screen while signing documents

          We are all getting a "gray" screen when trying to sign documents in Zoho sign. Anyone else having issues?

        • Projects custom colors replaced by default orange

          Since yesterday, projects uploaded to Zoho, to which I had assigned a custom color, have lost the customization and reverted to the default color (orange). Has anyone else had the same problem? If so, how did you resolve it?

        • Interview booked through Invite but no Notifications

          We have a workflow that was developed through a developer/partner that was tested and worked. Today, we pushed a candidate through the process and invited them to an in-office interview. They were sent the booking link (as usual and as tested before successfully)

        • WebDAV support

          I need WebDAV support so that I can upload/download (and modify) documents from my local file system. Is anything planned in his direction?

        • Automatiser la gestion des SLA dans Zoho Desk avec Zoho Contracts

          Les équipes du service client s’efforcent d’assurer un support rapide, régulier et fiable pour garantir la satisfaction de chaque client. Les accords de niveau de service (SLA) permettent de clarifier les engagements en définissant les termes et conditions

        • iOS App doesn't refresh for Document Creation

          Hello Zoho team, I have created a workflow to be used on a mobile iOS device which starts in Zoho Creater and ends with a murge and store function that then opens the newly created document within the Zoho Writer app. This process is working great however

        • Uploading a signed template from Sign to Creator

          Good day, Please help me on how to load a signed document back into Creator after the process has been completed in Sign. Below is the code that I am trying, pdfFile = response.toFile("SignedDocument_4901354000000372029.pdf"); info pdfFile; // Attach

        • Zoho DataPrep and File Pattern configuration

          I'm using Zoho data prep to ingest data from One Drive into Zoho Analytics... The pipeline is super simple but I can't any way to get all the files that I need. Basically I need to bring all the files with a certain pattern and for that I'm using a regex

        • Assistance needed: Activation of a domain

          Hello Zoho Support, I purchased the .com domain "primesolva.com" via Zoho 6 days ago. The domain is still pending, and I cannot access the DNS panel to add the TXT verification for domain ownership. Please confirm the registration status and help me activate

        • Operation not permitted

          I am trying to add an email address to the list of user but I am getting error Operation not permitted

        • Request to Permanently Delete Email User (info@mehbobgulf.com ) from Old Organization

          Please permanently delete the user email info@mehbobgulf.com It is still associated with my old Zoho organization. I cannot delete it because it shows ‘You cannot delete email. Zoho host’. I need to use this email in a new Zoho account.”

        • Client host [89.36.170.5] blocked using Spamhaus

          Hello please make make actions for delist ..... "Client host [89.36.170.5] blocked using Spamhaus"

        • Suggestion: Option to Re-run a migration

          As I'm going through a migration process, I like the IMAP migration tool, but it would be better if there were an option to re-run the same migration as configured. There's not even an option to copy/edit one that's already there. Just run if it hasn't

        • Issue with "Add Your Mobile Number"

          Hello, I am trying to sign up for email service for a domain name, and I cannot finish the authentication. When I enter my mobile number, I receive the message "We’re unable to send OTP to this mobile number. Please contact support-as@zohocorp.com". I

        • Next Page