# 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

```typescript
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)