ScriptForge (FaaS)

Document Metadata

Category: Applications Architecture / Scripting Engine
Audience: Engineers, Developers, Architects
Difficulty: Intermediate to Advanced
Time Required: Approximately 30–60 minutes
Prerequisites: Active ConnexCS account, access to the Applications / Developer module, familiarity with scripting basics and ConnexCS architecture concepts
Related Topics: ConnexCS Applications Overview, ScriptForge Scripting Reference, Database Integration
Next Steps: Review the ScriptForge architecture documentation; plan how scripts will integrate with your application logic or data flows; experiment with example scripts; validate integration with existing modules

Platform: Function-as-a-Service (FaaS) on ConnexCS SaaS Communication Platform
Runtime: QuickJS ES2023 Sandbox
Execution: Ephemeral, globally distributed, closest to ingestion point

ScriptForge is ConnexCS's serverless FaaS platform for building telephony applications, integrations, and automation workflows. Scripts are executed in a secure sandbox environment with access to powerful built-in modules.

Key Principles

• Ephemeral Execution — Global variables are not persisted between invocations
• Short Execution — Keep scripts fast; offload heavy processing to the job queue
• Persistent Storage — Use Key-Value store or database for data that needs to persist

---

Execution Types

ScriptForge can be invoked in several different contexts:

HTTP / WebSocket / SSE Requests

Scripts can be triggered via HTTP, WebSocket, or Server-Sent Events from three different entry points:

Entry Point	Description
Control Panel	Administrative interface for managing the switch. Supports Page Builder & Buttons to create custom apps, extensions, reports, and actions.
Customer Portal	End-customer facing interface with the same backend capabilities as the Control Panel.
App Platform	Standalone application platform with independent authentication. Used for creating and publishing independent applications.

All three are functionally equivalent on the backend — the same modules and capabilities are available.

HTTP Request Data:

// POST request — data contains the decoded JSON body
export function main(data, meta) {
    return { body: data };
}

// GET request — data contains query string parameters as an object
export function main(data, meta) {
    return { params: data };
}

Class 4 Routing Engine

Invoked once at the start of a call during routing decisions. The Routing Engine produces a JSON document containing call routing data, which is passed to ScriptForge for custom manipulation — providing unlimited control over call routing logic.

export function main(data, meta) {
    // data contains the routing document
    // Manipulate and return modified routing
    return data;
}

Class 5 Programmable Voice

Interactive call control at the application level. This execution type exclusively uses the cxC5Server module for real-time call manipulation — TTS, IVR, recording, transcription, bridging, etc.

Note: cxC5Server only works within Programmable Voice execution and cannot be used with other execution types.

Other modules (cxKV, cxRest, etc.) remain available for data operations during call handling.

Job Queue (cxJob)

Self-invocational background processing. Scripts can queue jobs that execute other scripts (or the same script with a different function). All modules are available within job execution with no restrictions. You should assume that a job will run on a different server each time.

---

Function Parameters

Exported functions receive two parameters: data and meta.

export function main(data, meta) {
    // data — request body, query params, or context-specific data
    // meta — metadata including authentication information
    return { data, meta };
}

The meta Parameter

The second parameter contains metadata about the request, including authentication information when available.

Authentication (meta.auth)

When a request is authenticated via JWT, the meta.auth object contains the decoded token claims and authentication guarantees:

export function main(data, meta) {
    if (meta.auth) {
        const userId = meta.auth.sub;
        const permissions = meta.auth.permissions;
        // Use authentication data for authorization decisions
    }
    return { authenticated: !!meta.auth };
}

---

Environment Variables

Scripts have access to both system and user-defined environment variables via process.env:

System Variables

Variable	Description
SCRIPTFORGE_ID	Numeric ID of the script
SCRIPTFORGE_UUID	UUID of the script
SCRIPTFORGE_NAME	Name of the script
APP_ID	Application ID
PID	Process ID
THREAD_ID	Worker thread ID
EXEC_HOST	Hostname of the executing server
CORRELATION_ID	Request correlation ID for tracing

User Variables

Custom environment variables can be configured per script and are merged with system variables.

export function main() {
    const scriptId = process.env.SCRIPTFORGE_ID;
    const myCustomVar = process.env.MY_CUSTOM_VAR;
    return { scriptId, myCustomVar };
}

---

Capabilities

ScriptForge provides a rich set of built-in modules:

Module	Description
cxCallControl	Control Class 4/5 telephony systems, originate calls, manage queues
cxC5Server	Real-time call control, media, TTS, IVR, recording, transcription
cxJob	Background job queue for heavy processing
cxKV	Globally synced atomic key-value storage with TTL support
cxKysely	SQL query builder
cxUserspace	Simple CRUD database operations
cxPubSub	Real-time publish/subscribe messaging
cxRest	HTTP client for ConnexCS API with JWT authentication
cxSend	Send Email and SMS messages
cxWebSocket	WebSocket connections for real-time communication

---

ES Module Syntax

ScriptForge uses ES modules. Any exported function can be executed.

Exported Functions

export async function myFunction() {
    return 'Hello From myFunction';
}

Imports and Exports

You can share code between scripts using named and default exports.

Export (test-export.js):

export const hello = 'world';

export default function functionTest() {
    return 'function result';
}

Import:

import { hello } from './test-export';
import newFunction from './test-export';

export function main() {
    return newFunction() + hello;
}

---

Third-Party NPM Libraries

You can use many 3rd party NPM libraries with the help of esm.sh. This bundles up NPM libraries and serves them as ESM modules ready to use — no npm install or package.json maintenance required.

import dayjs from 'esm.sh/dayjs';

export function main() {
    return dayjs().format('YYYY-MM-DD HH:mm:ss');
}

---

API Reference

• cxC5Server
• cxCallControl
• cxJob
• cxKV
• cxKysely
• cxPubSub
• cxRest
• cxSend
• cxUserspace
• cxWebSocket

---

Generated on 2026-02-13