Ida Dittrich cfeaccdf02 finished pagination feature with filter and search options

2025-12-15 07:16:20 +01:00

35 KiB

Raw Blame History

Interactive Workflow Planning UI Documentation

This document describes how to build an interactive user interface for planning and managing automated workflows, including what's currently available in the gateway, what's missing, and requirements for a complete UI implementation.

Overview
Current Gateway Capabilities
UI Requirements
Missing Gateway Features
Gateway API Endpoints Needed
UI Implementation Guide
Data Flow
Validation and Error Handling

Overview

The interactive workflow planning UI allows users to visually create, edit, and manage automated workflows without manually writing JSON. The gateway must provide all necessary metadata, validation, and execution capabilities to support a fully dynamic frontend that requires no hardcoded logic.

Key Principles:

Gateway-First: All business logic, validation, and metadata come from the gateway
No Frontend Hardcoding: Action types, parameters, validation rules, and schemas are served dynamically
Progressive Enhancement: UI should work with basic features and enhance as gateway capabilities expand
Real-time Validation: Validate plans as users build them, not just on save

Current Gateway Capabilities

Available API Endpoints

The gateway currently provides these automation-related endpoints:

1. Automation CRUD Operations

GET /api/automations: List all automations (with pagination)
POST /api/automations: Create new automation definition
GET /api/automations/{automationId}: Get single automation by ID
PUT /api/automations/{automationId}: Update automation definition
DELETE /api/automations/{automationId}: Delete automation definition
POST /api/automations/{automationId}/execute: Execute automation immediately

2. Metadata Endpoints

GET /api/automations/attributes: Get AutomationDefinition field definitions for form generation

3. Connection Management

GET /api/connections/: Get all user connections (for use in action parameters)
- Returns list of UserConnection objects with connection metadata
- Automatically refreshes expired OAuth tokens
- Users can only see their own connections (security enforced)
- Used by UI to populate connection selectors in action parameter forms

4. File Management

GET /api/files/list: Get all user files (for use in document references)
- Returns paginated list of FileItem objects
- Supports optional pagination, sorting, and filtering
- Used by UI to populate file selectors when building document references
- Enables users to reference existing files (e.g., docItem:{id}:{filename})
POST /api/files/upload: Upload new files to the system
- Accepts file upload via multipart form data
- Returns FileItem metadata with file ID and name
- Handles duplicate detection (exact duplicates reuse existing file)
- Optional workflowId parameter to associate file with workflow
- Used by UI to allow users to upload files during workflow creation
- After upload, UI should refresh file list to include newly uploaded file

Available Data Structures

AutomationDefinition Model

{
  "id": "uuid",
  "mandateId": "mandate-id",
  "label": "Workflow Name",
  "schedule": "0 22 * * *",
  "template": "Template text with <!--TEMPLATE_PLAN_START-->...<!--TEMPLATE_PLAN_END-->",
  "placeholders": {"KEY": "value"},
  "active": true,
  "eventId": "optional-event-id",
  "status": "active|inactive",
  "executionLogs": [...],
  "_createdBy": "user-id",
  "_createdAt": "timestamp",
  "_modifiedAt": "timestamp"
}

TaskPlan Structure (embedded in template)

{
  "overview": "Plan description",
  "tasks": [
    {
      "id": "task1",
      "objective": "Task objective",
      "dependencies": ["task0"],
      "successCriteria": ["criteria1"],
      "estimatedComplexity": "simple|medium|complex",
      "userMessage": "User-facing message",
      "actions": [
        {
          "id": "action1",
          "execMethod": "ai",
          "execAction": "process",
          "execParameters": {...},
          "execResultLabel": "result_label",
          "expectedDocumentFormats": ["pdf"],
          "userMessage": "Action description"
        }
      ]
    }
  ],
  "userMessage": "Overall user message"
}

Internal Capabilities (Not Yet Exposed)

The gateway has internal functions that could be exposed:

