stats: add order stats endpoint and extend orders index

* the endpoint returns a histogram for stats where requested metrics are grouped by and aggregated
* extend the orders index with a new stats object
* the stats object contains order_processing_time and document_request_waiting_time

Author: JakobMiesner

invenio_app_ils/acquisition/indexer.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Order indexer APIs."""
+
+from datetime import datetime
+
+from invenio_search import current_search_client
+
+from invenio_app_ils.acquisition.api import ORDER_PID_TYPE
+from invenio_app_ils.proxies import current_app_ils
+
+
+def index_stats_fields_for_order(order_dict):
+    """Indexer hook to modify the order record dict before indexing."""
+
+    # This is done through the hook and not through an indexer class,
+    # as we need access to the `_created` field
+
+    # Only calculate stats if order is received
+    if not order_dict.get("received_date"):
+        return
+
+    stats = {}
+
+    received_date = datetime.fromisoformat(order_dict["received_date"]).date()
+    creation_date = datetime.fromisoformat(order_dict["_created"]).date()
+
+    # Calculate ordering_time
+    ordering_time = (received_date - creation_date).days
+    stats["order_processing_time"] = ordering_time if ordering_time >= 0 else None
+
+    # Find related document request if any
+    order_pid = order_dict.get("pid")
+    if order_pid:
+        # Search for document requests that reference this order
+        doc_req_search_cls = current_app_ils.document_request_search_cls
+        search_body = {
+            "query": {
+                "bool": {
+                    "must": [
+                        {"term": {"physical_item_provider.pid": order_pid}},
+                        {"term": {"physical_item_provider.pid_type": ORDER_PID_TYPE}},
+                    ],
+                }
+            },
+            "size": 1,
+        }
+
+        search_result = current_search_client.search(
+            index=doc_req_search_cls.Meta.index, body=search_body
+        )
+
+        hits = search_result["hits"]["hits"]
+        if len(hits) > 0:
+            doc_request = hits[0]["_source"]
+            doc_req_creation_date = datetime.fromisoformat(
+                doc_request["_created"]
+            ).date()
+
+            order_dict["doc_request"] = {}
+
+            # Calculate document_request_waiting_time: received_date - document request creation date
+            waiting_time = (received_date - doc_req_creation_date).days
+            stats["document_request_waiting_time"] = (
+                waiting_time if waiting_time >= 0 else None
+            )
+
+    order_dict["stats"] = stats

invenio_app_ils/acquisition/mappings/os-v2/acq_orders/order-v1.0.0.json

@@ -358,6 +358,11 @@
       },
       "provider_pid": {
         "type": "keyword"
+      },
+      "stats": {
+        "type": "object",
+        "dynamic": true,
+        "enabled": true
       }
     }
   }

invenio_app_ils/acquisition/stats/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio App ILS acquisition stats module."""

invenio_app_ils/acquisition/stats/views.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2025 CERN.
+#
+# invenio-app-ils is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio App ILS acquisition stats views."""
+
+from flask import Blueprint, request
+from invenio_records_rest.query import default_search_factory
+from invenio_rest import ContentNegotiatedMethodView
+from marshmallow.exceptions import ValidationError
+
+from invenio_app_ils.acquisition.api import ORDER_PID_TYPE
+from invenio_app_ils.acquisition.proxies import current_ils_acq
+from invenio_app_ils.errors import InvalidParameterError
+from invenio_app_ils.permissions import need_permissions
+from invenio_app_ils.stats.histogram import (
+    HistogramParamsSchema,
+    create_histogram_view,
+    get_record_statistics,
+)
+
+
+def create_acquisition_stats_blueprint(app):
+    """Add statistics views to the blueprint."""
+    blueprint = Blueprint("invenio_app_ils_acquisition_stats", __name__, url_prefix="")
+
+    create_histogram_view(
+        blueprint, app, ORDER_PID_TYPE, OrderHistogramResource, "/acquisition"
+    )
+
+    return blueprint
+
+
+class OrderHistogramResource(ContentNegotiatedMethodView):
+    """Order stats resource."""
+
+    view_name = "order_histogram"
+
+    def __init__(self, serializers, ctx, *args, **kwargs):
+        """Constructor."""
+        super().__init__(serializers, *args, **kwargs)
+        for key, value in ctx.items():
+            setattr(self, key, value)
+
+    @need_permissions("stats-orders")
+    def get(self, **kwargs):
+        """Get order statistics."""
+
+        order_date_fields = [
+            "order_date",
+            "expected_delivery_date",
+            "received_date",
+            "_created",
+            "_updated",
+        ]
+
+        schema = HistogramParamsSchema(order_date_fields)
+        try:
+            parsed_args = schema.load(request.args.to_dict())
+        except ValidationError as e:
+            raise InvalidParameterError(description=e.messages) from e
+
+        # Construct search to allow for filtering with the q parameter
+        search_cls = current_ils_acq.order_search_cls
+        search = search_cls()
+        search, _ = default_search_factory(self, search)
+
+        aggregation_buckets = get_record_statistics(
+            order_date_fields,
+            search,
+            parsed_args["group_by"],
+            parsed_args["metrics"],
+        )
+
+        response = {
+            "buckets": aggregation_buckets,
+        }
+
+        return self.make_response(response, 200)

