Schema: ai_sam_workflows_base

Technical Truth - Models, API endpoints, and data structures

Module Overview

Models

canvas (Primary Model)

Purpose: N8N-compatible workflow definition storage. The json_definition field is the SINGLE SOURCE OF TRUTH for all workflow data.

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| save_canvas_state(workflow_id, canvas_state) | Save canvas JSON to database | bool |
| load_canvas_state(workflow_id) | Load canvas JSON from database | dict or False |
| update_workflow_name(workflow_id, new_name) | Update workflow name | bool |
| get_n8n_node_metadata() | Load N8N nodes from JSON file | list |
| get_content_node_metadata() | Load SAM content nodes | list |
| get_agent_node_metadata() | Load AI agent nodes | list |
| action_execute_workflow() | Execute workflow manually | action dict |
| action_generate_code() | Generate Python/JS from JSON | None |
| action_save_as_template() | Save workflow as template | action dict |
| action_import_n8n_workflow() | Show N8N import wizard | action dict |
| write_sam_debug_log(log_data) | Write debug logs to file | bool |

Relationships:
- execution_ids -> executions (One2many)
- template_id -> workflow.template (Many2one)
- business_unit_id -> workflow.business.unit (Many2one)
- branch_id -> ai.branch (Many2one, computed)
- team_ids -> res.users (Many2many)

executions

Purpose: Workflow execution tracking and logging

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| action_start_execution() | Start workflow execution | None |
| action_cancel_execution() | Cancel running execution | None |
| action_retry_execution() | Retry failed execution | action dict |
| _execute_workflow() | Internal: Execute the workflow | None |
| _execute_nodes() | Internal: Execute workflow nodes | None |
| _execute_single_node() | Internal: Execute individual node | dict |

nodes

Purpose: Canvas nodes with execution logic (N8N compatible)

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| execute_node(input_data) | Execute this node | dict |
| get_knowledge_context() | Aggregate knowledge from incoming nodes | str |
| get_incoming_nodes() | Get all feeding nodes | recordset |
| get_parameters_dict() | Get parameters as dictionary | dict |
| set_parameters_dict(params) | Set parameters from dictionary | None |

workflow.connection

Purpose: Edges/connections between nodes defining data flow paths

workflow.field.mapping

Purpose: Field mappings between source and target nodes on connections

workflow.template

Purpose: Reusable workflow templates with marketplace support

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| action_create_workflow() | Create workflow from template | action dict |
| action_validate_template() | Validate template structure | None |
| action_publish_to_marketplace() | Publish to marketplace | None |
| import_n8n_workflow(n8n_data, name) | Import N8N workflow as template | template record |
| get_marketplace_templates() | Get public validated templates | recordset |

workflow.business.unit

Purpose: Business unit organization for workflow filtering

Pre-loaded Data:
- SALES - Sales Department
- MKT - Marketing
- OPS - Operations
- FIN - Finance & Accounting
- HR - Human Resources
- IT - Information Technology

canvas.history

Purpose: Undo/redo support for canvas operations

Key Methods:
| Method | Purpose | Returns |
|--------|---------|---------|
| undo() | Restore previous state | dict |
| redo() | Re-mark as not undone | dict |
| get_canvas_history(canvas_id, limit, include_undone) | Get history entries | list |
| cleanup_old_history(canvas_id, keep_entries) | Cleanup old entries | None |

n8n.simple.node

Purpose: Denormalized N8N node type registry (505+ entries)

n8n.simple.supplier

Purpose: Supplier/vendor table for node grouping

Additional Models (Brief)

Controllers / API Endpoints

REST Endpoints

JSON-RPC Methods

Request/Response Examples

POST /api/workflow/vendors

Request:

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "search": "google",
        "limit": 50,
        "offset": 0
    }
}

Response:

{
    "vendors": [
        {
            "key": "Google",
            "name": "Google",
            "node_count": 28,
            "service_count": 20,
            "icon": "https://...",
            "has_services": true
        }
    ],
    "total": 1
}

RPC: canvas.save_canvas_state

Request:

self.env['canvas'].save_canvas_state(workflow_id=42, canvas_state={
    "nodes": [
        {"id": "node-1", "type": "n8n-nodes-base.start", "position": [250, 300]}
    ],
    "connections": {},
    "settings": {}
})

Response:

True  # Success

Data Relationships Diagram

┌─────────────────────────────────────────────────────────────┐
│                        canvas                                │
│  - json_definition (SOURCE OF TRUTH)                        │
│  - business_unit_id -> workflow.business.unit               │
│  - template_id -> workflow.template                         │
│  - execution_ids <- executions                              │
└─────────────────────────────────────────────────────────────┘
           │                    │                    │
           │ One2many           │ Many2one           │ Many2one
           ▼                    ▼                    ▼
┌──────────────────┐   ┌────────────────────┐  ┌─────────────────────┐
│   executions     │   │ workflow.business  │  │  workflow.template  │
│                  │   │      .unit         │  │                     │
│ - canvas_id (FK) │   │                    │  │ - json_definition   │
│ - state          │   │ - code (SALES)     │  │ - visibility        │
│ - node_outputs   │   │ - canvas_ids       │  │ - usage_count       │
└──────────────────┘   └────────────────────┘  └─────────────────────┘
           │
           │ One2many
           ▼
┌──────────────────────┐
│  workflow.node.output│
│                      │
│ - execution_id (FK)  │
│ - node_id            │
│ - json_output        │
│ - human_output       │
└──────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                         nodes                                │
│  - canvas_id -> canvas                                      │
│  - workflow_node_type_id -> n8n.simple.node                 │
│  - credential_id -> api_credentials                         │
└─────────────────────────────────────────────────────────────┘
           │
           │ Many2one/One2many
           ▼
┌──────────────────────┐        ┌──────────────────────────────┐
│ workflow.connection  │        │      n8n.simple.node         │
│                      │        │                              │
│ - source_node_id     │        │ - supplier (Google, Slack)   │
│ - target_node_id     │        │ - service (Gmail, Drive)     │
│ - field_mapping_ids  │        │ - is_trigger                 │
└──────────────────────┘        │ - supplier_name_rel          │
           │                    └──────────────────────────────┘
           │ One2many                      │
           ▼                               │ Many2one
┌──────────────────────────┐               ▼
│ workflow.field.mapping   │     ┌──────────────────────────────┐
│                          │     │    n8n.simple.supplier       │
│ - source_field           │     │                              │
│ - target_field           │     │ - has_services               │
│ - transform_type         │     │ - node_ids                   │
│ - mapping_status         │     └──────────────────────────────┘
└──────────────────────────┘

Security Rules

Database Tables

Indexes and Performance

Change History