Title: Actions API Reference

Description: Complete API documentation for interfaces, types, and functions in the Actions system

Tags: actions, api, reference, technical

---

Actions API Reference

Complete API documentation for all interfaces, types, and functions in the Actions system.

Core Interfaces

Action

The main interface representing a complete workflow.

interface Action extends TenantEntityWithAccess {
  title: string;
  description?: string;
  triggers?: ActionTrigger[];
  blocks?: ActionBlock[];
  connections?: ActionSocketConnection[];
}

Properties:
title: Required descriptive name for the automation workflow
description: Optional detailed explanation of what the workflow does
triggers: Array of triggers that can start this Action
blocks: Array of processing blocks in this workflow
connections: Array of socket connections defining data flow

Inheritance:
Extends TenantEntityWithAccess for multi-tenant support and access control

Schema Support:
Includes ActionSchema TypeSchema for form generation and validation
Form widgets configured for title and description fields
Triggers, blocks, and connections are hidden in forms (managed via visual editor)

ActionSchema

TypeSchema definition for Action form generation and validation.

const ActionSchema: TypeSchema = mergeObjects(
  TenantEntityWithAccessSchema,
  {
    type: "object",
    properties: {
      title: {
        type: "string",
        title: "Title",
        "x-type-schema": {
          inputWidget: INPUTWIDGETSTRING,
          viewWidget: { name: VIEWWIDGETSTRING }
        }
      },
      description: {
        type: "string", 
        title: "Description",
        "x-type-schema": {
          inputWidget: INPUTWIDGETSTRING,
          viewWidget: { name: VIEWWIDGETSTRING }
        }
      },
      triggers: {
        type: "array",
        title: "Triggers",
        "x-type-schema": { hiddenInForms: true }
      },
      blocks: {
        type: "array", 
        title: "Blocks",
        "x-type-schema": { hiddenInForms: true }
      },
      connections: {
        type: "array",
        title: "Connections", 
        "x-type-schema": { hiddenInForms: true }
      }
    },
    required: ["title"],
    additionalProperties: false
  }
);

Usage:
Integrated with FormComponent for create/edit dialogs
Used by DataViewComponent for column definitions
Provides automatic form generation based on schema
Triggers, blocks, and connections are managed via visual editor

ActionTrigger

Defines when an Action should execute.

interface ActionTrigger {
  id: string;
  triggerName: string;
  configuration?: { [key: string]: any };
}

Properties:
id: Unique identifier for this trigger instance
triggerName: Must match a value from ActionTriggers enum
configuration: Optional configuration parameters for the trigger

Related:
ActionTriggers enum defines available trigger types
DocumentActionTriggerData<T> interface for document-related trigger data

ActionBlock

Represents a processing unit in a workflow.

interface ActionBlock {
  id: string;
  blockName: string;
  configuration?: { [key: string]: any };
}

Properties:
id: Unique identifier for this block instance
blockName: Must match a registered block name in ActionBlockRegistry
configuration: Optional configuration parameters for the block

ActionSocketConnection

Defines data flow between triggers and blocks or between blocks.

interface ActionSocketConnection {
  sourceBlockId: string;
  sourceSocketName: string;
  targetBlockId: string;
  targetSocketName: string;
}

Properties:
sourceBlockId: ID of the source block (or trigger ID)
sourceSocketName: Name of the output socket on source block
targetBlockId: ID of the target block
targetSocketName: Name of the input socket on target block

Block Implementation Interfaces

ActionBlockImpl

Interface that all block implementations must conform to.

interface ActionBlockImpl {
  execute: (socketName: string, data: any) => Promise<ActionBlockResult>;
}

Methods:
execute: Processes input data and returns execution result

Parameters:
socketName: Name of the input socket being triggered
data: Input data from previous block or trigger

Returns:
Promise<ActionBlockResult>: Execution result with output data and logs

ActionBlockResult

Result of block execution.

interface ActionBlockResult {
  socketName: string;
  data?: any;
  logs: ActionExecutionResultLog[];
}

Properties:
socketName: Name of the output socket for routing to next block
data: Output data to pass to connected blocks (optional)
logs: Array of log entries from execution

Socket System

ActionSocket

Defines input/output sockets for type-safe data transfer.

interface ActionSocket {
  name: string;
  type: ActionSocketType;
  direction: ActionSocketDirection;
}

Properties:
name: Unique socket name within the block
type: Data type validation using ActionSocketType enum
direction: Socket direction using ActionSocketDirection enum

ActionSocketType

Enum defining supported data types for sockets.

enum ActionSocketType {
  NUMBER = "number",
  NUMBER_ARRAY = "number[]",
  STRING = "string", 
  STRING_ARRAY = "string[]",
  BOOLEAN = "boolean",
  BOOLEAN_ARRAY = "boolean[]",
  OBJECT = "object",
  OBJECT_ARRAY = "object[]",
  NULL = "null"
}

Values:
Primitive types: NUMBER, STRING, BOOLEAN, NULL
Array types: NUMBERARRAY, STRINGARRAY, BOOLEAN_ARRAY
Complex types: OBJECT, OBJECT_ARRAY

ActionSocketDirection

Enum defining socket direction.

enum ActionSocketDirection {
  IN = "in",
  OUT = "out"
}

Values:
IN: Input socket (receives data)
OUT: Output socket (produces data)

Trigger System

ActionTriggers

Enum of available trigger types.

