CRUD for automations in the API and UI

documentation/api/change_log.rst

@@ -5,6 +5,10 @@ API change log
 
 .. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL (e.g. `/api/v3_0`), allowing developers to upgrade at their own pace.
 
+v3.0-36 | September 11, 2026
+""""""""""""""""""""""""""""
+- Added ``POST /api/v3_0/assets/<id>/automations``, ``PATCH /api/v3_0/assets/<id>/automations/<automation_id>`` and ``DELETE /api/v3_0/assets/<id>/automations/<automation_id>`` for managing an asset's automations. They require the same permission as writing data under the asset, and an automation may only involve sensors that its creator can access: read access to the sensors it reads data from, and permission to record data on the sensors it writes to (a ``403`` otherwise). Both the creation and the update accept a ``timezone``, in which the automation's cron expression is interpreted; it defaults to the server's ``FLEXMEASURES_TIMEZONE``.
+
 v3.0-35 | September 9, 2026
 """""""""""""""""""""""""""
 - The ``resolution`` field is now rejected with a ``422 (Unprocessable Entity)`` response unless it spans a positive amount of time. This applies wherever the API accepts one: as a query parameter on ``GET /api/v3_0/sensors/<id>/data`` and on the ``chart_data`` endpoints under ``api/dev``, and in the request body of the ``POST`` schedule trigger endpoints. Previously, a zero resolution (such as ``PT0S``) either crashed the request with a ``500`` or was silently ignored, and a negative resolution returned an empty set of values.

documentation/changelog.rst

@@ -19,10 +19,18 @@ v1.1.0 | September XX, 2026
              Select a data source to see the schedule computed under one configuration.
              One scheduling request still records under a single data source, including the per-device jobs of a sequential schedule.
 
+.. warning:: A scheduler's data source now also records the flex config it computed under, where previously one data source per scheduler version recorded every schedule that scheduler made.
+             Schedules computed under different flex configs are therefore recorded by different data sources, and a sensor can carry schedules from several of them, as it already could for forecasts.
+             Values describing a single moment stay out of that config, so a ``soc-at-start``, or a ``soc-targets`` entry at a given datetime, does not make every run a new data source.
+             What does is a change to what the site and its devices can do, such as a device's ``power-capacity``.
+             After such a change, a sensor holds the schedule computed under each configuration, where the newer schedule used to supersede the older one, so a chart of that sensor draws both, and the asset's KPIs total both, as they report what the chart draws.
+             Select a data source to see the schedule computed under one configuration.
+             One scheduling request still records under a single data source, including the per-device jobs of a sequential schedule.
+
 New features
 -------------
 
-* Automations: recurring tasks defined per asset, computing forecasts or schedules, managed with new CLI commands (``flexmeasures add|edit|delete automation``), run by ``flexmeasures jobs run-automations``, and viewable in a new UI page and API endpoints (``[GET] /assets/(id)/automations``); each automation interprets its recurrence in its own timezone, and runs missed while the runner was down are caught up once, coalesced into one current forecast; a forecast automation points at a data source holding its forecaster configuration, while a schedule automation stores what the schedule trigger endpoint accepts, and schedules from each run's own time, unless the trigger message fixes a ``start``; an automation's details link to the sensors it reads from and writes to, a sensor's page lists the automations feeding it, and deleting a sensor warns about the automations that use it; jobs now also record whether they were created via the CLI, the API or an automation [see `PR #2290 <https://www.github.com/FlexMeasures/flexmeasures/pull/2290>`_, `PR #2396 <https://www.github.com/FlexMeasures/flexmeasures/pull/2396>`_ and `PR #2293 <https://www.github.com/FlexMeasures/flexmeasures/pull/2293>`_]
+* Automations: recurring tasks defined per asset, computing forecasts or schedules, managed with new CLI commands (``flexmeasures add|edit|delete automation``), run by ``flexmeasures jobs run-automations``, and viewable in a new UI page and API endpoints (``[GET] /assets/(id)/automations``); each automation interprets its recurrence in its own timezone, and runs missed while the runner was down are caught up once, coalesced into one current forecast; a forecast automation points at a data source holding its forecaster configuration, while a schedule automation stores what the schedule trigger endpoint accepts, and schedules from each run's own time, unless the trigger message fixes a ``start``; an automation's details link to the sensors it reads from and writes to, a sensor's page lists the automations feeding it, and deleting a sensor warns about the automations that use it; jobs now also record whether they were created via the CLI, the API or an automation; automations can also be created, edited and deleted in the UI and through new API endpoints (``[POST|PATCH|DELETE] /assets/(id)/automations``), by whoever may add data under the asset, with their recurrence expressed in a selectable IANA timezone, and only involving sensors they can access themselves (read access to the sensors an automation reads, and permission to record data on the sensors it writes to) [see `PR #2290 <https://www.github.com/FlexMeasures/flexmeasures/pull/2290>`_, `PR #2396 <https://www.github.com/FlexMeasures/flexmeasures/pull/2396>`_, `PR #2293 <https://www.github.com/FlexMeasures/flexmeasures/pull/2293>`_ and `PR #2294 <https://www.github.com/FlexMeasures/flexmeasures/pull/2294>`_]
 * A scheduler's data source now also records the flex config the scheduler computed under, so a schedule can be traced back to the configuration that produced it, and a schedule automation points at such a data source, the way a forecast automation points at its forecaster's [see `PR #2444 <https://www.github.com/FlexMeasures/flexmeasures/pull/2444>`_]
 * In the UI, the full record of the data source selected on a sensor page can be inspected, backed by a new API endpoint (``[GET] /sources/(id)``) [see `PR #2290 <https://www.github.com/FlexMeasures/flexmeasures/pull/2290>`_]
 * Try out a forecast without recording it, using ``flexmeasures add forecasts --dry-run``, which computes the forecast in full and reports the sensor, data source, number of beliefs and event range it would have saved [see `PR #2483 <https://www.github.com/FlexMeasures/flexmeasures/pull/2483>`_]

flexmeasures/api/v3_0/__init__.py

@@ -45,6 +45,10 @@
     StatusPageChildJobsJSONSchema,
 )
 from flexmeasures.data.schemas.annotations import AnnotationSchema
+from flexmeasures.data.schemas.automations import (
+    AutomationCreationSchema,
+    AutomationUpdateSchema,
+)
 from flexmeasures.data.schemas.generic_assets import GenericAssetSchema as AssetSchema
 from flexmeasures.data.schemas.reporting import ReportTriggerSchema
 from flexmeasures.data.schemas.sensors import QuantitySchema, TimeSeriesSchema
@@ -228,6 +232,8 @@ def create_openapi_specs(app: Flask):
         ("AssetAPIQuerySchema", AssetAPIQuerySchema),
         ("AssetSchema", AssetSchema),
         ("AnnotationSchema", AnnotationSchema),
+        ("AutomationCreationSchema", AutomationCreationSchema),
+        ("AutomationUpdateSchema", AutomationUpdateSchema),
         ("ReportTriggerSchema", ReportTriggerSchema),
         ("CopyAssetSchema", CopyAssetSchema),
         ("DefaultAssetViewJSONSchema", DefaultAssetViewJSONSchema),

flexmeasures/api/v3_0/assets.py

@@ -48,13 +48,20 @@
 from flexmeasures.data.models.automations import Automation
 from flexmeasures.data.models.user import Account
 from flexmeasures.data.models.audit_log import AssetAuditLog
-from flexmeasures.data.schemas.automations import AutomationSchema
+from flexmeasures.data.schemas.automations import (
+    AutomationCreationSchema,
+    AutomationSchema,
+    AutomationUpdateSchema,
+)
 from flexmeasures.data.services.automations import (
     AutomationSensorsUnknown,
+    create_automation,
+    delete_automation as remove_automation,
     describe_cronstr,
     get_automation_job_stats,
     resolve_automation_sensors,
     run_automation,
+    update_automation,
 )
 from flexmeasures.data.models.generic_assets import GenericAsset, GenericAssetType
 from flexmeasures.data.models.reporting import Reporter
