Trigger a single automation run on demand, via CLI, API and UI

[Flix6x]

Closes #2459.

Automations could only ever run on their own cron cadence, so trying one out after creating it, re-running it once the cause of a failure was fixed, or refreshing its results after late input data arrived meant temporarily rewriting its cron string, or bypassing the automation and triggering a forecast by hand with the same parameters (which loses the link to the automation).

This adds a way to run one automation now, once, through all three interfaces:

• CLI: flexmeasures jobs run-automation --automation 4
• API: POST /api/v3_0/assets/<id>/automations/<automation_id>/trigger
• UI: a Run now button per automation on the asset's Automations page

All three are thin wrappers around the same run_automation() that the recurring runner calls, so an on-demand run is the same run, and the jobs it queues carry the same automation trigger metadata — they show up in the automation's job stats like any other run.

Semantics

• The cursor is not touched. An on-demand run is extra work, not a claim on a scheduled occurrence, so the next recurring run still happens as scheduled, and a run missed while the runner was down is still caught up. A CLI test asserts exactly this: it triggers a run by hand, then lets the recurring runner run and checks that it still queues the scheduled run.
• No duplicate guard. The recurring path holds a Redis guard on automation-run:<id>:<scheduled_at>, which has no counterpart here: the operator asked for the run. Asking twice queues two runs, which the docs say plainly. The UI disables its button while a request is in flight.
• Inactive automations can be triggered, since an inactive automation is exactly the one you want to try out before switching it on.
• Permission: create-children on the asset, i.e. what writing data under the asset means, and what the other triggering endpoints (/assets/<id>/schedules/trigger, /sensors/<id>/forecasts/trigger) require. This is a deliberate change from the "require update" suggestion in Trigger a single automation run on demand, via CLI, API and UI #2459: an automation's output sensors were checked against this same permission when it was created, and its output scope is re-checked on every run, so requiring account-admin here would be stricter than triggering the very same forecast by hand. Say the word if you would rather have it the other way round.
• The endpoint falls under the stricter trigger rate limit the other triggering endpoints share (visible in the regenerated OpenAPI spec).
• The API path stays nested under the asset, matching the two merged automation endpoints, the CRUD endpoints under review in CRUD for automations in the API and UI #2294, and the UI route.

When #2393 (durable automation-run records) lands, an on-demand run should get its own run record, marked as manually triggered; that is noted in #2459 rather than done here.

Testing

• CLI, end to end (real queueing): jobs are queued and recorded as the automation's own, an audit-log record is written, the cursor stays put and the next scheduled run still happens, an inactive automation runs, and an unknown ID is reported cleanly.
• API: permissions (401/403/202), the response (job, n_jobs), a 404 for an unknown automation and for one requested through an asset it does not belong to, and a 422 (rather than a queued job) when the run cannot be set up.
• Each new assertion was verified to fail when the behaviour it covers is broken (cursor advanced on an on-demand run; the asset/automation consistency check dropped; n_jobs left out).

🤖 Generated with Claude Code

https://claude.ai/code/session_01G9NpBEcXs6MbCAzzm1sLxG

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34350691 | 📁 Comparing 561706c against latest (d4e0805)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• changelog.html
• genindex.html
• http-routingtable.html
• _autosummary/flexmeasures.api.v3_0.assets.html
• api/change_log.html
• api/v3_0.html
• cli/change_log.html
• features/automations.html

[Copilot]

🟡 Changes recommended

There are a few correctness/convention issues in newly added code (CLI success on missing job info, and repo-enforced comment/doc wrapping conventions) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds an on-demand “run once now” trigger for existing automations across CLI, API, and UI, reusing the existing run_automation() service so the queued jobs keep the same automation trigger metadata as scheduled runs.

Changes:

• CLI: introduce flexmeasures jobs run-automation --automation <id> plus end-to-end tests asserting cursor is unchanged and scheduled runs still occur.
• API: add POST /api/v3_0/assets/<id>/automations/<automation_id>/trigger (rate-limited like other trigger endpoints) with tests for auth, 404/422 behavior, and response shape.
• UI: add a per-automation “Run now” button gated by create-children permission, and wire it to the new API endpoint.

File summaries

File	Description
flexmeasures/ui/views/assets/views.py	Passes user_can_create_children into the Automations page template for permission-gated UI actions
flexmeasures/ui/templates/assets/asset_automations.html	Adds “Run now” button and AJAX trigger call plus success/error messaging
flexmeasures/ui/static/openapi-specs.json	Regenerated OpenAPI spec including the new automation trigger endpoint
flexmeasures/cli/tests/test_automations.py	Adds CLI integration tests for on-demand runs, including cursor semantics and inactive automations
flexmeasures/cli/jobs.py	Adds run-automation CLI command that queues a single automation run and writes an audit-log entry
flexmeasures/api/v3_0/tests/test_automations_api.py	Adds API tests for the new trigger endpoint (auth, 202 payload, 404/422 cases)
flexmeasures/api/v3_0/assets.py	Implements the new trigger endpoint with permission checks and audit logging
documentation/features/automations.rst	Documents on-demand automation runs and their semantics
documentation/cli/change_log.rst	Records the new CLI command in the CLI changelog
documentation/changelog.rst	Adds a user-facing changelog entry for the new on-demand trigger feature
documentation/api/change_log.rst	Records the new API endpoint and its semantics in the API changelog

Review details

Suppressed comments (1)

flexmeasures/ui/templates/assets/asset_automations.html:95

• This inline JavaScript comment should end with punctuation to follow the repo’s comment line-break convention (each physical line ends with a comma/semicolon/colon/period).

  // Run this automation once, now, on top of its recurring runs

• Files reviewed: 11/11 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The CLI/API/UI implementations are consistent with the stated semantics (not touching the cursor, shared run_automation() path, correct permission gating and rate limiting) and are covered by targeted tests and documentation updates.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 0 new
• Review effort level: Lite

[BelhsanHmida]

Approving.

I tested, Everything passed. The endpoint shows up correctly in Swagger under Assets with both path parameters
and the 202/401/403/404/422/429 responses, and the documented example matches the actual response
field for field. Triggering an active automation returns 202 with the job id and n_jobs, queues the
job with {"origin": "automation", "automation_id": 1} in its metadata, writes the audit record, and
leaves the cursor alone. Inactive automations trigger fine and stay inactive. Unknown ids and
automations requested through the wrong asset both return 404 without reaching run_automation, a
user from another account gets 403 with nothing queued, and an automation whose output sensor sits
outside the asset returns 422 with the real reason, no job and no audit record. The rate limit kicks
in exactly at 10 and does share its budget with /schedules/trigger, as described.

The CLI behaves the same way. run-automation queues and records the run, an unknown id exits 2
cleanly, and a run that cannot be set up aborts without queueing anything. The cursor semantics hold
end to end: I triggered a run by hand, saw the cursor stay put, then ran run-automations and it
still queued the scheduled run and advanced the cursor. Job stats counted the manually triggered jobs
as the automation's own, so they do show up like any other run.