Method Discovery: extractAvailableMethods() - Returns available execMethod/execAction combinations
Action Signatures: getActionSignature() - Returns parameter schemas for actions
Document Reference Resolution: getAvailableDocuments() - Returns available document references
Plan Validation: WorkflowValidator.validateTaskPlan() - Validates TaskPlan structure

Note: Connection references are already available via the existing GET /api/connections/ endpoint. The UI can format these into connection reference strings (e.g., connection:msft:username) based on the connection metadata returned by this endpoint.

UI Requirements

Core Features

1. Workflow Builder Interface

Visual Workflow Editor:

Drag-and-drop task creation
Visual dependency graph (tasks connected by dependencies)
Task and action configuration forms
Real-time validation feedback
Plan preview (JSON view)

Task Management:

Add/remove/reorder tasks
Configure task properties (id, objective, dependencies, success criteria)
Visual dependency editor (select dependencies from dropdown)
Task complexity indicator

Action Management:

Add/remove actions within tasks
Action type selector (method + action combination)
Dynamic parameter forms based on action signature
Document reference selector (dropdown of available references)
Connection selector (dropdown of user connections)
Result label configuration

2. Automation Definition Management

Form Fields:

Label (text input, required)
Schedule (cron expression selector or manual input)
Template (auto-generated from visual plan, editable)
Placeholders (key-value editor)
Active toggle (checkbox)

Metadata Display:

Execution logs viewer
Status indicator
Created/modified timestamps
Creator information

3. Plan Validation

Real-time Validation:

Required field checks
Task ID uniqueness
Dependency validation (no circular dependencies, valid task IDs)
Action parameter validation
Document reference validation
Connection reference validation

Error Display:

Inline field errors
Task-level errors
Action-level errors
Summary error list

4. Testing and Execution

Test Execution:

"Test Run" button (executes without saving)
Execution status monitoring
Result preview
Error display

Save and Schedule:

Save as draft
Activate automation
Schedule configuration

UI Components Needed

Task List/Board: Visual representation of tasks
Task Editor: Form for editing task properties
Action Editor: Dynamic form for action configuration
Dependency Graph: Visual representation of task dependencies
Parameter Forms: Dynamic forms based on action signatures
Reference Selectors: Dropdowns for documents and connections
Validation Panel: Real-time error display
Plan Preview: JSON view of generated plan
Execution Monitor: Status display for test runs

Missing Gateway Features

Critical Missing Endpoints

1. GET `/api/workflows/metadata/actions`

Purpose: Get list of available actions for action selection in workflow plans

Response Format:

{
  "actions": [
    {
      "compoundName": "ai.process",
      "method": "ai",
      "methodDescription": "AI processing capabilities",
      "action": "process",
      "actionDescription": "Process documents with AI",
      "signature": {
        "parameters": [
          {
            "name": "prompt",
            "type": "string",
            "required": true,
            "description": "AI prompt text",
            "default": null
          },
          {
            "name": "documentList",
            "type": "array[string]",
            "required": false,
            "description": "Document references",
            "default": []
          },
          {
            "name": "options",
            "type": "object",
            "required": false,
            "description": "Processing options",
            "default": {},
            "properties": {
              "operationType": {
                "type": "string",
                "enum": ["TEXT_ANALYSIS", "SUMMARIZATION", "TRANSLATION"],
                "description": "Type of operation"
              },
              "priority": {
                "type": "string",
                "enum": ["low", "normal", "high"],
                "default": "normal"
              }
            }
          }
        ],
        "returnType": "ActionResult"
      }
    },
    {
      "compoundName": "ai.analyze",
      "method": "ai",
      "methodDescription": "AI processing capabilities",
      "action": "analyze",
      "actionDescription": "Analyze documents and extract insights",
      "signature": {
        "parameters": [...]
      }
    },
    {
      "compoundName": "sharepoint.search",
      "method": "sharepoint",
      "methodDescription": "SharePoint integration capabilities",
      "action": "search",
      "actionDescription": "Search SharePoint for documents",
      "signature": {
        "parameters": [...]
      }
    }
  ],
  "groupedByMethod": {
    "ai": {
      "methodDescription": "AI processing capabilities",
      "actions": ["ai.process", "ai.analyze", "ai.generate"]
    },
    "sharepoint": {
      "methodDescription": "SharePoint integration capabilities",
      "actions": ["sharepoint.search", "sharepoint.download", "sharepoint.upload"]
    }
  }
}

