FlexMeasures · nhoening · Aug 1, 2026 · Aug 1, 2026 · Aug 1, 2026 · Aug 2, 2026
diff --git a/.dockerignore b/.dockerignore
@@ -7,6 +7,9 @@ flexmeasures.log*
 # Ignore locally made docs
 flexmeasures/ui/static/documentation
 
+# Checked out separately by Docker CI for host-side client integration tests
+flexmeasures-client
+
 # Ignore all forecasting artifacts (models, predictions, etc.)
 flexmeasures/data/models/forecasting/**/artifacts/
 flexmeasures/data/models/forecasting/**/*.pkl

diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
@@ -28,6 +28,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - name: Checkout flexmeasures-client
+        uses: actions/checkout@v4
+        with:
+          repository: FlexMeasures/flexmeasures-client
+          ref: main
+          path: flexmeasures-client
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.9"
+          enable-cache: true
       - name: Build Docker Image
         run: docker build -t flexmeasures:latest -f Dockerfile .
       - name: Generate random secret key
@@ -48,6 +59,10 @@ jobs:
       - name: Add toy user
         run: docker exec --env-file .env fm-container flexmeasures
           add toy-account --kind battery --shell-vars | grep '^FM_TOY_' >> $GITHUB_ENV
+      - name: Run data-ingestion tutorial
+        env:
+          FLEXMEASURES_CLIENT_PROJECT: ${{ github.workspace }}/flexmeasures-client
+        run: ./documentation/tut/scripts/run-data-ingestion-in-docker.sh fm-container
       - name: Generate prices dummy data
         run: ci/generate-dummy-price.sh
       - name: Copy prices dummy data

diff --git a/.github/workflows/docker-qa.yml b/.github/workflows/docker-qa.yml
@@ -84,6 +84,11 @@ jobs:
             echo "::endgroup::"
           done
 
+      - name: Run data-ingestion tutorial
+        env:
+          FLEXMEASURES_CLIENT_PROJECT: ${{ github.workspace }}/flexmeasures-client
+        run: ./documentation/tut/scripts/run-data-ingestion-in-docker.sh
+
       - name: Create HEMS admin account and user
         run: |
           OUTPUT=$(docker compose exec -T server flexmeasures add account --name "HEMS Admin Org")

diff --git a/documentation/changelog.rst b/documentation/changelog.rst
@@ -49,6 +49,8 @@ New features
 
 Infrastructure / Support
 ----------------------
