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.




        • Recent Topics

        • Free webinar alert! Seamless Transition with Lossless Migration: Zoho One + Zoho Mail

          Hello Zoho Mail Community! 🚀 Attention IT Admins and Email Administrators! Are you planning to migrate your organization's email to Zoho Mail within the Zoho One ecosystem? 📧 Join our exclusive webinar, Seamless Transition with Lossless Migration: Zoho

        • Add Resource to Export

          The Export Data feature does not include a column for the Resource field. Without this column, Zoho Bookings cannot be used by any business for resource-based services or event types e.g. room bookings, equipment bookings. It seems to be an oversight,

        • Client Script | Update - Client Script Support For Custom Buttons

          Hello everyone! We are excited to announce one of the most requested features - Client Script support for Custom Buttons. This enhancement lets you run custom logic on button actions, giving you greater flexibility and control over your user interactions.

        • Mandatory field via deluge code

          I would like to ask you if it is possible to make a field mandatory via deluge script. For example, if I have a decision box and I click on it then I want a single line field to be mandatory. If uncheck the decision box then to do the single line as optional. I think it is not possible to do that and I have to do it via validation in 'on validate' field. 

        • Revenue Management: #1 What does it mean to "recognize" revenue?

          Earning revenue isn't just about collecting cash from your customers. It's about recording the income correctly and consistently. Revenue recognition is the process of deciding when and how to record revenue in financial statements so that they reflect

        • Power of Automation :: Auto-Populate Integration Field in Projects with CRM Account Data

          Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

        • Zoho Forms and ChatGPT - populating a field using AI.

          I have a form where I would like the user to enter a response or query, and have another field populated using AI. For example, user enters Field 1, AI populates Field 2 in response. I want to be able to wrap some additional instruction text around the

        • campo tag para api

          debo conectarme a una api de zoho inventory y ocupo tomar el campo tag para poder asi jalar el articulo que cuente con el campo correcto en tag ejemplo que tag existen carro y avion que cuando busque los articulo con tag carro arroje solo estos por mas

        • Uploading file as attachment to Zoho CRM

                 Hi,   I am trying to attach a file to a Zoho CRM contact using Zoho Flow. Right now, I try to do it through the “Upload File” field in Zoho CRM (In my screenshots, it’s called Téléchargement du fichier 1).   Here is what I tried:   Case 1: Webmerge document The Flow is called “Custom Function” (see screenshot 101).   Step  1: Creating a Webmerge document (screenshot 99)   Step 2: I use “Update module entry” to upload the created file. I upload Webmerge’s “Document” in my “Téléchargemet du

        • Zia Answer Bot - Create Ticket

          Surprisingly, the current iteration of Zia will try to answer a question and unless you have "transfer to SalesIQ chat" enabled, it won't create a ticket for the user or offer them a method to create a ticket. We don't want it to create chats for us,

        • meassure leads phases

          Hi, I need to create a table to meassure the time that a lead stay in blueprint phases. the phases are first contact, second contact, lead spam, contacted, appointment. any idea? I have attached an example

        • Zoho Desk API Documentation missing a required field

          We are trying to create a section using this information. Even after preparing everything based on that page, we still get an error. The error we get is this: {"errorCode":"INVALID_DATA","message":"The data is invalid due to validation restrictions","errors":[{"fieldName":"/translations","errorType":"missing","errorMessage":""}]}

        • In the Custom Module I have 500 Records , this 500 record only want to view to the specific user only example user A ,

          In the Custom Module, I have 500 Old records that should only be visible to a specific user, for example, User A. Any new records created from today onwards should be visible to Record owner in the Custom Module. Pls help how i achive this .

        • Invoice template, how to change the text under "Notes" and "Terms and Conditions"

          In "Invoice templates", there are two text/info sections at the bottom:"Notes" and "Terms and Conditions". It is possible to change the names of these two headings, but how is it possible to change/alter the text under it. As a standard it says "Thank you for your business" under Notes - I need to change it into something different- How? Thank you.

        • How to reply to thread via API

          We have built a webapp for our customers that uses the Zoho Desk API to enable each customer to view their full list of tickets, view individual tickets and raise new tickets. The Zoho Desk API doesn't have the ability to reply to a ticket/thread. Replies

        • Sending merged mail templates for signatures fail since today

          We have ZOHO one, we use merge templates in CRM to edit in ZOHO Writer, and from there send it for signature through zoho sign. This all worked up until today, suddenly we read in the log that the merge is succesfull but the sending for signature failed.

        • Feature Request - Make Lead List Larger and Adjustable

          Hi LandingPage team, I recently started using LandingPage and I am happy to share my feedback to help improve the app. I've noticed on the Leads page, there is no option to make the columns wider. It would be great if the comlumns expanded to fit the

        • Zoho Projects - Pin Recent Projects

          Hi Projects Team, It would be great if I could "pin" projects on the Recent Projects list in Zoho Projects. We have some internal projects which we regularly have to add time and some regular client projects. It would be great if I could pin those projects

        • ZDK Error

          I get this error when trying to trigger a CRM Function from Client Script: Uncaught (in promise) ZDKError: {"code":"NOT_ACTIVE","details":{"api_name":"activate_client_from_prospect"},"message":"api is inactive for the given custom function","status":"error"}

        • "Disbursing product components in phases, monitoring them, and displaying only the final product."

          i have a product composed of multiple components, and these components will be delivered to the customer in batches. However, the final invoice should only show the finished product. How can I issue (or release) the components and track their delive

        • Followed Subtasks doesn't show up in the Subtasks Section

          I have a task assigned to me now in the same task, there's a subtask and I am added as the follower on that task Even though I am a follower I still don't see that in the subtasks section The view permission for the profile is Related It's supposed to

        • Tip #39- Strengthen account security with Multi-factor Authentication (MFA) – ‘Insider Insights’

          Securing your organization's data begins with verifying that only the correct individuals have access to it. One of the simplest yet most effective ways to accomplish this is to enable Multi-factor Authentication (MFA) within Zoho Assist. MFA introduces

        • Automate timeout chat tracking with Workflows in SalesIQ

          With our feature-packed Nova release, Workflows has become one of the most powerful tools in Zoho SalesIQ. They let you automate follow-up actions when key events occur, such as when a chat ends, a visitor leaves a bad/good rating, or a lead is updated.

        • Mass edit / Mass update products

          Hi, Is there any way to mass update or bulk edit product fields in Zoho Inventory?

        • Automatic Verification of IMAP Integration Status

          Our sales staff have their O365 email integrated with CRM, over time this integration requires re-authentication via the UI. I can manually check the integration status by accessing Settings -> Channels -> Email -> Email Sharing -> "Configuration Type"

        • Tip of the Week #68– Share and access files faster with Zoho WorkDrive extension.

          Have you ever wasted time searching for the right file to attach to your emails—or worried whether the right people could access it? Without proper sharing settings, files might end up inaccessible to teammates or, worse, visible to people who shouldn’t

        • CV-Library: The Newest Source Booster in Zoho Recruit!

          We’ve expanded your sourcing toolkit — CV-Library, one of the UK’s largest and most trusted online job boards, is now available as a Source Booster in Zoho Recruit. This gives recruiters instant access to millions of UK-based candidate profiles, all without

        • Zoho AI Translate Task as Rest API

          I cant find any docs on how to use Zoho AI Translate Task from a rest api call https://www.zoho.com/deluge/help/ai-tasks/translate.html I am working on a custom Widget and I dont think I can execute zoho deluge ai translate task from a custom widget.

        • Is there the possibility to book less than 250 customer portal users?

          If you use the Creator, which is included in Zoho ONe, you can create a customer portal and give access to a maximum of 3 external people / customers, right? On the Creator website I saw that you can add 250 users for 100€/month. However, we don't need

        • Display Parts custom fields in the Work Order

          Hello, I see that is it possible to add custom fields in the Parts module. Would it be possible to also add those custom fields in the Work Order Module under Parts? This would be very useful for customer who want to showcase more information about parts.

        • Unable to edit Saved Estimates

          We are facing issue with editing the price or discount for a saved estimate for nearly 1 week.

        • Translation Blueprint & Picklists with Custom Values

          Hello everyone, I downloaded the translation file and I'm not finding the blueprint transitions. Does this means that the transitions cannot be translated? Also, the picklist values to be translated in the document are not the same that are actually used the in module. For exemple, for my lead module, the picklist values for Lead Status are : Not-contacted, contacted, junk and lost lead. In the translation document (English to French), this is what I see: PicklistValues.Leads.Lead_Status.Contact

        • How to create a custom sales signal?

          I want to create a custom sales signal for a custom module. is it possible to create one? If anyone know please let me know

        • Only show products in offers based on lead source

          We work with several lead sources, each with their own products and different pricing. For example, one product might have two or three different prices. Sometimes, when creating a quote, the wrong product is accidentally selected. Is there a way to only

        • Narrative 7 - The importance of data sharing

          Behind the scenes of a successful ticketing system - BTS Series Narrative 7 - The importance of data sharing Definition Data sharing requires a commitment to preserving the integrity and dependability of shared data throughout its entire lifecycle. This

        • TrueSync regularly filling up my local disk

          Seems that WorkDrive's TrueSync randomly starts filling up my local hard drive space. None of the folders have been set as "Make Offline" but still it seems to randomly start making file offline. The settings of the app is so minimal and is of no real

        • Check out in Meetings

          Why there is no check out in Meetings of Zoho CRM, very difficult to track

        • Issue with Zoho Projet

          Zoho Project on all the cellphones of my customer is crashing. He has mixed brands (Samsung and Pixel). Everything is fine on website and mobile website. Could not reproduce the issue in workshop using Samsung/Pixel/iPhone Uninstallation of Zoho Project

        • SecurePass email English language issue -- please hire someone to correct the English language issues sprinkled throughout your interface

          I wrote previously about some incorrect English in your SecurePass offering. After about six months it was corrected. I have never revoked permission before today and just discovered another language mistake that was not corrected. When you revoke a SecurePass

        • Published Components

          @zoho team, Checking if we can add a password for the public links as we have non-licensed users

        • Next Page