enum ActionTriggers {
  DOCUMENT_CREATED = "documentCreated",
  DOCUMENT_UPDATED = "documentUpdated",
  DOCUMENT_DELETED = "documentDeleted"
}

Values:
DOCUMENT_CREATED: Triggered when a new document is created
DOCUMENT_UPDATED: Triggered when an existing document is modified
DOCUMENT_DELETED: Triggered when a document is removed

DocumentActionTriggerData

Type definition for document-related trigger data.

interface DocumentActionTriggerData<T> {
  entity: T;
  collectionName: string;
  userId?: string;
}

Properties:
entity: The document that triggered the action (typed)
collectionName: Name of the collection containing the document
userId: Optional ID of the user who performed the action

Execution System

ActionExecutor

Interface for classes that execute Actions.

interface ActionExecutor {
  executeActionsByTrigger({
    triggerName,
    data
  }: {
    triggerName: string;
    data: any;
  }): Promise<ActionExecutionResult[]>;
}

Methods:
executeActionsByTrigger: Executes all Actions matching a trigger name

Parameters:
triggerName: Name of the trigger to execute
data: Data to pass to the triggered Actions

Returns:
Promise<ActionExecutionResult[]>: Array of execution results

ActionExecutionResult

Result of Action execution.

interface ActionExecutionResult {
  success: boolean;
  logs: ActionExecutionResultLog[];
}

Properties:
success: Whether the Action executed successfully
logs: Array of log entries from the execution

ActionExecutionResultLog

Individual log entry from Action execution.

interface ActionExecutionResultLog {
  timestamp: number;
  message: string;
  level: "info" | "warn" | "error";
}

Properties:
timestamp: Unix timestamp when log was created
message: Human-readable log message
level: Log severity level

Registry System

ActionBlockRegistry

Registry for managing block implementations.

class ActionBlockRegistry {
  private blocks: Map<string, ActionBlockImpl>;
  
  registerBlock(blockName: string, impl: ActionBlockImpl): void;
  getBlockByName(blockName: string): Promise<ActionBlockImpl | undefined>;
}

Methods:

registerBlock
Registers a new block implementation.

Parameters:
blockName: Unique name for the block
impl: Implementation conforming to ActionBlockImpl

Returns: void

getBlockByName
Retrieves a block implementation by name.

Parameters:
blockName: Name of the block to retrieve

Returns: Promise<ActionBlockImpl | undefined>

Execution Functions

executeActionsByTrigger

Main function for executing Actions based on trigger.

async function executeActionsByTrigger(
  options: ActionsByTriggerExecutionOptions
): Promise<ActionExecutionResult[]>

Parameters:
options: Execution options object

Returns:
Promise<ActionExecutionResult[]>: Array of execution results

ActionsByTriggerExecutionOptions

Options for trigger-based execution.

interface ActionsByTriggerExecutionOptions {
  triggerName: string;
  triggerData: any;
  blockRegistry: ActionBlockRegistry;
  actions: Action[];
}

Properties:
triggerName: Name of trigger to match
triggerData: Data to pass to triggered Actions
blockRegistry: Registry containing block implementations
actions: Array of Actions to consider for execution

Constants

TRIGGERSOCKETNAME

Special socket name used by all triggers.

const TRIGGERSOCKETNAME = "trigger";

This constant defines the output socket name that all triggers use when connecting to blocks.

Type Schema Integration

ActionSocketSchema

TypeSchema definition for ActionSocket validation.

const ActionSocketSchema: TypeSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    type: { 
      type: "string",
      enum: Object.values(ActionSocketType)
    },
    direction: {
      type: "string", 
      enum: Object.values(ActionSocketDirection)
    }
  },
  required: ["name", "type", "direction"]
};

Used for validating socket definitions in the type system.

Error Handling

Common Error Scenarios
Block Not Found
      throw new Error(Block implementation for ${blockName} not found);
Target Block Missing
      throw new Error(Target block ${targetBlockId} not found for connection);
Missing Trigger Name
      throw new Error("Trigger name is required for execution");
No Actions Found
      throw new Error("No actions found for the specified trigger");
   

Error Recovery
Block execution errors are captured and logged
Execution continues with remaining blocks/Actions
All results (success and failure) are returned
Errors don't cascade to other workflows

Usage Examples

Basic Block Implementation

const myBlock: ActionBlockImpl = {
  execute: async (socketName: string, data: any): Promise<ActionBlockResult> => {
    return {
      socketName: "output",
      data: { processed: true },
      logs: [{
        timestamp: Date.now(),
        message: "Processing completed",
        level: "info"
      }]
    };
  }
};

Registry Usage

const registry = new ActionBlockRegistry();
registry.registerBlock("my-block", myBlock);

const impl = await registry.getBlockByName("my-block");
if (impl) {
  const result = await impl.execute("input", { value: 42 });
}

Action Definition

const action: Action = {
  triggers: [{
    id: "trigger-1",
    triggerName: "documentCreated"
  }],
  blocks: [{
    id: "block-1", 
    blockName: "send-mail",
    configuration: { to: "admin@example.com" }
  }],
  connections: [{
    sourceBlockId: "trigger-1",
    sourceSocketName: "trigger",
    targetBlockId: "block-1",
    targetSocketName: "in"
  }]
};

Execution

const results = await executeActionsByTrigger({
  triggerName: "documentCreated",
  triggerData: { documentId: "123", userId: "user-456" },
  blockRegistry: myRegistry,
  actions: [action]
});