Skip to main content

EPANET Forms Implementation Plan

Overview

This document outlines the implementation plan for frontend forms to manage EPANET models, integrating with the new API controllers. The forms are categorized into two distinct types based on their relationship to network elements.

Model Categories

These models are directly tied to specific network elements (nodes/links) and will be editable from the 2D network map via onclick popup events.

  • Demand - Junction demand parameters

    • Fields: JunctionId, Category, BaseDemand, DemandPattern, DemandCharge
    • UI: Popup form when clicking on junction nodes
    • API: /api/demand
  • Quality - Node water quality parameters

    • Fields: NodeId, ScenarioId, InitialQuality
    • UI: Popup form when clicking on junction/tank/reservoir nodes
    • API: /api/quality
  • Emitter - Node emitter parameters

    • Fields: NodeId, Coefficient
    • UI: Popup form when clicking on junction nodes
    • API: /api/emitter
  • Source - Node source parameters

    • Fields: NodeId, SourceType, Quality, Pattern, Strength
    • UI: Popup form when clicking on reservoir/tank nodes
    • API: /api/source
  • TankMixing - Tank mixing parameters

    • Fields: TankId, MixingModel, Fraction
    • UI: Popup form when clicking on tank nodes
    • API: /api/tankmixing
  • Leakage - Pipe leakage parameters

    • Fields: LinkId, CrackArea, ExpansionRate
    • UI: Popup form when clicking on pipe links
    • API: /api/leakage
  • Status - Link status parameters

    • Fields: LinkId, ScenarioId, StatusValue
    • UI: Popup form when clicking on pipe/pump/valve links
    • API: /api/status

Category 2: Network-Wide Fields

These models are not tied to specific nodes/links and will be editable from the scenario page or dedicated forms.

Global Network Models

  • TimeParameters - Simulation time settings

    • Fields: Duration, HydraulicTimestep, QualityTimestep, RuleTimestep, PatternTimestep, PatternStart, ReportTimestep, ReportStart, StartClocktime, Statistic
    • UI: Scenario form or dedicated time parameters form
    • API: /api/timeparameters
  • Options - Simulation options

    • Fields: Units, Pressure, Headloss, Hydraulics, Unbalanced, DemandModel, EmitterBackflow, Quality, Trials, Accuracy, Tolerance, Checkfreq, Maxcheck, Damplimit
    • UI: Scenario form or dedicated options form
    • API: /api/options
  • Report - Report settings

    • Fields: Status, Summary, Energy, Nodes, Links, File, PageSize
    • UI: Scenario form or dedicated report settings form
    • API: /api/report
  • Energy - Energy calculation settings

    • Fields: ScenarioId, PumpEfficiency, Price, Pattern, DemandCharge
    • UI: Scenario form or dedicated energy settings form
    • API: /api/energy
  • Reaction - Chemical reaction parameters

    • Fields: ScenarioId, Order, Coefficient, ReactionType
    • UI: Scenario form or dedicated reaction settings form
    • API: /api/reaction

Reference Data Models

  • Pattern - Time patterns

    • Fields: Id, Multipliers, Description
    • UI: Dedicated patterns management page
    • API: /api/pattern
  • DataCurve - Data curves

    • Fields: Id, CurveType, XValues, YValues, Description
    • UI: Dedicated curves management page
    • API: /api/datacurve

Design Decisions and Implementation Approach

Asset Popup Integration Strategy

Based on analysis of the existing EsriCustomPopup component, the following design decisions have been made:

Current System Analysis

  • Existing Popup: Shows static asset properties in table view and measured data in graph view
  • Toggle System: Uses GraphTableSwitch component with table/graph buttons
  • Entity Detection: Automatically detects asset type (Junction, Tank, Pipe, etc.)
  • SCADA Integration: Special handling for SCADA assets with tag selection
  • Docking Support: Can be docked to right side or floated as modal
Option Selected: "Edit Asset" Button with Dialog-Based Editing

Rationale:

  • Maintains existing UX patterns and user familiarity
  • Clean separation between viewing (dialog) and editing (dialog)
  • Preserves all current functionality (table/graph toggles, docking, SCADA)
  • Allows for comprehensive editing without cluttering the popup
  • Supports complex form hierarchies and validation

Implementation Details:

  1. Add "Edit Asset" button to existing popup header (next to table/graph toggles)
  2. Create AssetEditDialog component for comprehensive asset editing
  3. Tabbed interface within dialog for different form categories
  4. Smart form detection - only show relevant EPANET forms based on asset type
  5. Contextual help - indicate which parameters inherit from defaults
  6. Dialog navigation - ensure closing/saving returns to original table view

Asset Type to Form Mapping

Node-Related Assets:

  • Junction: Demand, Quality, Emitter
  • Tank: Quality, Source, TankMixing
  • Reservoir: Quality, Source

Link-Related Assets:

  • Pipe: Leakage, Status, LinkGeom
  • Pump: Status, LinkGeom
  • Valve: Status, LinkGeom

Dialog Design Specifications

Tab Structure:

  1. Basic Properties - Static asset data (existing popup functionality)
  2. Additional Parameters - Dynamic forms based on asset type
  3. Advanced Settings - Additional configuration (if applicable)

Form Organization:

  • Each EPANET parameter type gets its own form section
  • Forms are collapsible/expandable for better organization
  • Clear visual indicators for default vs scenario-specific values
  • Inline validation with helpful error messages

Dialog Navigation Flow:

  1. User clicks assetEsriCustomPopup opens with table/graph view
  2. User clicks "Edit Asset"AssetEditDialog opens with tabs
  3. User edits forms → Individual form components handle validation
  4. User saves changes → API calls update data, dialog closes
  5. Return to popup → Original EsriCustomPopup refreshes with updated data
  6. User cancels → Dialog closes, returns to original popup state

Implementation Strategy

1.1 Network Map Integration

  • Existing Popup Enhancement

    • Add "Edit Asset" button to existing EsriCustomPopup component
    • Integrate with current table/graph toggle system
    • Maintain existing docking/floating functionality
    • Preserve current SCADA and quality chart functionality
  • Asset Edit Modal System

    • Create AssetEditModal component for comprehensive asset editing
    • Implement tabbed interface for different form categories:
      • Basic Properties - Static asset data (existing functionality)
      • Additional Parameters - Dynamic forms based on asset type
      • Advanced Settings - Additional configuration options
    • Add smart form detection to show only relevant EPANET forms
    • Implement contextual help for default value inheritance
  • Form Integration Strategy

    • Extend existing EsriCustomPopup with edit functionality
    • Create modal-based editing system that doesn't disrupt current UX
    • Maintain separation between viewing (popup) and editing (modal)
    • Support both create and edit modes for EPANET parameters

1.2 AssetEditDialog Component

  • Dialog Structure

    • MUI Dialog with header, tabs, and footer
    • Responsive design for mobile and desktop
    • Loading states and error handling
    • Save/Cancel functionality with confirmation dialogs
  • Tab Implementation

    • Basic Properties Tab: Static asset data editing (existing popup functionality)
    • Additional Parameters Tab: Dynamic forms based on asset type
      • Junction: Demand, Quality, Emitter forms
      • Tank: Quality, Source, TankMixing forms
      • Reservoir: Quality, Source forms
      • Pipe: Leakage, Status, LinkGeom forms
      • Pump: Status, LinkGeom forms
      • Valve: Status, LinkGeom forms
    • Advanced Settings Tab: Additional configuration options
    • Tab switching with form state preservation
    • Visual indicators for unsaved changes
  • Smart Form Detection

    • Automatically determine relevant EPANET forms based on asset type
    • Show/hide form sections dynamically
    • Contextual help text for each parameter type
    • Default value inheritance indicators

1.3 Individual Form Components

  • DemandForm - Junction demand management
  • QualityForm - Node quality parameters
  • EmitterForm - Node emitter settings
  • SourceForm - Node source parameters
  • TankMixingForm - Tank mixing settings
  • LeakageForm - Pipe leakage parameters
  • StatusForm - Link status settings
  • LinkGeomForm - Link geometry editor

1.4 EsriCustomPopup Enhancement

  • Edit Asset Button

    • Add button to existing popup header
    • Position next to table/graph toggle buttons
    • Icon-based button with tooltip
    • Disabled state when no edit permissions
  • Modal Integration

    • Pass asset data and type to AssetEditModal
    • Handle modal open/close state
    • Refresh popup data after successful edits
    • Maintain popup state during editing

