Introduction

Mayan Electronic Document Management System (Mayan EDMS) is an open-source document management platform designed for organizations to efficiently store, organize, and manage digital documents. It offers features such as document versioning, workflow automation, and secure access control.

Mayan DMS File Upload plugin allows users to seamlessly upload and download documents to/from Mayan EDMS. There are three components of this plugin.

• Mayan File Upload - Upload & Download
• Mayan Option Binder - Allows users to populate the values of Document Types, Cabinets and Tags from Mayan EDMS.
• Mayan File Formatter - Allows users to format the filename and download the file directly from the datalist.
  
  

This plugin is created using the REST API REST API — Mayan EDMS Documentation as documented in the Mayan EDMS Documentation to perform RESTful API calls.

Plugin Info

Plugin Available in the Bundle:

1. Mayan DMS File Upload

This plugin bundle is compatible with Joget DX 8.

Expected Outcome

Upon successful configuration, Joget will have the capability to upload files to Mayan EDMS, enabling users to seamlessly upload and download documents to and from the system.

Figure 1: Example of successful integration

Getting Started

Prerequisites

The prerequisite for this plugin is to have Docker installed on your system. Docker is essential because the easiest way to deploy Mayan EDMS is through its official Docker image . Before attempting to install Mayan EDMS, ensure that Docker is properly installed and operational.

Setting up Mayan EDMS

1. Installation Steps

Install Docker:

Open a terminal and run the following command to install Docker.

wget -qO- https://get.docker.com/ | sh

Download the Mayan EDMS Docker Compose files:

Mayan EDMS provides Docker Compose files for easy setup. Run the following commands to download the necessary files:

curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/docker-compose.yml -O
curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/.env -O

These commands will download the docker-compose.yml and .env files required for the Docker Compose setup.

Launch Mayan EDMS using Docker Compose: 

With the Docker Compose files in place, run the following command to start Mayan EDMS:

docker compose up --detach

2. Login to Mayan EDMS

After you have installed Mayan EDMS using Docker and Docker Compose on a Linux system, confirm the installation by accessing the login page.

You can login at http://localhost/authentication/login/.

Once Mayan EDMS has been successfully hosted, you will be able to see the login page (see figure 1).

You can now log in using the automatically generated credentials provided below. Typically, you will find:

• Username: admin
• Email: autoadmin@example.com
• Password: (a generated password)
  
  

Figure 2: Mayan EDMS Login Page

After logging in with the automatically generated credentials, you will see the homepage of Mayan EDMS.

Figure 3: Mayan EDMS Homepage

3. Creating Documents types, Tags, and Cabinets in Mayan EDMS

To efficiently use the Joget integration with Mayan EDMS, you first need to set up your document organizational structure within Mayan EDMS. Here is how to create document types, tags, and cabinets:

Creating a Document Type:

• Click on the 'System' menu in the upper right corner of the Mayan EDMS homepage.
• From the drop-down, select 'Setup'.
  
  
  Figure 4: Mayan EDMS Homepage
  
  
• In the Setup menu, find and click on 'Document types' to manage types of documents.
  
  
  
  Figure 5: Setup Items section
  
  
• In the 'Document types' section, click on the 'Actions' button located at the top-right corner of the screen (Figure 6). 
  
  
  
  Figure 6: Document types section
  
  
• Type the name of the new document type in the 'Label' field.
• Click the 'Save' button to finalize the creation of the new document type.
  
  
  Figure 7: Creating a New Document Type in Mayan EDMS
  
  

Creating a Tag:

• Go to the navigation menu on the left-hand side of the screen.
• Click on the 'Tags' section to expand it, if it is not already expanded.
• Within the 'Tags' section, you will see the option to 'Create new tag.' Click on this option to create a new tag.
  
  
  Figure 8: Tags option
  
  
• After clicking on the create new tag option, in the 'Label' field, enter the name you want to give to your new tag.
• After filling out the details, click the 'Save' button to create your new tag.
  
  
  Figure 9: Create Tag
  
  
• After a new tag has been successfully created in Mayan EDMS, you can see it listed under the 'Tags' section.
• Select 'All' to display all tags that have been created in the system.
• In the list of tags, you will find your newly created tag, labeled as you have named it during creation.
  
  
  Figure 10: View created tags
  
  

Creating a Cabinet:

• Go to the navigation menu on the left-hand side of the screen.
• Click on the 'Cabinets' section to expand it, if it is not already expanded.
  
  
  Figure 11: Cabinets Option
  
  
• Within the 'Cabinets' section, you will see the option to 'Create cabinet.' Click on this option to create a new cabinet.
• After clicking on the Create cabinet option, in the 'Label' field, enter the name you want to give to your new cabinet.
  
  
  Figure 12: Create cabinet
  
  
• After a new cabinet has been successfully created in Mayan EDMS, you can see it listed under the 'Cabinets' section.
• Select 'All' to display all cabinets that have been created in the system.
• In the list of Cabinets, you will find your newly created cabinet, labeled as you have named it during creation.
  
  
  
  Figure 13: View created cabinets
  

We are done with setting up Mayan EDMS. We will now proceed to set up this plugin in Joget.
 

Plugin Setup

1. Obtain the Plugin

Get the plugin jar file from https://github.com/jogetoss/mayan-dms-fileupload

2. Upload the Plugin

Upload the plugin jar file in Joget by going to Settings → Manage Plugins → Upload Plugin

Setup Mayan EDMS Plugin

In the Joget Form Builder, drag and drop three select box form elements onto your form. Name them 'Document Types', 'Cabinets', and 'Tags', respectively. Then, configure each select box to use the Mayan Option Binder, which will populate them with the corresponding document types, tags, or cabinets from Mayan EDMS.




Figure 14: Joget Form Builder (Select Box with Mayan Option Binder)

In the 'Mayan EDMS Settings' section for each select box, navigate to the 'Options' field. Use the dropdown menu to select the corresponding option—'Document Types', 'Tags', or 'Cabinets'—to map the respective data from Mayan EDMS to the select box.

For instance, for the Document types selectbox, in the options field choose document Types (Figure 15).

Figure 15: Map option based on select Box (Document Types)

Similarly for Tag select box choose 'Tags'  in the options field (Figure 16).

Figure 16: Map option based on select Box (Tag)

Mayan Option Binder

Configure Mayan Option Binder

Select Box→ or Load Data From → Mayan Option Binder → Mayan EDMS Settings

Figure 3: Joget Form Builder(Select Box with Mayan Option Binder)

Make sure to apply the basic validator to the 'Document Types' select box.

Document Types Select Box → Advanced Options → Validator → Basic



Figure 4: Mandatory select box Document types

Provide the necessary credentials in the 'Mayan EDMS Settings' section for the three select boxes: 'Document Types', 'Cabinets', and 'Tags'. The credentials include the server URL where Mayan EDMS is hosted, and the username and password for an account with appropriate permissions. These details will enable the plugin to communicate with the Mayan EDMS and function as intended.

Figure 5: Joget Form Builder (Select Box Mayan EDMS Settings Configuration)

Mayan File Upload Plugin Configuration

Configure Mayan File Upload

Drag and drop the Mayan File Upload Element to attach into the form as a form element. More details on default configurations for file upload: File Upload - Knowledge Base for DX 8 - Joget | COMMUNITY

Below are configurations for section "Mayan EDMS Settings" in the Mayan File Upload form element

Enter the automatic credentials previously obtained during the login process for Mayan EDMS in order to establish a connection. In the Fields Mapping section, we can now map the select box fields respectively 

Figure 6: Mayan EDMS Settings for Mayan File Upload form Element

Figure 7: Mayan EDMS Settings 

Mayan File Formatter

Configure Mayan File Formatter

In the datalist builder, we can format the file upload column by using the Mayan File Formatter. Similar configurations can be key in to enable users to download the file directly from datalist.

Below are configurations for section "Configure Mayan EDMS File Formatter":

List --> mayan_file_upload column --> formatter --> Mayan DMS File Formatter 



Figure 8: Mayan EDMS File Formatter Configuration

If you wish to avoid entering the credentials multiple times, you can add them to App variables and then use a hash variable to reference the values. For more information, please refer to App Variable.

Using the Mayan Plugin

After all the configurations have been done, the user can retrieve the Document Types, Cabinets, and Tags from Mayan EDMS in the select boxes, then choose a file to upload.

For Instance if we create a cabinet in the Mayan EDMS, we can retrieve the Cabinets' information in the Cabinets Selectbox see Figure 10.

Figure 9: Create Cabinet in Mayan EDMS

Figure 10: Displaying cabinet information from Mayan EDMS within the Joget form interface

Upload a file

Figure 11: Mayan EDMS UI (Form)

After uploading, we can download the file retrieved from Mayan in the datalist using the formatter.

Figure 12: Mayan EDMS UI (List)

At Mayan EDMS, we can view the file being uploaded. If we modify the file here, we can also get the modified newest file in Joget.

Figure 13: Mayan EDMS Homepage with Uploaded File

To upload multiple files and other file upload features, please visit File Upload - Knowledge Base for DX 8 - Joget | COMMUNITY for further information.

Related Links

• https://docs.mayan-edms.com/apps/rest_api/index.html
• Installation — Mayan EDMS 4.5.2 documentation (mayan-edms.com)
• https://dev.joget.org/community/display/DX8/File+Upload
• https://dev.joget.org/community/display/DX7/Environment+Variable

Sample App

• APP_kb_dx8_MayanEDMS.jwa