feat(paperless): add flexible multi-field custom fields mapping

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-02-10 15:00:28 +00:00
parent eeb32ac77f
commit 327244c43a
5 changed files with 130 additions and 19 deletions
@@ -212,11 +212,45 @@ SECURITY_HEADER_CSP_VALUE="default-src 'self'; script-src 'self' https://trusted

 ### Paperless NGX

-| **Variable**                      | **Description**                                                                                     |
-|-----------------------------------|-----------------------------------------------------------------------------------------------------|
-| `PAPERLESS_NGX_API_TOKEN`         | API token for Paperless NGX.                                                                        |
-| `PAPERLESS_HOST`                  | Root URL for Paperless NGX (e.g. `https://paperless.example.com`).                                 |
-| `PAPERLESS_CUSTOM_FIELD_ABSENDER` | (Optional) Name of the custom field in Paperless-ngx to store the sender ("absender") information. If set, the extracted sender will be automatically set as a custom field after document upload. Example: `Absender` or `Sender` |
+| **Variable**                        | **Description**                                                                                     |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `PAPERLESS_NGX_API_TOKEN`           | API token for Paperless NGX.                                                                        |
+| `PAPERLESS_HOST`                    | Root URL for Paperless NGX (e.g. `https://paperless.example.com`).                                 |
+| `PAPERLESS_CUSTOM_FIELD_ABSENDER`   | (Optional, Legacy) Name of the custom field in Paperless-ngx to store the sender ("absender") information. If set, the extracted sender will be automatically set as a custom field after document upload. Example: `Absender` or `Sender` |
+| `PAPERLESS_CUSTOM_FIELDS_MAPPING`   | (Optional, Recommended) JSON mapping of extracted metadata fields to Paperless custom field names. This allows you to map multiple fields at once. Format: `{"metadata_field": "CustomFieldName", ...}`. See examples below. |
+
+#### Custom Fields Mapping Examples
+
+**Single Field (Legacy Method)**:
+```bash
+PAPERLESS_CUSTOM_FIELD_ABSENDER=Absender
+```
+
+**Multiple Fields (Recommended Method)**:
+```bash
+# Map multiple metadata fields to custom fields in Paperless
+PAPERLESS_CUSTOM_FIELDS_MAPPING='{"absender": "Sender", "empfaenger": "Recipient", "language": "Language"}'
+```
+
+**All Available Metadata Fields**:
+DocuElevate extracts the following fields that can be mapped to Paperless custom fields:
+- `absender` - Sender/author of the document
+- `empfaenger` - Recipient of the document
+- `correspondent` - The issuing entity/company (shortened name)
+- `document_type` - Type classification (Invoice, Contract, etc.)
+- `language` - Document language (ISO 639-1 code, e.g., "de", "en")
+- `kommunikationsart` - Communication type (German classification)
+- `kommunikationskategorie` - Communication category (German classification)
+- `reference_number` - Invoice/order/reference number if found
+- `title` - Human-readable document title
+- `tags` - List of thematic keywords (array)
+
+**Complete Example**:
+```bash
+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.

 ### Dropbox

@@ -150,13 +150,44 @@ Depending on the system configuration, DocuElevate can perform:
 If Paperless-ngx is configured, DocuElevate can automatically upload processed documents and set custom fields with extracted metadata:

 1. **Automatic Upload**: After processing, documents are automatically uploaded to Paperless-ngx
-2. **Custom Fields**: If configured via `PAPERLESS_CUSTOM_FIELD_ABSENDER`, the sender ("absender") information extracted by AI will be automatically set as a custom field in Paperless
-3. **Setup Requirements**:
-   - Create a custom field in Paperless-ngx (e.g., named "Absender" or "Sender")
-   - Set the `PAPERLESS_CUSTOM_FIELD_ABSENDER` environment variable to match your custom field name
-   - Ensure the custom field exists in Paperless before processing documents
+2. **Custom Fields Support**: DocuElevate can automatically populate custom fields in Paperless with extracted metadata
+3. **Flexible Field Mapping**: Map any extracted metadata field to any custom field in Paperless

-**Note**: The custom field feature requires that the field is already created in your Paperless-ngx instance. DocuElevate will look up the field by name and set its value automatically.
+#### Setting Up Custom Fields
+
+**Basic Setup (Single Field)**:
+```bash
+# In your .env file
+PAPERLESS_CUSTOM_FIELD_ABSENDER=Absender
+```
+
+**Advanced Setup (Multiple Fields)**:
+```bash
+# Map multiple metadata fields to Paperless custom fields
+PAPERLESS_CUSTOM_FIELDS_MAPPING='{"absender": "Sender", "empfaenger": "Recipient", "language": "Language", "correspondent": "Correspondent"}'
+```
+
+**Available Metadata Fields**:
+- `absender` - Sender/author
+- `empfaenger` - Recipient  
+- `correspondent` - Issuing company (short name)
+- `language` - Document language (e.g., "de", "en")
+- `document_type` - Classification (Invoice, Contract, etc.)
+- `reference_number` - Invoice/order/reference number
+- `kommunikationsart` - Communication type
+- `kommunikationskategorie` - Communication category
+- And more...
+
+**Requirements**:
+- Create the custom fields in Paperless-ngx first (Settings → Custom Fields)
+- The field names in your configuration must exactly match the names in Paperless
+- Ensure `PAPERLESS_HOST` and `PAPERLESS_NGX_API_TOKEN` are configured
+
+**How It Works**:
+1. DocuElevate extracts metadata from your documents using AI
+2. The document is uploaded to Paperless-ngx
+3. After successful upload, custom fields are automatically populated
+4. You can view the populated fields in your Paperless-ngx document details

 ## API Access