From 8165d7b2a6d17b065e7dd1e4182f444d897e082e Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Wed, 13 May 2026 21:09:43 +0000 Subject: [PATCH] docs(n8n): version school intake workflow artifacts --- docs/operations/SCHOOL_PAPERLESS_INTAKE.md | 30 +++++++++++++++---- ...n => 18-school-paperless-intake-v1.0.json} | 5 ++-- ...less-school-metadata-enrichment-v1.0.json} | 5 ++-- n8n-workflows/README.md | 18 ++++++++--- 4 files changed, 45 insertions(+), 13 deletions(-) rename n8n-workflows/{18-school-paperless-intake.json => 18-school-paperless-intake-v1.0.json} (98%) rename n8n-workflows/{19-paperless-school-metadata-enrichment.json => 19-paperless-school-metadata-enrichment-v1.0.json} (98%) diff --git a/docs/operations/SCHOOL_PAPERLESS_INTAKE.md b/docs/operations/SCHOOL_PAPERLESS_INTAKE.md index 406229c..5922fd1 100644 --- a/docs/operations/SCHOOL_PAPERLESS_INTAKE.md +++ b/docs/operations/SCHOOL_PAPERLESS_INTAKE.md @@ -1,13 +1,22 @@ # School Paperless Intake Workflow -Workflows: -- `n8n-workflows/18-school-paperless-intake.json` -- `n8n-workflows/19-paperless-school-metadata-enrichment.json` +Current workflow versions: +- `n8n-workflows/18-school-paperless-intake-v1.0.json` +- `n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json` -This workflow is meant for a Telegram chat-driven upload pipeline that sends schoolwork into Paperless-NGX while recording intake metadata in shared Postgres. +This workflow set is meant for a Telegram chat-driven upload pipeline that sends schoolwork into Paperless-NGX while recording intake metadata in shared Postgres. + +## Versioning rule + +When these workflow artifacts change, the version must change too: +- the filename keeps a `-vX.Y` suffix +- the internal n8n workflow `name` also carries the same version +- docs and testing notes should reference the current version explicitly ## What it does +### Workflow 18 — v1.0 + 1. Accepts a multipart upload at `POST /webhook/school/intake/upload` 2. Requires form fields: - `class_name` @@ -46,6 +55,10 @@ PAPERLESS_DOCUMENT_TYPE_SCHOOL= PAPERLESS_TAG_SCHOOL= PAPERLESS_TAG_ASSIGNMENTS= PAPERLESS_TAG_TELEGRAM= +PAPERLESS_TAG_CLASS_MAP_JSON={} +PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON={} +PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON={} +PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON={} NODE_FUNCTION_ALLOW_BUILTIN=crypto ``` @@ -59,12 +72,17 @@ Add to the `n8n` service `environment:` block in `automation/docker-compose.yaml PAPERLESS_TAG_SCHOOL: ${PAPERLESS_TAG_SCHOOL} PAPERLESS_TAG_ASSIGNMENTS: ${PAPERLESS_TAG_ASSIGNMENTS} PAPERLESS_TAG_TELEGRAM: ${PAPERLESS_TAG_TELEGRAM} + PAPERLESS_TAG_CLASS_MAP_JSON: ${PAPERLESS_TAG_CLASS_MAP_JSON} + PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON: ${PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON} + PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON: ${PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON} + PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON: ${PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON} NODE_FUNCTION_ALLOW_BUILTIN: crypto ``` Notes: - `PAPERLESS_CORRESPONDENT_SCHOOL` and `PAPERLESS_DOCUMENT_TYPE_SCHOOL` should be numeric IDs if you want those fields auto-assigned. -- Leave optional Paperless IDs blank if you prefer Paperless rules to classify later. +- `PAPERLESS_TAG_CLASS_MAP_JSON`, `PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON`, `PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON`, and `PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON` are optional JSON maps used by workflow 19. +- Leave optional Paperless IDs and JSON maps blank/default if you prefer to start with deterministic title + generic tags only. - `NODE_FUNCTION_ALLOW_BUILTIN=crypto` is required because the Code node hashes the uploaded file. - `N8N_BLOCK_ENV_ACCESS_IN_NODE` must remain `false`. @@ -80,6 +98,8 @@ Workflow 18 deliberately keeps the Paperless upload minimal and safe: The deterministic filename/title preserve the `intake_id` for later correlation. +### Workflow 19 — v1.0 + Workflow 19 handles the follow-up metadata pass after Paperless finishes processing: - fetch Paperless document by webhook document id - resolve `intake_id` from the stored filename diff --git a/n8n-workflows/18-school-paperless-intake.json b/n8n-workflows/18-school-paperless-intake-v1.0.json similarity index 98% rename from n8n-workflows/18-school-paperless-intake.json rename to n8n-workflows/18-school-paperless-intake-v1.0.json index 548586b..a562507 100644 --- a/n8n-workflows/18-school-paperless-intake.json +++ b/n8n-workflows/18-school-paperless-intake-v1.0.json @@ -1,5 +1,5 @@ { - "name": "Telegram School Intake → Postgres → Paperless", + "name": "Telegram School Intake → Postgres → Paperless v1.0", "active": false, "isArchived": false, "nodes": [ @@ -217,7 +217,8 @@ }, "staticData": null, "meta": { - "templateCredsSetupCompleted": false + "templateCredsSetupCompleted": false, + "artifactVersion": "v1.0" }, "pinData": {}, "tags": [ diff --git a/n8n-workflows/19-paperless-school-metadata-enrichment.json b/n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json similarity index 98% rename from n8n-workflows/19-paperless-school-metadata-enrichment.json rename to n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json index 5e65849..28164dd 100644 --- a/n8n-workflows/19-paperless-school-metadata-enrichment.json +++ b/n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json @@ -1,5 +1,5 @@ { - "name": "Paperless School Intake Metadata Enrichment", + "name": "Paperless School Intake Metadata Enrichment v1.0", "active": false, "isArchived": false, "nodes": [ @@ -274,7 +274,8 @@ }, "staticData": null, "meta": { - "templateCredsSetupCompleted": false + "templateCredsSetupCompleted": false, + "artifactVersion": "v1.0" }, "pinData": {}, "tags": [ diff --git a/n8n-workflows/README.md b/n8n-workflows/README.md index e628eee..506c02d 100644 --- a/n8n-workflows/README.md +++ b/n8n-workflows/README.md @@ -15,8 +15,8 @@ | 14 | Paperless Inbox Reminder | Scheduled (Monday 9 AM) | Queries Paperless for untagged documents; sends Gotify reminder with oldest items listed, or a ✅ clear if inbox is empty | | 15 | n8n Self-Health Monitor | Scheduled (every 15 min) | Checks n8n execution history for failures in the past hour; deduplicates via Postgres; pushes Gotify alert with workflow name and error summary | | 16 | NFS Mount Watchdog | Scheduled (every 5 min) | Probes NFS mount points on PD; if missing: runs mount script, re-probes, restarts affected containers (Plex, Audiobookshelf, Immich); notifies via Gotify on heal or escalation | -| 18 | Telegram School Intake → Postgres → Paperless | `POST /webhook/school/intake/upload` | Accepts multipart schoolwork uploads plus class/assignment metadata, writes an intake record to shared Postgres, then uploads into Paperless with deterministic `intake_id` in the filename/title | -| 19 | Paperless School Intake Metadata Enrichment | `POST /webhook/school/intake/paperless-enrich` | Handles Paperless post-consumption webhooks, looks up the intake record by deterministic filename, then applies deterministic title/tags and optional document-type/correspondent mapping | +| 18 | Telegram School Intake → Postgres → Paperless v1.0 | `POST /webhook/school/intake/upload` | Accepts multipart schoolwork uploads plus class/assignment metadata, writes an intake record to shared Postgres, then uploads into Paperless with deterministic `intake_id` in the filename/title | +| 19 | Paperless School Intake Metadata Enrichment v1.0 | `POST /webhook/school/intake/paperless-enrich` | Handles Paperless post-consumption webhooks, looks up the intake record by deterministic filename, then applies deterministic title/tags and optional document-type/correspondent mapping | ## How to Import @@ -289,9 +289,9 @@ curl -X POST https://n8n.paccoco.com/webhook/git/push \ }' ``` -## Workflow 18 — Telegram School Intake → Postgres → Paperless +## Workflow 18 — Telegram School Intake → Postgres → Paperless v1.0 -Import `18-school-paperless-intake.json` for a chat-driven schoolwork intake flow. Supporting notes live at `docs/operations/SCHOOL_PAPERLESS_INTAKE.md` and the tracked schema lives at `docs/reference/SCHOOL_INTAKE_POSTGRES_SCHEMA.sql`. +Import `18-school-paperless-intake-v1.0.json` for a chat-driven schoolwork intake flow. Supporting notes live at `docs/operations/SCHOOL_PAPERLESS_INTAKE.md` and the tracked schema lives at `docs/reference/SCHOOL_INTAKE_POSTGRES_SCHEMA.sql`. Highlights: - multipart upload endpoint: `POST /webhook/school/intake/upload` @@ -303,6 +303,16 @@ Highlights: Testing fixture: - `fixtures/school-paperless-intake-webhook.curl.example.txt` +## Workflow Versioning Convention + +For n8n workflow artifacts in this repo: +- include the version in the **filename** (example: `18-school-paperless-intake-v1.0.json`) +- include the version in the workflow's internal **`name`** field +- bump the version whenever behavior, schema expectations, webhook payload handling, or env requirements change +- update `n8n-workflows/README.md` and `n8n-workflows/TESTING-STATUS.md` when introducing a new workflow version + +Do not overwrite a workflow artifact with silent behavior changes and no version bump. That way lies confusion and sweaty guesswork. Ha ha. + ## Customizing RSS Feeds (Workflow 06) Edit the "Define RSS Feeds" Code node to add/remove feeds. Default feeds: