Title: Save Entity Action Block

Description: Save incoming data as entities in the database with upsert functionality

Tags: actions, blocks, save-entity, database

---

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
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)
Entity without ID: Creates a new entity using createDocument
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)