invenio_app_ils/document_requests/indexer.py

@@ -13,6 +13,8 @@
 from flask import current_app
 from invenio_indexer.api import RecordIndexer
 
+from invenio_app_ils.acquisition.api import ORDER_PID_TYPE
+from invenio_app_ils.acquisition.proxies import current_ils_acq
 from invenio_app_ils.documents.api import DOCUMENT_PID_TYPE
 from invenio_app_ils.indexer import ReferencedRecordsIndexer
 from invenio_app_ils.proxies import current_app_ils
@@ -26,14 +28,25 @@ def index_referenced_records(docreq):
     indexer = ReferencedRecordsIndexer()
     indexed = dict(pid_type=DOCUMENT_REQUEST_PID_TYPE, record=docreq)
 
+    referenced = []
+
     # fetch and index the document
     document_pid = docreq.get("document_pid")
-    referenced = []
     if document_pid:
         document_cls = current_app_ils.document_record_cls
         document = document_cls.get_record_by_pid(document_pid)
         referenced.append(dict(pid_type=DOCUMENT_PID_TYPE, record=document))
 
+    # fetch and index the related order (physical_item_provider)
+    physical_item_provider = docreq.get("physical_item_provider")
+    if physical_item_provider:
+        provider_pid = physical_item_provider.get("pid")
+        provider_pid_type = physical_item_provider.get("pid_type")
+        if provider_pid and provider_pid_type == ORDER_PID_TYPE:
+            order_cls = current_ils_acq.order_record_cls
+            order = order_cls.get_record_by_pid(provider_pid)
+            referenced.append(dict(pid_type=ORDER_PID_TYPE, record=order))
+
     indexer.index(indexed, referenced)
 
 

invenio_app_ils/ext.py

@@ -20,6 +20,7 @@
 )
 
 from .circulation import config as circulation_config
+from .acquisition.indexer import index_stats_fields_for_order
 from .circulation.indexer import (
     index_extra_fields_for_loan,
     index_stats_fields_for_loan,
@@ -224,6 +225,7 @@ def __init__(self, app=None):
             self.init_app(app)
             self.init_metadata_extensions(app)
             self.init_loan_indexer_hook(app)
+            self.init_order_indexer_hook(app)
 
     def init_app(self, app):
         """Flask application initialization."""
@@ -278,6 +280,15 @@ def init_loan_indexer_hook(self, app):
             index="{0}s-{0}-v1.0.0".format("loan"),
         )
 
+    def init_order_indexer_hook(self, app):
+        """Custom order indexer hook init."""
+        before_record_index.dynamic_connect(
+            before_order_index_hook,
+            sender=app,
+            weak=False,
+            index="acq_orders-order-v1.0.0",
+        )
+
     def update_config_records_rest(self, app):
         """Merge overridden circ records rest into global records rest."""
         for k in dir(circulation_config):
@@ -331,3 +342,15 @@ def before_loan_index_hook(sender, json=None, record=None, index=None, **kwargs)
     """
     index_extra_fields_for_loan(json)
     index_stats_fields_for_loan(json)
+
+
+def before_order_index_hook(sender, json=None, record=None, index=None, **kwargs):
+    """Hook to transform order record before ES indexing.
+
+    :param sender: The entity sending the signal.
+    :param json: The dumped Record dict which will be indexed.
+    :param record: The corresponding Record object.
+    :param index: The index in which the json will be indexed.
+    :param kwargs: Any other parameters.
+    """
+    index_stats_fields_for_order(json)

invenio_app_ils/permissions.py

@@ -206,6 +206,7 @@ def __init__(self, record):
 _is_backoffice_read_permission = [
     "stats-most-loaned",
     "stats-loans",
+    "stats-orders",
     "get-notifications-sent-to-patron",
 ]
 _is_patron_owner_permission = [

setup.cfg

@@ -114,6 +114,7 @@ invenio_base.api_apps =
 invenio_base.api_blueprints =
     ils_circulation = invenio_app_ils.circulation.views:create_circulation_blueprint
     ils_circulation_stats = invenio_app_ils.circulation.stats.views:create_circulation_stats_blueprint
+    ils_acquisition_stats = invenio_app_ils.acquisition.stats.views:create_acquisition_stats_blueprint
     ils_ill = invenio_app_ils.ill.views:create_ill_blueprint
     ils_relations = invenio_app_ils.records_relations.views:create_relations_blueprint
     ils_document_request = invenio_app_ils.document_requests.views:create_document_request_action_blueprint

tests/api/conftest.py

@@ -201,6 +201,23 @@ def testdata_loan_histogram(db, testdata):
     return testdata
 
 
+@pytest.fixture()
+def testdata_order_histogram(db, testdata):
+    """Create, index and return test data for orders histogram."""
+    orders_histogram = load_json_from_datadir("acq_orders_histogram.json")
+    recs = _create_records(db, orders_histogram, Order, ORDER_PID_TYPE)
+
+    ri = RecordIndexer()
+    for rec in recs:
+        ri.index(rec)
+
+    current_search.flush_and_refresh(index="acq_orders")
+
+    testdata["orders_histogram"] = orders_histogram
+
+    return testdata
+
+
 @pytest.fixture()
 def item_record(app):
     """Fixture to return an Item payload."""