Triggers and Associations

How Functions Are Associated to CRM Events

A Function does not run on its own. Associate it with a trigger to tell Zoho CRM when and where to execute it.

The association always happens at the trigger's configuration, not inside the Function editor. For example, you associate a Function to a Workflow Rule inside the Workflow Rule setup, not in the Function code. The Function editor is where you write logic; the trigger configuration is where you wire it into CRM.

When you create a Function, you choose a category (Automation, Button, Schedule, Standalone, etc.) that determines which triggers the Function is eligible for. A Function’s category determines which triggers it can be associated with. For example, an Automation Function can be associated with Workflow Rules, Blueprints, and Approvals, but not with Custom Buttons or Schedules. Choose the category based on the trigger you intend to use.

For a full breakdown of each category and when to use it, see Function Categories.

Arguments in Deluge vs Java, Node.js, Python

The way a Function receives data from its trigger depends on the language:

• Deluge: Arguments must be explicitly declared in the Function (via the Arguments panel or the code signature) and manually mapped to CRM fields at the point of association. You map each argument to a merge variable like ${Deals.Deal Name} inside the Workflow Rule, Button, or Blueprint setup. Inside the script, arguments are accessed via the input map.
• Java, Node.js, Python: Functions in these languages use basicIO, a standardized input and output mechanism that automatically passes the trigger context (record data, user info, org details) to the Function as a structured payload. You do not need to declare or map individual arguments manually. The Function reads from the basicIO request object and writes its response back through it.

The trigger sections below describe argument mapping primarily in Deluge terms (merge variables). If you are writing a Function in Java, Node.js, or Python, the trigger association UI automatically uses basicIO instead of manual argument mapping.

Trigger Reference

Workflow Rules On Record Create / Edit / Delete

Category: Automation

Workflow Rules are the most common trigger for Functions. A Workflow Rule fires when a record is created, edited, or deleted — or when a record meets a specific field condition (e.g. Stage equals "Closed Won").

Where to associate: Setup -> Automation -> Workflow Rules -> [Select or create a rule] -> Instant Actions (or Scheduled Actions) -> Function

Argument mapping: In Deluge, each argument defined in the Function is mapped to a CRM field using merge variables like ${Deals.Deal Name} or ${Deals.Amount}. The Workflow Rule resolves these at execution time and passes the values to the Function. In Java, Node.js, and Python, the trigger context is passed automatically via basicIO — no manual argument mapping is required.

Return type: Void. The Function executes asynchronously. The record is saved immediately, without waiting for the Function to complete. The Function cannot return a value back to the workflow.

Key behavior:

• A single Workflow Rule can trigger multiple Functions (added as separate actions).
• Functions run asynchronously after the record operation completes.
• Scheduled Actions allow you to delay the Function execution (e.g. run 2 hours after record creation).

Blueprints

Category: Automation

Blueprints are state machines that define how a record moves through a process (e.g. a Deal moving from "Qualification" to "Proposal" to "Closed Won"). Functions can be attached to a specific transition — the arrow between two states — so they execute when a record moves through that step.

Where to associate: Setup -> Automation -> Blueprint -> [Open Blueprint] -> Click on a transition arrow -> Actions tab -> Function

Argument mapping: As with Workflow Rules, Deluge Functions require you to map Function arguments to CRM fields using merge variables. In Java, Node.js, and Python, the record context is passed automatically via basicIO.

Return type: Void. The transition completes independently of the Function's execution.

Key behavior:

• The Function runs when a user (or another automation) moves the record through that specific transition.
• You can attach Functions to multiple transitions within the same Blueprint.
• Blueprint transitions can also enforce mandatory fields, require notes, or run other actions alongside the Function.

Approval Processes On Submit / Approve / Reject

Category: Automation

Approval Processes route records through an approval chain. Functions can be triggered at three points in the approval lifecycle: when a record is submitted for approval, when it is approved, or when it is rejected.

Where to associate: Setup -> Automation -> Approval Processes -> [Select or create a process] -> Actions on Approve / Actions on Reject -> Function

Argument mapping: As with Workflow Rules, Deluge Functions require manual argument mapping using merge variables. Java, Node.js, and Python Functions automatically receive the execution context through basicIO.

Return type: Void.

Key behavior:

