Merge pull request #54 from openagri-eu/main

arruda · web-flow · commit 14c2c2537625 · 2025-10-15T11:13:51.000+02:00
Implemented script and added example datasets (#12)
diff --git a/README.md b/README.md
@@ -222,6 +222,11 @@ This will run the tests and return success values for each api tested in the ter
 
 <h3>These tests will NOT result in generated .pdf files.</h3>
 
+## Working examples
+You can find working examples for animal, irrigation as well as compost reports generation in the following pages:
+
+[Script](scripts/report_client.py)
+
 ## Contributing
 
 We welcome first-time contributions!
diff --git a/scripts/animal_data.json b/scripts/animal_data.json
@@ -0,0 +1,40 @@
+{
+  "@graph": [
+    {
+      "@id": "urn:ngsi-ld:FarmAnimal:bessie-001",
+      "name": "Bessie",
+      "description": "Holstein cow, record created upon purchase.",
+      "species": "Bos taurus",
+      "sex": 1,
+      "birthdate": "2022-04-12",
+      "isCastrated": false,
+      "status": 1,
+      "hasAgriParcel": {
+        "@id": "urn:ngsi-ld:AgriParcel:parcel-uuid-001"
+      },
+      "isMemberOfAnimalGroup": {
+        "hasName": "Main Herd"
+      },
+      "dateCreated": "2025-10-09T10:00:00Z",
+      "invalidatedAtTime": null
+    },
+    {
+      "@id": "urn:ngsi-ld:FarmAnimal:clover-002",
+      "name": "Clover",
+      "description": "Jersey cow, born on farm.",
+      "species": "Bos taurus",
+      "sex": 1,
+      "birthdate": "2023-01-15",
+      "isCastrated": false,
+      "status": 1,
+      "hasAgriParcel": {
+        "@id": "urn:ngsi-ld:AgriParcel:parcel-uuid-002"
+      },
+      "isMemberOfAnimalGroup": {
+        "hasName": "Main Herd"
+      },
+      "dateCreated": "2025-10-09T11:00:00Z",
+      "invalidatedAtTime": null
+    }
+  ]
+}
diff --git a/scripts/compost_data.json b/scripts/compost_data.json
@@ -0,0 +1,64 @@
+{
+  "@graph": [
+    {
+      "@id": "urn:ngsi-ld:CompostTurningOperation:op-b42-20251010",
+      "@type": "CompostTurningOperation",
+      "title": "Monthly Compost Check",
+      "details": "Regular check and turning of compost pile B-42.",
+      "hasStartDatetime": "2025-10-10T08:00:00Z",
+      "hasEndDatetime": "2025-10-10T09:00:00Z",
+      "responsibleAgent": "John Doe",
+      "isOperatedOn": {
+        "@id": "urn:ngsi-ld:CompostPile:cp-b42"
+      },
+      "hasAgriParcel": {
+        "@id": "urn:ngsi-ld:AgriParcel:parcel-for-compost-b42"
+      },
+      "usesAgriculturalMachinery": [
+        {
+          "@id": "urn:ngsi-ld:AgriculturalMachinery:tractor-01"
+        }
+      ],
+      "hasMeasurement": [
+        {
+          "hasMember": [
+            {
+              "@id": "urn:ngsi-ld:CropObservation:obs-temp-001",
+              "@type": "CropObservation",
+              "type": "observed",
+              "phenomenonTime": "2025-10-10T08:15:00Z",
+              "observedProperty": "temperature",
+              "hasResult": {
+                "@id": "urn:ngsi-ld:Property:result-temp-001",
+                "@type": "Property",
+                "hasValue": "62",
+                "unit": "CEL"
+              },
+              "details": "Core temperature reading."
+            }
+          ]
+        }
+      ],
+      "hasNestedOperation": [
+        {
+          "@id": "urn:ngsi-ld:AddRawMaterialOperation:raw-mat-001",
+          "@type": "AddRawMaterialOperation",
+          "type": "raw",
+          "hasStartDatetime": "2025-10-10T08:30:00Z",
+          "details": "Added fresh green waste.",
+          "hasCompostMaterial": [
+            {
+              "@type": "CompostMaterial",
+              "typeName": "Grass Clippings",
+              "quantityValue": {
+                "@type": "QuantitativeValue",
+                "numericValue": "150",
+                "unit": "KGM"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/scripts/irrigation_data.json b/scripts/irrigation_data.json
@@ -0,0 +1,32 @@
+{
+  "@graph": [
+    {
+      "@id": "urn:ngsi-ld:IrrigationOperation:op-001",
+      "@type": "IrrigationOperation",
+      "operatedOn": {
+        "@id": "urn:ngsi-ld:AgriParcel:parcel-north-42"
+      },
+      "hasStartDatetime": "2025-10-11T09:00:00Z",
+      "hasEndDatetime": "2025-10-11T12:30:00Z",
+      "hasAppliedAmount": {
+        "numericValue": 150,
+        "unit": "Cubic Meter"
+      },
+      "usesIrrigationSystem": "Center Pivot Irrigation"
+    },
+    {
+      "@id": "urn:ngsi-ld:IrrigationOperation:op-002",
+      "@type": "IrrigationOperation",
+      "operatedOn": {
+        "@id": "urn:ngsi-ld:AgriParcel:parcel-south-15"
+      },
+      "hasStartDatetime": "2025-10-10T14:00:00Z",
+      "hasEndDatetime": "2025-10-10T16:00:00Z",
+      "hasAppliedAmount": {
+        "numericValue": 75,
+        "unit": "Cubic Meter"
+      },
+      "usesIrrigationSystem": "Drip Irrigation System"
+    }
+  ]
+}
diff --git a/scripts/readme.md b/scripts/readme.md
@@ -0,0 +1,68 @@
+This command-line script (report_client.py) provides a simple way to interact with the Reporting service. It allows you to request the generation of three different types of reports (animal, irrigation, or compost) by uploading a corresponding JSON data file.
+
+The script handles the entire workflow:
+
+    It sends the initial request to start the PDF generation process.
+
+    It waits and periodically checks the server's status.
+
+    Once the PDF is ready, it downloads the file to the same directory where the script is run.
+
+Prerequisites
+
+    Python 3.6+
+
+    The requests library. If you don't have it, install it via pip:
+
+    pip install requests
+
+    A valid authentication token from the reporting service.
+
+    A correctly formatted JSON data file for the report you wish to generate.
+
+Usage
+
+The script is run from your terminal and accepts four command-line arguments.
+```
+python3 report_client.py --type <REPORT_TYPE> --token <YOUR_TOKEN> --file <PATH_TO_JSON> [--url <SERVICE_URL>]
+```
+Command-Line Arguments
+
+
+| Argument | Required | Description |
+|----------|----------|----|
+| --type   | Yes      | The type of report to generate. Must be one of animal, irrigation, or compost.  |
+| --token  | Yes      | Your personal authentication bearer token for the service. |
+| --file   | Yes      | The relative or absolute path to the JSON file containing the data for the report. |
+| --url    | No       | The base URL of the reporting service. If not provided, it defaults to http://127.0.0.1:8009. |
+
+Example Commands
+Animal Report
+```
+python3 report_client.py --type animal --token "your-auth-token-here" --file "./animal_data.json"
+```
+Irrigation Report
+```
+python3 report_client.py --type irrigation --token "your-auth-token-here" --file "data/irrigation_data.json"
+```
+Compost Report (with a custom URL)
+```
+python3 report_client.py --type compost --token "your-auth-token-here" --file "compost.json" --url "http://api.myfarm.com"
+```
+How It Works
+
+    Generate Report: The script sends a POST request to the appropriate endpoint (e.g., /api/v1/openagri-report/animal-report/) with your token and JSON file. The server accepts the request and returns a unique uuid for the report job.
+
+    Download PDF: The script then enters a loop, sending GET requests to the retrieval endpoint (e.g., /api/v1/openagri-report/<uuid>/).
+
+        If the server responds with status 202 Accepted, it means the PDF is still being created, and the script waits a few seconds before trying again.
+
+        If the server responds with 200 OK, the PDF is ready. The script writes the content to a new file named <uuid>.pdf.
+
+        The script will retry up to 10 times before timing out.
+
+Important Notes
+
+    The success of the report generation depends entirely on providing a correctly formatted JSON file. If the server's validation fails, the PDF generation will fail.
+
+    The final PDF file will be saved in the same directory from which you execute the script.
diff --git a/scripts/report_client.py b/scripts/report_client.py
@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+import requests
+import time
+import os
+import argparse
+
+# --- Configuration ---
+# Maximum number of times to check for the PDF before giving up
+MAX_RETRIES = 10
+# Seconds to wait between check attempts
+RETRY_DELAY_SECONDS = 3
+
+# USAGE EXAMPLES:
+
+# python report_client.py --type animal --token "your-long-auth-token-here" --file "path/to/animal_data.json"
+# python report_client.py --type irrigation --token "your-long-auth-token-here" --file "data/irrigation_payload.json"
+# python report_client.py --type compost --token "your-long-auth-token-here" --file "compost.json" --url "http://localhost:5000"
+
+# --- End Configuration ---
+
+def generate_report(report_type: str, base_url: str, token: str, json_file: str) -> str | None:
+    """
+    Calls the appropriate report endpoint and returns the report UUID.
+
+    Args:
+        report_type: The type of report ('animal', 'irrigation', 'compost').
+        base_url: The base URL of the reporting service.
+        token: The authentication bearer token.
+        json_file: The path to the JSON data file to upload.
+
+    Returns:
+        The report UUID string if successful, otherwise None.
+    """
+    # The API endpoint is dynamically constructed from the report_type
+    report_url = f"{base_url}/api/v1/openagri-report/{report_type}-report/"
+    print(f"➡️  Attempting to generate '{report_type}' report from '{json_file}'...")
+
+    headers = {
+        "Authorization": f"Bearer {token}"
+    }
+
+    try:
+        with open(json_file, 'rb') as f:
+            # The API expects the file in a multipart/form-data request
+            files = {
+                "data": (os.path.basename(json_file), f, "application/json")
+            }
+            response = requests.post(report_url, headers=headers, files=files)
+            response.raise_for_status()  # Raises an exception for 4XX/5XX errors
+
+        response_data = response.json()
+        report_uuid = response_data.get("uuid")
+
+        if not report_uuid:
+            print("❌ Report generation failed: 'uuid' not found in the server response.")
+            return None
+
+        print(f"✅ Report generation started successfully. Report ID: {report_uuid}")
+        return report_uuid
+
+    except FileNotFoundError:
+        print(f"❌ Error: The data file '{json_file}' was not found.")
+        return None
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Report generation failed: {e}")
+        if e.response is not None:
+            print(f"   Server Response ({e.response.status_code}): {e.response.text}")
+        return None
+
+
+def download_pdf(report_uuid: str, base_url: str, token: str):
+    """
+    Polls the retrieval endpoint and downloads the generated PDF.
+    """
+    print(f"⏳ Attempting to download PDF for report ID: {report_uuid}...")
+    pdf_url = f"{base_url}/api/v1/openagri-report/{report_uuid}/"
+
+    headers = {
+        "Authorization": f"Bearer {token}"
+    }
+
+    for attempt in range(MAX_RETRIES):
+        try:
+            print(f"   Attempt {attempt + 1}/{MAX_RETRIES}... ", end="", flush=True)
+            response = requests.get(pdf_url, headers=headers)
+
+            if response.status_code == 202:
+                print(f"PDF is still being generated. Retrying in {RETRY_DELAY_SECONDS}s...")
+                time.sleep(RETRY_DELAY_SECONDS)
+                continue
+
+            response.raise_for_status()
+
+            output_filename = f"{report_uuid}.pdf"
+            with open(output_filename, 'wb') as f:
+                f.write(response.content)
+                f.flush()
+                os.fsync(f.fileno())
+
+            print(f"\n🎉 PDF downloaded successfully! Saved as '{output_filename}'")
+            return
+
+        except requests.exceptions.RequestException as e:
+            print(f"\n❌ Failed to download PDF: {e}")
+            if e.response is not None:
+                print(f"   Server Response ({e.response.status_code}): {e.response.text}")
+            return
+
+    print(
+        f"\n❌ Failed to retrieve PDF after {MAX_RETRIES} attempts. The report might still be processing or an error occurred on the server.")
+
+def main():
+    """
+    Main function to parse arguments and run the reporting process.
+    """
+    parser = argparse.ArgumentParser(
+        description="A command-line client to generate and download PDF reports from the reporting service.",
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=['animal', 'irrigation', 'compost'],
+        help="The type of report to generate."
+    )
+    parser.add_argument(
+        "--token",
+        required=True,
+        help="Your authentication bearer token."
+    )
+    parser.add_argument(
+        "--file",
+        required=True,
+        help="Path to the JSON data file to upload."
+    )
+    parser.add_argument(
+        "--url",
+        default="http://127.0.0.1:8009",
+        help="The base URL of the reporting service. (default: http://127.0.0.1:8009)"
+    )
+
+    args = parser.parse_args()
+
+    report_id = generate_report(args.type, args.url, args.token, args.file)
+    if report_id:
+        download_pdf(report_id, args.url, args.token)
+
+
+if __name__ == "__main__":
+    main()
