/catalyst-functions

Function Templates — Event, Cron, Job, Integration

Handler templates for background and scheduled function types. Load this file when the query is about Event, Cron, Job, or Integration functions — NOT Basic I/O or Advanced I/O (those are in functions-basics.md).

catalyst-config.json — type Field Values

The type field is set by the CLI when a function is created. Do not change it manually.

"browserlogic" for Browser Logic — NOT "browselogic". Basic I/O is "basicio" — NOT "basiccron".

Event Function Template

Triggered by Catalyst Signals or Event Listeners.

'use strict';
const catalyst = require('zcatalyst-sdk-node');

module.exports = (event, context) => {
  try {
    const catalystApp = catalyst.initialize(context);
    const eventData = JSON.parse(event.getArgument());
    console.log('Event received:', eventData);
    context.close();
  } catch (error) {
    console.error('Event processing error:', error);
    context.close();
  }
};

Cron Function Template

Triggered on a schedule. Always call closeWithSuccess() or closeWithFailure() — never leave the context open.

'use strict';
const catalyst = require('zcatalyst-sdk-node');

module.exports = async (cronDetails, context) => {
  try {
    const catalystApp = catalyst.initialize(context);
    const maxMs = context.getMaxExecutionTimeMs(); // "900000" (STRING) = 15 minutes
    
    // Your scheduled task logic here
    
    context.closeWithSuccess();
  } catch (error) {
    context.closeWithFailure();
  }
};

Job Function Template

Triggered via Job Scheduling. Use { scope: 'admin' } for system-level DataStore/ZCQL operations that don't need a specific user context.

'use strict';
const catalyst = require('zcatalyst-sdk-node');

module.exports = async (jobData, context) => {
  try {
    const catalystApp = catalyst.initialize(context, { scope: 'admin' });
    const jobDetails = jobData.getAllJobParams();
    const maxMs = context.getMaxExecutionTimeMs(); // "900000" (STRING) = 15 minutes

    const zcql = catalystApp.zcql();
    const rows = await zcql.executeZCQLQuery('SELECT * FROM MyTable LIMIT 0, 300');

    context.closeWithSuccess();
  } catch (error) {
    context.closeWithFailure();
  }
};

Using Zoho MCP to submit a job? Always call CatalystbyZoho_List_All_Jobpools before CatalystbyZoho_Create_Immediate_Job. jobpool_id is required — there is no default. If no pools exist, call CatalystbyZoho_Create_Job_Pool (type "Function", memory e.g. "256") first.

Python Job Function Template

import logging
import zcatalyst_sdk

def handler(job_request, context):
    logger = logging.getLogger()
    try:
        # catalyst.initialize(context) defaults to Admin scope in non-HTTP functions
        app = zcatalyst_sdk.initialize(req=context)

        max_ms = context.get_max_execution_time_ms()        # "900000" (STRING) = 15 minutes
        remaining_ms = context.get_remaining_execution_time_ms()  # decrements as function runs

        all_params = job_request.get_all_job_params()
        job_details = job_request.get_job_details()

        zcql = app.zcql()
        rows = zcql.execute_query('SELECT * FROM MyTable LIMIT 0, 300')
        logger.info(f'Fetched {len(rows)} rows')

        context.close_with_success()
    except Exception as e:
        logger.error(f'Job failed: {e}')
        context.close_with_failure()

Python context API (Job and Cron):

• context.get_max_execution_time_ms() — returns "900000" (STRING, 15 min)
• context.get_remaining_execution_time_ms() — decrements live
• context.close_with_success() — mark job succeeded
• context.close_with_failure() — mark job failed

Local execute vs deployed runtime

catalyst functions:execute proves your handler logic — it does NOT prove deployed environment variables, scheduled timing, or Job pool behavior. After local smoke tests, verify long-running Job logic with a real remote/scheduled run before declaring it working.

If edited source doesn't appear in functions:execute output, delete the stale build cache: rm -rf functions/<name>/.build and re-run.

Note: Job pool memory and function memory are separate settings — raising the pool size alone does not raise the function's execution memory (jobs run at the FUNCTION's memory; the pool is a ceiling). The job function's memory must be ≤ the job pool's memory, or every submission is REJECTED at submit time with INVALID_INPUT: The memory allocated for the Job Function is higher than the memory allocated for its associated Job Pool. (runtime-confirmed — it is a hard error, not a dispatch delay).

Integration Function Template

Triggered by events from other Zoho services (e.g., Zoho CRM, Zoho Books).

'use strict';
const catalyst = require('zcatalyst-sdk-node');

module.exports = (event, context) => {
  try {
    const catalystApp = catalyst.initialize(context);
    const integrationData = JSON.parse(event.getArgument());
    context.close();
  } catch (error) {
    context.close();
  }
};

Integration functions are NOT available in EU, AU, IN, JP, SA, or CA data centers.

SDK Component Reference

npm install zcatalyst-sdk-node

const dataStore = catalystApp.datastore();
const table = dataStore.table('TableName');

const inserted = await table.insertRow({ ColumnName: value });
const insertedRows = await table.insertRows([{ ColumnName: value1 }, { ColumnName: value2 }]);
const updated = await table.updateRow({ ROWID: rowId, ColumnName: value });
await table.deleteRow(rowId);

const row = result.TableName; // unwrap ZCQL table wrapper, e.g. result.Orders

const zcql = catalystApp.zcql();
const cache = catalystApp.cache();
const stratus = catalystApp.stratus();
const email = catalystApp.email();
const userManagement = catalystApp.userManagement();
const pushNotification = catalystApp.pushNotification();
const search = catalystApp.search();
const nosql = catalystApp.nosql();
const connection = catalystApp.connection();

Data Store tables must exist before SDK operations target them. Functions cannot create tables programmatically — use Zoho MCP for table creation and schema updates.

Retry Behavior

Cron failure handling: Configure Application Alerts (Console → Cloud Scale → Cron → Alerts) to receive email notifications when a cron fails, times out, or throws an exception. Review execution history from the console to debug and rerun.

50-consecutive-failures auto-disable applies ONLY to crons associated with a third-party URL target — NOT to function-based crons. Function-based crons never auto-disable regardless of repeated failures.

Design Event and Job handlers to be idempotent (safe to run multiple times). Cron handlers should also be idempotent to safely support manual reruns.

Cold Starts

Mitigation: Keep packages small, avoid heavy initialization outside the handler, use Job Scheduling to ping critical functions warm.

Common Errors