Using Paperless-ngx Apps to access SeedDMS

Unfortunately, there is no native Android App to access SeedDMS. If somebody has some spare time and thinks this has to be changed, then please contact me at info@seeddms.org. I’ll support wherever I can. Well, in the mean time there is another way, which covers at least the basic access on documents stored in SeedDMS. A brand new extension makes SeedDMS behave like a Paperless-ngx server by adding its REST API endpoints. Consequently, the native apps for Paperless-ngx believe they are talking to a Paperless-ngx server while actually talking to a SeedDMS server. Not a perfect solution but amazingly good, which also makes uploads of files from your mobile phone into SeedDMS a lot easier.

The focus of the SeedDMS extension is less on implementing a Paperless-ngx replacement but to be able to use the paperless apps with SeedDMS. Keep this in mind when you are missing a feature of Paperless-ngx.

There are currently three known apps for Paperless-ngx

The last two apps collected a bit of dust (though they are working perfectly). That’s why I would like to focus on the first one.

What is Paperless-ngx

Paperless-ngx is a document management system that transforms your physical documents into a searchable online archive. Its focus is more on scanning documents and storing them in a common flat archive, instead of a folder hierarchy as used by SeedDMS. Documents in Paperless-ngx are mainly organized by correspondents, document types and tags. Tags are similar to categories in SeedDMS, but correspondents and document types have no direct equivalent, but could be mimic with custom attributes (which is currently not implemented). Searching for documents in Paperless-ngx heavily relies on the document content. Hence, the full text search must be turned on in SeedDMS for good search results. Besides the already mentioned app, Paperless-ngx has a web gui for managing the documents, but that will not be covered here.

paperless-mobile

The extension has been tested with paperless-mobile which is an app for Android. In my opinion, it is currently the best app to talk to a Paperless-ngx server. It’s a fairly young project, but covers already many features and is intuitive to use and last but not least good looking. Below are screenshots of paperless-mobile showing a document list, scanning documents and a list of tags.

List of documents Scanning a document List of tags

Installation

  1. First of all make sure you are running at least SeedDMS 6.0.22. Older versions will not work.
  2. Turn on fulltext search and update your index (use sqlitefts)
  3. Next download the latest release of the extension and install it.
  4. You will find an sql file in the extension’s directory (www/ext/paperless) that needs to be imported into your database. Use paperless.sql if you use mysql and paperless-sqlite3.sql for sqlite3.
  5. There are several configuration options, but for now only the folder used as a root folder (any folder in your SeedDMS) and the secret for the json web token (some arbitrary string) must be set.
  6. Download and install the Android app paperless-mobile on your phone or tablet.
  7. Open the app and login with your regular login credentials.

How it works

The nice thing about Paperless-ngx is its REST API, which is used by all the paperless apps including paperless-mobile. The SeedDMS extension implements all required endpoints of that REST API, which lets SeedDMS look like a Paperless-ngx server.

As mentioned earlier, there are similarities between SeedDMS and Paperless-ngx, but there are far more differences. Fortunately, SeedDMS is much more powerful and can mimic the features of Paperless-ngx with just a few drawbacks.

Flat versus hierarchical storage structure

The most obvious difference is the way documents are organized. SeedDMS has a classical folder tree while Paperless-ngx has no hierarchical structure at all. A Paperless app will see a long list of documents which is a full text search below the configured root folder. This list can of course be sorted by the creation date and title of the document. Just like the correspondents and document type. This may change in the future when correspondents and document types can be mapped on custom attributes. There is no way to tell where a document in SeedDMS is actually located, but in many caseŃ• this is irrelevant anyway. Though, it raises the question where uploaded documents are stored. If not explicitly configured an uploaded document will be placed in the configured root folder. Alternatively, the upload folder can be set to any folder in SeedDMS. It could even be a folder outside the configured root folder, which of course can be very confusing for the uploader, if the document successfully uploads but doesn’t show up afterwards. So, in most cases there is probably a dedicated upload folder below the configured root folder.

The extension knows another config option which makes the home folder of the logged in user the root folder used for the app. This effectively separates users from each other, but of course requires to have the home folder set for each user.

No matter how the root or upload folder is set, the access rules in SeedDMS will always be obeyed. Missing write access on the upload folder will prevent the app from uploading documents.

The inbox

Paperless-ngx has a notion of an inbox being a list of documents that need to be looked at. Those documents are just marked with an inbox tag. That’s a regular tag flagged as an inbox tag. There can be actually more than one tag of this kind and a list of them can be set in the extension’s configuration.

Authentication

When starting paperless-mobile the first time, you will be asked to provide a host and your credentials. The host is the URL for SeedDMS’ REST API, e.g. https://my-seeddms/restapi/index.php and the credentials are your regular username and password.

The app will not save your username and password (which is good) but requests a token which is stored by the app. To make things easier on the server side, this token is encrypted and includes the username, password and an expiration date. Hence, it contains all data to identify the user and there is no need to store the token on the server. The encryption key and the life time of the token must be configured for the extension. If no life time is set, it defaults to 365 days. If some day your app reasks for your credentials, then it’s probably because the token expired. Changing the encryption key will instantly invalidate all tokens and users are forced to reauthenticate.

Stuff that does not work

As mentioned above a major difference between Paperless-ngx and SeedDMS is the way documents are organized. There is at first sight no folder hierarchy in Paperless-ngx, but a closer look reveals so called storage paths which are somewhat similar.

While SeedDMS cares little about the type of document, Paperless-ngx has a focus on documents for business communication in general, like invoices, offers, contracts, etc. That influences the set of attributes of a document, which is fixed and consists of

  • tags
  • correspondents
  • document types

Storage path

As long as you use any of the Paperless-ngx apps or the web gui, storage paths appear to be just another attribute. Indeed, they have no impact on how documents are listed. Storage paths only determine how documents are stored on disc. According to the Paperless-ngx documentation, one of the best things is that you can not only access the documents via the web interface, but also via the file system. Without storage paths this feature would almost be unusable, because all documents are stored in one folder on disc. With storage path they can be split up into different path.

There is no sensible equivalent in SeedDMS and I don’t see a need for it. So, just leave it untouched for now when using paperless-mobile.

Document type and correspondent

While tags in Paperless-ngx have an equivalent in categories in SeedDMS, the two other attributes (correspondents, document types) are without an equivalent in SeedDMS. There are plans to map them on custom attributes, but currently they are not used.

Conclusion

The paperless extension for SeedDMS isn’t a perfect solution and covers only a very limit set of operations. But in cases where you need quick access on a document or would like to upload a scanned document, it does a good job. Just give it a try and let me know your comments at info@seeddmsorg.