+
+* Add a hands-on data-ingestion tutorial with executable FlexMeasures Client examples for Excel and CSV uploads and export scripts [see `PR #2376 <https://www.github.com/FlexMeasures/flexmeasures/pull/2376>`_]
 * The database migration for this release splits each stored flex-context's ``inflexible-device-sensors`` field into ``inflexible-consumption``/``inflexible-production`` sensor references, classifying each sensor by its ``consumption_is_positive`` attribute (behavior-preserving; sensor attributes themselves are kept). Downgrading merges them back into bare sensor IDs, dropping any source filters added in the meantime [see `PR #2358 <https://www.github.com/FlexMeasures/flexmeasures/pull/2358>`_]
 * Speed up listing assets: eager-load each asset's sensors instead of lazy-loading them one query per asset during serialization, and skip loading sensors entirely for field-filtered responses that do not include them [see `PR #2363 <https://www.github.com/FlexMeasures/flexmeasures/pull/2363>`_]
 * Price fields in the flex-context (including nested commitment prices, which are now also held to the flex-context's shared currency) are selected for currency validation by field type (``PriceField``) instead of by name suffix [see `PR #2311 <https://www.github.com/FlexMeasures/flexmeasures/pull/2311>`_]
@@ -76,6 +78,7 @@ Infrastructure / Support
 
 Bugfixes
 -----------
+* Include the Excel reader in default installations so XLSX sensor-data uploads work outside test environments [see `PR #XXXX <https://www.github.com/FlexMeasures/flexmeasures/pull/XXXX>`_]
 * Replaying a chart for a past window no longer shows annotations that were only recorded later; annotation searches and the ``chart_annotations`` endpoints can now be scoped by recording (belief) time [see `PR #2367 <https://www.github.com/FlexMeasures/flexmeasures/pull/2367>`_]
 * Continuing the query-parameter cleanup started in PR #2352: the chart-related endpoints now use ``prior``, ``start``, ``end`` and hyphenated field names, with a new ``duration`` field to derive a missing ``start``/``end``; old spellings keep working as legacy aliases [see `PR #2367 <https://www.github.com/FlexMeasures/flexmeasures/pull/2367>`_]
 * Scheduling jobs no longer print ``Job ... made schedule.`` before ``scheduler.compute()`` runs (only after a successful schedule) [see `PR #2342 <https://www.github.com/FlexMeasures/flexmeasures/pull/2342>`_]

diff --git a/documentation/dev/scripting.rst b/documentation/dev/scripting.rst
@@ -13,6 +13,7 @@ Scripting via the FlexMeasures-Client
 
 The most universal way to script FlexMeasures is via `the FlexMeasures Client <https://github.com/FlexMeasures/flexmeasures-client/>`_.
 Actually, this is scripting via the API, as the client is not much more than a wrapper around the FlexMeasures server API.
+For a hands-on example which uploads Excel or CSV data and posts values from an export script, see :ref:`tut_posting_data`.
 
 Let's look at two examples, to give an impression. The first one creates a sensor:
 

diff --git a/documentation/getting-started.rst b/documentation/getting-started.rst
@@ -29,6 +29,7 @@ Find an optimized schedule for your flexible asset, like a battery, with standar
 2. Automate
 ^^^^^^^^^^^^^^^^^^^
 
+Turn spreadsheet or export-script data into a repeatable pipeline with :ref:`tut_posting_data`.
 Get the prices from an open API, for instance `ENTSO-E <https://transparency.entsoe.eu/>`_ (using a plugin like `flexmeasures-entsoe <https://github.com/SeitaBV/flexmeasures-entsoe>`_), and run the scheduler regularly in a cron job. Do more, like automating forecasts, too. And for scale, copy your successfully-tested asset programmatically (or in the UI), to set up new customers quickly, e.g. as you are servicing the same kind of site often.
 
 3. Integrate
@@ -89,4 +90,3 @@ Core developers
 ^^^^^^^^^^^^^^^^
 
 You want to help develop FlexMeasures, e.g. to fix a bug. We provide a getting-started guide to becoming a developer at :ref:`developing`.
-
diff --git a/documentation/host/installation.rst b/documentation/host/installation.rst
@@ -312,9 +312,10 @@ Below are some additional steps you might consider.
 Add time series data (beliefs)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are three ways to add data:
+For a complete walkthrough from a first UI upload to an automated pipeline, see :ref:`tut_posting_data`.
+The main ingestion routes are the FlexMeasures Client and the API; hosts can also import files directly with the CLI.
 
-First, you can load in data from a file (CSV or Excel) via the ``flexmeasures`` :ref:`cli`:
+To load data from a CSV or Excel file on the server, use the ``flexmeasures`` :ref:`cli`:
 
 .. code-block:: bash
 
@@ -323,11 +324,11 @@ First, you can load in data from a file (CSV or Excel) via the ``flexmeasures``
 This assumes you have a file `my-data.csv` with measurements, which was exported from some legacy database, and that the data is about our sensor with ID 1. This command has many options, so do use its ``--help`` function.
 For instance, to add data as forecasts, use the ``--beliefcol`` parameter, to say precisely when these forecasts were made. Or add  ``--horizon`` for rolling forecasts if they all share the same horizon.
 
-Second, you can use the `POST /api/v3_0/sensors/<id>/data <../api/v3_0.html#post--api-v3_0-sensors-id-data>`_ endpoint in the FlexMeasures API to send meter data.
+For automated pipelines running elsewhere, use the `FlexMeasures Client <https://github.com/FlexMeasures/flexmeasures-client/>`_ or call the `POST /api/v3_0/sensors/<id>/data <../api/v3_0.html#post--api-v3_0-sensors-id-data>`_ and file-upload endpoints directly.
 
 You can also use the API to send forecast data. Similar to the ``add beliefs`` commands, you would use here the fields ``prior`` (to denote time of knowledge of data) or ``horizon`` (for rolling forecast data with equal horizon). Consult the documentation at :ref:`posting_sensor_data`.
 
-Finally, you can tell FlexMeasures to compute forecasts based on existing meter data with the ``flexmeasures add forecasts`` command, here is an example:
+After ingesting meter data, you can tell FlexMeasures to compute forecasts with the ``flexmeasures add forecasts`` command, here is an example:
 
 .. code-block:: bash
 

diff --git a/documentation/index.rst b/documentation/index.rst
@@ -184,12 +184,12 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
     tut/toy-example-from-scratch
     tut/toy-example-expanded
     tut/toy-example-multiasset-curtailment
-    tut/toy-example-group-constraints
     tut/flex-model-v2g
     tut/multi-feed-storage
     tut/multi-commodity
     tut/toy-example-process
     tut/toy-example-reporter
+    tut/toy-example-group-constraints
     tut/posting_data
     tut/forecasting_scheduling
     tut/building_uis

diff --git a/documentation/tut/forecasting_scheduling.rst b/documentation/tut/forecasting_scheduling.rst
@@ -148,9 +148,8 @@ It usually involves a linear program that combines a state of energy flexibility
 There are two ways to queue a scheduling job:
 
 First, we can add a scheduling job to the queue via the API.
-We already learned about the `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-id-schedules-trigger>`_ endpoint in :ref:`posting_flex_states`, where we saw how to post a flexibility state (in this case, the state of charge of a battery at a certain point in time).
-
-Here, we extend that (storage) example with an additional target value, representing a desired future state of charge.
+The `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-id-schedules-trigger>`_ endpoint accepts a flexibility state, such as the state of charge of a battery at a certain point in time.
+This storage example also includes a target value representing a desired future state of charge.
 
 .. code-block:: json
     :emphasize-lines: 6-11
@@ -292,7 +291,7 @@ This example requests a prognosis for 24 hours, with a rolling horizon of 6 hour
 Getting schedules (control signals)
 -----------------------
 
-We saw above how FlexMeasures can create optimised schedules with control signals for flexible devices (see :ref:`posting_flex_states`). You can access the schedules via the `[GET] /schedules/<uuid> <../api/v3_0.html#get--api-v3_0-sensors-id-schedules-uuid>`_ endpoint. The URL then looks like this:
+After FlexMeasures creates an optimised schedule with control signals for flexible devices, you can access it via the `[GET] /schedules/<uuid> <../api/v3_0.html#get--api-v3_0-sensors-id-schedules-uuid>`_ endpoint. The URL then looks like this:
 
 .. code-block:: html