Save Entity Action Block

Save incoming data as entities in the database with upsert functionality

actionsblockssave-entitydatabase

Save Entity Action Block

Overview

The Save Entity Action Block is a new action block that enables saving incoming data as entities in the database. It implements upsert functionality - updating existing entities or creating new ones based on whether the entity already exists.

Features

  • Upsert Logic: Automatically determines whether to update or create entities
  • Configurable Collection: Specify which collection to save entities to
  • Error Handling: Comprehensive error handling with proper error outputs
  • Type Safety: Full TypeScript support with proper type definitions
  • Multilingual: Supports German and English labels and descriptions

Configuration

The block requires the following configuration:

Parameter Type Required Description
collectionName string Yes The name of the collection where entities should be saved

Sockets

Input Sockets

  • data (object): The entity data to be saved

Output Sockets

  • entity (object): The successfully saved/updated entity
  • error (string): Error message if the operation fails

Behavior

  1. Entity with ID: If the incoming data contains an id field:

    • Attempts to find the existing entity in the specified collection
    • If found: Updates the entity using patchDocument
    • If not found: Creates a new entity (removes the ID from data)

  2. Entity without ID: Creates a new entity using createDocument

  3. Error Cases: Returns error output for:

    • Missing collection name configuration
    • Missing entity data
    • Database operation failures

Usage Example

const action: Action = {
  blocks: [
    {
      id: "save-block",
      blockName: ActionBlocks.SAVE_ENTITY,
      configuration: {
        collectionName: "contacts"
      }
    }
  ],
  connections: [
    {
      sourceBlockId: "trigger",
      sourceSocketName: "trigger",
      targetBlockId: "save-block", 
      targetSocketName: "data"
    }
  ]
};

Implementation Files

  • Constants: packages/shared/src/actions/action-block.ts - Added SAVE_ENTITY enum value
  • Template: packages/shared/src/actions/action-block.ts - Block template definition
  • Implementation: packages/server/src/actions/blocks/save-entity.block.ts - Core logic
  • Registration: packages/server/src/actions/add-server-actions.ts - Server registry
  • Unit Tests: packages/server/src/actions/blocks/save-entity.block.test.ts
  • Integration Tests: packages/server/src/actions/save-entity.integration.test.ts

Testing

Unit Tests (3 tests)

  • ✅ Create new entity when no ID provided
  • ✅ Return error when collection name is missing
  • ✅ Return error when entity data is missing

Integration Tests (3 tests)

  • ✅ Create new entity through action execution
  • ✅ Update existing entity through action execution
  • ✅ Handle missing collection name configuration

All tests pass with proper mocking and validation of the ServerDocumentService interactions.

Architecture

The implementation follows established patterns:

  • Uses existing ServerDocumentService for database operations
  • Implements standard ActionBlockImpl interface
  • Proper error handling and logging
  • Transaction-safe operations
  • Follows the same patterns as existing action blocks (Send Mail, AI Summary)
Markdown llm.txt