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 %}