# Actions System

> **Quick Links**: [User Guide](./user-guide.md) | [Examples](./examples.md) | [Developer Guide](../developer/actions-developer-guide.md)

The Actions system is a powerful Business Logic Module that enables customers to define and execute automated workflows based on various triggers. It provides a visual, node-based interface for creating complex business logic without requiring custom code.

## Overview

Actions enable customers to:
- **Automate responses** to data changes (document creation, updates, deletion)
- **Build workflows** using a visual, drag-and-drop interface
- **Connect different services** through a standardized block system
- **Execute complex business logic** across their applications

## Key Concepts

### 🔗 Actions
An Action is a complete workflow that defines:
- **Title**: A descriptive name for the automation workflow
- **Description**: Optional details about what the automation does
- **Triggers**: What events start the workflow
- **Blocks**: Individual processing units that perform specific tasks
- **Connections**: How data flows between triggers and blocks

### ⚡ Triggers
Triggers define when an Action should execute:
- `documentCreated`: When a new document is created
- `documentUpdated`: When an existing document is modified  
- `documentDeleted`: When a document is removed
- `cron`: On a schedule defined by a cron expression (minimum: every 5 minutes)
- `webhook`: When a webhook URL is called
- `api`: Can be triggered via API call or manually

### 🧱 Blocks
Blocks are reusable processing units that:
- Receive input data through **input sockets**
- Perform specific operations (send email, transform data, etc.)
- Output results through **output sockets**
- Can be connected to other blocks to create workflows

Available block types include:
- **Send Email**: Send notification emails to users
- **Update Database**: Modify database records and relationships
- **Call Webhook**: Make HTTP requests to external services
- **Conditional Logic**: Add decision points and branching logic

### 🔌 Connections
Connections define the data flow between:
- Triggers → Blocks (workflow initiation)
- Blocks → Blocks (sequential processing)
- Using named sockets for type-safe data transfer

### 🎨 Visual Flow Editor
The system includes a visual, node-based editor that allows users to:
- **Drag and drop** triggers and blocks onto a canvas
- **Visually connect** components to define workflow logic
- **Zoom and pan** to navigate complex workflows
- **Preview workflow** structure before execution

## Badges & Achievements

Creating your first Action in a project awards the **First Action Created** (`FIRST_ACTION_CREATED`) badge to the user who created it. This badge is granted automatically upon successful creation and can be viewed in your user profile under Badges.

## Quick Example

```typescript
const emailNotificationAction: Action = {
  title: "Email Notification Workflow",
  description: "Sends admin email when new documents are created",
  triggers: [{
    id: "trigger1",
    triggerName: "documentCreated"
  }],
  blocks: [{
    id: "block1", 
    blockName: "send-mail",
    configuration: {
      to: "admin@example.com",
      subject: "New document created"
    }
  }],
  connections: [{
    sourceBlockId: "trigger1",
    sourceSocketName: "trigger",
    targetBlockId: "block1", 
    targetSocketName: "in"
  }]
};
```

This creates a workflow that sends an email whenever a new document is created.

## Documentation Structure

- **[User Guide](./user-guide.md)** - Complete guide for using the Actions interface in the backoffice
- **[Architecture](./overview.md)** - Technical architecture and component details
- **[Developer Guide](./developer-guide.md)** - How to create custom blocks and extend the system
- **[API Reference](./api-reference.md)** - Complete interface documentation
- **[Examples](./examples.md)** - Practical usage scenarios and patterns

## Getting Started

### For End Users
If you want to create and manage automation workflows using the backoffice interface:

1. Start with the **[User Guide](./user-guide.md)** to learn how to use the Actions interface
2. Explore the **[Examples](./examples.md)** for common automation patterns
3. Reference the user interface features for creating visual workflows

### For Developers
For developers looking to extend the Actions system:

1. Start with the **[Architecture](./overview.md)** to understand the system design
2. Follow the **[Developer Guide](./developer-guide.md)** to create custom blocks
3. Reference the **[API documentation](./api-reference.md)** for detailed interfaces
4. Check **[Examples](./examples.md)** for common patterns and best practices

## Multi-Tenant Support

The Actions system is built with multi-tenancy in mind:
- All actions are scoped to specific tenants
- Block execution includes tenant context
- Data isolation is maintained throughout workflow execution
- Access control is enforced at the Action level