Schedules as automations

[Flix6x]

Description

Automations can now compute schedules on a recurring basis, alongside forecasts. The automation
still only decides when work is due and queues it; the existing scheduling machinery computes the
schedule and records it.

Parameters are a trigger message. A schedule automation stores what the
[POST] /assets/(id)/schedules/trigger endpoint accepts, without the asset id, validated against
AssetTriggerSchema when the automation is created. Use the canonical API field names, including
flex-model, flex-context and force-new-job-creation.

The schedule moves with the clock. Omit start and each run schedules from its own run time,
floored to the message's resolution when given and otherwise to the minute. A fixed start is
accepted, but then every run computes the same period, so the CLI warns when creating such an
automation.

Minimal triggers inherit stored flex config. The flex-model and flex-context can live on the
asset tree instead of in the trigger message, so duration: "PT12H" on its own is a complete
automation for an asset that already describes its own flexibility. The scheduler resolves the rest
the same way it does for a triggered schedule.

Task names. An automation's type now names the task, like the rest of the codebase does: forecasting and scheduling, rather than forecasts and schedules. The type is therefore also the name of the queue the jobs go to. A migration renames the values of existing rows.

No data generator. A forecast automation points at a data source holding its forecaster
configuration; a schedule automation has nothing equivalent, so generator_id is now nullable and a
database constraint requires it only for forecasts.

Provenance. Scheduling jobs record how they came about in the same way forecasting jobs do:
{"origin": "automation", "automation_id": <id>}, so a scheduled job queued by an automation is
distinguishable from one triggered through the API or the CLI. Job statistics count scheduling jobs
for schedule automations, including the per-device jobs of a sequential schedule.

CLI. flexmeasures add automation --type scheduling takes the trigger message through
--parameters. Forecaster options are refused for schedule automations — the check asks which
options were actually given on the command line, rather than comparing their values against their
defaults, so naming the default forecaster is refused too instead of passing silently. A
--parameters or --config file that is not a mapping is reported as such rather than failing
obscurely later.

UI. The Schedules tab on an asset's Automations page is now populated, with one listing per
automation type. Reports remain a disabled placeholder until #2297.

• Added changelog item in documentation/changelog.rst

Look & Feel

The Schedules tab is now populated, with its own listing alongside the forecasts one. Here an hourly
schedule automation on a battery, recurring in Europe/Amsterdam. Reports remains a placeholder until
#2297:

How to test

See the manual test walkthrough in the PR comments.

pytest \
  flexmeasures/cli/tests/test_automations.py \
  flexmeasures/data/tests/test_automations_fresh_db.py \
  flexmeasures/data/tests/test_automation_scheduling_fresh_db.py \
  flexmeasures/api/v3_0/tests/test_automations_api.py \
  flexmeasures/api/v3_0/tests/test_automations_api_fresh_db.py \
  flexmeasures/ui/tests/test_asset_crud.py

Further improvements

• Which sensors a schedule automation reads and writes is worked out by resolving the flex config
  and then looking for the fields that name where results go. That agrees with the scheduler's own
  resolution for the shapes that matter — a device's sensor, and its consumption and
  production outputs — and errs towards reporting more rather than fewer, which is the safe
  direction once the same resolution guards who may create an automation (CRUD for automations in the API and UI #2294). Checking outputs
  against what a scheduler actually returns at run time is tracked in Check the sensors a scheduler actually writes to, instead of predicting them when an automation is created #2421.
• Catch-up policy is defined for forecasts. What it should mean for a schedule — whether a missed
  occurrence is worth scheduling at all once its window has passed — is still open.

Related items

Closes #2370. Part of the automations story #2334. Stacked on #2290, followed by #2294.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or another incompatible license.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34350412 | 📁 Comparing 12903db against latest (60cfda8)

  🔍 Preview build  

139 files changed · + 24 added · ± 115 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html
• _autodoc/GROUP.html
• _autodoc/INFLEXIBLE_CONSUMPTION.html
• _autodoc/INFLEXIBLE_PRODUCTION.html
• _autodoc/OPERATION_MODES.html
• _autosummary/flexmeasures.api.common.rate_limiting.html
• _autosummary/flexmeasures.api.v3_0.utils.html
• _autosummary/flexmeasures.data.models.automations.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• and 14 more...

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/COMMITMENTS.html
• _autodoc/CONSUMPTION_CAPACITY.html
• _autodoc/INFLEXIBLE_DEVICE_SENSORS.html
• and 105 more...

[BelhsanHmida]

Manual test walkthrough

Everything below was run against a development database on this branch. It assumes the forecast
roundtrip from #2290 already makes sense; this covers only what schedules add.

Pick an asset that describes its own flexibility, so a minimal trigger has something to work with —
a battery with a stored flex-model is ideal. The examples use asset 25, a charge point whose
flex-model is {soc-max: 56 kWh, soc-min: 13.02 kWh, power-capacity: 5.75 kW}.

flexmeasures jobs run-worker --name schedules-demo --queue scheduling

1. A minimal trigger is enough

The parameters of a schedule automation are a trigger message: what
[POST] /assets/(id)/schedules/trigger accepts, without the asset id. When the asset already
carries its flex config, the message can be one line.

echo 'duration: "PT12H"' > trigger-message.yml

flexmeasures add automation \
  --asset 25 \
  --name "Hourly schedules" \
  --cron "0 * * * *" \
  --timezone Europe/Amsterdam \
  --type schedules \
  --inactive \
  --parameters trigger-message.yml
# → Successfully created inactive automation 'Hourly schedules' (ID: N) to compute schedules
#   for asset 25, recurring per cron string '0 * * * *' in timezone 'Europe/Amsterdam'.

Note it needs no forecaster and no data source: generator_id is null for schedule automations, and
a database constraint requires a generator only for forecasts.

2. The schedule starts when the run starts

Omitting start is the point of a recurring schedule. Each run fills it in from its own run time,
floored to the message's resolution if given and otherwise to the minute, so the stored
{"duration": "PT12H"} becomes, at run time:

{'duration': 'PT12H', 'id': 25, 'start': '2026-08-12T22:53:00+00:00'}

A fixed start is accepted, but then every run computes the same window, so the CLI says so:

echo 'start: "2025-11-16T00:00:00+01:00"' >  trigger-fixed.yml
echo 'duration: "PT12H"'                  >> trigger-fixed.yml

flexmeasures add automation --asset 25 --name "Fixed window" --type schedules \
  --inactive --parameters trigger-fixed.yml
# → Warning: the schedule 'start' is fixed, so each run will compute the same period.
#   Omit 'start' to schedule from the run time instead.
# → Successfully created inactive automation 'Fixed window' (ID: M) ...

3. Forecaster options do not apply

A schedule automation is not computed by a forecaster, so anything configuring one is refused and
names the option at fault:

flexmeasures add automation --asset 25 --name "Wrong options" --type schedules \
  --parameters trigger-message.yml --forecaster SomeOtherForecaster
# → Error: --forecaster cannot be combined with --type schedules: a schedule automation is not
#   computed by a forecaster.

flexmeasures add automation --asset 25 --name "Wrong options" --type schedules \
  --parameters trigger-message.yml --train-period P7D
# → Error: --train-period cannot be combined with --type schedules: ...

Naming the default forecaster is refused as well, since it was still given:

flexmeasures add automation --asset 25 --name "Wrong options" --type schedules \
  --parameters trigger-message.yml --forecaster TrainPredictPipeline
# → Error: --forecaster cannot be combined with --type schedules: ...

The check asks which options were passed rather than comparing their values against their defaults,
so an option cannot slip through by happening to match the default.

A parameters file that is not a mapping is reported plainly rather than failing later:

echo 'just a string, not a mapping' > bad.yml
flexmeasures add automation --asset 25 --name "Bad yaml" --type schedules --parameters bad.yml
# → Error: The --parameters file must contain a YAML or JSON object at the top level.

4. Run it, and see a scheduling job

flexmeasures edit automation --id N --cron "* * * * *" --activate
flexmeasures jobs run-automations
# → Automation N ('Hourly schedules') queued 1 scheduling job(s) for asset 25.

The job lands on the scheduling queue, not the forecasting one, and carries the same provenance
a forecast automation gives its jobs:

queued on queue : scheduling
job trigger meta: {'origin': 'automation', 'automation_id': N}
asset_or_sensor : {'id': 25, 'class': 'Asset'}

For a sequential schedule the automation queues one job per device plus the wrap-up job, and the job
statistics on the automations page count all of them.

5. The Schedules tab

/assets/25/automations

The Schedules tab is now populated, alongside Forecasts. Each type has its own listing, and the
tables resize correctly when switching between tabs. Reports stays disabled until #2297.

6. Clean up

flexmeasures edit automation --id N --deactivate
flexmeasures delete automation --id N --force

[Flix6x]

Notes to self (will pick them up now).

[Flix6x]

Did we consider the alternative, which I guess would be making the Scheduler a DataGenerator? I'd like to discuss implications on this comment thread before making a decision.

[Flix6x]

Discussed, nothing changed here yet — here is the analysis, so we can decide before I touch anything.

Where we stand today. Scheduler is almost a DataGenerator already: schedulers are registered
in app.data_generators["scheduler"] (app.py:177), and DataSource.data_generator accepts type
"scheduler" and even says "Only the classes Scheduler, Forecaster and Reporters are DataGenerator's"
(data_sources.py:437). But Scheduler does not subclass it — only Reporter and Forecaster do.
So the alternative is not a small change: it means a _config_schema/_parameters_schema split for
schedulers, _clean_parameters, and compute conforming to the base class.

Would it remove the nullable column? I do not think so, and that is the crux.

For a forecast automation, the data source is the choice the user made up front: this forecaster,
with this configuration. --source even lets you point at an existing one. Storing a pointer to it
is natural, and the config is static by construction — changing it yields a different source.

A schedule has no equivalent up-front choice:

• The scheduler class is resolved per run, from the asset, by find_scheduler_class(asset_or_sensor),
  or from a scheduler spec inside the flex config. The user never names it when creating the automation.
• Its data source is created by the scheduling job, with the class version current at run time. Pinning
  a generator source when the automation is created would freeze the class and its version, so an
  automation would keep scheduling with an old scheduler version after an upgrade, unlike the same
  trigger message sent through the API.
• The config/parameters split does not map either. A trigger message is per-run input (flex-model,
  flex-context, duration), not static config. Treating it as config would fragment sources: a
  soc-at-start that differs per run would spawn a new data source each time.

So even with Scheduler as a DataGenerator, a schedule automation would have nothing to point at
when it is created, and generator_id would still have to be nullable — the check constraint
(type != 'forecasting' OR generator_id IS NOT NULL) is exactly the shape of that asymmetry.

Recommendation. Keep the nullable column here, and make Scheduler a DataGenerator on its own
merits, in its own PR — it changes how every scheduler data source is created, which is a scheduling
change rather than an automations one, and it would not be blocked by anything in this PR. Happy to
open an issue for it (or to do it first, if you would rather have that order).

[Flix6x]

Discussing this in this comment thread instead.

I am interested to learn more about potential resolutions to these complexities.

Issue 1

The scheduler class is resolved per run, from the asset, by find_scheduler_class(asset_or_sensor),
or from a scheduler spec inside the flex config. The user never names it when creating the automation.

There is an existing mechanism for API users to pick the scheduling model, though.

Issue 2

Its data source is created by the scheduling job, with the class version current at run time. Pinning
a generator source when the automation is created would freeze the class and its version, so an
automation would keep scheduling with an old scheduler version after an upgrade, unlike the same
trigger message sent through the API.

Does it have to? Can't the automation create a new source when the code is updated to a new version of e.g. the StorageScheduler (if it is not pinned to a specific --source)?

Issue 3

The config/parameters split does not map either. A trigger message is per-run input (flex-model,
flex-context, duration), not static config. Treating it as config would fragment sources: a
soc-at-start that differs per run would spawn a new data source each time.

I imagine it should still be possible to:

1. create a scheduling automation in case the flex-model and flex-context only contain sensor references (or fixed values, but no time series specs; and no fields like soc-at-start which are kind of slated for deprecation anyway), so they do form a static config. The duration should be part of the automation instead of the data source.
2. or just use the Scheduler.source.id as the generator ID. I still don't see why it would need to be nullable?

[Flix6x]

You are right on 1 and 2; my framing there was too absolute. Issue 3 is where I think the real
question sits, and it turns out to be sharper than I put it.

Issue 1 — conceded

find_scheduler_class reads custom-scheduler off the asset or sensor attributes
(data/services/scheduling.py:969), so the class is resolvable when the automation is created, not
only per run. My "the user never names it" was wrong.

One caveat that survives: it is an asset attribute, so it can be changed after the automation
exists. Resolving it once at creation time either freezes it (the automation keeps using the class
the asset named back then) or has to be re-resolved per run. Which is really your issue 2.

Issue 2 — conceded, at a price worth naming

Yes, the runner could re-resolve and write a new generator_id when __version__ changes. What
that costs is the column's meaning. For a forecast automation, generator_id is user intent: the
forecaster and config chosen at creation, optionally reused via --source, and documented as
required for as long as the automation exists (the source cannot be deleted). If the runner rewrites
it for schedules, the same column is user intent in one row and runner-maintained cache in the next
— including for that deletion rule, where the "protected" source would be one nobody chose.

That is a design cost, not an impossibility. It is a fair trade if it buys a meaningful column.
Which brings me to 3, where I no longer think it does — unless we do your 3.1.

Issue 3 — a scheduler data source carries no config today

This is the bit I under-stated. A scheduler's source is not built like a DataGenerator's:

• DataGenerator.data_source (data/models/data_sources.py:244) puts the dumped config into
  attributes["data_generator"]["config"], so the config is part of the source's identity — a
  different config is a different source. That is what makes generator_id meaningful for forecasts.
• Scheduler.get_data_source_info (data/models/planning/__init__.py:222) returns only
  model (class name), version (__version__) and name (__author__). The call site,
  make_schedule (data/services/scheduling.py:837 and 884), looks that up with get_data_source
  and never passes attributes.

So today, every StorageScheduler schedule in an instance shares one data source per version,
whatever its flex-model. That makes your 3.2 possible but hollow: Scheduler.source.id would give us
a non-null column that records the algorithm and its version, and nothing at all about what the
automation actually computes. Non-nullable, but not the same column as for forecasts.

Your 3.1 is the version I would defend, precisely because it fixes that: if a schedule automation
requires a flex-model and flex-context free of per-run values (sensor references and fixed
quantities, no time series specs, no soc-at-start), then the flex config genuinely is static
config, and it belongs in the source's config attribute like any other DataGenerator. Timing
(start, duration, resolution) stays on the automation, which matches _clean_parameters, whose
fields_to_remove is already ["start", "end", "resolution", "belief_time"].

Two consequences to weigh before we commit to it:

1. It changes scheduler provenance product-wide, not just for automations. Once the flex config
   is part of source identity, scheduler sources fragment per distinct config, where today one source
   per scheduler version serves everything. That affects anyone attributing or filtering saved
   schedules by source id, and it is a change to scheduling, arriving through an automations PR.
   (It also argues, separately, for filtering by source type rather than id.)
2. It makes automations a strict subset of triggers. A trigger message the API accepts could be
   un-automatable, and we would owe a precise error naming the field that made it non-static. That is
   defensible while soc-at-start is on its way out, but it is a real asymmetry, and worth being
   deliberate about rather than discovering it in the error message.

Where that leaves us

My preference, in order:

1. Land this PR as it stands (nullable + type != 'forecasting' OR generator_id IS NOT NULL). The
   constraint is a visible, temporary statement of the asymmetry rather than a hidden one.
2. Do Scheduler as a DataGenerator with a real _config_schema — your 3.1 — in its own PR, on
   its own merits, judged as the scheduling-provenance change it is.
3. When that lands, drop the constraint and make generator_id NOT NULL for both types. One
   migration, and the asymmetry is gone for the right reason.

What I would rather not do is 3.2 now: it removes the nullable column but leaves generator_id
meaning two different things depending on the row.

If you would rather not merge the asymmetry at all, I will do 3.1 first and rebase this PR onto it —
just say so, since it is the larger change and it touches how every scheduler source is created.
Happy to open the issue either way, with the two consequences above written up as the open questions.

[Flix6x]

About the two consequences:

It changes scheduler provenance product-wide, not just for automations.

I see how this affects users/hosts using source filters. I was about to propose fragmenting the scheduler source only for use within automations, to not affect existing usage of the scheduler. However, I want to note that the scheduler source already updates from time to time, for instance, with every FM release that bumps the scheduler version. In other words, already regularly breaking installations that supposedly filter by scheduler source ID makes me less conservative about taking care not to break such installations.

It makes automations a strict subset of triggers.

I agree.

---

If you agree, please create a new PR on top of this PR's branch that implements 3.1 and resolves the asymmetry. Make sure the PR's base branch is feat/2288-schedule-automations rather than main.

[Flix6x]

Agreed on the churn argument — a source id that already changes on every version bump is not a
stable thing to filter on, so config-fragmenting it product-wide is a difference of degree, not kind.
I withdraw that objection, and I would rather do it product-wide than only inside automations: a
scheduler source that means one thing for automated schedules and another for ad-hoc ones is the
same two-meanings problem we are trying to remove from generator_id.

One thing 3.1 has to decide before I write it, because it changes the design rather than the code.

Which config goes into the source?

A schedule's effective configuration is not in the trigger message. Scheduler.collect_flex_config
(data/models/planning/__init__.py:260) merges the passed flex-model and flex-context with
asset.get_flex_model() and asset.get_flex_context() from the asset tree, at compute time. So:

• If the source's config is the trigger message, this PR's flagship example — duration: "PT12H"
  on an asset that describes its own flexibility — has an empty config. Every minimal-trigger
  automation in the instance would share one source while computing entirely different schedules.
  That is exactly the hollowness I objected to in 3.2, moved one level up.
• If the source's config is the resolved config, it is meaningful, and it changes whenever
  somebody edits the asset's flex-model or flex-context through the ordinary asset API — nothing to
  do with the automation.

I think the second is right, and that the consequence is a feature rather than a cost: if a battery's
power-capacity changes, schedules computed before and after should carry different sources. That
is what "config is part of source identity" means.

But it settles the shape of generator_id: it becomes runner-maintained, re-resolved per run,
exactly as you proposed in issue 2 — now for config drift as well as version drift. Non-null and
always meaningful, but derived rather than chosen, so the rule that an automation's generator cannot
be deleted needs rethinking for derived sources. I am fine with that; I want it to be a decision
rather than a side effect.

Two practical wrinkles, flagged not blocking

• Resolving the config when the automation is created means running the merge outside a compute call,
  and Scheduler.__init__ warns that timing and flex-model are intertwined ("E.g. start and
  flex_model[soc_at_start] are intertwined", planning/__init__.py:163). Forbidding per-run fields
  should defuse this, but it is where I expect the sharp edges.
• Making generator_id NOT NULL needs the existing schedule-automation rows backfilled with a
  resolved source, which is app logic in a migration. I would rather resolve them on the automation's
  next run and tighten the column in a follow-up migration than run scheduler resolution inside
  Alembic.

Unless you read the first point differently, I will implement it that way — resolved config, sources
fragmenting product-wide, generator_id derived and refreshed per run — in a PR based on
feat/2288-schedule-automations.

[Flix6x]

Implemented in #2464, based on feat/2288-schedule-automations.

Two things came up while building it that changed the shape of the work, both now resolved in the PR:

A scheduling request spawns several schedulers. With the config in the source, each device job of
a sequential schedule resolved a source from its own slice of the flex-model, and
[GET] /sensors/(id)/schedules/(uuid) then answered UNKNOWN_SCHEDULE for every device after the
first — the request's job knows one source, and the device's schedule was under another. So
create_sequential_scheduling_job now resolves the request's source once and hands it to each device
job: one request, one generator run, one source.

The CLI hands over a deserialized flex config. flexmeasures add schedule passes quantities and
sensor objects, not their serialized form, so recording the config raised
TypeError: Object of type Quantity is not JSON serializable on nine tests. Values that JSON cannot
hold are now recorded by how they print, so the configuration is still described rather than lost.

On the deletion rule we discussed in the session: it is enforced by nothing but the plain foreign
key, and the honest change is to what the documentation claims it does, not to the schema. It now
reads as the source describing the automation's configuration, which is true for both types, rather
than as protecting a configuration the user chose.

Full suite green: 1788 passed, 12 skipped, 4 xfailed. Migration exercised up, down and up again on a
sandboxed Postgres.