feat(paperless): add support for setting absender custom field

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

.env.demo

@@ -117,6 +117,10 @@ NEXTCLOUD_PASSWORD=<NEXTCLOUD_PASSWORD>
 # Paperless-ngx
 PAPERLESS_HOST=https://paperless.example.com
 PAPERLESS_NGX_API_TOKEN=<PAPERLESS_API_TOKEN>
+# Optional: Name of the custom field in Paperless-ngx to store the "absender" (sender) value
+# If set, the extracted sender information will be automatically set as a custom field in Paperless
+# Example: PAPERLESS_CUSTOM_FIELD_ABSENDER=Absender
+# PAPERLESS_CUSTOM_FIELD_ABSENDER=
 
 # Dropbox
 DROPBOX_APP_KEY=<DROPBOX_APP_KEY>

app/config.py

@@ -31,6 +31,7 @@ class Settings(BaseSettings):
     # Making Paperless optional
     paperless_ngx_api_token: Optional[str] = None
     paperless_host: Optional[str] = None
+    paperless_custom_field_absender: Optional[str] = None  # Name or ID of the "absender" custom field in Paperless
 
     azure_ai_key: str
     azure_region: str

app/tasks/upload_to_paperless.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import json
 import logging
 import os
 import time
@@ -78,10 +79,85 @@ def poll_task_for_document_id(task_id: str) -> int:
     raise TimeoutError(f"Task {task_id} didn't reach SUCCESS within {POLL_MAX_ATTEMPTS} attempts.")
 
 
+def get_custom_field_id(field_name: str) -> int:
+    """
+    Retrieves the ID of a custom field by its name from Paperless-ngx.
+
+    Args:
+        field_name: The name of the custom field to look up
+
+    Returns:
+        The integer ID of the custom field
+
+    Raises:
+        ValueError: If the custom field is not found
+    """
+    url = _paperless_api_url("/api/custom_fields/")
+    try:
+        resp = requests.get(url, headers=_get_headers(), timeout=settings.http_request_timeout)
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Handle paginated response
+        results = data.get("results", []) if isinstance(data, dict) else data
+
+        for field in results:
+            if field.get("name") == field_name:
+                return field.get("id")
+
+        raise ValueError(f"Custom field '{field_name}' not found in Paperless-ngx")
+    except requests.exceptions.RequestException as exc:
+        logger.error(f"Failed to retrieve custom fields from Paperless: {exc}")
+        raise
+
+
+def set_document_custom_fields(doc_id: int, custom_fields: dict, task_id: str) -> None:
+    """
+    Updates custom fields for a document in Paperless-ngx using PATCH.
+
+    Args:
+        doc_id: The Paperless document ID
+        custom_fields: Dictionary mapping field names to values
+        task_id: Task ID for logging
+    """
+    if not custom_fields:
+        return
+
+    # Build custom_fields array for PATCH request
+    custom_fields_array = []
+    for field_name, value in custom_fields.items():
+        if value and value != "Unknown":  # Only set non-empty, non-Unknown values
+            try:
+                field_id = get_custom_field_id(field_name)
+                custom_fields_array.append({"field": field_id, "value": value})
+                logger.info(f"[{task_id}] Mapped custom field '{field_name}' to ID {field_id} with value '{value}'")
+            except ValueError as e:
+                logger.warning(f"[{task_id}] {str(e)}, skipping this field")
+                continue
+
+    if not custom_fields_array:
+        logger.info(f"[{task_id}] No valid custom fields to set")
+        return
+
+    # PATCH the document with custom fields
+    url = _paperless_api_url(f"/api/documents/{doc_id}/")
+    payload = {"custom_fields": custom_fields_array}
+
+    try:
+        logger.info(f"[{task_id}] Setting custom fields for document {doc_id}: {payload}")
+        resp = requests.patch(url, headers=_get_headers(), json=payload, timeout=settings.http_request_timeout)
+        resp.raise_for_status()
+        logger.info(f"[{task_id}] Successfully set custom fields for document {doc_id}")
+    except requests.exceptions.RequestException as exc:
+        logger.error(f"[{task_id}] Failed to set custom fields for document {doc_id}: {exc}")
+        # Don't raise - this is a non-critical failure, document is already uploaded
+        logger.error(f"[{task_id}] Response: {getattr(exc.response, 'text', '<no response>')}")
+
+
 @celery.task(base=BaseTaskWithRetry, bind=True)
 def upload_to_paperless(self, file_path: str, file_id: int = None):
     """
-    Uploads a file to Paperless-ngx.
+    Uploads a file to Paperless-ngx and sets custom fields from metadata.
 
     Args:
         file_path: Path to the file to upload
@@ -113,6 +189,20 @@ def upload_to_paperless(self, file_path: str, file_id: int = None):
         log_task_progress(task_id, "upload_to_paperless", "failure", error_msg, file_id=file_id)
         raise ValueError(error_msg)
 
+    # Try to load metadata from accompanying JSON file
+    metadata = {}
+    json_path = os.path.splitext(file_path)[0] + ".json"
+    if os.path.exists(json_path):
+        try:
+            with open(json_path, "r", encoding="utf-8") as f:
+                metadata = json.load(f)
+            logger.info(f"[{task_id}] Loaded metadata from {json_path}")
+        except Exception as e:
+            logger.warning(f"[{task_id}] Failed to load metadata from {json_path}: {e}")
+            metadata = {}
+    else:
+        logger.info(f"[{task_id}] No metadata file found at {json_path}")
+
     # Upload the PDF
     logger.info(f"[{task_id}] Posting document to Paperless")
     log_task_progress(task_id, "post_document", "in_progress", "Posting to Paperless API", file_id=file_id)
@@ -153,6 +243,24 @@ def upload_to_paperless(self, file_path: str, file_id: int = None):
         task_id, "upload_to_paperless", "success", f"Uploaded to Paperless: Doc ID {doc_id}", file_id=file_id
     )
 
+    # Set custom fields if configured and metadata available
+    if settings.paperless_custom_field_absender and metadata.get("absender"):
+        logger.info(f"[{task_id}] Setting custom fields for document {doc_id}")
+        log_task_progress(task_id, "set_custom_fields", "in_progress", "Setting custom fields", file_id=file_id)
+
+        # Prepare custom fields to set
+        custom_fields_to_set = {}
+        if settings.paperless_custom_field_absender:
+            custom_fields_to_set[settings.paperless_custom_field_absender] = metadata.get("absender")
+
+        try:
+            set_document_custom_fields(doc_id, custom_fields_to_set, task_id)
+            log_task_progress(task_id, "set_custom_fields", "success", "Custom fields set", file_id=file_id)
+        except Exception as e:
+            logger.error(f"[{task_id}] Failed to set custom fields: {e}")
+            log_task_progress(task_id, "set_custom_fields", "failure", f"Failed: {str(e)}", file_id=file_id)
+            # Don't fail the entire upload if custom fields fail
+
     return {
         "status": "Completed",
         "paperless_task_id": raw_task_id,