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

    • Kaizen #152 - Client Script Support for the new Canvas Record Forms

      Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

    • Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

      Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

    • Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

      Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

    • Recent Topics

    • Automatic Portal invite

      We have numerous customers we move through a blueprint in deals, when they get to a certain point we need to give them portal access, how can this be done through deluge or a workflow?

    • Preview Emails with Merge Fields before sending

      Hello, Are there plans to preview an email with merge fields before sending out? Currently, all you see in the preview are the merge field values, but before I send out the email I want to make sure the merge is working. Also, the saved emails only show

    • User Filter not selecting All Items

      We are encountering 2 issues when using the user filter. When users are trying to search using the filter option, the OK button is grayed out. Users have to unselect or make a change before it filters properly. 2. When filtering and the OK button works,

    • Support Nested JavaScript Variables in PageSense Pop-up Targeting

      Hello Zoho PageSense Team, I hope you're doing well. I’d like to request a feature enhancement for the PageSense pop-up targeting functionality. Current Limitation: Currently, PageSense pop-ups can be triggered using simple JavaScript variables. However,

    • Cannot Invert Axis for Rankings

      Hi there I want to be able to create a ranking graph in Analytics/BI, with 1 at the top of the Y axis, but I am unable to invert the axis. Super simple example in Excel below. Higher rankings need to be higher up on the graph to give the correct visual

    • How to copy value from a single line field into a picklist field within a module's subform?

      Hello there, I have a single line field in a module's subform. I would like the value in the field to automatically update a picklist field within the same subform (both have items with the same names). Is this possible via function? Unfortunately, workflows

    • Committed Stock and To Be Received Stock via API?

      Is it possible to retrieve Committed Stock and/or To Be Received Stock for an Item via the API? I want to use this information for calculating the amount of inventory needed to be purchased.

    • Creating Email template that attaches file uploaded in specific field.

      If there's a way to do this using Zoho CRM's built-in features, then this has eluded me! I'm looking to create a workflow that automatically sends an email upon execution, and that email includes an attachment uploaded in a specific field. Email templates

    • Marketer’s Space - Automate a Personalized Holiday Workflow with Zoho Campaigns

      Hello marketers, Welcome back to another post in Marketer’s Space! From Thanksgiving through Christmas, you have a flurry of opportunities to connect with your audience. In this post, we’ll see how you can plan an entire month-long automated workflow

    • Service Account Admin for API Calls and System Actions

      Hello, I would like to request the addition of a Service Account Admin option in Zoho product. This feature would allow API calls and system actions to be performed on behalf of the system, rather than an active user. Current Issue: At present, API calls

    • Sorting columns in Zoho Projects

      Hi, In project management best practice, sorting columns (ascending, descending) is an important tool. Sorting dates to see the order of tasks starting, sorting on priority or even on planned hours is a must for an efficient project control. Currently,

    • Zoho CRM - Calendar Cards View - Let Users Decide What Is Displayed On Calendar Entries

      Imagine planning your week of face-to-face meetings across three counties. You’re trying to group appointments by location to make the best use of your time, but Zoho CRM’s calendar doesn’t show where each meeting is happening. You’re left trying to remember

    • Zoho Inventory - How to pay a supplier up front then receive multiple deliveries

      How do we manage situations where we pay a supplier up front, then the receive the products in increments? Example Workflow: Create Purchase Order > Receive Bill for full amount > Receive Items 2 or more deliveries. Currently, once a Bill is created against

    • How can I add or change the active customer in Zoho Projects?

      I'm trying to change the customer in an active Zoho project. Is it possible to add or change the customer?

    • What happens when someone clicks 'unsubscribe' in a zoho CRM email

      Hello, As per, i am going round in circles trying to find an answer to these 2 question. I have an email template that has an unsubscribe link in the footer in zoho CRM. First, what happens when someone clicks it - where does the contact get unsubscribed

    • Zoho CRM - Scheduled Reports Which Contain Chart

      Hi Zoho CRM Team, I'm requesting that the Report Export and Scheduling feature be enhanced to include a chart, if one has been created on a report. At the moment I have a report which shows Sales This Week by Deal Owner and a pie chart at the top of the

    • Can I add Conditional merge tags on my Templates?

      Hi I was wondering if I can use Conditional Mail Merge tags inside my Email templates/Quotes etc within the CRM? In spanish and in our business we use gender and academic degree salutations , ie: Dr., Dra., Sr., Srta., so the beginning of an email / letter

    • Cadences

      I have just started using Cadences for follow-up up email pipeline. Is it just me or do you find the functionality very basic? For example, it will tell me (if I go looking for it) if someone has replied to a follow-up and been unenrolled; but it won't

    • Canvas View in Zoho Recruit

      Is it possible or would it be possible to have the new 'Canvas View' in Zoho Recruit?

    • Zoho Inventory - Move Orders

      Quick question about Move Orders... Why is there no status to say something like "Draft", "In Progress" and "Completed", similar to Transfer Orders? I'm assuming that when something needs to be moved it should be planned in Inventory, executed and then

    • Kaizen #215 - Workflow APIs - Part 3 - Create and Update Workflow Rules

      Welcome back to another week of Kaizen! Over the last couple of weeks, we’ve joined Zylker Cloud Services as they review and improve their workflows. In Part 1, we discovered and audited their sprawling workflow landscape. In Part 2, we learned how to

    • DataPrep Bigquery Connection failed

      Hello everybody, I want to create a connnection beetwen Bigquery and Dataprep but when I try to connect my project I got this error Loading tables has failed. Table list fetched from the data source expired.

    • Utilisation de Zoho en conformité avec l’article 286 du Code général des impôts (CGI)

      Cher(e) client(e), Conformément à l’article 286 du Code général des impôts (CGI) impose aux entreprises assujetties à la TVA d’utiliser des systèmes de caisse ou de gestion commerciale certifiés lorsqu’elles enregistrent des ventes à des particuliers.

    • Issue in Zoho People Regularization – Incorrect Hour Calculation

      I have noticed that when applying attendance regularization in Zoho People for previous dates, the total working hours are not calculated correctly. For example, even if the check-in is 10:00 AM and check-out is 6:00 PM, the system shows an incorrect

    • Free Webinar : Unlock AI driven business insights with Zoho Inventory + Zoho Analytics

      Are you tired of switching between apps and exporting data to build customized reports? Say hello to smarter & streamlined insights! Join us for this exclusive webinar where we explore the power of the Zoho Inventory–Zoho Analytics integration. Learn

    • Allow Multiple usage units to items while adding them to sales/purchase transactions

      The usage unit of items added in zoho books are static right now and can not be changed. But certain items are received or sold in multiple usage units. One example is fabric. It can be bought in Meters, inches, kgs or other units. Another example would

    • PO receive quantities

      At last, Zoho has finally got around to allowing us to receive a larger qty than recorded in the PO :-) Saves us all from editing the PO's before receiving larger quantities ( usual for us ) ! It's still in "beta" but available upon request, I've tested

    • Analytics : How to share to an external client ?

      We have a use case where a client wants a portal so that several of his users can view dashboards that we have created for them in Zoho Analytics. They are not part of our company or Zoho One account. The clients want the ability to have user specific,

    • Reference Deal Categories in Deluge

      Hello, Is there a way to reference Deal Category in deluge functions? So for our Deals, we have several different WON stages in a pipeline.  Rather than type each stage into our functions, we'd like to be able to reference the Deal Category.  Similar

    • Users Name & Email in Reports

      Hi, I would like to show the Users Name from their Zoho Acount in All Entries/Reports as well as the current Account Email. Thanks Dan

    • Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

      Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals

    • Workflow Creation with Zia gets stuck

      It gets stuck here:

    • Unable to Add Asset to Work Order Due to Different Contact and Company

      Hello Zoho Team, I’m facing an issue in our environment related to asset linking in Work Orders. Here’s the situation: When our engineers go for field activities, they initially create the Work Order using the salesperson’s contact details. After completing

    • I NEED MORE CUSTOM FIELDS!!!

      Why can I only have 60 custom fields! It's not enough. I want another 100 extra custom fields to do what's necessary for my business! I'm sure I can't be the only one with this problem!!! How hard would it be to fix this? Just fix it for me please at

    • Zoho Webinar et Zapier : de la prise de rendez-vous aux relances — une automatisation performante

      Organiser un webinaire réussi et gérer efficacement les participants peut être un véritable défi. Avec Zoho Webinar et Zapier, vous pouvez rendre vos processus plus simples. Vous gagnez du temps en automatisant les tâches répétitives. Résultat : une expérience

    • Ticket Stages Report

      From data to decisions: A deep dive into ticketing system reports Ticket stages refer to the series of transitions from the moment a support ticket is created until it is closed. It moves through various stages based on the actions taken at each preceding

    • 【参加無料】今年最後のZoho ユーザー交流会｜東京・大阪・名古屋で開催！ 活用事例＆ユーザー同士の情報交換

      ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 11月に東京、大阪、名古屋の3都市でZoho ユーザー交流会を開催します！ 毎回ご好評いただいている本イベントでは、実際の Zohoユーザーによるリアルな活用事例の共有や 参加者同士でノウハウを交換し合うグループワークを予定しています。 「他社の活用を参考にしたい」「Zoho をもっと使いこなしたい」方にぴったりの場です。 初参加の方もぜひお気軽にご参加ください！ ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー

    • Slow Performance on desk.zoho.com. 11/3/2025

      I’m not seeing any active service alerts for desk.zoho.com, but everyone on our account is currently experiencing very slow load times when opening or navigating tickets. We’ve already tried the standard troubleshooting steps — clearing cache and cookies,

    • Create View to See Tickets Closed within the last 3 days

      I'm trying to create a view in Zoho Desk that shows me "recently closed ticket," which I will define as tickets closed in the last 3 days. I want this view to update so that whenever I click to view it is recalculates and shows me tickets closed within

    • My notes from the past 2 months have disappeared

      Hola, necesito ayuda urgente. Hoy, al iniciar sesión en mi Zoho Notebook como todos los días, me llevé una gran sorpresa al descubrir que todas mis notas de los últimos dos meses habían desaparecido. Estas notas son muy importantes para mí, ya que uso

    • Next Page