Paperless-ngx 3.5.0 agiliza los workflows y las tareas masivas
Los workflows manuales y las operaciones masivas asíncronas hacen más práctico automatizar Paperless-ngx desde un homelab.
El atasco no está solo en el OCR
Cuando una instancia de Paperless-ngx empieza a acumular documentos, el trabajo no termina al escanearlos y aplicar OCR. También hay que corregir metadatos, mover documentos entre estados, etiquetar lotes y ejecutar reglas que no siempre encajan en el momento de la importación. Hasta ahora, esas tareas podían convertir una limpieza de biblioteca en una sesión incómoda delante de una interfaz esperando respuestas.
Paperless-ngx 3.5.0 cambia dos piezas importantes de ese flujo: incorpora disparadores manuales para workflows y deriva las operaciones masivas a tareas asíncronas. La combinación tiene sentido para quien usa Paperless como archivo real y no solo como destino de PDFs. Permite separar la selección de documentos del trabajo pesado que debe hacerse después.
Lanzar un workflow cuando toca
Un workflow no tiene por qué depender únicamente de la llegada de un documento, de una actualización o de una programación periódica. Con el disparador manual, puedo preparar una regla para un caso concreto y ejecutarla cuando haya revisado una selección. Es útil cuando el criterio necesita una decisión humana antes de aplicar cambios.
Por ejemplo, puedo localizar facturas que han entrado sin clasificar, comprobar que pertenecen a un proveedor concreto y ejecutar un workflow que asigne etiquetas, tipo documental, ruta de almacenamiento o campos personalizados. El valor no está en automatizar a ciegas, sino en evitar repetir la misma edición documento a documento. El workflow sigue siendo una regla reutilizable, pero ahora puedo decidir cuándo aplicarla.
Los workflows de Paperless-ngx ejecutan acciones de forma secuencial según su orden. Las acciones de asignación posteriores pueden sobrescribir asignaciones anteriores, salvo los datos que admiten varios valores, como etiquetas, campos personalizados o permisos, que se combinan. Conviene diseñar la secuencia con intención antes de lanzar una regla sobre una selección amplia.
Las operaciones masivas pasan a segundo plano
La otra mejora relevante es que las operaciones masivas se entregan de forma asíncrona. En la práctica, la interfaz puede enviar el trabajo a la cola y dejar de esperar a que termine toda la operación para responder. Esto importa cuando se trabaja con colecciones grandes y cuando el servidor ya está ocupado consumiendo documentos, creando archivos de archivo o actualizando índices.
No es una promesa de que cualquier operación vaya a terminar antes. El trabajo sigue necesitando CPU, disco, base de datos y workers disponibles. Lo que cambia es el comportamiento de la interfaz: una acción extensa no debería mantener la pantalla bloqueada mientras Paperless procesa cada documento.
En un homelab esto obliga a mirar de nuevo la capacidad de la cola. Paperless utiliza un broker compatible con Redis para procesar tareas en segundo plano, y PAPERLESS_TASK_WORKERS define cuántas puede ejecutar en paralelo. Subir ese valor sin revisar el consumo de CPU no es una optimización automática, especialmente si también se está haciendo OCR.
Un webhook abre la puerta a Laravel
Las acciones de tipo webhook permiten que un workflow envíe una petición POST a una URL elegida. El cuerpo puede enviarse como JSON o como datos de formulario, admite pares clave-valor y puede incluir cabeceras configuradas en el propio workflow. También se pueden usar plantillas Jinja en el título y en las cargas útiles de los webhooks.
Ahí es donde Laravel encaja bien. Un endpoint pequeño puede recibir el evento, guardar los datos mínimos en una cola propia y decidir qué proceso interno corresponde: sincronizar información con otra aplicación, abrir una revisión, completar una clasificación o llamar después a la API de Paperless-ngx. No hace falta meter toda la lógica de negocio dentro del workflow si Laravel ya es el punto donde concentras automatizaciones del homelab.
Los placeholders documentados permiten enviar referencias útiles sin construir integraciones frágiles. {{ doc_id }} identifica el documento, {{ doc_title }} aporta el título actual y {{ doc_url }} genera la URL del documento en la interfaz cuando PAPERLESS_URL está configurado. También se pueden incluir datos como el remitente, el tipo documental, la fecha de creación o campos personalizados.
Limitar a dónde pueden salir los eventos
Si el webhook de Laravel está publicado detrás de un proxy inverso con HTTPS, conviene limitar los destinos permitidos desde Paperless. Estas variables son configuración real de Paperless-ngx y pueden añadirse al entorno del despliegue Docker. El ejemplo restringe los webhooks a HTTPS por el puerto 443 y evita peticiones hacia direcciones internas.
PAPERLESS_WEBHOOKS_ALLOWED_SCHEMES=https
PAPERLESS_WEBHOOKS_ALLOWED_PORTS=443
PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS=falseNo usaría esta configuración sin pensar si Laravel vive solamente en una red privada. En ese caso, bloquear solicitudes internas impedirá que Paperless contacte con el servicio, y habrá que decidir si se expone el endpoint mediante el proxy o si se permiten expresamente destinos internos. El objetivo es evitar que un workflow con permisos excesivos pueda convertirse en una vía para solicitar recursos de la red local.
La letra pequeña antes de actualizar
Los workflows manuales no sustituyen una estrategia de clasificación. Si no tienes filtros claros, etiquetas consistentes y un orden razonable de acciones, solo tendrás una forma más rápida de aplicar errores a muchos documentos. Antes de lanzar una regla sobre una selección importante, probaría primero con unos pocos documentos que representen casos normales y casos límite.
Los webhooks tampoco convierten Paperless en un bus de eventos completo. La acción envía una petición HTTP, pero Laravel debe ocuparse de validar el acceso al endpoint, registrar fallos, evitar procesados duplicados y enviar el trabajo pesado a una cola. Un controlador que intenta hacer todo durante la petición puede volver a introducir el mismo bloqueo que esta versión evita en Paperless.
También revisaría PAPERLESS_ALLOWED_HOSTS al actualizar. La nota de la versión avisa de que algunas instalaciones pueden necesitar ajustarlo, algo habitual si Paperless está detrás de un dominio propio, un proxy inverso o varios nombres de host. Es una comprobación pequeña, pero puede evitar que la actualización termine en errores de acceso que parecen no tener relación con los workflows.
Para mí, la mejora está menos en el botón manual y más en el cambio de modelo. Paperless-ngx puede seguir siendo el archivo documental, mientras Laravel recibe eventos y ejecuta la lógica específica de cada homelab. Cada herramienta mantiene su responsabilidad y el flujo deja de depender de una interfaz bloqueada por tareas largas.
Fuente de la versión Paperless-ngx v3.5.0 Documentación oficial de workflows