• You can attach different Functions to different stages of the same approval process (one on approve, a different one on reject).
• The Function receives the record context at the time of the approval action, not at the time of original submission.
• Approval Functions are useful for notifying external systems, escalating to managers, or updating related records based on the approval outcome.

Custom Buttons

Category: Button

Custom Buttons let users trigger a Function manually by clicking a button on a CRM record page, list view, or create/edit page.

Where to associate: Setup -> Customization -> Modules and Fields -> [Select module] -> Links and Buttons tab -> Create New Button -> Action: Writing a Function

Argument mapping: In Deluge, map each Function argument to CRM record fields using merge variables. In Java, Node.js, and Python, the record context is delivered via basicIO.

Return type: String. The return value is displayed as a modal dialog in the CRM UI. Use this to show a confirmation message, a result summary, or an error message to the user.

Key behavior:

• During button setup, choose where the button appears: the record detail page, list view, or create/edit page.
• During button setup, choose which user profiles can see and use the button.
• Since the user is waiting for the modal response, Button Functions should complete quickly. Long-running logic is better suited to Workflow or Standalone Functions.
• Button Functions are ideal for on-demand actions: generating a quote, syncing a record to an external system, or running a quick validation before a sales rep proceeds.

Scheduled Functions

Category: Schedule

Scheduled Functions run automatically at regular intervals, independent of any user action or record event. They are configured through the Schedules interface, not through a Workflow Rule or Button.

Where to associate: Setup -> Developer Hub -> Functions -> [Open Schedule Function] -> Schedules in editor toolbar. Or: Setup -> Automation -> Schedules -> Create New Schedule

Argument mapping: Scheduled Functions typically do not receive arguments from a trigger (there is no record context). If the Function requires additional data, retrieve it from Zoho CRM. In Deluge, use tasks such as zoho.crm.v8.searchRecords in Java, Node.js, and Python, use the equivalent SDK or ZRC calls.

Return type: Void. Scheduled Functions perform their work during execution (data sync, report generation, cleanup) without returning a value.

Key behavior:

• Supported frequencies: hourly, daily, weekly, monthly, or custom intervals.
• Each schedule has a start date/time and an optional end date.
• Schedules can be enabled or disabled without modifying the Function code.
• The execution time limit for Scheduled Functions is 15 minutes. Check out the Platform Limits and Quotas help page for specifics.

Related Lists

Category: Related List

Related List Functions render custom data directly within a related list section on a CRM record page. Unlike standard related lists that display linked CRM records, Related List Functions retrieve and format data programmatically from Zoho CRM, external systems, or runtime calculations.

Where to associate: Setup -> Customization -> Modules and Fields -> [Select module] -> Related Lists tab -> Create New Related List -> Source: Function

Argument mapping: Deluge does not automatically receive the parent record ID. Declare it as a Function argument and map it during related list configuration so the Function has the parent record context. Additional arguments can also be configured and mapped to merge variables. In Java, Node.js, and Python, the execution context, including the parent record ID, is passed automatically through basicIO.

Return type: String (XML). The Function must return an XML string that defines the column headers and row data. CRM parses this XML and renders it as the related list table on the record page. For Python, Node.js and Java, the return type is JSON.

Key behavior:

• The Function is called every time a user views the record and scrolls to (or clicks on) the related list section.
• Since the Function runs on every page view, it should be lightweight and fast. Avoid heavy computation or numerous external API calls.
• Related List Functions are useful for displaying real-time data from external systems (e.g. recent support tickets from Zoho Desk, payment history from Stripe) directly on a CRM record without data duplication.
• The returned XML must follow the required schema. Define the column names in the header, and map each row’s values to those columns.

Signals

Category: Signals

Signals are real-time notifications that appear in the CRM notification area when specific events occur. A Signals Function is triggered by an inbound webhook from an external system. The Function receives the webhook payload, processes it, and invokes a Signal in CRM.

Where to associate: Setup -> Developer Hub -> Functions -> Create a Function with the Signals category. The Function is then used as the webhook endpoint for a custom Sales Signal, which external systems can call.

Argument mapping: The Function receives the inbound webhook payload as its input. In Deluge, arguments are mapped to extract specific fields from the payload. In Java, Node.js, and Python, the full payload is accessible via basicIO. The structure of the payload depends on the external system sending the webhook.

Return type: The Function processes the payload and invokes the configured Sales Signal with the relevant event and record information.

Key behavior:

• Signals appear in the CRM notification panel, giving users real-time visibility into external events without leaving CRM.
• Common use cases: notifying a sales rep when a prospect opens a proposal (via a third-party tracking tool), alerting when a payment is received (via Stripe webhook), or flagging when a support ticket is escalated (via Zoho Desk webhook).
• The external system must be configured to send its webhook to the Zoho-provided endpoint URL for the Signals Function.
• Signals Functions are distinct from Standalone/Serverless endpoints: Signals are about raising CRM notifications, while Serverless endpoints are about executing logic and returning an HTTP response.
• For details on creating custom Sales Signals and invoking them through Functions, refer to the Sales Signals documentation.

Widgets and Client Scripts

Category: Standalone (invoked via ZDK)

Widgets are custom UI components embedded within CRM pages — inside record detail views, related list panels, or custom tabs. Client Scripts are JavaScript scripts that run on CRM pages to extend UI behavior. Both Widgets and Client Scripts use the ZDK (Zoho Developer Kit) to invoke Functions.

Where to associate: The Function itself is created as a Standalone Function. The Widget or Client Script then calls the Function programmatically using the ZDK's ZOHO.CRM.FUNCTIONS.execute method (or equivalent).

How it works:

1. Create a Standalone Function with the logic you need.
2. Build a Widget (using the Zoho Widget SDK) or write a Client Script.

3. In the Widget or Client Script JavaScript code, call the Function using ZDK:

    

   ZOHO.CRM.FUNCTIONS.execute("my_standalone_function", {
       arguments: JSON.stringify({
           paramName: "value"
       })
   }).then(function(response) {
       // Handle the Function's return value
   });

4. Deploy the Widget to a CRM page or enable the Client Script for the target module.

Return type: String (Standalone Functions return a string). The Widget or Client Script receives the return value in its JavaScript callback and can use it to update the UI, display a message, or trigger further actions.

Key behavior:

• Widgets provide a fully customizable user interface within Zoho CRM, making them ideal for dashboards, custom forms, and integration panels.
• Client Scripts add custom JavaScript behavior to existing CRM pages, making them ideal for dynamic field validation, conditional UI changes, and background data synchronization.
• Both use ZDK as the bridge between the CRM front-end and server-side Functions.
• The Function executes server-side; the Widget/Client Script handles the UI-side logic and the response.

Serverless REST Endpoints

Category: Standalone

Standalone Functions can be exposed as REST endpoints, allowing them to be invoked by any HTTP client, including external applications, partner systems, AI agents, and integration platforms. This is covered in detail in Exposing Functions as REST APIs.

Where to associate: Setup -> Developer Hub -> Functions -> [Open Standalone Function] -> REST API tab in the editor -> Enable API and configure authentication

Key behavior:

• The Function receives the HTTP request context via crmAPIRequest (headers, parameters, body) and returns a response via crmAPIResponse (full HTTP control) or basicIO (body only). Both crmAPIRequest and crmAPIResponse work in all supported languages.
• Authentication options include OAuth 2.0 or API Key.
• The endpoint URL follows Zoho's API domain pattern and is unique per Function.
• Serverless endpoints are the primary way external systems invoke CRM Functions without going through a Workflow Rule or Button.

Trigger-to-Category Quick Reference

This table summarizes which category you need for each trigger type.

Choosing the Right Trigger

If you're not sure which trigger to use, work backwards from the use case:

• "I want something to happen automatically when a record changes." -> Workflow Rule or Blueprint Transition (Automation category).
• "I want a user to click a button and see a result." -> Custom Button (Button category).
• "I want this to run every night / every hour / every Monday." -> Scheduled Function (Schedule category).
• "I want to show external data on a record page." -> Related List Function (Related List category).
• "I want to trigger a custom Sales Signal in CRM based on an event from an external system." -> Signals Function (Signals category).
• "I want to validate data before a record is saved." -> Validation Rule Function (Validation Rule category).
• "I want an external system to call my CRM logic via HTTP." -> Standalone Function exposed as a Serverless REST Endpoint.
• "I want a Widget or Client Script to call server-side logic." -> Standalone Function invoked via ZDK.
• "I want to share logic across multiple triggers without duplicating code." -> Standalone Function called inline from other Functions. This is supported only in Deluge.