Here is a guide on how I set up mobile push notifications to my android phone whenever a document is consumed in paperless-ngx. This saves me the hassle of logging in to make sure documents were processed successfully, especially when those documents are coming from less-than-reliable clients like all-in-one printers.
For this setup I am using MQTT for messaging, Home Assistant for the push notifications, and Node-RED to glue it all together. You could easily substitute other protocols if needed (HTTP instead of MQTT, Telegram instead of Home Assistant, ...).
I have paperless-ngx hosted in docker on a Debian VM. This will not work for a bare-metal installation of paperless-ngx.
How it works
Paperless-ngx exposes hooks into the document consumption process. In particular, we will use the post-consumption hook to run a bash script. The process works like this:
Upload document to paperless-ngx
Document is queued and processed by paperless-ngx
Post-consumption script executes, publishes a JSON summary of the document to the MQTT broker.
Node-RED consumes the message from the MQTT broker and uses the Home Assistant notify service to push out the notification.
Set up MQTT Client
First, we need to add the MQTT client so that paperless-ngx can publish messages to our broker.
Create a new file Dockerfile at the same location as docker-compose.env. This allows us to build our own container with Mosquitto installed on top of the latest paperless-ngx image.
Now, edit docker-compose.yml so that it builds from the Dockerfile instead of using the paperless-ngx image.
Post-consumption Script
Now we can add our script to publish new document messages to the MQTT broker. Make a new scripts directory next to docker-compose.yml and add a new file post-consumption.sh. Replace the host, username, and password arguments according to your configuration.
After saving the script, make sure to make the file executable.
$ chmod ug+x post-consumption.sh
Now, we need to mount the scripts folder so that the post-consumption script is available to the container. We do this by adding a new volume to docker-compose.env. Then we tell paperless about the script by setting the PAPERLESS_POST_CONSUME_SCRIPT environment variable.
Node-RED Subscriber
Next, we can jump over to Node-RED and see the messages flowing in on our new MQTT topic. Add a new mqtt in node and set the topic to /paperless/post-consumption, then run that node into a debug node.
Now, try uploading a document to paperless and check the debug output. You should get a JSON payload populated with data from the new document.
This payload should be all you need to set up all kinds of automations in Home Assistant. Note that you can also use the REST API to pull in even more details from paperless.
Mobile App Push Notifications
Here is how I automated push notifications to my Android device.
This works by subscribing to our new MQTT topic, downloading the thumbnail to Home Assistant local storage, then publishing the notification using the notify service.
Tapping the notification opens the document in the paperless-ngx web interface where I can quickly review the upload and set up the tags.
Thanks for reading!
Thank you for visiting. Support my work by buying me a coffee!