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
Category 1: Node and Link Related Fields
These models are directly tied to specific network elements (nodes/links) and will be editable from the 2D network map via onclick popup events.
Node-Related Models
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
Link-Related Models
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
GraphTableSwitchcomponent 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
Recommended Integration Approach
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:
- Add "Edit Asset" button to existing popup header (next to table/graph toggles)
- Create
AssetEditDialogcomponent for comprehensive asset editing - Tabbed interface within dialog for different form categories
- Smart form detection - only show relevant EPANET forms based on asset type
- Contextual help - indicate which parameters inherit from defaults
- 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:
- Basic Properties - Static asset data (existing popup functionality)
- Additional Parameters - Dynamic forms based on asset type
- 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:
- User clicks asset →
EsriCustomPopupopens with table/graph view - User clicks "Edit Asset" →
AssetEditDialogopens with tabs - User edits forms → Individual form components handle validation
- User saves changes → API calls update data, dialog closes
- Return to popup → Original
EsriCustomPopuprefreshes with updated data - User cancels → Dialog closes, returns to original popup state
Implementation Strategy
Phase 1: Category 1 Forms (Node/Link Related)
1.1 Network Map Integration
Existing Popup Enhancement
- Add "Edit Asset" button to existing
EsriCustomPopupcomponent - Integrate with current table/graph toggle system
- Maintain existing docking/floating functionality
- Preserve current SCADA and quality chart functionality
- Add "Edit Asset" button to existing
Asset Edit Modal System
- Create
AssetEditModalcomponent 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
- Create
Form Integration Strategy
- Extend existing
EsriCustomPopupwith 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
- Extend existing
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
- User clicks asset →
EsriCustomPopupopens with table/graph view - User clicks "Edit Asset" →
AssetEditDialogopens with tabs - User edits forms → Individual form components handle validation
- User saves changes → API calls update data, dialog closes
- Return to popup → Original
EsriCustomPopuprefreshes with updated data - 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 managementvalidationSlice- Validation state and errorsapiSlice- API call state and caching
Scenario State Management
scenarioSlice- Current scenario contextdefaultsSlice- Default values managementinheritanceSlice- 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
AssetEditDialogcomponent 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
Phase 2: Node-Related Forms (Weeks 3-4)
- Implement
DemandFormfor junction demand management - Implement
QualityFormfor node quality parameters - Implement
EmitterFormfor node emitter settings - Implement
SourceFormfor node source parameters - Implement
TankMixingFormfor tank mixing settings - Integrate node forms with
AssetEditModal - Add smart form detection for node types
Phase 3: Link-Related Forms (Weeks 5-6)
- Implement
LeakageFormfor pipe leakage parameters - Implement
StatusFormfor link status settings - Implement
LinkGeomFormfor 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
- Rectangle Selection: Button in action bar enables "multi select" mode
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
- Use
- 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, createAssetEditDialogwith 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.