Mayan EDMS version 3.1 "papercuts" released

Mon, Sep 17, 2018


Why is this release called “Papercuts”?

Papercuts are a special kind of “bug” in software. It is not really a bug in the practical sense as it doesn’t stop the software from working. It doesn’t cause data loss or system errors either. It is just something the software does or doesn’t do that is annoying, breaks the flow of actions or interferes with the user experience.

This release as with all others brings all manner of updates to the backend in terms of features or improvement to existing feature but also focused in fixing (or at least improving) some of Mayan’s user interface “papercuts”.

The full release notes are available here:

What follows is a summary of the biggest changes in this release:

Client side caching of images

Caching is a technique where a calculated file, in this case a preview or a thumbnail is generated and retained after used. If this file is needed again it doesn’t need to be generated again. The problem with caching thumbnails in Mayan is knowing when not to use the cached file because the original content may have been changed. Maybe a new version was uploaded or a transformation was applied.

This inability to know when to use and not to use a cached thumbnail is what prevented the implementation of this feature long requested. This is a common issue in software development and is know as cache invalidation.

Thanks to the latest updates in the document image generator we are able to implement this feature in a way that is invisible to the user.

Document images are now generated and along with a hash. A hash is an unique identifier for a file. By using a hash we are able to determine is the cached thumbnail is still valid and can be reused or if the browser needs to download a more recent version of the thumbnail from the server.

The end result of this feature is the speed at which often visited document views with images will display. The images should display almost instantly with and will not incur in network traffic.

By default the browser is instructed to cache these images for 1 year. This does not mean the file will be cache for a whole year filling the user’s hard drive but that the browser should regard the cached image “valid” for a year. The browser’s internal caching policies will delete it at any moment the cache size threshold is triggered.

This default 1 year retention time can be changed with the DOCUMENTS_PAGE_IMAGE_CACHE_TIME setting. Cache invalidation happens automatically so there is no need to clear the browser’s cache when images change.


Web-based setting editor

Another big change included in this release is the web based configuration system. While still available, it is no longer necessary to create and modify Python setting files. Almost all configuration changes can now be performed from the browser. Changes are stored in a YAML encoded file in the media folder. Users can also provide their own YAML configuration file. Changes still require a restart of the Mayan service process, there is still no way around this as it is a design decision of Django, the we framework used by Mayan. We are exploring methods to improve this.


Custom installation titles

A frequently request feature by systems integrator is being able to change the title of the project to rebrand their offerings. This can now be easily achieved with the COMMON_PROJECT_TITLE setting.


Database conversions

Many updates were added to the models to improve how data was exported and improved. This means that converting from a database manager to another has a much higher rate of success than before, using Django’s dumpdata and loaddata. We’ve also added a custom command named convertdb that handles the entire process of database conversion. We will be adding a documentation change and/or a wiki section on different methods to do this.

More events

Many more events are now tracked and available for subscription or as triggers for workflows. A link for the events of specific of an object (metadata, tags,etc) was also addded.



ACL support was added to more objects in the system allowing for administration delegation. Some examples: Metadata types, Message of the day, settings and indexes.


Dynamic menu

The main menu at the top of the screen now refreshes when there are changes in the available objects in the system. For example: If there are not tags available the view all tags menu item is not displayed, only the create tag menu entry. As soon one tag is created the menu updates and the view all tags is also available. This refreshing/updating intelligence also extends to permissions and access controls. If an user doesn’t have permission to view any of the available tags, the view tags menu entry will not be displayed. If that same user is granted access to a tag, the menu updates accordingly. This feature reduces confusion form users that see a menu entry but see the permission denied page when they try to access those menus.


Sorted menus

The actions and links in most views are also now sorted alphabetically. This breaks the previous groupings by function but our testing indicated that users preferred alphabetically sorted links as they were easier to scan visually and find in a hurry.

Self documenting

In other to make Mayan more self documenting we’ve added help messages in many views. Instead of a staring at a blank screen and having to open a tab to browse the documentation, the view will now display an icon, a short explanation of the view or the objects it should display and the most common links that will affect that view.


Restrict password change

It now possible to disable password changes. This is useful when your installation has an guest or demo account meant to be used by many users.

Dashboard customization

While they’ve remained visually the same, the dashboard widgets have been refactored to support many new features like access checking, custom templates and custom renderers. It is now possible to customize the dashboard widgets to display not just text but graphics and charts too. This release added the code changes and if no problems are reported subsequent versions will add the visual changes to the widgets.

Access new documents

Besides the existing menu entry to view the recently accessed documents. A new entry was added to view the newly uploaded documents. By default the 40 most recently added documents are shown but this number can be changed with the DOCUMENTS_RECENT_ADDED_COUNT setting.

We also added support for favorite documents. Each user can add up to 40 documents in their own favorite list. This number can be changed with the DOCUMENTS_FAVORITE_COUNT setting.


Fill color for transformations

It is now possible to specify a fill color for the empty space that is created when adding rotation transformation.


Per page OCR results

We made it possible to view the OCR results for each page of a document. In the document page view a link name OCR was added that will switch the view to show the OCR results for the page being browsed.


Extended compressed file support

In addition to the existing Zip file support, users can now do bulk document uploads using archives in Tar, Bzip and Gzip formats.


These are the biggest features added but there many other small improvements and additions in many other areas. The release notes detailing all of these can be found in here: