Everything appears to be working

docs/consumption.rst

@@ -35,6 +35,42 @@ appropriate for your use and put some documents in there.  When you're ready,
 follow the :ref:`consumer <utilities-consumer>` instructions to get it running.
 
 
+.. _consumption-directory-hook:
+
+Hooking into the Consumption Process
+------------------------------------
+
+Sometimes you may want to do something arbitrary whenever a document is
+consumed.  Rather than try to predict what you may want to do, Paperless lets
+you execute a script of your own choosing every time a document is consumed.
+
+Just write a script, put it somewhere that Paperless can read & execute, and
+then put the path to that script in ``paperless.conf`` with the variable name
+``PAPERLESS_POST_CONSUME_SCRIPT``.
+
+
+.. _consumption-directory-hook-variables
+
+What Can This Script Do?
+........................
+
+It's your script, so you're limited by own imagination and the laws of physics.
+However, the following values are passed to the script in order:
+
+* Document id
+* Generated file name
+* Source path
+* Thumbnail path
+* Download URL
+* Thumbnail URL
+* Correspondent
+* Tags
+
+The script can be in any language you like, but for a simple shell script
+example, you can take a look at ``post-consumption-example.sh`` in the
+``scripts`` directory in this project.
+
+
 .. _consumption-imap:
 
 IMAP (Email)

paperless.conf.example

@@ -32,12 +32,20 @@ PAPERLESS_PASSPHRASE="secret"
 # have a shared secret here.
 PAPERLESS_SHARED_SECRET=""
 
+# After a document is consumed, Paperless can trigger an arbitrary script if
+# you like.  This script will be passed a number of arguments for you to work
+# with.  For more information, please see the documentation.  The default is
+# blank, which means nothing will be executed.
+#PAPERLESS_POST_CONSUME_SCRIPT="/path/to/an/arbitrary/script.sh"
+
+
 #
 # The following values use sensible defaults for modern systems, but if you're
-# running Paperless on a low-resource machine (like a Rasberry Pi), modifying
+# running Paperless on a low-resource machine (like a Raspberry Pi), modifying
 # some of these values may be necessary.
 #
 
+
 # By default, Paperless will attempt to use all available CPU cores to process
 # a document, but if you would like to limit that, you can set this value to
 # an integer:

scripts/post-consumption-example.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+DOCUMENT_FILE_NAME=${1}
+DOCUMENT_SOURCE_PATH=${2}
+DOCUMENT_THUMBNAIL_PATH=${3}
+DOCUMENT_DOWNLOAD_URL=${4}
+DOCUMENT_THUMBNAIL_URL=${5}
+DOCUMENT_ID=${6}
+DOCUMENT_CORRESPONDENT=${7}
+DOCUMENT_TAGS=${8}
+
+echo "
+
+A document with an id of ${DOCUMENT_ID} was just consumed.  I know the
+following additional information about it:
+
+* Generated File Name: ${DOCUMENT_FILE_NAME}
+* Source Path: ${DOCUMENT_SOURCE_PATH}
+* Thumbnail Path: ${DOCUMENT_THUMBNAIL_PATH}
+* Download URL: ${DOCUMENT_DOWNLOAD_URL}
+* Thumbnail URL: ${DOCUMENT_THUMBNAIL_URL}
+* Correspondent: ${DOCUMENT_CORRESPONDENT}
+* Tags: ${DOCUMENT_TAGS}
+
+"

src/documents/apps.py

@@ -8,9 +8,11 @@ class DocumentsConfig(AppConfig):
     def ready(self):
 
         from .signals import document_consumption_finished
-        from .signals.handlers import set_correspondent, set_tags
+        from .signals.handlers import (
+            set_correspondent, set_tags, run_external_script)
 
         document_consumption_finished.connect(set_tags)
         document_consumption_finished.connect(set_correspondent)
+        document_consumption_finished.connect(run_external_script)
 
         AppConfig.ready(self)

src/documents/signals/handlers.py

@@ -1,5 +1,9 @@
 import logging
 
+from subprocess import Popen
+
+from django.conf import settings
+
 from ..models import Correspondent, Tag
 
 
@@ -51,3 +55,21 @@ def set_tags(sender, document=None, logging_group=None, **kwargs):
     )
 
     document.tags.add(*relevant_tags)
+
+
+def run_external_script(sender, document, **kwargs):
+
+    if not settings.POST_CONSUME_SCRIPT:
+        return
+
+    Popen((
+        settings.POST_CONSUME_SCRIPT,
+        document.file_name,
+        document.source_path,
+        document.thumbnail_path,
+        document.download_url,
+        document.thumbnail_url,
+        str(document.id),
+        str(document.correspondent),
+        str(",".join(document.tags.all().values_list("slug", flat=True)))
+    )).wait()

src/paperless/settings.py

@@ -227,6 +227,9 @@ PASSPHRASE = os.getenv("PAPERLESS_PASSPHRASE")
 # the API.
 SHARED_SECRET = os.getenv("PAPERLESS_SHARED_SECRET", "")
 
+# Trigger a script after every successful document consumption?
+POST_CONSUME_SCRIPT = os.getenv("PAPERLESS_POST_CONSUME_SCRIPT")
+
 #
 # TODO: Remove after 0.2
 #