gateway/docs/frontend-documentation/workflow-page-requirements.md

# Workflow Page Requirements

This document contains the complete frontend requirements for the workflow management page and its views/components. All UI components are dynamically generated from backend metadata—no hardcoding required.

## Table of Contents

1. [Overview](#overview)
2. [Page Structure and Layout](#page-structure-and-layout)
3. [User Interactions and Functionality](#user-interactions-and-functionality)
4. [Backend Routes and API Integration](#backend-routes-and-api-integration)
5. [Field and Attribute Reference](#field-and-attribute-reference)
6. [Dynamic Rendering Guidelines](#dynamic-rendering-guidelines)

---

## Overview

The workflow management page enables users to manage and monitor workflows that are already running or completed. The frontend consists of a single page (`/workflows`) with different views/states:

- **List View** - Browse, search, filter, and sort workflows
- **Detail View** - View complete workflow information, messages, and logs (expandable sections, roll down to see more)
- **Edit View** - Edit workflow properties (can be shown as popup/modal or inline edit)

All views use backend-driven UI generation, meaning field definitions, labels, validation rules, and UI structure come entirely from backend metadata through the `/api/attributes/ChatWorkflow` endpoint. Views are managed through component state and UI extensions (expandable sections, popups, modals) within the same page, not as separate routes.

---

## Page Structure and Layout

### Workflow Management Page (`/workflows`)

The workflow management page uses different views/states and UI extensions to handle different user interactions. Views are managed through component state and UI extensions (expandable sections, popups, modals) within the same page component.

### List View

**State:** `view === 'list'` or `selectedWorkflowId === null`

**What the user sees:**

- **Main Content Area:**
  - Table or card grid displaying all workflows
  - Each workflow row/card shows: name, status badge, last activity timestamp, progress indicators
  - Clickable rows/cards that expand to show Detail View (expandable section or roll down)

- **Search and Filter Controls:**
  - General search input box (searches across all text fields)
  - Field-specific filter controls (one filter per visible field)
  - Active filter indicators (chips/badges showing applied filters)
  - "Clear all filters" button when filters are active

- **Sorting Controls:**
  - Clickable column headers with sort indicators (up/down arrows)
  - Visual indication of current sort field and direction
  - Support for multi-level sorting

- **Pagination Controls:**
  - Page information display ("Page X of Y", "Showing 1-20 of 45 workflows")
  - Previous/Next page buttons
  - Page number buttons
  - Page size selector (10, 20, 50, 100 items per page)

### Detail View (Expandable Section)

**State:** `view === 'detail'` and `selectedWorkflowId !== null`

**UI Pattern:** Expandable section that rolls down from the selected workflow row, or inline expansion within the list

**What the user sees:**

- **Workflow Header Section:**
  - Workflow name (editable indicator if user has permission)
  - Status badge with color coding
  - Key metrics (progress indicators, timestamps)

- **Workflow Information Section:**
  - All workflow properties displayed as formatted fields
  - Read-only fields shown as formatted text
  - Editable fields shown with edit indicators (if user has permission)
  - Special formatting:
    - Status → Color-coded badge
    - Timestamps → Relative time ("2 hours ago") or absolute date/time
    - Progress fields → Progress bars
    - Select fields → Display localized labels (not enum values)

- **Messages Section:**
  - List of all messages in chronological order
  - Each message shows: role (user/assistant/system), content, timestamp, attached files
  - Message threading support (if `parentMessageId` exists)
  - Pagination controls if many messages
  - Delete button for each message (if user has permission)

- **Logs Section:**
  - List of execution logs in reverse chronological order (newest first)
  - Color-coded by type (info/warning/error)
  - Progress indicators if `progress` field exists
  - Filter controls by log type
  - Pagination controls if many logs

- **Action Buttons:**
  - Edit button (if user has permission and editable fields exist)
  - Delete button (if user has permission)

- **Real-Time Updates** (when workflow is running):
  - Status indicator that updates automatically
  - New messages appearing in the messages list
  - New logs appearing in the logs viewer
  - Progress indicators updating
  - Activity indicators showing workflow is active

### Workflow Edit Page (`/workflows/{workflowId}/edit`)

**What the user sees:**

- **Form Section:**
  - Dynamic form with editable workflow fields only
  - Field labels with required indicators (asterisk for required fields)
  - Help text/tooltips from field descriptions
  - Input validation errors displayed inline

- **Action Buttons:**
  - Save button (submits form)
  - Cancel button (navigates back to detail page)

- **Confirmation Dialogs:**
  - Delete confirmation dialog (on workflow detail page)
  - Message deletion confirmation dialog
  - File deletion confirmation dialog

---

## User Interactions and Functionality

### Browsing and Discovery

**Search Functionality:**
- User types in general search box
- Frontend debounces input (300-500ms delay)
- Search applies across all text fields in workflow objects
- Results update automatically
- Page resets to page 1 when search changes

**Field Filtering:**
- User selects field to filter by
- Frontend shows appropriate filter UI based on field type:
  - Text fields → Text input with operator selection (contains, equals, startsWith, endsWith)
  - Select fields → Dropdown with options from backend metadata
  - Integer fields → Number input with comparison operators (gt, gte, lt, lte) or range inputs
  - Timestamp fields → Date picker with comparison operators or date range picker
  - Checkbox fields → Boolean toggle (true/false/any)
- User applies filter → Filter appears as active chip/badge
- User can remove individual filters
- Multiple filters work together (AND logic)
- Page resets to page 1 when filters change

**Sorting:**
- User clicks column header
- Sort direction toggles (asc → desc → remove)
- Multiple columns can be sorted (multi-level sorting)
- Sort indicators show on column headers
- All filters and search preserved when sorting

**Pagination:**
- User clicks page number or navigation button
- Page updates and data refetches
- All filters, search, and sort preserved
- User changes page size → Page resets to 1, data refetches

**View Switching:**
- User clicks workflow row/card → Expands Detail View (expandable section rolls down, or switches to Detail View state)
- User clicks workflow name → Expands Detail View (expandable section rolls down, or switches to Detail View state)
- User clicks collapse/back button → Collapses Detail View, returns to List View

### Viewing Workflow Details

**Information Display:**
- All workflow fields displayed using dynamic rendering
- Read-only fields shown as formatted text
- Editable fields shown with edit indicators
- Special fields formatted appropriately (status badges, timestamps, progress bars)

**Messages Display:**
- Messages shown in chronological order (`publishedAt`)
- Role-based styling (user/assistant/system)
- Attached files displayed with download/view options
- Threading support for parent-child message relationships
- Pagination if many messages

**Logs Display:**
- Logs shown in reverse chronological order (newest first)
- Color-coded by type (info/warning/error)
- Progress indicators displayed if available
- Filtering by log type supported

**Real-Time Monitoring** (when workflow is running):
- Status polling every 2-5 seconds
- New messages polling every 2-3 seconds (incremental loading)
- New logs polling every 2-3 seconds (incremental loading)
- All polling stops when workflow status changes to "completed", "stopped", or "error"
- Completion message shown when workflow finishes

### Editing Workflows

**Form Interaction:**
- User clicks "Edit" button → Opens Edit View as popup/modal overlay
- Form pre-populated with current workflow values
- User modifies fields
- Client-side validation shows errors immediately
- User clicks Save → Form validates and submits
- User clicks Cancel → Closes popup/modal, returns to Detail View

**Form Validation:**
- Required field validation (shows error if empty)
- Type validation (e.g., integer fields must be numbers)
- Select field validation (value must be in options array)
- Validation errors displayed inline below fields

**Form Submission:**
- Only changed fields sent (or all form data)
- Success → Close popup/modal, refresh Detail View data, show success message
- Error handling:
  - 403 (permission denied) → Show permission error in popup
  - 400 (validation errors) → Display backend validation errors in popup
  - Other errors → Show generic error message in popup

### Managing Messages

**Message Actions:**
- User clicks delete button on message
- Confirmation dialog appears
- User confirms → Message deleted, list updates
- User cancels → Dialog closes, no action

**File Actions:**
- User clicks delete button on file attachment
- Confirmation dialog appears
- User confirms → File removed from message, display updates
- User cancels → Dialog closes, no action

### Deleting Workflows

**Delete Action:**
- User clicks delete button (on detail page or list)
- Confirmation dialog appears with workflow name
- Warning about permanent deletion
- User confirms → Workflow deleted
- User cancels → Dialog closes, no action

**Delete Success Handling:**
- Success message displayed
- If Detail View is expanded → Collapse Detail View, return to List View
- If in List View → Remove workflow from list or refresh

---

## Backend Routes and API Integration

### Complete Route Reference

All backend routes used by workflow pages:

| Route | Method | Purpose | When Used |
|-------|--------|---------|-----------|
| `/api/workflows/` | GET | Get all workflows (with pagination) | Initial page load, pagination changes, sort changes, filter changes, search changes |
| `/api/workflows/{workflowId}` | GET | Get workflow details | Detail View expansion, Edit View popup open |
| `/api/workflows/{workflowId}` | PUT | Update workflow | Edit form submission in popup |
| `/api/workflows/{workflowId}` | DELETE | Delete workflow | User confirms deletion in popup |
| `/api/workflows/{workflowId}/status` | GET | Get current workflow status | Real-time polling (every 2-5s when running, Detail View expanded) |
| `/api/workflows/{workflowId}/messages` | GET | Get workflow messages | Detail View expansion, refresh, real-time polling (every 2-3s when running) |
| `/api/workflows/{workflowId}/messages` | GET | Get new messages (incremental) | Real-time polling with `messageId` parameter (Detail View expanded) |
| `/api/workflows/{workflowId}/messages/{messageId}` | DELETE | Delete message | User confirms message deletion in popup |
| `/api/workflows/{workflowId}/messages/{messageId}/files/{fileId}` | DELETE | Delete file from message | User confirms file deletion in popup |
| `/api/workflows/{workflowId}/logs` | GET | Get workflow logs | Detail View expansion, refresh, real-time polling (every 2-3s when running) |
| `/api/workflows/{workflowId}/logs` | GET | Get new logs (incremental) | Real-time polling with `logId` parameter (Detail View expanded) |
| `/api/attributes/ChatWorkflow` | GET | Get field definitions | Page load (once per page) - used to generate all UI components |

### API Request Patterns

**Pagination Request:**
```
GET /api/workflows/?pagination={"page":1,"pageSize":20,"sort":[],"filters":null}
```
- `pagination` parameter is JSON-encoded string
- If user wants all workflows: omit `pagination` parameter entirely
- Filters structure: `{"search":"query","fieldName":"value",...}`

**Incremental Loading (Polling):**
```
GET /api/workflows/{workflowId}/messages?messageId={lastMessageId}
GET /api/workflows/{workflowId}/logs?logId={lastLogId}
```
- Used for real-time updates
- Only fetch new items after the specified ID
- Prevents reloading all data

**Update Request:**
```
PUT /api/workflows/{workflowId}
Content-Type: application/json
Body: {fieldName: value, ...}
```
- Send only changed fields or all form data
- Handle 403 (permission denied) and 400 (validation errors)

**Delete Requests:**
```
DELETE /api/workflows/{workflowId}
DELETE /api/workflows/{workflowId}/messages/{messageId}
DELETE /api/workflows/{workflowId}/messages/{messageId}/files/{fileId}
```
- All delete operations require user confirmation
- Handle 403 (permission denied) and 404 (not found) gracefully

### Response Handling

**Paginated Response:**
```json
{
  "items": [...],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 45,
    "totalPages": 3,
    "sort": [...],
    "filters": {...}
  }
}
```

**Error Responses:**
- 403 Forbidden → Show permission error message
- 404 Not Found → Show "not found" error message
- 400 Bad Request → Display validation errors from response
- 500 Internal Server Error → Show generic error message

---

## Field and Attribute Reference

### Complete Field List

The following is a comprehensive list of all parameters, attributes, and fields that will be displayed for workflows. All of these are provided by the backend through the `/api/attributes/ChatWorkflow` endpoint and should never be hardcoded in the frontend.

#### Core Workflow Fields

**Identification Fields:**
- `id` - Unique workflow identifier (text, readonly, not required, visible)
- `mandateId` - ID of the mandate this workflow belongs to (text, readonly, not required, visible)

**Status and Configuration Fields:**
- `status` - Current workflow status (select, editable, not required, visible)
  - Options: "running", "completed", "stopped", "error"
  - Each option has localized labels (en/fr)
- `name` - Workflow name (text, editable, required, visible)
- `workflowMode` - Workflow execution mode (select, editable, not required, visible)
  - Options: "Dynamic", "Automation", "Actionplan"
  - Each option has localized labels (en/fr)
- `maxSteps` - Maximum number of iterations in react mode (integer, editable, not required, visible)

**Progress Tracking Fields:**
- `currentRound` - Current round number in workflow execution (integer, readonly, not required, visible)
- `currentTask` - Current task number within the current round (integer, readonly, not required, visible)
- `currentAction` - Current action number within the current task (integer, readonly, not required, visible)
- `totalTasks` - Total number of tasks in the workflow (integer, readonly, not required, visible)
- `totalActions` - Total number of actions in the workflow (integer, readonly, not required, visible)

**Timestamp Fields:**
- `startedAt` - When the workflow started (timestamp, readonly, not required, visible)
- `lastActivity` - Timestamp of last activity (timestamp, readonly, not required, visible)

**Related Data Fields (Lists):**
- `logs` - List of workflow log entries (text/list, readonly, not required, visible)
- `messages` - List of workflow messages (text/list, readonly, not required, visible)
- `stats` - List of workflow statistics (text/list, readonly, not required, visible)
- `tasks` - List of tasks in the workflow (text/list, readonly, not required, visible)
- `expectedFormats` - List of expected file format extensions (text/list, readonly, not required, visible)

### Pagination Parameters

**Request Parameters (`PaginationParams`):**
- `page` - Current page number (1-based, minimum 1)
- `pageSize` - Number of items per page (minimum 1, maximum 1000)
- `sort` - Array of sort field configurations
  - Each sort field contains:
    - `field` - Field name to sort by (must match a workflow field name)
    - `direction` - Sort direction: "asc" or "desc"
- `filters` - Filter criteria dictionary
  - `search` - General search term (searches across all text fields, case-insensitive)
  - Field-specific filters: `{fieldName: value}` or `{fieldName: {operator: "operator", value: value}}`
  - Supported operators: "equals", "contains", "startsWith", "endsWith", "gt", "gte", "lt", "lte", "in", "notIn"

**Response Metadata (`PaginationMetadata`):**
- `currentPage` - Current page number (1-based)
- `pageSize` - Number of items per page
- `totalItems` - Total number of items across all pages (after filters applied)
- `totalPages` - Total number of pages (calculated from totalItems / pageSize)
- `sort` - Current sort configuration applied (array of SortField objects)
- `filters` - Current filters applied (mirrors request filters)

### Attribute Definition Structure

Each field returned from `/api/attributes/ChatWorkflow` contains:

- `name` - Field name (e.g., "status", "name", "lastActivity")
- `type` - Field data type (e.g., "text", "select", "integer", "timestamp", "checkbox")
- `label` - Localized field label (object with language keys: {"en": "English Label", "fr": "French Label"})
- `description` - Field description text
- `required` - Boolean indicating if field is required
- `readonly` - Boolean indicating if field is read-only
- `editable` - Boolean indicating if field can be edited (inverse of readonly)
- `visible` - Boolean indicating if field should be displayed in UI
- `options` - Array of options for select fields (each option has `value` and localized `label`)

---

## Dynamic Rendering Guidelines

The frontend must render all UI components dynamically based on backend metadata. No field definitions, labels, validation rules, or UI structure should be hardcoded.

### Table Column Generation

When rendering the workflow list table:

1. Fetch attribute definitions from `/api/attributes/ChatWorkflow`
2. Filter attributes where `visible: true` to determine which columns to display
3. Use `label` property for column headers (select appropriate language based on user preference)
4. Use `type` property to determine how to format cell values:
   - `text` fields → Display as plain text
   - `select` fields → Display value using label from options array (match value to option.value, then display option.label)
   - `integer` fields → Display as formatted number
   - `timestamp` fields → Format as relative time ("2 hours ago") or absolute date/time based on user preference
   - `checkbox` fields → Display as checkmark icon or boolean indicator
5. Use `readonly` property to determine if column should be sortable (readonly fields may still be sortable, but editable fields definitely are)
6. Generate click handlers for column headers to update sort parameters and refetch data

### Filter Control Generation

When rendering filter controls:

1. Fetch attribute definitions from `/api/attributes/ChatWorkflow`
2. Filter attributes where `visible: true` to determine which filters to show
3. For each visible field, generate appropriate filter UI based on `type`:
   - `text` fields → Text input filter (supports "contains", "equals", "startsWith", "endsWith" operators)
   - `select` fields → Dropdown filter with options from `options` array (use localized labels)
   - `integer` fields → Number range filter (min/max inputs) or single number input with comparison operators (gt, gte, lt, lte)
   - `timestamp` fields → Date range picker or single date picker with comparison operators
   - `checkbox` fields → Boolean toggle filter (true/false/any)
4. Use `label` property for filter labels (localized)
5. When user applies filter, update `filters` object in pagination parameters and refetch data
6. Display active filters as chips/badges showing field label and value
7. Allow removing individual filters by removing them from `filters` object

### Search Implementation

For general search functionality:

1. Display a single search input box (not field-specific)
2. When user types, update `filters.search` in pagination parameters
3. Debounce search input (wait 300-500ms after user stops typing before sending request)
4. Search applies across all text fields in the workflow object
5. Reset to page 1 when search query changes
6. Combine search with field-specific filters (both are in the `filters` object)

### Form Field Generation

When rendering edit forms:

1. Fetch attribute definitions from `/api/attributes/ChatWorkflow`
2. Filter attributes where `visible: true` AND `editable: true` to determine which fields to show
3. For each editable field, generate appropriate form input based on `type`:
   - `text` fields → Text input
   - `select` fields → Dropdown/select input with options from `options` array (use localized labels)
   - `integer` fields → Number input with appropriate min/max constraints
   - `timestamp` fields → Date/time picker
   - `checkbox` fields → Checkbox input
4. Use `label` property for field labels (localized)
5. Use `required` property to show required indicators (asterisk, etc.)
6. Use `description` property to show help text or tooltips
7. Validate form before submission:
   - Check all `required: true` fields have values
   - Validate types (e.g., integer fields must be numbers)
   - Validate select fields (value must be in options array)
8. On submit, send only changed fields or all form data to update endpoint

### Display Formatting

When displaying field values:

1. Use `type` property to determine formatting:
   - `text` → Display as-is (may need HTML escaping)
   - `select` → Look up value in `options` array and display localized label
   - `integer` → Format with thousand separators if needed
   - `timestamp` → Format as relative time or absolute date/time
   - `checkbox` → Display as checkmark icon or "Yes"/"No" text
2. Handle `null` or `undefined` values gracefully (show "-" or "Not set")
3. For list fields (logs, messages, stats), render as expandable sections or separate tables
4. Use `readonly` property to determine if field should show edit indicators

### Real-Time Polling

When monitoring running workflows:

1. **Status Polling:**
   - Poll every 2-5 seconds if workflow status is "running"
   - Stop polling if status is "completed", "stopped", or "error"
   - Update status badge and workflow information on each poll

2. **Message Polling (Incremental Loading):**
   - Store ID of last displayed message
   - Poll every 2-3 seconds for messages after last message ID
   - Append new messages to list (don't reload all)
   - Only poll if workflow is "running"

3. **Log Polling (Incremental Loading):**
   - Store ID of last displayed log
   - Poll every 2-3 seconds for logs after last log ID
   - Prepend new logs to list (newest first)
   - Only poll if workflow is "running"

4. **Polling Management:**
   - Stop all polling when workflow completes
   - Show completion message
   - Update UI to indicate workflow is finished

### Localization

All labels and options support multiple languages:

1. Use user's preferred language (from user settings or browser locale)
2. Access localized labels from `label` object: `label[userLanguage]` or `label.en` as fallback
3. For select options, use `option.label[userLanguage]` or `option.label.en` as fallback
4. If label for current language is missing, fall back to English

### Key Principles

- Never hardcode field names, labels, types, or validation rules
- Always fetch attribute definitions from backend before rendering UI
- Use attribute metadata to determine what to display and how to display it
- Support all field types dynamically - if backend adds new types, frontend should handle them
- Respect `visible`, `editable`, `readonly`, and `required` flags from backend
- Use localized labels from backend metadata
- Generate filters, forms, and tables entirely from attribute definitions
- When backend adds new fields, frontend should automatically display them without code changes
- Handle all error cases gracefully (403, 404, 400, 500)
- Provide user feedback for all actions (loading states, success messages, error messages)

---

## Summary

This document provides complete frontend requirements for the workflow management page and its views/components. All requirements follow the principle of **backend-driven UI generation**—no hardcoding of field definitions, labels, or validation rules. The frontend should dynamically generate all UI components from backend metadata provided through the `/api/attributes/ChatWorkflow` endpoint.

**Key Architecture Pattern:** The workflow management interface is a single page (`/workflows`) with different views managed through component state. Detail View is shown as an expandable section (roll down from selected workflow row), and Edit View is shown as a popup/modal overlay. All interactions happen within the same page component without separate routes.

For generic patterns that apply across all entity types (not just workflows), see the [Dynamic Forms and Pagination documentation](./dynamic-forms-and-pagination.md).