Implementation Notes:

Should call extractAvailableMethods() or getMethodsList() internally
Should flatten the structure to prioritize actions (users select actions, not methods)
Should include full parameter schemas from getActionSignature() for each action
Should include parameter descriptions from docstrings
Should include enum values for select fields
Should indicate required vs optional parameters
Should include groupedByMethod for UI grouping/filtering by method category
Each action should include its parent method information for context

2. POST `/api/workflows/validate/plan`

Purpose: Validate a TaskPlan JSON structure before saving

Request Format:

{
  "plan": {
    "overview": "...",
    "tasks": [...]
  }
}

Response Format:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "validationDetails": {
    "structureValid": true,
    "taskIdsUnique": true,
    "dependenciesValid": true,
    "actionsValid": true,
    "documentReferencesValid": true
  }
}

Error Format:

{
  "valid": false,
  "errors": [
    {
      "level": "plan|task|action",
      "taskId": "task1",
      "actionId": "action1",
      "field": "execMethod",
      "message": "Invalid execMethod: 'invalid_method'",
      "code": "INVALID_METHOD"
    }
  ],
  "warnings": [
    {
      "level": "task",
      "taskId": "task1",
      "message": "Task has no dependencies but may depend on previous tasks",
      "code": "MISSING_DEPENDENCY"
    }
  ]
}

Implementation Notes:

Should use WorkflowValidator.validateTaskPlan()
Should validate action method/action combinations exist
Should validate document references format (not existence, as workflow may not exist yet)
Should check for circular dependencies
Should validate parameter types match signatures

3. GET `/api/workflows/metadata/document-references`

Purpose: Get available document reference patterns and examples

Response Format:

{
  "referencePatterns": [
    {
      "pattern": "docList:round1_usercontext",
      "description": "All documents from user's first message",
      "example": "docList:round1_usercontext"
    },
    {
      "pattern": "docList:{label}",
      "description": "All documents with specific label from previous action",
      "example": "docList:extracted_content"
    },
    {
      "pattern": "docItem:{id}:{filename}",
      "description": "Specific document by ID and filename",
      "example": "docItem:123:report.pdf"
    }
  ],
  "availableReferences": [
    "docList:round1_usercontext"
  ]
}

Implementation Notes:

For new workflows, only show docList:round1_usercontext (initial user documents)
For existing workflows, show actual available references from workflow
Should include pattern descriptions for UI tooltips

4. GET `/api/workflows/metadata/taskplan-schema`

Purpose: Get JSON schema for TaskPlan structure

Response Format:

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "overview": {
        "type": "string",
        "description": "Overall plan description"
      },
      "tasks": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/TaskStep"
        }
      }
    },
    "definitions": {
      "TaskStep": {...},
      "ActionItem": {...}
    }
  },
  "fieldDescriptions": {
    "overview": "Brief description of the overall plan",
    "tasks[].id": "Unique task identifier (e.g., 'task1', 'extract_content')",
    "tasks[].objective": "What the task accomplishes"
  }
}

Implementation Notes:

Should generate from Pydantic models (TaskPlan, TaskStep, ActionItem)
Should include field descriptions from model docstrings
Should include validation rules (required fields, types, enums)

5. GET `/api/workflows/metadata/action-signature/{method}/{action}`

Purpose: Get detailed parameter schema for specific action

Request: GET /api/workflows/metadata/action-signature/ai/process

Response Format:

{
  "method": "ai",
  "action": "process",
  "compoundName": "ai.process",
  "description": "Process documents with AI",
  "parameters": {
    "prompt": {
      "type": "string",
      "required": true,
      "description": "AI prompt text",
      "uiType": "textarea",
      "uiLabel": "Prompt",
      "uiPlaceholder": "Enter your prompt..."
    },
    "documentList": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "required": false,
      "description": "Document references",
      "uiType": "multiselect",
      "uiLabel": "Documents",
      "uiOptions": "document-references"
    },
    "options": {
      "type": "object",
      "required": false,
      "description": "Processing options",
      "properties": {
        "operationType": {
          "type": "string",
          "enum": ["TEXT_ANALYSIS", "SUMMARIZATION", "TRANSLATION"],
          "required": false,
          "default": "TEXT_ANALYSIS",
          "uiType": "select",
          "uiLabel": "Operation Type"
        }
      }
    }
  },
  "returnType": "ActionResult",
  "resultLabelRequired": false
}

Implementation Notes:

Should extract from method action signatures
Should include UI hints (uiType, uiLabel, uiPlaceholder)
Should indicate which parameters reference documents/connections
Should include default values
Should include enum values for select fields

6. GET `/api/workflows/templates`

Purpose: Provide pre-built workflow templates

Response Format:

{
  "templates": [
    {
      "id": "template-doc-processing",
      "name": "Document Processing Pipeline",
      "description": "Extract, analyze, and generate report",
      "category": "document-processing",
      "plan": {...},
      "placeholders": ["DATE", "REPORT_TITLE"]
    }
  ]
}

UI Implementation Guide

Architecture Overview

┌─────────────────┐
│   UI Frontend    │
│  (React/Vue/etc)│
└────────┬─────────┘
         │
         │ HTTP API Calls
         │
┌────────▼─────────────────────────────────────┐
│         Gateway API Layer                     │
│  ┌─────────────────────────────────────────┐ │
│  │ Metadata Endpoints                       │ │
│  │ - /api/workflows/metadata/*             │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │ Validation Endpoints                    │ │
│  │ - /api/workflows/validate/*             │ │
│  └─────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────┐ │
│  │ Automation CRUD                         │ │
│  │ - /api/automations/*                    │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

Data Flow

Why Connection and File Management Routes Are Needed:

The workflow planning UI requires access to existing connections and files for two critical purposes:

Connection References: Many actions require connection references (e.g., connection:msft:username for SharePoint actions). Users need to see their available connections to select them when configuring action parameters. The UI fetches connections via GET /api/connections/ to populate connection selectors in action parameter forms.
File References: Users may need to reference specific files in document lists (e.g., docItem:{id}:{filename}). The UI fetches available files via GET /api/files/list to enable file selection when building document references. This is especially important when users want to reference files uploaded to the system rather than workflow-generated documents.

These routes are existing gateway endpoints that are already available and should be used by the UI rather than creating new metadata endpoints for the same purpose.

1. Initial Load

sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Open workflow builder
    UI->>Gateway: GET /api/workflows/metadata/actions
    Gateway-->>UI: List of available actions
    UI->>Gateway: GET /api/connections/
    Gateway-->>UI: User's available connections
    UI->>Gateway: GET /api/files/list
    Gateway-->>UI: User's available files
    UI-->>User: UI Ready - Can build workflows

2. Creating New Workflow

sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Click "New Workflow"
    UI->>UI: Create empty plan structure
    User->>UI: Add task
    User->>UI: Add action to task
    UI->>Gateway: GET /api/workflows/metadata/action-signature/{method}/{action}
    Gateway-->>UI: Action parameter schema
    UI->>UI: Render dynamic parameter form
    
    alt Action requires connections
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: User's available connections
        UI->>UI: Populate connection selector dropdown
    end
    
    alt Action requires document references
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: User's available files
        UI->>UI: Populate file/document selector dropdown
        
        alt User uploads new file
            User->>UI: Click "Upload File"
            User->>UI: Select file to upload
            UI->>Gateway: POST /api/files/upload (with file)
            Gateway-->>UI: Uploaded file metadata
            UI->>Gateway: GET /api/files/list (refresh list)
            Gateway-->>UI: Updated files list (includes new file)
            UI->>UI: Update file selector dropdown
        end
    end
    
    User->>UI: Fill parameters
    User->>UI: Select document references (from metadata + files)
    User->>UI: Select connections (from connections API)
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results (errors/warnings)
    UI->>UI: Display validation feedback
    User->>UI: Click "Save"
    UI->>UI: Embed plan in template field
    UI->>Gateway: POST /api/automations (with template)
    Gateway-->>UI: Created automation
    UI-->>User: Success message

3. Editing Existing Workflow

sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Open automation
    UI->>Gateway: GET /api/automations/{id}
    Gateway-->>UI: AutomationDefinition with template
    UI->>UI: Extract plan from template field (client-side parsing)
    
    alt Need to resolve references in plan
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: User's available connections (for validation)
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: User's available files (for validation)
    end
    
    UI->>UI: Render plan in visual editor
    UI-->>User: Display workflow editor
    User->>UI: Edit plan
    
    alt User modifies action requiring connections/files
        UI->>Gateway: GET /api/connections/
        Gateway-->>UI: Updated connections list
        UI->>Gateway: GET /api/files/list
        Gateway-->>UI: Updated files list
    end
    
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results
    UI->>UI: Display validation feedback
    User->>UI: Click "Save"
    UI->>UI: Embed plan in template field
    UI->>Gateway: PUT /api/automations/{id} (with updated template)
    Gateway-->>UI: Updated automation
    UI-->>User: Success message

4. Plan Validation

sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    Note over UI: User edits workflow plan
    
    alt Real-time validation (on change)
        User->>UI: Modify plan (add/edit task/action)
        UI->>UI: Debounce timer (wait for pause in typing)
        UI->>Gateway: POST /api/workflows/validate/plan
        Note right of Gateway: Validates:<br/>- Structure<br/>- Task IDs uniqueness<br/>- Dependencies<br/>- Action methods/actions<br/>- Parameter types<br/>- Document references format
        Gateway-->>UI: Validation results (errors/warnings)
        alt Plan has errors
            UI->>UI: Display inline errors
            UI->>UI: Highlight invalid fields
            UI->>UI: Show error summary panel
            UI-->>User: Visual feedback (red indicators)
        else Plan has warnings only
            UI->>UI: Display warnings
            UI->>UI: Show warning summary panel
            UI-->>User: Visual feedback (yellow indicators)
        else Plan is valid
            UI->>UI: Clear all error indicators
            UI->>UI: Show success indicator
            UI-->>User: Visual feedback (green checkmark)
        end
    end
    
    alt Manual validation (before save/execute)
        User->>UI: Click "Save" or "Test Run"
        UI->>Gateway: POST /api/workflows/validate/plan (final check)
        Gateway-->>UI: Validation results
        alt Plan is invalid
            UI->>UI: Display validation errors prominently
            UI-->>User: Block save/execute, show errors
        else Plan is valid
            UI->>UI: Proceed with save/execute
        end
    end

5. Testing Workflow

sequenceDiagram
    participant User
    participant UI as UI Frontend
    participant Gateway as Gateway API
    
    User->>UI: Click "Test Run"
    UI->>Gateway: POST /api/workflows/validate/plan
    Gateway-->>UI: Validation results
    alt Plan is valid
        UI->>UI: Embed plan in template field
        UI->>Gateway: POST /api/automations (temporary)
        Gateway-->>UI: Created automation
        UI->>Gateway: POST /api/automations/{id}/execute
        Gateway-->>UI: Workflow started
        loop Poll for status
            UI->>Gateway: GET /api/workflows/{workflowId}
            Gateway-->>UI: Workflow status
        end
        UI-->>User: Display execution results
    else Plan is invalid
        UI-->>User: Display validation errors
    end

UI Component Structure

Component Hierarchy

WorkflowBuilder
├── WorkflowHeader (label, schedule, placeholders)
├── TaskList
│   ├── TaskCard (for each task)
│   │   ├── TaskHeader (id, objective, dependencies)
│   │   ├── ActionList
│   │   │   └── ActionCard (for each action)
│   │   │       ├── ActionSelector (method/action dropdown)
│   │   │       ├── ParameterForm (dynamic based on signature)
│   │   │       ├── DocumentReferenceSelector
│   │   │       ├── ConnectionSelector
│   │   │       └── ResultLabelInput
│   │   └── DependencySelector
│   └── AddTaskButton
├── ValidationPanel
├── PlanPreview (JSON view)
└── ActionBar (Save, Test, Execute)

Key Components

1. ActionSelector Component

// Fetches from: GET /api/workflows/metadata/actions
interface ActionOption {
  compoundName: string;  // e.g., "ai.process"
  method: string;         // e.g., "ai"
  methodDescription: string;
  action: string;         // e.g., "process"
  actionDescription: string;
}

// Renders dropdown with actions as primary selection:
// [ai.process - Process documents with AI ▼]
// [ai.analyze - Analyze documents and extract insights ▼]
// [sharepoint.search - Search SharePoint for documents ▼]
// 
// Can be grouped/filtered by method using groupedByMethod from response

2. ParameterForm Component

// Fetches from: GET /api/workflows/metadata/action-signature/{method}/{action}
interface ParameterSchema {
  name: string;
  type: string;
  required: boolean;
  description: string;
  uiType: 'text' | 'textarea' | 'select' | 'multiselect' | 'object';
  uiLabel: string;
  enum?: string[];
  properties?: ParameterSchema[]; // For nested objects
}

// Dynamically renders form fields based on schema

3. DocumentReferenceSelector Component

// Fetches from: GET /api/workflows/metadata/document-references
interface DocumentReference {
  pattern: string;
  description: string;
  example: string;
}

// Renders dropdown with:
// - docList:round1_usercontext (All documents from user's first message)
// - docList:{label} (Custom label input)
// - docItem:{id}:{filename} (Specific document)

4. ValidationPanel Component

// Validates via: POST /api/workflows/validate/plan
interface ValidationError {
  level: 'plan' | 'task' | 'action';
  taskId?: string;
  actionId?: string;
  field?: string;
  message: string;
  code: string;
}

// Displays errors inline and in summary panel

State Management

Plan State Structure

interface WorkflowPlanState {
  plan: {
    overview: string;
    userMessage: string;
    tasks: TaskStep[];
  };
  metadata: {
    actions: ActionMetadata[];
    documentReferences: DocumentReference[];
    connectionReferences: ConnectionReference[];
    schema: JSONSchema;
  };
  validation: {
    errors: ValidationError[];
    warnings: ValidationWarning[];
    isValid: boolean;
  };
  ui: {
    selectedTaskId: string | null;
    selectedActionId: string | null;
    expandedTasks: Set<string>;
    viewMode: 'visual' | 'json';
  };
}

State Updates Flow

User Action
  ↓
Update Local State
  ↓
Debounced Validation Call
  ↓
POST /api/workflows/validate/plan
  ↓
Update Validation State
  ↓
Update UI (show errors, enable/disable save)

Form Generation Strategy

Dynamic Form Generation

Fetch Schema: Get action signature from gateway
Generate Fields: Create form fields based on parameter types
Apply UI Hints: Use uiType, uiLabel, uiPlaceholder from schema
Handle Special Types:
- documentList → DocumentReferenceSelector
- connections → ConnectionSelector
- enum → Select dropdown
- object → Nested form or JSON editor
Validate: Use schema types for client-side validation
Submit: Format as execParameters object

Example: AI Process Action Form

// Schema from: GET /api/workflows/metadata/action-signature/ai/process
{
  "prompt": {
    "type": "string",
    "required": true,
    "uiType": "textarea",
    "uiLabel": "Prompt"
  },
  "documentList": {
    "type": "array",
    "uiType": "multiselect",
    "uiOptions": "document-references"
  },
  "options": {
    "type": "object",
    "properties": {
      "operationType": {
        "type": "string",
        "enum": ["TEXT_ANALYSIS", "SUMMARIZATION"],
        "uiType": "select"
      }
    }
  }
}

// Generated Form:
<Form>
  <TextareaField name="prompt" required />
  <DocumentReferenceSelector name="documentList" multiple />
  <ObjectField name="options">
    <SelectField name="operationType" options={["TEXT_ANALYSIS", "SUMMARIZATION"]} />
  </ObjectField>
</Form>

Validation and Error Handling

Validation Levels

1. Client-Side Validation (Immediate)

Required field checks
Type validation (string, number, array, object)
Format validation (task IDs, document references)
Basic structure validation

2. Gateway Validation (On Change/Save)

Full structure validation
Method/action existence
Parameter type matching
Dependency validation
Reference format validation

3. Execution Validation (On Execute)

Document reference existence
Connection availability
Parameter completeness

Error Display Strategy

Inline Errors

Show errors next to fields
Highlight invalid fields
Show error messages in tooltips

Task/Action Level Errors

Show error badges on task/action cards
Expand to show details
Highlight affected fields

Summary Panel

List all errors grouped by level
Allow clicking to navigate to error location
Show error codes for debugging

Error Recovery

Validation Errors

Prevent save until resolved
Allow test run with warnings
Show suggestions for fixing errors

Execution Errors

Display in execution log
Allow retry
Show error details

Implementation Checklist

Gateway Implementation

Phase 1: Critical Endpoints
- Implement GET /api/workflows/metadata/actions
- Implement GET /api/workflows/metadata/action-signature/{method}/{action}
- Implement POST /api/workflows/validate/plan
- Implement GET /api/workflows/metadata/document-references
Phase 2: High Priority
- Implement GET /api/workflows/metadata/taskplan-schema
- Implement GET /api/workflows/templates

UI Implementation

Core Components
- WorkflowBuilder container
- TaskList component
- TaskCard component
- ActionList component
- ActionCard component
Form Components
- ActionSelector dropdown
- Dynamic ParameterForm generator
- DocumentReferenceSelector
- ConnectionSelector
- DependencySelector
Validation Components
- ValidationPanel
- Inline error display
- Error summary
Utility Components
- PlanPreview (JSON view)
- PlanEditor (visual editor)
- ExecutionMonitor
State Management
- Plan state management
- Metadata caching
- Validation state
- UI state
API Integration
- Metadata fetching
- Plan validation
- Plan save/load
- Automation CRUD
- Execution monitoring

Example Implementation Flow

Scenario: User Creates Document Processing Workflow

User opens workflow builder
- UI fetches: methods, document references, connection references, schema
- UI renders empty workflow builder
User adds first task
- User clicks "Add Task"
- UI creates task with ID "task1"
- User enters objective: "Extract content from documents"
User adds action to task
- User clicks "Add Action" in task1
- UI shows action selector dropdown
- User selects "extraction.extractContent"
- UI fetches action signature
- UI renders parameter form:
  - documentList: DocumentReferenceSelector (shows "docList:round1_usercontext")
  - options: Object editor with processDocumentsIndividually, chunkAllowed
- User selects "docList:round1_usercontext"
- User sets resultLabel: "extracted_content"
User adds second task
- User clicks "Add Task"
- UI creates task with ID "task2"
- User enters objective: "Analyze extracted content"
- User sets dependency: ["task1"]
- User adds action "ai.process"
- UI renders parameter form:
  - prompt: Textarea
  - documentList: DocumentReferenceSelector (shows "docList:extracted_content" from task1)
  - options: Object editor
- User enters prompt
- User selects "docList:extracted_content"
- User sets resultLabel: "analysis_result"
User validates plan
- UI automatically validates on change
- POST /api/workflows/validate/plan
- Gateway returns: valid=true, no errors
- UI shows green checkmark
User saves workflow
- User enters label: "Document Analysis Workflow"
- User sets schedule: "0 22 * * *"
- User clicks "Save"
- UI embeds plan in template field (client-side, wraps JSON in HTML comment markers)
- UI calls POST /api/automations (creates automation with template field)
- UI shows success message
User tests workflow
- User clicks "Test Run"
- UI calls POST /api/automations/{id}/execute
- UI monitors execution status
- UI displays results

Conclusion

This documentation outlines the complete requirements for building an interactive workflow planning UI. The gateway must provide comprehensive metadata, validation, and plan management endpoints to support a fully dynamic frontend. By implementing the critical endpoints first, a basic UI can be built, with enhanced features added incrementally.

Key Takeaways:

Gateway must serve all metadata (actions, schemas, document references)
Gateway must provide validation before save/execute
UI handles plan extraction/embedding client-side (parsing template field)
UI should be fully dynamic based on gateway responses
No hardcoded logic in frontend - everything comes from gateway

Required Gateway Endpoints:

GET /api/workflows/metadata/actions - Action selection
POST /api/workflows/validate/plan - Plan validation
GET /api/workflows/metadata/document-references - Document reference patterns
GET /api/workflows/metadata/taskplan-schema - TaskPlan schema
GET /api/workflows/metadata/action-signature/{method}/{action} - Action parameter schemas
GET /api/workflows/templates - Pre-built templates

Next Steps:

Implement critical gateway endpoints (Phase 1)
Build basic UI components
Integrate validation
Add template library support

35 KiB Raw Blame History

Interactive Workflow Planning UI Documentation

Table of Contents

Overview

Current Gateway Capabilities

Available API Endpoints

1. Automation CRUD Operations

2. Metadata Endpoints

3. Connection Management

4. File Management

Available Data Structures

AutomationDefinition Model

TaskPlan Structure (embedded in template)

Internal Capabilities (Not Yet Exposed)

UI Requirements

Core Features

1. Workflow Builder Interface

2. Automation Definition Management

3. Plan Validation

4. Testing and Execution

UI Components Needed

Missing Gateway Features

Critical Missing Endpoints

1. GET /api/workflows/metadata/actions

2. POST /api/workflows/validate/plan

3. GET /api/workflows/metadata/document-references

4. GET /api/workflows/metadata/taskplan-schema

5. GET /api/workflows/metadata/action-signature/{method}/{action}

6. GET /api/workflows/templates

UI Implementation Guide

Architecture Overview

Data Flow

1. Initial Load

2. Creating New Workflow

3. Editing Existing Workflow

4. Plan Validation

5. Testing Workflow

UI Component Structure

Component Hierarchy

Key Components

State Management

Plan State Structure

State Updates Flow

Form Generation Strategy

Dynamic Form Generation

Example: AI Process Action Form

Validation and Error Handling

Validation Levels

1. Client-Side Validation (Immediate)

2. Gateway Validation (On Change/Save)

3. Execution Validation (On Execute)

Error Display Strategy

Inline Errors

Task/Action Level Errors

Summary Panel

Error Recovery

Validation Errors

Execution Errors

Implementation Checklist

Gateway Implementation

UI Implementation

Example Implementation Flow

Scenario: User Creates Document Processing Workflow

Conclusion

35 KiB

Raw Blame History

1. GET `/api/workflows/metadata/actions`

2. POST `/api/workflows/validate/plan`

3. GET `/api/workflows/metadata/document-references`

4. GET `/api/workflows/metadata/taskplan-schema`

5. GET `/api/workflows/metadata/action-signature/{method}/{action}`

6. GET `/api/workflows/templates`