1.5 API Integration

  • Implement API service layer for each model
  • Add error handling and retry logic
  • Implement optimistic updates for better UX
  • Add caching for frequently accessed data

Component Architecture Updates

New Components Required

// Main dialog component
AssetEditDialog.jsx
├── BasicPropertiesTab.jsx
├── EpanetParametersTab.jsx
├── AdvancedSettingsTab.jsx
└── components/
├── FormSection.jsx
├── ParameterForm.jsx
└── DefaultValueIndicator.jsx

// Individual EPANET form components
forms/category1/
├── DemandForm.jsx
├── QualityForm.jsx
├── EmitterForm.jsx
├── SourceForm.jsx
├── TankMixingForm.jsx
├── LeakageForm.jsx
├── StatusForm.jsx
└── LinkGeomForm.jsx

// Enhanced existing component
EsriCustomPopup.jsx
└── + Edit Asset button integration

Tabbed Organization Clarification

Yes, separate tabs for each form type:

  • Basic Properties Tab: Static asset data (existing popup functionality)
  • Additional Parameters Tab: Contains multiple form sections based on asset type:
    • Junction: Demand form, Quality form, Emitter form
    • Tank: Quality form, Source form, TankMixing form
    • Reservoir: Quality form, Source form
    • Pipe: Leakage form, Status form, LinkGeom form
    • Pump: Status form, LinkGeom form
    • Valve: Status form, LinkGeom form
  • Advanced Settings Tab: Additional configuration (if applicable)

Form Organization Within Additional Parameters Tab:

  • Each EPANET parameter type gets its own collapsible form section
  • Forms are organized vertically within the tab
  • Clear visual separation between different parameter types
  • Smart detection shows only relevant forms for the asset type

Component Integration Flow

  1. User clicks assetEsriCustomPopup opens with table/graph view
  2. User clicks "Edit Asset"AssetEditDialog opens with tabs
  3. User edits forms → Individual form components handle validation
  4. User saves changes → API calls update data, dialog closes
  5. Return to popup → Original EsriCustomPopup refreshes with updated data
  6. User cancels → Dialog closes, returns to original popup state

Phase 2: Category 2 Forms (Network-Wide)

2.1 Scenario Integration

  • Scenario Form Enhancement

    • Add tabs for different parameter categories
    • Implement collapsible sections for each model type
    • Add validation for cross-field dependencies
  • Default Values Management

    • Implement "Edit Defaults" functionality
    • Add visual indicators for default vs scenario-specific values
    • Support inheritance from defaults to scenarios

2.2 Dedicated Management Pages

  • Patterns Management

    • List view with search and filter
    • Create/edit pattern form with multiplier editor
    • Pattern visualization (time series chart)
    • Import/export functionality
  • Curves Management

    • List view with curve type filtering
    • Create/edit curve form with coordinate editor
    • Curve visualization (XY plot)
    • Import/export functionality

2.3 Form Components

  • TimeParametersForm - Simulation time settings
  • OptionsForm - Simulation options
  • ReportForm - Report settings
  • EnergyForm - Energy calculation settings
  • ReactionForm - Chemical reaction parameters

Phase 3: Advanced Features

3.1 Default Values System

  • Default Management UI

    • Dedicated "Network Defaults" page
    • Clear visual distinction between defaults and scenario values
    • Bulk edit capabilities for defaults
    • Inheritance visualization
  • Scenario Inheritance

    • Show which parameters inherit from defaults
    • Allow selective override of default values
    • Bulk operations (inherit all, override all)

3.2 Validation and Constraints

  • Cross-Field Validation

    • Ensure logical consistency between related parameters
    • Real-time validation feedback
    • Constraint checking (e.g., time step relationships)
  • Business Rule Validation

    • EPANET-specific validation rules
    • Warning system for potential issues
    • Suggestion system for parameter optimization

3.3 User Experience Enhancements

  • Form State Management

    • Auto-save functionality
    • Undo/redo capabilities
    • Form state persistence across sessions
  • Visualization Integration

    • Parameter impact visualization
    • Real-time preview of changes
    • Parameter sensitivity analysis

Technical Implementation

Component Architecture

