From 6fe4fa59666f68e5584d24370d8313f8f56ad3ae Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Mon, 14 Jul 2025 21:18:50 +0200 Subject: [PATCH 1/9] extended paperless ngx docs - example, use case, troubleshooting, data updates, known limitations --- source/_integrations/paperless_ngx.markdown | 74 +++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index ab10ea8274cf..58ab084f873c 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -54,6 +54,16 @@ Verify SSL certificate: description: "Verify the SSL certificate of the Paperless-ngx instance. Disable this option if you're using a self-signed certificate." {% endconfiguration_basic %} +## Use cases + +The integration can be used to build automations to help and notify you of new documents in your paperless instance. +The update sensor could notify you if a new paperless-ngx version is available. + +## Supported functionality + +The Paperless-ngx intergation provides statistic and diagnostic entities to Home Assistant. +Below is an overview of these entities and their function. + ## Sensors This integration provides {% term sensors %} for the following information from Paperless-ngx: @@ -76,9 +86,73 @@ This integration provides {% term sensors %} for the following information from | **Status sanity** | Indicates the sanity of the Paperless-ngx documents. | | **Software** | Indicates whether a new Paperless-ngx update ist available. | +## Example automations + +{% details "Send a push notification if a new document is available" %} +{% raw %} + +```yaml +alias: New document push notification +description: Sends a push notification if a new document is available +triggers: + - entity_id: sensor.paperless_documents_inbox + to: null + trigger: state +conditions: + - condition: template + value_template: | + {% if trigger.from_state is not none and trigger.to_state is not none %} + {{ trigger.to_state.state > trigger.from_state.state }} + {% else %} + false + {% endif %} +actions: + - action: notify.mobile_app_ + metadata: {} + data: + message: A new document is available. +``` + +{% endraw %} +{% enddetails %} + +## Data Updates + +This integration retrieves data using a pull-based mechanism. + +- **Statistic sensors** are pulled every **120 seconds** +- **Diagnostic sensors** are pulled every **300 seconds** +- **Update checks** to detect new Paperless-ngx versions are performed **every 24 hours** + +## Known limitations + +There are a few known limitations for using the integration: +- This integration is only fully supported with **Paperless-ngx version 2.15 or later**. Earlier versions are not supported. +- To enable monitoring of diagnostic sensors, you must have **administrator permissions**. Without administrator rights, specific API endpoints cannot be accessed, and the sensor states will not be available. ## Removing the integration This integration follows standard integration removal. No extra steps are required. {% include integrations/remove_device_service.md %} + +## Troubleshooting + +{% details "Invalid hostname or IP address" %} +Make sure you enter a complete URL, such as `https://192.168.178.11:8011`. + +SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. + +If you're using a self-signed certificate, disable the **Verify SSL certificate** option. +{% enddetails %} + +{% details "The token does not have permission to access the API" %} +In this case, verify whether the token is still valid and correctly assigned to the user. + +You can also test the token using the Swagger interface available at +`https://example.com/api/schema/view/` + +Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**, then try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. + +If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an HTTP 403 error. If so, the integration may also report this as a permission issue. +{% enddetails %} From bfeaaee5ffbdf8c7d101866f4782b81c75c57d9d Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Mon, 14 Jul 2025 21:26:03 +0200 Subject: [PATCH 2/9] Minor changes --- source/_integrations/paperless_ngx.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 58ab084f873c..84ecbb5a9809 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -61,7 +61,7 @@ The update sensor could notify you if a new paperless-ngx version is available. ## Supported functionality -The Paperless-ngx intergation provides statistic and diagnostic entities to Home Assistant. +The Paperless-ngx integration provides statistic and diagnostic entities to Home Assistant. Below is an overview of these entities and their function. ## Sensors From 2a9b83367f13e4952068666e76cc9ae4f289f069 Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Mon, 14 Jul 2025 21:43:51 +0200 Subject: [PATCH 3/9] Minor fixes --- source/_integrations/paperless_ngx.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 84ecbb5a9809..b4836abd229f 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -139,7 +139,7 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting {% details "Invalid hostname or IP address" %} -Make sure you enter a complete URL, such as `https://192.168.178.11:8011`. +Make sure you enter a complete URL, such as `https://paperless.example.com` or `http://192.168.178.11:8011`. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. @@ -150,7 +150,7 @@ If you're using a self-signed certificate, disable the **Verify SSL certificate* In this case, verify whether the token is still valid and correctly assigned to the user. You can also test the token using the Swagger interface available at -`https://example.com/api/schema/view/` +`https://paperless.example.com/api/schema/view/` Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**, then try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. From ca7f8159a9ee8dd799ccdca16eb1d755afebfb32 Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Mon, 14 Jul 2025 22:04:26 +0200 Subject: [PATCH 4/9] Minor fixes --- source/_integrations/paperless_ngx.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index b4836abd229f..71fbfe6c1040 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -139,7 +139,7 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting {% details "Invalid hostname or IP address" %} -Make sure you enter a complete URL, such as `https://paperless.example.com` or `http://192.168.178.11:8011`. +Make sure you enter a complete URL, such as `https://​paperless.example.com` or `https://​192.168.178.11:8011`. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. @@ -154,5 +154,5 @@ You can also test the token using the Swagger interface available at Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**, then try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. -If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an HTTP 403 error. If so, the integration may also report this as a permission issue. +If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an **HTTP 403 error**. If so, the integration may also report this as a permission issue. {% enddetails %} From cc59c4bbd7caa4f9959553a02c2bc4b4a25e9e34 Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Mon, 14 Jul 2025 22:45:48 +0200 Subject: [PATCH 5/9] fixes --- source/_integrations/paperless_ngx.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 71fbfe6c1040..3096c3225df0 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -139,7 +139,7 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting {% details "Invalid hostname or IP address" %} -Make sure you enter a complete URL, such as `https://​paperless.example.com` or `https://​192.168.178.11:8011`. +Make sure you enter a complete URL, such as `https://paperless.example.com/` or `https://192.168.178.11:8011/`. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. From 204409555026c75119ceb1cc8a5805d4c3a2148e Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Sat, 26 Jul 2025 10:59:29 +0000 Subject: [PATCH 6/9] Last fixed --- source/_integrations/paperless_ngx.markdown | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 3096c3225df0..48bbfeafb964 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -107,7 +107,7 @@ conditions: false {% endif %} actions: - - action: notify.mobile_app_ + - action: notify.mobile_app_iphone metadata: {} data: message: A new document is available. @@ -127,6 +127,7 @@ This integration retrieves data using a pull-based mechanism. ## Known limitations There are a few known limitations for using the integration: + - This integration is only fully supported with **Paperless-ngx version 2.15 or later**. Earlier versions are not supported. - To enable monitoring of diagnostic sensors, you must have **administrator permissions**. Without administrator rights, specific API endpoints cannot be accessed, and the sensor states will not be available. @@ -139,14 +140,17 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting {% details "Invalid hostname or IP address" %} -Make sure you enter a complete URL, such as `https://paperless.example.com/` or `https://192.168.178.11:8011/`. + +Make sure you enter a complete URL, such as `https://paperless.example.com` or `https://192.168.178.11:8011`. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. If you're using a self-signed certificate, disable the **Verify SSL certificate** option. + {% enddetails %} {% details "The token does not have permission to access the API" %} + In this case, verify whether the token is still valid and correctly assigned to the user. You can also test the token using the Swagger interface available at @@ -155,4 +159,5 @@ You can also test the token using the Swagger interface available at Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**, then try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an **HTTP 403 error**. If so, the integration may also report this as a permission issue. + {% enddetails %} From 5c21f09019e7edcfdd1921bb223184cafd275109 Mon Sep 17 00:00:00 2001 From: Florian von Garrel Date: Wed, 30 Jul 2025 17:17:32 +0000 Subject: [PATCH 7/9] Changed troubleshooting to steps; minor changes --- source/_integrations/paperless_ngx.markdown | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 48bbfeafb964..a7f4a7df78db 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -116,7 +116,7 @@ actions: {% endraw %} {% enddetails %} -## Data Updates +## Data updates This integration retrieves data using a pull-based mechanism. @@ -139,25 +139,25 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting -{% details "Invalid hostname or IP address" %} +{% details "If you get the message 'Invalid hostname or IP address', try the following steps:"" %} -Make sure you enter a complete URL, such as `https://paperless.example.com` or `https://192.168.178.11:8011`. +1. Make sure you enter a complete URL, such as `https://paperless.example.com` or `https://192.168.178.11:8011`. -SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. +2. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. -If you're using a self-signed certificate, disable the **Verify SSL certificate** option. +3. If you're using a self-signed certificate, disable the **Verify SSL certificate** option. {% enddetails %} -{% details "The token does not have permission to access the API" %} +{% details "If you get the message 'The token does not have permission to access the API', try the following steps:" %} -In this case, verify whether the token is still valid and correctly assigned to the user. +1. Verify whether the token is still valid and correctly assigned to the user. -You can also test the token using the Swagger interface available at +2. Test the token using the Swagger interface available at `https://paperless.example.com/api/schema/view/` + - Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**. + - Then, try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. -Click on **"Authorize"** in the Swagger UI to enter your token at **tokenAuth (apiKey)**, then try accessing the relevant endpoints like `/api/statistics/` to ensure they respond as expected. - -If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an **HTTP 403 error**. If so, the integration may also report this as a permission issue. +3. If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an **HTTP 403 error**. If so, the integration may also report this as a permission issue. {% enddetails %} From ea0b7fc99f73d9c71eb87c3bf5e86db233147073 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Thu, 31 Jul 2025 06:08:45 +0200 Subject: [PATCH 8/9] tiny tweak --- source/_integrations/paperless_ngx.markdown | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index a7f4a7df78db..4c2902baf6de 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -139,8 +139,9 @@ This integration follows standard integration removal. No extra steps are requir ## Troubleshooting -{% details "If you get the message 'Invalid hostname or IP address', try the following steps:"" %} +{% details "Message: 'Invalid hostname or IP address'" %} +If you get the message **Invalid hostname or IP address**, try the following steps: 1. Make sure you enter a complete URL, such as `https://paperless.example.com` or `https://192.168.178.11:8011`. 2. SSL is enabled by default. If you're using an unencrypted connection, you must explicitly use `http://` instead of `https://` in the URL. @@ -149,8 +150,9 @@ This integration follows standard integration removal. No extra steps are requir {% enddetails %} -{% details "If you get the message 'The token does not have permission to access the API', try the following steps:" %} +{% details "Message: 'The token does not have permission to access the API'" %} +If you get the message **The token does not have permission to access the API**, try the following steps: 1. Verify whether the token is still valid and correctly assigned to the user. 2. Test the token using the Swagger interface available at From ac50f488f3de87546492d90b231aafd1cbd466a5 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Thu, 31 Jul 2025 09:01:17 +0200 Subject: [PATCH 9/9] Update source/_integrations/paperless_ngx.markdown --- source/_integrations/paperless_ngx.markdown | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/_integrations/paperless_ngx.markdown b/source/_integrations/paperless_ngx.markdown index 4c2902baf6de..97646eb4cf29 100644 --- a/source/_integrations/paperless_ngx.markdown +++ b/source/_integrations/paperless_ngx.markdown @@ -163,3 +163,9 @@ If you get the message **The token does not have permission to access the API**, 3. If everything works correctly in Swagger but the integration still fails, check whether a reverse proxy (e.g., NGINX) is returning an **HTTP 403 error**. If so, the integration may also report this as a permission issue. {% enddetails %} + +## Removing the integration + +This integration follows standard integration removal, no extra steps are required. + +{% include integrations/remove_device_service.md %} pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy