Save Entity Action Block

Save incoming data as entities in the database with upsert functionality

actionsblockssave-entitydatabase

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 Type: Specify which type the entity belongs to (the underlying collection is derived from the type)
  • 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
typeId string Yes The ID of the type where the entity should be saved. The MongoDB collection name is derived from this type at execution time.

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 collection derived from the configured type
    • 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 typeId configuration
    • Type with the given typeId not found
    • Missing entity data
    • Database operation failures

Usage Example

const action: Action = {
  blocks: [
    {
      id: "save-block",
      blockName: ActionBlocks.SAVE_ENTITY,
      configuration: {
        typeId: "contact"
      }
    }
  ],
  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 typeId 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 typeId 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