@@ -1476,7 +1483,7 @@ def get_automations(self, id: int, asset: GenericAsset):
                           - id: 1
                             created_at: "2026-07-11T00:00:00+00:00"
                             asset_id: 1
-                            type: forecasts
+                            type: forecasting
                             name: Day-ahead PV forecasts
                             cronstr: "0 6 * * *"
                             timezone: Europe/Amsterdam
@@ -1556,7 +1563,7 @@ def get_automation(self, id: int, automation_id: int, asset: GenericAsset):
                         id: 1
                         created_at: "2026-07-11T00:00:00+00:00"
                         asset_id: 1
-                        type: forecasts
+                        type: forecasting
                         name: Day-ahead PV forecasts
                         cronstr: "0 6 * * *"
                         timezone: Europe/Amsterdam
@@ -1637,6 +1644,243 @@ def get_automation(self, id: int, automation_id: int, asset: GenericAsset):
         automation_data["redis_connection_err"] = redis_connection_err
         return automation_data, 200
 
+    @route("/<id>/automations", methods=["POST"])
+    @use_kwargs(
+        {"asset": AssetIdField(data_key="id")},
+        location="path",
+    )
+    # Managing an automation is gated like running one: an automation exists to write data
+    # under the asset, so the same principals that may add data there may define it.
+    # The sensors it involves are checked separately, against the user's own access.
+    @permission_required_for_context("create-children", ctx_arg_name="asset")
+    @as_json
+    def post_automation(self, id: int, asset: GenericAsset):
+        """
+        .. :quickref: Assets; Create an automation on an asset.
+
+        ---
+        post:
+          summary: Create an automation on an asset.
+          description: |
+            Create a recurring task (computing forecasts or schedules) on the asset.
+            The parameters are validated by the schema matching the automation type:
+            forecast parameters for type `forecasts`, or a schedule trigger message
+            (without the asset id) for type `schedules`.
+            Requires permission to add data under the asset.
+
+            The automation can only involve sensors that you have access to yourself:
+            read access to the sensors it reads data from, and permission to record data
+            on the sensors it writes to.
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - in: path
+              name: id
+              required: true
+              description: ID of the asset to create the automation on.
+              schema:
+                type: integer
+          requestBody:
+            content:
+              application/json:
+                schema: AutomationCreationSchema
+                examples:
+                  daily_forecasts:
+                    summary: Daily forecasts of sensor 2092
+                    value:
+                      name: Day-ahead PV forecasts
+                      cronstr: "0 6 * * *"
+                      type: forecasting
+                      parameters:
+                        sensor: 2092
+          responses:
+            201:
+              description: CREATED
+            400:
+              description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            422:
+              description: UNPROCESSABLE_ENTITY
+          tags:
+            - Assets
+        """
+        body = request.get_json(silent=True)
+        if not body:
+            return unprocessable_entity("No JSON data provided.")
+        try:
+            automation_data = AutomationCreationSchema().load(body)
+        except ValidationError as e:
+            return unprocessable_entity(e.messages)
+        try:
+            automation, warnings = create_automation(
+                asset=asset,
+                name=automation_data["name"],
+                cronstr=automation_data["cronstr"],
+                timezone=automation_data["timezone"],
+                automation_type=automation_data["type"],
+                active=automation_data["active"],
+                parameters=automation_data["parameters"],
+                forecaster_class=automation_data["forecaster"],
+                config=automation_data["config"],
+                origin="API",
+                check_permissions=True,
+            )
+        except ValidationError as e:
+            return unprocessable_entity({"parameters": e.messages})
+        except ValueError as e:
+            return unprocessable_entity(str(e))
+        db.session.commit()
+        response = automation_schema.dump(automation)
+        response["recurrence_description"] = describe_cronstr(automation.cronstr)
+        response["warnings"] = warnings
+        return response, 201
+
+    @route("/<id>/automations/<int:automation_id>", methods=["PATCH"])
+    @use_kwargs(
+        {
+            "asset": AssetIdField(data_key="id"),
+            "automation_id": fields.Int(),
+        },
+        location="path",
+    )
+    # Managing an automation is gated like running one: an automation exists to write data
+    # under the asset, so the same principals that may add data there may define it.
+    # The sensors it involves are checked separately, against the user's own access.
+    @permission_required_for_context("create-children", ctx_arg_name="asset")
+    @as_json
+    def patch_automation(self, id: int, automation_id: int, asset: GenericAsset):
+        """
+        .. :quickref: Assets; Update an automation's name, cron string or activation status.
+
+        ---
+        patch:
+          summary: Update an automation's name, cron string or activation status.
+          description: |
+            Any subset of the fields `name`, `cronstr` and `active` can be sent.
+            Other automation fields cannot be updated; instead, create a new automation.
+            Requires permission to add data under the asset.
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - in: path
+              name: id
+              required: true
+              description: ID of the asset.
+              schema:
+                type: integer
+            - in: path
+              name: automation_id
+              required: true
+              description: ID of the automation.
+              schema:
+                type: integer
+          requestBody:
+            content:
+              application/json:
+                schema: AutomationUpdateSchema
+                examples:
+                  deactivate:
+                    summary: Deactivate the automation
+                    value:
+                      active: false
+          responses:
+            200:
+              description: PROCESSED
+            400:
+              description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            404:
+              description: NOT_FOUND
+            422:
+              description: UNPROCESSABLE_ENTITY
+          tags:
+            - Assets
+        """
+        automation = db.session.get(Automation, automation_id)
+        if automation is None or automation.asset_id != asset.id:
+            return {
+                "message": f"Asset {asset.id} has no automation with id {automation_id}."
+            }, 404
+        body = request.get_json(silent=True)
+        if not body:
+            return unprocessable_entity("No JSON data provided.")
+        try:
+            automation_data = AutomationUpdateSchema().load(body)
+        except ValidationError as e:
+            return unprocessable_entity(e.messages)
+        update_automation(automation, origin="API", **automation_data)
+        db.session.commit()
+        response = automation_schema.dump(automation)
+        response["recurrence_description"] = describe_cronstr(automation.cronstr)
+        return response, 200
+
+    @route("/<id>/automations/<int:automation_id>", methods=["DELETE"])
+    @use_kwargs(
+        {
+            "asset": AssetIdField(data_key="id"),
+            "automation_id": fields.Int(),
+        },
+        location="path",
+    )
+    # Managing an automation is gated like running one: an automation exists to write data
+    # under the asset, so the same principals that may add data there may define it.
+    # The sensors it involves are checked separately, against the user's own access.
+    @permission_required_for_context("create-children", ctx_arg_name="asset")
+    @as_json
+    def delete_automation(self, id: int, automation_id: int, asset: GenericAsset):
+        """
+        .. :quickref: Assets; Delete an automation.
+
+        ---
+        delete:
+          summary: Delete an automation.
+          description: |
+            Delete the automation. Any jobs it already queued are unaffected.
+            Requires permission to add data under the asset.
+          security:
+            - ApiKeyAuth: []
+          parameters:
+            - in: path
+              name: id
+              required: true
+              description: ID of the asset.
+              schema:
+                type: integer
+            - in: path
+              name: automation_id
+              required: true
+              description: ID of the automation.
+              schema:
+                type: integer
+          responses:
+            204:
+              description: DELETED
+            400:
+              description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
+            401:
+              description: UNAUTHORIZED
+            403:
+              description: INVALID_SENDER
+            404:
+              description: NOT_FOUND
+          tags:
+            - Assets
+        """
+        automation = db.session.get(Automation, automation_id)
+        if automation is None or automation.asset_id != asset.id:
+            return {
+                "message": f"Asset {asset.id} has no automation with id {automation_id}."
+            }, 404
+        remove_automation(automation, origin="API")
+        db.session.commit()
+        return {}, 204
+
     @route("/<id>/automations/<int:automation_id>/trigger", methods=["POST"])
     @limit_triggers()
     @use_kwargs(