Schedule Management

Endpoints for creating, managing, and monitoring flow execution schedules.

Schedule Data Types

FlowSchedule

interface FlowSchedule {
  id: string;
  name?: string | null;
  flowId: string;
  deviceId?: string | null;
  machineIds?: string[] | null;
  scheduleType: "RECURRING" | "ONE_TIME";
  cronExpression?: string | null;
  intervalMs?: number | null;
  intervalType?: "MINUTES" | "HOURS" | "DAYS" | "WEEKS" | "MONTHS" | null;
  intervalValue?: number | null;
  startDate: string; // ISO date string
  endDate?: string | null; // ISO date string
  timeOfDay?: string | null; // HH:mm format
  dayOfWeek?: number | null; // 0-6 (Sunday-Saturday)
  dayOfMonth?: number | null; // 1-31
  isActive: boolean;
  lastRunAt?: string | null; // ISO date string
  nextRunAt: string; // ISO date string
  createdAt: string; // ISO date string
  updatedAt: string; // ISO date string
}

CreateScheduleRequest

interface CreateScheduleRequest {
  name?: string;
  flowId: string;
  deviceId?: string;
  machineIds?: string[];
  scheduleType: "RECURRING" | "ONE_TIME";
  cronExpression?: string;
  intervalMs?: number;
  intervalType?: "MINUTES" | "HOURS" | "DAYS" | "WEEKS" | "MONTHS";
  intervalValue?: number;
  startDate: string; // ISO date string
  endDate?: string; // ISO date string
  timeOfDay?: string; // HH:mm format
  dayOfWeek?: number; // 0-6 (Sunday-Saturday)
  dayOfMonth?: number; // 1-31
  isActive?: boolean;
}

Schedule CRUD Operations

GET /api/schedules

Gets all schedules with optional filtering.

Query Parameters:

• isActive (optional): Filter by active status (true or false)
• flowId (optional): Filter by flow ID

Response:

{
  "success": true,
  "schedules": [
    {
      "id": "schedule-123",
      "name": "Daily Health Check",
      "flowId": "flow-456",
      "machineIds": ["machine-1", "machine-2"],
      "scheduleType": "RECURRING",
      "intervalValue": 1,
      "intervalType": "DAYS",
      "timeOfDay": "09:00",
      "startDate": "2024-01-01T00:00:00.000Z",
      "isActive": true,
      "nextRunAt": "2024-01-02T09:00:00.000Z",
      "lastRunAt": "2024-01-01T09:00:00.000Z",
      "createdAt": "2024-01-01T08:00:00.000Z",
      "updatedAt": "2024-01-01T08:00:00.000Z"
    }
  ],
  "count": 1,
  "message": "Schedules retrieved successfully"
}

Error Response:

{
  "success": false,
  "error": "Database connection failed",
  "code": "SCHEDULES_FETCH_ERROR",
  "message": "Failed to retrieve schedules"
}

GET /api/schedules/:id

Gets a specific schedule by ID.

Parameters:

• id: Schedule identifier

Response:

{
  "success": true,
  "schedule": {
    "id": "schedule-123",
    "name": "Daily Health Check",
    "flowId": "flow-456",
    "scheduleType": "RECURRING",
    "intervalValue": 1,
    "intervalType": "DAYS",
    "timeOfDay": "09:00",
    "startDate": "2024-01-01T00:00:00.000Z",
    "isActive": true,
    "nextRunAt": "2024-01-02T09:00:00.000Z",
    "createdAt": "2024-01-01T08:00:00.000Z",
    "updatedAt": "2024-01-01T08:00:00.000Z"
  },
  "message": "Schedule retrieved successfully"
}

Error Responses:

Not found (404):

{
  "success": false,
  "error": "Schedule not found",
  "code": "SCHEDULE_NOT_FOUND",
  "message": "Schedule with ID schedule-123 not found"
}

POST /api/schedules

Creates a new schedule.

Request Body:

{
  "name": "Daily Health Check",
  "flowId": "flow-456",
  "machineIds": ["machine-1"],
  "scheduleType": "RECURRING",
  "intervalType": "DAYS",
  "intervalValue": 1,
  "timeOfDay": "09:00",
  "startDate": "2024-01-01T00:00:00.000Z",
  "isActive": true
}

Response:

{
  "success": true,
  "schedule": {
    "id": "schedule-123",
    "name": "Daily Health Check",
    "flowId": "flow-456",
    "machineIds": ["machine-1"],
    "scheduleType": "RECURRING",
    "intervalType": "DAYS",
    "intervalValue": 1,
    "timeOfDay": "09:00",
    "startDate": "2024-01-01T00:00:00.000Z",
    "isActive": true,
    "nextRunAt": "2024-01-01T09:00:00.000Z",
    "createdAt": "2024-01-01T08:00:00.000Z",
    "updatedAt": "2024-01-01T08:00:00.000Z"
  },
  "message": "Schedule created successfully"
}

Error Responses:

Flow not found (404):

{
  "success": false,
  "error": "Flow not found",
  "code": "FLOW_NOT_FOUND",
  "message": "Flow with ID flow-456 not found"
}

Validation error (400):

{
  "success": false,
  "error": "Invalid schedule parameters",
  "code": "VALIDATION_ERROR",
  "message": "startDate is required for schedule creation",
  "details": {
    "field": "startDate",
    "value": null,
    "message": "startDate cannot be null"
  }
}

PUT /api/schedules/:id

Updates an existing schedule.

Parameters:

• id: Schedule identifier

Request Body:

