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 user to seamlessly upload and download documents to/from Mayan EDMS.  facilitates a seamless process for users to upload documents from Joget to Mayan EDMS. Once uploaded, these documents become accessible within Mayan EDMS, where users can subsequently download them as needed.. There are three components of this plugin.

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

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

Plugin

Info

1. Obtain the Plugin

 Get the plugin jar file from https://github.com/jogetoss/sp-saml-directory-manager

2. Upload the Plugin

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

Expected Outcome

Getting Started

Prerequisites

Setting up Mayan EDMS

The easiest way to use Mayan EDMS is by using the official Docker image. You need to have Docker properly installed and working before attempting to install Mayan EDMS.

Please follow the below instructions to set up Mayan EDMS.

Docker Compose installation

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.

Image Added

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

a. Install Docker:

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

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

b. 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.

c. 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

Image Added

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 

For this example, OpenKM is run on Docker with Linux using Docker Compose.

When you see the following page http://localhost/authentication/login/, it shows that your .

Once Mayan EDMS has been successfully hosted. Login with the automatic credentials shown in the page. 

Image Removed

, you will be able to see the login page (see Figure 3).

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

• Username: admin
• Email: autoadmin@example.com
• Password: (This is automatically generated)

Note that these credentials will remain the same for all subsequent logins unless you update them.

Image Added

Figure 3Figure 4: Mayan EDMS Login Page
 

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

Image Modified

Figure 4: 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'.
  
  Image Added
  
  Figure 5: Mayan EDMS Homepage
  
  

• In the Setup menu, find and click on 'Document types' to manage types of documents.
  
  Image Added
  
  Figure 6: Setup Items section
  
  
• In the 'Document types' section, click on the 'Actions' button located at the top-right corner of the screen (Figure 7). 
  
  Image Added
  
  Figure 7: 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.
  
  Image Added
  
  Figure 8: Creating a New Document Type in Mayan

Configure Mayan Option Binder

Drag three select boxes respectively, known as Document Types, Cabinets, and Tags. For all the three select boxes, use the Mayan Option Binder to load the values respectively from Mayan.

Image Removed
Figure :

Make sure to apply basic validator to the select box Document types. 

Image Removed

Fill in the required credentials for the plugin to work as intended. 

Image Removed

• 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.
  
  Image Added
  
  Figure 9: 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.
  
  Image Added
  
  Figure 10: 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.
  
  Image Added
  
  Figure 11: 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.
  
  Image Added
  
  Figure 12: 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.
  
  Image Added
  
  Figure 13: 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.
  
  Image Added
  
  Figure 14: 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

Download the Mayan DMS Plugin Jar file here https://github.com/jogetoss/mayan-dms-fileupload/releases/tag/8.0.1.
To learn more about the plugin, you can read the documentation 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.

Image Added

Figure 15: 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 option name that matches with your selectbox. This will map the respective data from Mayan EDMS with the selectbox.

For instance, for the Document types selectbox, in the options field choose document Types (Figure 16). Ensure to make this selectbox a required field.

Image Added

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

Similarly for 'Tag ' and 'Cabinets' selectbox, choose 'Tags' and 'Cabinets'  in the Option field dropdown menu respectively.

Next, input the required credentials to all the select boxes to ensure the plugin functions properly (refer to Figure 17). These are the same username and password you use to log into Mayan EDMS, as shown in Figure 3.

Image Added

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

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.

After this, 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 previously obtained credentials during the login process (Figure 3) for Mayan EDMS in order to establish a connection. In the Fields Mapping section, we can now map the select box fields respectively.

Image Added 

Figure 18: Joget Form Builder (Mayan File Upload Element)

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

Image Added

Figure 19: Joget List Builder (Mayan DMS File Formatter)

Mayan File Upload Plugin Demo

Upload File

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

Image Added

Figure 20: Mayan EDMS UI (Form)

Once the file has been uploaded through the Joget, you can verify the document types, tags, and cabinets to which it has been assigned in Mayan EDMS. Additionally, the file can be directly downloaded from within the Mayan EDMS interface.

Image Added

Figure 21: 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.

Image Added

Figure 22:  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.

Delete File

If "Delete Actual File During Overwrite or Removal?" checkbox is checked, when user deletes the file, the actual file in Mayan will also get deleted.

 Image Added

Figure 23:  Delete Actual File During Overwrite or Removal? Config

Click on remove file and save the form again.

Image Added

Figure 24:  Remove file and save form

You will see in Mayan that the document has been removed.

Image Added

Figure 25:  File removed at Mayan

At Joget, the document has also been deleted. Please note that deleting the entire record in datalist does not mean deleting file.

Image Added

Figure 26:  File removed at Joget

 Mayan Option Binder

Mayan File Upload

Properties

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

Image Removed

Image Removed

Figure 9: Required Credentials

Mayan

More details on default configurations for file upload: File Upload - Knowledge Base for DX 8 - Joget | COMMUNITY

DMS

Image Removed

File Formatter

Name	Description
Enable File Download	Checkbox field. If true, enables file download.
Credentials	Header field.
Server URL *	The URL that Mayan EDMS is hosted at. Example: http://localhost
Username *	Mayan EDMS username.
Password *	Mayan EDMS password.

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

.

 

List → mayan column →  formatter →  Mayan DMS File Formatter →Configure Mayan EDMS File Formatter

Image Removed

Figure 9: Joget Form Builder (Mayan File Formatter)

If we do not wish to type If you wish to avoid entering the credentials multiple times, the credentials can also be easily added into environment variables, you can add them to App variables and then use a hash variable to refer to reference the values in environmental variables. For  For more information, please refer to Environment Variable - Knowledge Base for DX 7 - Joget | COMMUNITY.

Using the Mayan Plugin

After all the configurations has 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.

Image Removed

Figure 10: Mayan EDMS UI (Form)

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

Image Removed

Figure 11: 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.

Image Removed

Figure 12: 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.

App Variable.

Source Code and Plugin Download

1. Please visit https://github.com/jogetoss/mayan-dms-fileupload for the plugin's source code.
2. You can find the latest release at https://github.com/jogetoss/mayan-dms-fileupload/releases .
3. Upload the plugin to your Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.

Related Links

• Refer to https

Related Links

• https://docs.mayan-edms.com/apps/rest_api/index.html if you wish to learn more about Mayan EDMS RESTful API.
• Mayan EDMS Installation Website: Installation — Mayan EDMS 4.5.2 documentation (mayan-edms.com)
• File Upload Documentation: https://dev.joget.org/community/display/DX8/File+Uploadhttps://dev.joget.org/community/display/DX7/Environment+Variable
• Refer to App Variable to know more about App Variable.

Sample App

APP_

Kb_dx8_MayanEDMS.jwa