Skip to main content

​
Overview

The processSingleNode workflow executes a single node within a workflow. It handles the complete lifecycle of node execution, including validation, processing, token charging, file generation, and error handling.

​
Purpose

This workflow is designed to:
  • Execute a single node independently
  • Validate user access to required AI models
  • Process the node based on its type
  • Track token usage for billing
  • Generate output files when configured
  • Handle errors gracefully with comprehensive logging
  • Notify users of execution status changes

​
Workflow signature

export async function processSingleNode(
  nodeId: string,
  userId: string,
  sessionId: string,
  flowId: string
)

​
Parameters

ParameterTypeDescription
nodeIdstringUnique identifier of the node to execute
userIdstringID of the user executing the workflow
sessionIdstringSession identifier for tracking execution context
flowIdstringID of the flow containing the node

​
Return value

Returns "Node executed successfully" on successful completion, or throws an error on failure.

​
Execution flow

The workflow follows this sequence:
1

Set initial status

Notifies the user that the node execution has started by setting status to PENDING using notifyStatusActivity.
2

Retrieve node information

Queries the database to get node details (type, flow_id, data) using getInfoInDatabaseActivity.
3

Validate node exists

Throws an error if the node is not found in the database.
4

Process by node type

Executes different logic based on the node type:
  • TEXT_GENERATOR: Validates model access, generates text, charges tokens, and optionally generates files
  • SCRIPTING: Runs user JavaScript or Python via Lambda (see the Scripting node doc)
  • Other types: Currently throws an error (not yet supported)
5

Log successful execution

Creates an execution log entry with success status using generateExecutionLogsActivity.
6

Notify completion

Updates the node status to COMPLETED using notifyStatusActivity.

​
Node type: TEXT_GENERATOR

When processing a TEXT_GENERATOR node, the workflow:
  1. Validates model access: Uses validateModelAccessActivity to ensure the user has access to the specified AI model and system
  2. Generates text: Executes textGeneratorActivity to produce the output
  3. Validates tokens: Ensures both input and output tokens are returned
  4. Charges tokens: Records token usage for billing using chargeTokensActivity
  5. Generates file (optional): If saveOutput and fileType are configured, generates a file using generateFileActivity

​
Error handling

The workflow implements comprehensive error handling:
1

Catch errors

All errors are caught in a try-catch block
2

Extract error information

Extracts error message and stack trace for logging
3

Log error

Creates an execution log entry with error status using generateExecutionLogsActivity
4

Update node data

Updates the node’s data with execution status using nodeExecutionErrorActivity
5

Notify failure

Updates the node status to FAILED using notifyStatusActivity
6

Re-throw error

Re-throws the error to allow Temporal to handle retries if configured

​
Activities used

This workflow uses the following activities:

​
Status transitions

The node status progresses through these states:
  1. PENDING - Workflow started, node execution beginning
  2. COMPLETED - Node executed successfully
  3. FAILED - Node execution encountered an error

​
Example usage

// Triggered by Temporal when a node execution is requested
await processSingleNode(
  "node-123",
  "user-456",
  "session-789",
  "flow-abc"
);