{
  "name": "Updated Daily Health Check",
  "timeOfDay": "10:00",
  "isActive": false
}

Response:

{
  "success": true,
  "schedule": {
    "id": "schedule-123",
    "name": "Updated Daily Health Check",
    "flowId": "flow-456",
    "scheduleType": "RECURRING",
    "intervalType": "DAYS",
    "intervalValue": 1,
    "timeOfDay": "10:00",
    "startDate": "2024-01-01T00:00:00.000Z",
    "isActive": false,
    "nextRunAt": "2024-01-02T10:00:00.000Z",
    "createdAt": "2024-01-01T08:00:00.000Z",
    "updatedAt": "2024-01-01T09:00:00.000Z"
  },
  "message": "Schedule updated successfully"
}

DELETE /api/schedules/:id

Deletes a schedule.

Parameters:

• id: Schedule identifier

Response:

{
  "success": true,
  "message": "Schedule deleted successfully"
}

Schedule Control Operations

POST /api/schedules/:id/pause

Pauses a schedule.

Parameters:

• id: Schedule identifier

Response:

{
  "success": true,
  "schedule": {
    "id": "schedule-123",
    "name": "Daily Health Check",
    "isActive": false,
    "updatedAt": "2024-01-01T09:00:00.000Z"
  },
  "message": "Schedule paused successfully"
}

POST /api/schedules/:id/resume

Resumes a paused schedule.

Parameters:

• id: Schedule identifier

Response:

{
  "success": true,
  "schedule": {
    "id": "schedule-123",
    "name": "Daily Health Check",
    "isActive": true,
    "nextRunAt": "2024-01-02T09:00:00.000Z",
    "updatedAt": "2024-01-01T09:30:00.000Z"
  },
  "message": "Schedule resumed successfully"
}

Calendar and Upcoming Schedules

GET /api/schedules/upcoming

Gets upcoming schedules for calendar view within a date range.

Query Parameters:

• startDate: Start date in ISO format (required)
• endDate: End date in ISO format (required)

Response:

{
  "success": true,
  "schedules": [
    {
      "id": "schedule-123",
      "name": "Daily Health Check",
      "flowId": "flow-456",
      "scheduleType": "RECURRING",
      "nextRunAt": "2024-01-02T09:00:00.000Z",
      "isActive": true
    }
  ],
  "count": 1,
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-01-31T23:59:59.999Z",
  "message": "Upcoming schedules retrieved successfully"
}

GET /api/schedules/calendar

Gets calendar view data for schedules within a date range (alias for upcoming).

Query Parameters:

• startDate: Start date in ISO format (required)
• endDate: End date in ISO format (required)

Response: Same as /api/schedules/upcoming

Usage Examples

Create a Daily Schedule

curl -X POST http://localhost:3000/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "flowId": "flow-backup-001",
    "scheduleType": "RECURRING",
    "intervalType": "DAYS",
    "intervalValue": 1,
    "timeOfDay": "02:00",
    "startDate": "2024-01-01T00:00:00.000Z"
  }'

Create a Weekly Schedule

curl -X POST http://localhost:3000/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Report",
    "flowId": "flow-report-001",
    "scheduleType": "RECURRING",
    "dayOfWeek": 1,
    "timeOfDay": "09:00",
    "startDate": "2024-01-01T00:00:00.000Z"
  }'

Get Active Schedules

curl -X GET "http://localhost:3000/api/schedules?isActive=true"

Pause a Schedule

curl -X POST http://localhost:3000/api/schedules/schedule-123/pause

Get Upcoming Schedules for Calendar

curl -X GET "http://localhost:3000/api/schedules/upcoming?startDate=2024-01-01T00:00:00.000Z&endDate=2024-01-31T23:59:59.999Z"

Scheduling Logic

Next Run Calculation

The system automatically calculates the next execution time based on:

• One-time schedules: Execute once at startDate + optional timeOfDay
• Recurring schedules: Use various strategies:
  • Interval-based: Add intervalMs to last execution time
  • Time-of-day: Schedule at specific time, advance by interval days
  • Day-of-week: Find next occurrence of specified weekday
  • Day-of-month: Schedule on specified day of month
  • Cron expressions: Use cron parsing for complex schedules

Machine Assignment

• Schedules can be assigned to specific machines via machineIds array
• Empty machineIds means all machines can execute the schedule
• Scheduler service only executes schedules on assigned machines
• Load balancing distributes executions across available machines

Atomic Execution

• Uses database-level atomic operations to prevent duplicate executions
• Multiple scheduler instances won't execute the same schedule simultaneously
• Failed executions automatically reset next run time for retry

Error Codes

Code	Description
SCHEDULES_FETCH_ERROR	Failed to retrieve schedules
SCHEDULE_NOT_FOUND	Schedule with specified ID not found
FLOW_NOT_FOUND	Referenced flow does not exist
VALIDATION_ERROR	Invalid schedule parameters
SCHEDULE_UPDATE_ERROR	Failed to update schedule
SCHEDULE_DELETE_ERROR	Failed to delete schedule
SCHEDULE_PAUSE_ERROR	Failed to pause schedule
SCHEDULE_RESUME_ERROR	Failed to resume schedule
UPCOMING_SCHEDULES_ERROR	Failed to get upcoming schedules

Integration Notes

• Schedules are automatically managed by the background scheduler service
• Next run times are recalculated on every schedule update
• One-time schedules are automatically deactivated after execution
• Machine assignment filters ensure schedules only run on appropriate machines
• Execution results are tracked in flow execution history
• Failed executions are automatically retried with recalculated next run times