src/
├── components/
│ ├── forms/
│ │ ├── category1/ # Node/Link related forms
│ │ │ ├── DemandForm.jsx
│ │ │ ├── QualityForm.jsx
│ │ │ ├── EmitterForm.jsx
│ │ │ ├── SourceForm.jsx
│ │ │ ├── TankMixingForm.jsx
│ │ │ ├── LeakageForm.jsx
│ │ │ ├── StatusForm.jsx
│ │ │ └── LinkGeomForm.jsx
│ │ ├── category2/ # Network-wide forms
│ │ │ ├── TimeParametersForm.jsx
│ │ │ ├── OptionsForm.jsx
│ │ │ ├── ReportForm.jsx
│ │ │ ├── EnergyForm.jsx
│ │ │ └── ReactionForm.jsx
│ │ ├── management/ # Dedicated management pages
│ │ │ ├── PatternsPage.jsx
│ │ │ └── CurvesPage.jsx
│ │ └── common/ # Shared form components
│ │ ├── FormPopup.jsx
│ │ ├── FormDialog.jsx
│ │ ├── ValidationMessage.jsx
│ │ └── FormField.jsx
│ └── map/ # Map integration
│ ├── NetworkMap.jsx
│ ├── NodeClickHandler.jsx
│ └── LinkClickHandler.jsx
├── services/
│ ├── api/
│ │ ├── demandApi.js
│ │ ├── qualityApi.js
│ │ ├── emitterApi.js
│ │ ├── sourceApi.js
│ │ ├── tankMixingApi.js
│ │ ├── leakageApi.js
│ │ ├── statusApi.js
│ │ ├── linkGeomApi.js
│ │ ├── timeParametersApi.js
│ │ ├── optionsApi.js
│ │ ├── reportApi.js
│ │ ├── energyApi.js
│ │ ├── reactionApi.js
│ │ ├── patternApi.js
│ │ └── dataCurveApi.js
│ └── validation/
│ ├── epanetValidation.js
│ └── businessRules.js
├── hooks/
│ ├── useFormValidation.js
│ ├── useApiMutation.js
│ └── useFormState.js
└── utils/
├── formHelpers.js
├── apiHelpers.js
└── validationHelpers.js

State Management Strategy

Redux Toolkit Integration

  • Form State Slices

    • formsSlice - Global form state management
    • validationSlice - Validation state and errors
    • apiSlice - API call state and caching
  • Scenario State Management

    • scenarioSlice - Current scenario context
    • defaultsSlice - Default values management
    • inheritanceSlice - Default inheritance tracking

Context Providers

  • FormContext - Form-specific state and actions
  • ValidationContext - Validation rules and messages
  • ApiContext - API configuration and error handling

API Integration Patterns

Service Layer Pattern

// Example: demandApi.js
export const demandApi = {
// CRUD operations
getAll: (scenarioId) => api.get(`/api/demand?scenarioId=${scenarioId}`),
getById: (id) => api.get(`/api/demand/${id}`),
create: (data) => api.post('/api/demand', data),
update: (id, data) => api.put(`/api/demand/${id}`, data),
delete: (id) => api.delete(`/api/demand/${id}`),

// Specialized operations
getByJunction: (junctionId, scenarioId) =>
api.get(`/api/demand/junction/${junctionId}?scenarioId=${scenarioId}`),
getDefaults: () => api.get('/api/demand/defaults'),
updateDefaults: (data) => api.put('/api/demand/defaults', data)
};

React Query Integration

// Example: useDemandForm.js
export const useDemandForm = (junctionId, scenarioId) => {
const { data: demands, isLoading } = useQuery({
queryKey: ['demands', junctionId, scenarioId],
queryFn: () => demandApi.getByJunction(junctionId, scenarioId)
});

const createMutation = useMutation({
mutationFn: demandApi.create,
onSuccess: () => {
queryClient.invalidateQueries(['demands', junctionId, scenarioId]);
}
});

return { demands, isLoading, createMutation };
};

Form Validation Strategy

Client-Side Validation

  • Field-Level Validation

    • Required field validation
    • Type validation (number, string, array)
    • Range validation (min/max values)
    • Format validation (regex patterns)
  • Cross-Field Validation

    • Time parameter relationships
    • Unit consistency checks
    • Logical constraint validation

Server-Side Validation Integration

  • Error Handling

    • Display server validation errors
    • Field-specific error mapping
    • Retry mechanisms for transient errors
  • Business Rule Validation

    • EPANET-specific constraints
    • Parameter compatibility checks
    • Performance impact warnings

