Integration of Paperless NGX

[szaiser]

What is the problem you are trying to solve with this feature?

More powerful document handling with help of Paperless NGX
I currently manage documents (e.g., manuals, bills, warranty information) in Paperless NGX. I’d like to fully use Homebox for asset management while also maintaining Paperless NGX’s strengths (OCR, document preview, advanced tagging, global search, etc.).

A native integration between Homebox and Paperless NGX would let users manage their assets and related documents in a frictionless way, playing to each tool’s strengths. This approach would allow asset data to remain authoritative in Homebox, while document management continues to benefit from Paperless NGX’s rich features.

What is the solution you are proposing?

Link Homebox assets to Paperless NGX e.g. via Tags

Introduce a “Paperless Tag” field within Homebox. For each asset in Homebox, users could define one or more Paperless tags. Additionally, Homebox needs some way of authenticating with Paperless. Using a token could work.

For the implementation, we could go step by step:

• Step 1: Minimum scope implementation
  Homebox uses the tag(s) to automatically create links to the paperless documents in the Homebox attachement area. My current assumption is, that given experience with both Homebox and Paperless NGX Api, this can be done in a few days.

• Step 2: Additional document Preview
  In addition to a link, the document is downloaded and previewed with a file viewer, e.g. when hovering over the link. A caching mechanism could be useful here.

• Step 3: Deeper integration with Paperless NGX
  Here I begin to dream a bit and hope that we can actually get a preview object from Paperless and therefore would not even need to cache or download. This feature could work similarly to the way some code editors let you peak preview the code definitions that are in another files. I would not know how to do this at this point.

Possible enhancement
Automatically map Paperless Tags to Homebox labels, thereby completely removing manual steps required in Homebox.

Advantages

• Retains Paperless NGX’s OCR, powerful search, and document previews.
• Centralizes asset data in Homebox, which is better suited for asset management.
• Reduces duplicate effort: we avoid manually moving or re-processing documents.
• Scales nicely as new documents come in or new assets are created—just apply the relevant tag(s).

I welcome any input on how best to integrate these two systems and would be happy to collaborate on an implementation.

What alternatives have you considered?

Right now, I see two options:

• Option (1) Move all documents to Homebox: This would force me to give up Paperless NGX’s strong document-centric features (OCR, previews, advanced tags, searching).
• Option (2) Leave documents in Paperless and link from Homebox: Continue to manage documents in Paperless NGX, tag relevant documents with the Homebox asset name, and link back from Homebox to Paperless.

Option (1) seems too disruptive, since I’d lose the specialized document workflows and search capabilities. Option (2) is workable, but it involves manual tagging and linking without deeper integration.

Additional context

No response

Contributions

• I have searched through existing issues and feature requests to see if my idea has already been proposed.
• If this feature is accepted, I would be willing to help implement and maintain this feature.
• If this feature is accepted, I'm willing to sponsor the development of this feature.

[saschabrockel]

I often think very carefully about the link between Paperless and HomeBox myself. That would be a dream. My current workflow is such that when I buy something new, for example, I have redundancy. Whether this is absolutely necessary remains to be seen.

Example for an iPhone:
I upload the invoice to Paperless with the relevant correspondent (in this case, Apple) and my tags. I then add the iPhone to its storage location in HomeBox and manually enter the invoice data, such as the price and purchase date.

I think even a direct reference to Paperless could be great. In other words, you can enter your Paperless BASE_URL and then the number of the document so that you can jump directly to it and perhaps delete old invoices or archive items in the inventory using webhooks, depending on which system is to be the leading one.

[ados8]

Agreed, there's lots of ways to implement this and some is a bigger implementation than others.
It would be really nice to have the option to make an object in HomeBox and then have a scan Paperless button.
It could scan for the title and maybe description and show you a list, allowing you to select the document which then links to the object.
Currently, the process is painfully manual for me.

1. Documents added to Paperless via consumption
2. Add new object in Homebox
3. Search for that object in Paperless and enter the purchase company, cost and date
4. Then add a new a new custom field Paperless with the URL to the document. It's also annoying that you can't save/have a global custom field. Why do I have to type out the name every time 😅.

[ados8]

I'm not sure how possible it would be, likely very impossible, to have the price added; the most you could add is the date.
It would be very hard for Homebox to know what cost is right when there's multiple prices in a document.
Maybe you could have it show some suggestions but it would then need to recognise costs and then grab some words before and after, giving you a list to then select the correct cost to which it then needs to extract the value 🫤.

[szaiser]

Document suggestion and info-extract mechanisms (homebox <- paperless) for me steps that build onto a clean linking mechanism (homebox -> paperless).
Order

1. allow to link documents
2. auto suggest linkable documents based on
   a) rules (manual but clean)
   b) llm (requires a user feedback mechanism)
3. auto extract information from these linked documents.

[ados8]

Again, the linking is about the only practical solution.
Having costs and other data extracted would require an LLM. Now you're asking for users to pay for API calls to a cloud AI provider or have high end hardware to handle local LLM processing. I'm not against features which can just be options, just outlining the complexity.

[szaiser]

Agreed, I misread your comment as wanting to have further capabilities. My goal would be linking to and integration of paperless with homebox. Everything else will be optional and to be seen.