Skip to main content

​
Scheduling

BindAI’s workflow package includes basic scheduling primitives, but it does not provide a complete, automatically running workflow scheduling service. The current implementation includes a WorkflowScheduler that stores schedules in memory, identifies enabled schedules that are due, and can advance a schedule’s next-run time by a configured interval. It does not automatically poll for due schedules, execute the associated workflows, or persist schedules across process restarts. Applications that need automatic time-based execution must provide the orchestration around these primitives or use an external scheduling system.

​
Current Behavior

The workflow package provides a WorkflowScheduler with methods for managing an in-memory list of schedules. At a high level, the primitives support this sequence:
The scheduler does not automatically start a background loop to perform these steps. An application must call the relevant methods and decide what to do with the schedules returned as due. In particular, identifying a schedule as due is not the same as executing its workflow.

​
Available Scheduling Primitives

The current implementation provides the following basic capabilities:
  • Add a schedule to an in-memory scheduler.
  • Identify schedules that are enabled and whose next_run time is less than or equal to the current UTC time.
  • Advance a schedule’s next_run timestamp by its configured interval when an interval is present.
  • Represent whether a schedule is enabled.
These are low-level primitives, not a complete scheduling service.

​
WorkflowSchedule

A WorkflowSchedule represents scheduling information for a workflow. The current schedule model includes these fields: The scheduler compares next_run with the current UTC time when checking whether a schedule is due. Use timezone-aware datetimes, preferably UTC, when working with schedule timestamps. Do not assume the primitives provide timezone conversion or daylight-saving-time handling.

​
WorkflowScheduler

The WorkflowScheduler manages an in-memory list of schedules. Its current methods provide these operations: The scheduler does not itself run workflows. An application is responsible for using the returned schedules to trigger the appropriate workflow executions.

​
Checking Due Schedules

The due() method checks the schedules currently held by the scheduler. Conceptually, a schedule is due when both conditions are true:
The method returns schedules that satisfy those conditions. It does not automatically mark them as completed, execute them, or advance their next-run timestamps. The caller must decide how to process the returned schedules and whether to reschedule them. Because the scheduler is in-memory, only schedules added to that scheduler instance are considered.

​
Rescheduling

The reschedule(schedule) method advances a schedule’s next_run timestamp by its configured interval when interval_seconds is truthy. Conceptually:
This is an interval-based timestamp update. It does not create a recurring background job or guarantee that the associated workflow will execute. The caller is responsible for deciding when to invoke reschedule() and how to handle execution failures. If a schedule has no truthy interval_seconds, the method does not advance its next-run time.

​
Explicit Workflow Execution

Workflow scheduling primitives are separate from workflow execution. The scheduler does not automatically invoke the workflow executor when a schedule becomes due. An application must connect due schedules to the appropriate workflow execution mechanism. The overall application-managed flow is therefore:
The scheduling package supplies part of this process, not the entire lifecycle.

​
Recurring Workflows

The interval_seconds field and reschedule() method provide a basic primitive for advancing a schedule by a recurring interval. They do not implement a recurring execution service. For recurring workflows, the application must arrange to:
  1. Check schedules periodically.
  2. Identify due schedules.
  3. Start the corresponding workflows.
  4. Handle execution results and failures.
  5. Decide when and how to advance each schedule.
  6. Continue checking schedules while the application is running.
Without that orchestration, schedules do not trigger workflows automatically.

​
One-Time Scheduled Workflows

The scheduler can represent a schedule with a next_run timestamp and no recurring interval. However, the current implementation does not provide a complete one-time scheduling lifecycle. In particular, it does not automatically execute a workflow and remove or disable the schedule after execution. Applications implementing one-time scheduling must manage execution and post-execution schedule state themselves.

​
Cron and Calendar Schedules

The current scheduling primitives do not provide a cron-expression parser or a calendar-based scheduling engine. They do not natively implement scheduling rules such as:
  • Run every weekday at a specified local time.
  • Run on the first day of every month.
  • Run at a specified time in a named timezone.
  • Apply daylight-saving-time transitions to local schedules.
These features require additional scheduling logic or an external scheduling service. An interval expressed in seconds should not be treated as equivalent to a local-time or calendar-based recurrence.

​
Time Zones

The current scheduler compares schedule timestamps against the current UTC time. It does not provide a separate timezone-aware scheduling API for local-time rules, nor does it implement daylight-saving-time handling. Applications should use consistent, timezone-aware timestamps and implement any required conversion from local scheduling rules to UTC. For schedules based on a named timezone or local calendar, additional logic is needed to determine the correct next-run time.

​
Missed Schedules

The current scheduler does not implement a missed-run recovery policy. The due() method identifies enabled schedules whose next_run time has passed. It does not decide whether a missed schedule should be executed once, executed repeatedly to catch up, skipped, or delayed. Applications must define and implement the desired behavior, including what should happen after downtime.

​
Overlapping Scheduled Runs

The current scheduler does not manage overlapping workflow executions. It does not provide built-in policies to:
  • Allow multiple runs of the same workflow to overlap.
  • Prevent a new run while a previous run is active.
  • Queue a due run until the previous run finishes.
  • Skip a run when another execution is already in progress.
Applications that require these policies must coordinate schedule processing with their workflow execution infrastructure.

​
Persistence and Restart Behavior

Schedules are stored in the scheduler’s in-memory list. The current WorkflowScheduler does not persist schedules to a database or another durable store. Schedules held only in memory are not preserved automatically across process restarts. Applications that require durable scheduling must implement schedule persistence and restore schedules when the application starts. Schedule persistence is separate from workflow execution persistence and history.

​
Scheduling and Workflow Control Flow

Scheduling determines when an application should initiate a workflow. Workflow control-flow features determine what happens after execution begins. BindAI’s workflow package provides control-flow capabilities such as:
  • Conditions
  • Loops
  • Parallel execution
  • Join synchronization
  • Human Tasks
These features do not automatically create time-based triggers. For example, a loop repeats logic within a workflow execution, while a schedule can be used by an application to decide when to initiate another execution.

​
Current Implementation Boundaries

The current scheduling implementation:
  • Stores schedules in memory.
  • Supports enabled/disabled state on schedule records.
  • Checks whether enabled schedules are due.
  • Uses UTC time when checking next_run.
  • Can advance next_run by a configured interval.
The current implementation does not:
  • Poll for due schedules automatically.
  • Execute workflows automatically when schedules become due.
  • Persist schedules across process restarts.
  • Provide a complete recurring execution service.
  • Provide a cron-expression or calendar scheduling engine.
  • Provide timezone conversion or daylight-saving-time policies.
  • Define missed-schedule recovery behavior.
  • Manage overlapping workflow runs.
  • Provide a complete scheduling management API or Studio scheduling interface.

​
Best Practices

  • Treat WorkflowScheduler as a set of scheduling primitives, not a background service.
  • Use consistent, timezone-aware schedule timestamps.
  • Keep schedule checking and workflow execution as explicit application responsibilities.
  • Define how schedules should be advanced after success or failure.
  • Decide how missed schedules should be handled.
  • Implement overlap protection if multiple runs of the same workflow must not execute concurrently.
  • Persist schedules externally if they must survive process restarts.
  • Use an external scheduling service when you need cron rules, calendar schedules, or managed background execution.

​
Documentation Scope

This page documents the scheduling primitives that currently exist without implying that a complete scheduler service is available. It intentionally does not describe unimplemented behavior such as automatic background polling, durable schedule storage, cron execution, or automatic workflow triggering as built-in BindAI functionality. Examples of classes or methods should be verified against the current package API before being used in application code.

​
Related Templates

Scheduling is conceptually related to:
  • 08.3 workflow-loop.md
  • 08.6 workflow-retry.md
  • 08.7 workflow-timeout.md
Loops, retries, and timeouts affect workflow execution. Scheduling primitives help an application determine when a workflow should be started.

​
Summary

BindAI’s workflow package includes basic scheduling primitives through WorkflowScheduler and WorkflowSchedule. The scheduler can hold schedules in memory, identify enabled schedules that are due, and advance next_run by a configured interval. It does not automatically poll for schedules, start workflows, persist schedules, or implement complete recurring, cron-based, or timezone-aware scheduling. Applications that require automatic time-based workflow execution must supply the orchestration and persistence needed for their scheduling requirements, or use an external scheduling service.