Default Values Management

Default vs Scenario Values

// DefaultValueManager utility functions
const DefaultValueManager = {
// Check if a parameter uses default value
isUsingDefault: (parameter, scenarioId) => {
// Implementation logic
},

// Get the effective value (default or scenario-specific)
getEffectiveValue: (parameter, scenarioId) => {
// Implementation logic
},

// Override default with scenario-specific value
overrideDefault: (parameter, value, scenarioId) => {
// Implementation logic
},

// Inherit from default (remove scenario override)
inheritFromDefault: (parameter, scenarioId) => {
// Implementation logic
}
};

UI Indicators

  • Visual Distinction

    • Different styling for default vs overridden values
    • Icons indicating inheritance status
    • Color coding for parameter sources
  • Bulk Operations

    • "Use Default" button for individual parameters
    • "Override All" / "Inherit All" for parameter groups
    • "Reset to Defaults" for entire scenario

Implementation Timeline

Phase 1: Foundation and AssetEditDialog (Weeks 1-2)

  • Create AssetEditDialog component with tab structure
  • Implement API service layer for all EPANET models
  • Set up validation framework with React Hook Form
  • Create base form components and shared utilities
  • Add "Edit Asset" button to EsriCustomPopup
  • Implement DemandForm for junction demand management
  • Implement QualityForm for node quality parameters
  • Implement EmitterForm for node emitter settings
  • Implement SourceForm for node source parameters
  • Implement TankMixingForm for tank mixing settings
  • Integrate node forms with AssetEditModal
  • Add smart form detection for node types
  • Implement LeakageForm for pipe leakage parameters
  • Implement StatusForm for link status settings
  • Implement LinkGeomForm for link geometry editor
  • Integrate link forms with AssetEditModal
  • Add smart form detection for link types
  • Test complete asset editing workflow

Phase 4: Category 2 Forms (Weeks 7-8)

  • Implement network-wide forms (TimeParameters, Options, Report, Energy, Reaction)
  • Integrate with scenario management
  • Add default values management
  • Implement inheritance system

Phase 5: Management Pages (Weeks 9-10)

  • Implement Patterns management page
  • Implement Curves management page
  • Add visualization components
  • Implement import/export functionality

Phase 6: Advanced Features (Weeks 11-12)

  • Add cross-field validation
  • Implement business rule validation
  • Add form state persistence
  • Implement bulk operations

Phase 7: Testing and Polish (Weeks 13-14)

  • Unit testing for all components
  • Integration testing with API
  • User acceptance testing
  • Performance optimization
  • Documentation and training materials

Success Criteria

Functional Requirements

  • All EPANET models have corresponding forms
  • Forms support both create and edit operations
  • Default values system works correctly
  • Scenario inheritance functions properly
  • Validation prevents invalid data entry

User Experience Requirements

  • Forms are intuitive and easy to use
  • Loading states provide clear feedback
  • Error messages are helpful and actionable
  • Forms integrate seamlessly with existing UI
  • Performance is acceptable for large datasets

Technical Requirements

  • Code is maintainable and well-documented
  • Components are reusable and modular
  • API integration is robust and error-resistant
  • State management is efficient and predictable
  • Testing coverage meets quality standards

Risk Mitigation

Technical Risks

  • API Integration Complexity: Implement comprehensive error handling and retry logic
  • Form State Management: Use proven patterns (React Hook Form, Redux Toolkit)
  • Performance with Large Datasets: Implement virtualization and pagination
  • Validation Complexity: Start with basic validation, add advanced rules incrementally

User Experience Risks

  • Form Complexity: Break complex forms into logical sections
  • Default Values Confusion: Implement clear visual indicators and help text
  • Data Loss: Implement auto-save and confirmation dialogs
  • Learning Curve: Provide comprehensive documentation and training

Business Risks

  • Scope Creep: Maintain clear boundaries between phases
  • Timeline Delays: Build in buffer time and prioritize core functionality
  • User Adoption: Involve users in design process and gather feedback early
  • Data Integrity: Implement comprehensive validation and backup strategies

Potential Upgrades (Future Iterations)

Multi-Asset Editing

