refactor: improve code quality and documentation clarity

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

app/tasks/upload_to_paperless.py

@@ -16,7 +16,8 @@ logger = logging.getLogger(__name__)
 
 POLL_MAX_ATTEMPTS = 10
 POLL_INTERVAL_SEC = 3
-UNKNOWN_VALUE = "Unknown"  # Magic value used to indicate missing metadata
+# Sentinel value used to indicate missing/unknown metadata that should not be set as custom fields
+METADATA_UNKNOWN_PLACEHOLDER = "Unknown"
 
 
 def _get_headers():
@@ -35,6 +36,25 @@ def _paperless_api_url(path: str) -> str:
     return f"{host}{path}"
 
 
+def normalize_metadata_value(value) -> str:
+    """
+    Normalizes a metadata value to a string suitable for Paperless custom fields.
+
+    Args:
+        value: The metadata value to normalize
+
+    Returns:
+        Empty string if value should be excluded, otherwise the string representation
+    """
+    if value is None:
+        return ""
+    str_value = str(value)
+    # Exclude empty strings and the "Unknown" placeholder
+    if not str_value or str_value == METADATA_UNKNOWN_PLACEHOLDER:
+        return ""
+    return str_value
+
+
 def poll_task_for_document_id(task_id: str) -> int:
     """
     Polls /api/tasks/?task_id=<uuid> until we get status=SUCCESS or FAILURE,
@@ -127,13 +147,14 @@ def set_document_custom_fields(doc_id: int, custom_fields: dict, task_id: str) -
     # Build custom_fields array for PATCH request
     custom_fields_array = []
     for field_name, value in custom_fields.items():
-        # Ensure value is a string for consistent comparison
+        normalized_value = normalize_metadata_value(value)
-        str_value = str(value) if value is not None else ""
+        if normalized_value:  # Only set non-empty values
-        if str_value and str_value != UNKNOWN_VALUE:  # Only set non-empty, non-Unknown values
             try:
                 field_id = get_custom_field_id(field_name)
-                custom_fields_array.append({"field": field_id, "value": str_value})
+                custom_fields_array.append({"field": field_id, "value": normalized_value})
-                logger.info(f"[{task_id}] Mapped custom field '{field_name}' to ID {field_id} with value '{str_value}'")
+                logger.info(
+                    f"[{task_id}] Mapped custom field '{field_name}' to ID {field_id} with value '{normalized_value}'"
+                )
             except ValueError as e:
                 logger.warning(f"[{task_id}] {str(e)}, skipping this field")
                 continue

docs/ConfigurationGuide.md

@@ -250,7 +250,7 @@ DocuElevate extracts the following fields that can be mapped to Paperless custom
 PAPERLESS_CUSTOM_FIELDS_MAPPING='{"absender": "Sender", "empfaenger": "Recipient", "correspondent": "Correspondent", "language": "Language", "reference_number": "ReferenceNumber"}'
 ```
 
-**Note**: Custom fields must be created in your Paperless-ngx instance before DocuElevate can use them. The field names in the mapping (right side of the JSON) must exactly match the names in Paperless.
+**Note**: Custom fields must be created in your Paperless-ngx instance before DocuElevate can use them. The field names in the mapping (right side of the JSON) must **exactly** match the names in Paperless (case-sensitive).
 
 ### Dropbox