Hangfire UI-Driven Schedule Management - Generic Structure Implementation

Author(s)

• Yeasa Mondal
• Dipak Mourya

Submission Date

05/03/2026

---

Version History

Version	Date	Changes	Author
1.0	2026-03-05	Generic Structure Approach	Yeasa Mondal, Dipak Mourya

---

Objective

This document outlines the implementation plan for enhancing the existing Hangfire schedule management system with a single, unified JSON structure for all schedule types. The feature standardizes schedule configuration to make it easier for UI development and consistent across all schedule modes.

---

Scope

This implementation includes:

• Single unified JSON structure for all schedule modes (interval, hourly, daily, weekly, yearly, custom)
• Generic field set: mode, minute, hour, dayOfWeek, dayOfMonth, month
• Mode-based validation with automatic cron generation

---

Related Features

• Feature 1: UI-driven schedule configuration management
• Feature 2: Generic schedule structure for all schedule types
• Feature 3: Trigger button for any scheduler manually

---

Technical Approach

Current State

• ✅ Hangfire configured in IntegrationService with recurring jobs
• ✅ Database table tblintegration_job_config exists with schedule_config JSONB and cron_schedule VARCHAR(100)
• ✅ Jobs execute based on cron_schedule from database

Target State

• 🎯 Single unified JSON structure for all schedule modes
• 🎯 Generic field set with mode-based validation
• 🎯 Automatic cron generation from generic structure
• 🎯 APIs to perform following tasks
• 🎯 Simplified UI development with consistent 6-field interface

Generic Schedule Structure

All schedule modes use this unified JSON format:

{
  "mode": "string (required)",
  "minute": "int or null",
  "hour": "int or null",
  "dayOfWeek": "int or null",
  "dayOfMonth": "int or null",
  "month": "int or null",
  "description": "string"
}

Field Usage Matrix

Mode	minute	hour	dayOfWeek	dayOfMonth	month
interval	✅ Value	❌ null	❌ null	❌ null	❌ null
hourly	✅ 0-59	❌ null	❌ null	❌ null	❌ null
daily	✅ 0-59	✅ 0-23	❌ null	❌ null	❌ null
weekly	✅ 0-59	✅ 0-23	✅ 0-6	❌ null	❌ null
yearly	✅ 0-59	✅ 0-23	❌ null	✅ 1-31	✅ 1-12
custom	✅ 0-59	✅ 0-23	⚠️ XOR	⚠️ XOR	⚠️ opt

---

Design Specifications

Below, you can see the provided UI design showcasing these changes.

• UI/UX Design:
  The first image displays the table listing all scheduled cron jobs. The second image shows the sidebar form that opens from the right side when the user clicks the View (eye) button to configure or view the cron job settings.

Click here to view the live demo page:
https://muddvision.lovable.app/

Development Tasks & Estimates

No	TaskName	Estimate (Hours)	Dependencies	Notes
1	Create GenericScheduleConfig DTO in ContractLibrary	2 hours	No dependency	Includes all mode validations
2	Implement ToCronExpression() for all 6 modes	3 hours	Task 1	Interval, hourly, daily, weekly, yearly, custom
3	Update UpsertJobConfigRequest/Response DTOs	1 hour	Task 1	Replace old config with generic
4	Update JobConfigDAL serialization logic	2 hours	Task 3	Include backward compatibility
5	Add GetDescription() helper method	1 hour	Task 1	Human-readable schedule descriptions
6	Create unit tests for all schedule modes	4 hours	Task 2	Test validation and cron generation
7	Create integration tests for API flow	3 hours	Task 4	End-to-end testing
8	Document frontend integration guidelines	1 hour	Task 3	UI form structure and field rules
9	Implement migration script for existing configs	2 hours	Task 4	Convert old format to generic
10	Code review and documentation	1 hour	All tasks	Final review and API docs
11	Set up the Scheduler Frequency Cron Job page and configure the route for the Admin scope	1 hour	No dependency	Frontend page and routing setup
12	Create a table to display cron job configuration details	2 hours	Task 11	Table UI for cron jobs
13	Integrate the API to retrieve cron job configuration and job details	1 hour	Task 12	API integration for table data
14	Create a mock API for the cron job configuration data used in the table	1 hour	Task 12	Mock data for development/testing
15	Develop a modal where users can update cron job settings based on the selected mode and handle all possible cases	6 hours	Task 12, Task 13	Modal UI and logic for all schedule modes
16	Test all scenarios thoroughly to ensure proper functionality	2 hours	Task 15	Frontend testing for all cases
Total		34 hours		~4 days

---

Testing & Validation

Unit Test Coverage

• ✅ Interval mode: minute-based and hour-based intervals with validation
• ✅ Hourly mode: minute validation (0-59)
• ✅ Daily mode: minute and hour validation
• ✅ Weekly mode: dayOfWeek validation (0-6, Sunday=0)
• ✅ Yearly mode: full date/time validation
• ✅ Custom mode: XOR validation for dayOfWeek/dayOfMonth

Integration Tests

• POST schedule with each mode and verify cron generation
• GET schedule and verify all fields match
• Update schedule and verify changes propagate
• Test backward compatibility with old format
• Verify job execution with generated cron expressions

Sample Test Scenarios

Interval Mode:

// Every 15 minutes
{"mode":"interval","minute":15,"hour":null,"dayOfWeek":null,"dayOfMonth":null,"month":null}
// Expected cron: */15 * * * *

Weekly Mode:

// Every Monday at 9:00 AM
{"mode":"weekly","minute":0,"hour":9,"dayOfWeek":1,"dayOfMonth":null,"month":null}
// Expected cron: 0 9 * * 1

Custom Mode:

// First day of every month at 9:00 AM
{"mode":"custom","minute":0,"hour":9,"dayOfWeek":null,"dayOfMonth":1,"month":null}
// Expected cron: 0 9 1 * *

---

Risks & Mitigations

Risk	Impact	Mitigation
Breaking changes for existing schedules	High	Implement backward compatibility layer in DAL
Invalid cron expressions generated	High	Comprehensive unit tests for all mode combinations
UI/API contract mismatch	Medium	Clear documentation and integration tests
Migration script edge cases	Medium	Thorough testing with production-like data
Performance impact of JSON validation	Low	Optimize validation logic, use caching if needed

---

Conclusion

The Generic Structure Implementation provides a unified, maintainable approach to Hangfire schedule management. By standardizing on a single JSON structure with mode-based validation, we achieve:

• Simplified Backend: Single DTO class instead of 6 derived classes
• Easier Frontend Development: Always work with same 6 fields
• Consistent Database Schema: No polymorphic type discriminators needed
• Better Testability: Predictable validation rules and test patterns

Status: Ready for Implementation
Document Version: 1.0
Expected Completion: ~4 days (34 hours)