Multi-Select Functionality

  • Selection Methods:
    • Rectangle Selection: Button in action bar enables "multi select" mode
      • Override click-drag functionality to draw selection rectangle instead of panning
      • Visual feedback for selection area
      • Clear selection mode when complete
    • Individual Selection: Shift+click or Ctrl+click to multi-select/deselect assets
      • Visual indicators for selected assets
      • Selection counter in UI
      • Clear all selection option

Multi-Asset Edit Dialog

  • Bulk Property Setting:
    • Open forms dialog for multiple selected assets
    • Option to set same value for all selected assets
    • Bulk validation and error handling
    • Progress indicators for bulk operations

Property Setting Strategies

  • All Same Value: Set identical values across all selected assets
    • Single input field affects all selected assets
    • Clear visual indication of bulk operation
    • Confirmation dialog before applying changes
  • Individual Values: Allow setting different values for each asset
    • Table/grid view with one row per selected asset
    • Individual input fields for each asset
    • Bulk operations (copy value to all, reset to defaults)
  • Hybrid Approach: Combination of bulk and individual editing
    • Set common values first, then adjust individual assets
    • "Apply to All" button for individual fields
    • "Reset to Common" button to revert individual changes

Technical Implementation Considerations

  • ESRI Integration: Leverage ESRI's selection capabilities
    • Use view.on("click") with selection logic
    • Implement custom selection graphics
    • Handle selection state management
  • Performance: Optimize for large numbers of selected assets
    • Virtual scrolling for large selection lists
    • Batch API calls for bulk operations
    • Progress indicators for long operations
  • User Experience: Clear feedback and error handling
    • Visual distinction between selected and unselected assets
    • Confirmation dialogs for destructive operations
    • Undo/redo capabilities for bulk changes

UI/UX Design Challenges

  • Reconciling Bulk vs Individual: How to handle mixed editing modes
    • Tab-based approach: "Bulk Edit" vs "Individual Edit" tabs
    • Toggle between modes with data preservation
    • Clear indication of current editing mode
  • Selection Management: Maintaining selection state across operations
    • Persist selection when opening/closing dialogs
    • Clear selection after successful operations
    • Selection history and navigation
  • Form Complexity: Managing multiple asset forms simultaneously
    • Collapsible sections for each asset
    • Summary view of common vs different values
    • Conflict resolution for incompatible values

Implementation Priority

  • Phase 1: Basic multi-select with rectangle and click selection
  • Phase 2: Bulk property setting with "all same value" functionality
  • Phase 3: Individual value editing for selected assets
  • Phase 4: Advanced features (hybrid editing, undo/redo, conflict resolution)

Key Design Decisions Summary

Asset Popup Integration

  • Selected Approach: "Edit Asset" button with dialog-based editing
  • Rationale: Maintains existing UX patterns while providing comprehensive editing capabilities
  • Implementation: Add button to existing EsriCustomPopup, create AssetEditDialog with tabs

Form Organization

  • Tab Structure: Basic Properties, Additional Parameters, Advanced Settings
  • Smart Detection: Show only relevant forms based on asset type
  • Visual Indicators: Clear distinction between default and scenario-specific values

Component Architecture

  • Dialog-Based: MUI Dialog for comprehensive editing
  • Tabbed Interface: Organized form categories within dialog
  • Individual Forms: Separate components for each EPANET parameter type
  • Integration: Seamless connection with existing popup system

Asset Type Mapping

  • Nodes: Junction (Demand, Quality, Emitter), Tank (Quality, Source, TankMixing), Reservoir (Quality, Source)
  • Links: Pipe (Leakage, Status, LinkGeom), Pump (Status, LinkGeom), Valve (Status, LinkGeom)

Conclusion

This implementation plan provides a structured approach to building comprehensive EPANET forms that integrate seamlessly with the existing frontend architecture. The "Edit Asset" button approach ensures that node/link-related forms are accessible from the network map while maintaining the familiar UX patterns users expect.

The modal-based editing system provides a clean separation between viewing (popup) and editing (modal), allowing for comprehensive form management without cluttering the existing interface. The phased implementation approach allows for iterative development and testing, reducing risk while ensuring that core functionality is delivered early.

The emphasis on user experience and technical quality will result in a robust, maintainable system that meets the needs of EPANET users while preserving the existing functionality they rely on.