Knowledge Base
  • Select Role
  • English
  • Login

OpenKM DMS Plugin

Introduction

The OpenKM Document Management System (DMS) plugin facilitates the seamless integration of OpenKM and Joget. This integration currently utilises a few plugin types:

  • Datalist Formatter: Format datalist file upload column to download file from OpenKM directly.
  • File Upload Element: Upload files to OpenKM. Bind folder paths from the select box field that uses the Form Options Binder. Able to choose whether to create a folder that follows Joget form ID when uploading.
  • Form Options Binder: Retrieve folder paths from OpenKM.

The plugin is created using RESTful Guide - OpenKM Documentation to perform RESTful API calls on OpenKM.

Plugin information

Plugin Available in the Bundle:

  1. OpenKM DMS Datalist Formatter
  2. OpenKM DMS File Upload
  3. OpenKM DMS Form Options Binder

This plugin bundle is compatible with Joget DX 8.

Getting started

Prerequisites

1. Java 8 Environment

In order to successfully install OpenKM, Java 8 is an essential prerequisite that must be present on the system environment, which can be downloaded from the Oracle Official Website. This version of Java provides the necessary runtime environment for OpenKM to operate effectively and efficiently. Without Java 8, the installation process may encounter errors or fail altogether, rendering OpenKM unusable.

2. OpenKM Community Version

The OpenKM Community Version JAR file can be obtained from the official OpenKM Website using the OpenKM Community Version Download button. This official source ensures users access the software's most up-to-date and authentic version, safeguarding against potential security risks and ensuring compatibility with existing systems.

3. OpenKM Database

OpenKM is able to integreate with MySQL, PostgreSQL, Oracle or SQL Server. In this article, you will be using MySQL as the OpenKM database.

Where to get the plugin

You can download the OpenKM DMS plugin from the JogetOSS Github Repository.

How to install

  1. Click Download on this plugin screen (It will be a .jar file).
  2. Go to your Joget localhost or server. In the Joget Console, go to Admin Bar > Systems Settings > Manage Plugins and click the Upload Plugins button.
  3. Under Upload Plugin, select the plugin .jar file you downloaded and click Upload.
  4. Depending on the plugin type, you can now view your new plugin in your form, List, or UI Builder.
  5. Remember to uninstall the old plugin before uploading a new version.
  6. The Joget Knowledge Base has more information on managing and developing plugins.

Setting up OpenKM DMS

1. OpenKM Installer Setup

To set up the OpenKM installer, open Command Prompt as Administrator and open the file directory where you stored the OpenKM installer.
In the command prompt, use java—jar OKMInstaller.jar to start installing OpenKM. After entering the command, it will display the output as shown below, and you can enter the configuration you prefer. 
OpenKM installation will automatically install Tomcat in the current path directory. After successfully installing OpenKM, it will display a SUCCESS: Specified value was saved. with a database query to create the database, user and password based on the information entered in the above image.


Copy & Paste
Copy and paste the query during MySQL setup in step 2.
CREATE DATABASE okmdb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_bin;
CREATE USER openkm@localhost IDENTIFIED BY 'YourPassword';
GRANT ALL ON okmdb.* TO openkm@localhost WITH GRANT OPTION;

As a confirmation of a successful installation, open Services in the computer's system and search for OpenKM:

2. MySQL Setup

Access the root database to execute the query in step 1 to create an okmdb database.



Go to Server > Users and Privileges, select the newly created User, and check all the following boxes to give the User full database privileges. Failure to do so will create an error when trying to access the OpenKM browser.


Create a new connection and enter all the information set in step 1.

3. OpenKM.cfg First Time User Setup

For first time user, an error will occur when accessing OpenKM local browser because there is no existing UUID for the current user. To prevent this error from occurring, we will need to create a UUID when loading the browser. To do so we will make some configuration in the Tomcat folder.
Open Tomcat folder > OpenKM.cfg in IDE(Visual Studio code, Intellij, etc.) and make small changes in a line of code:

Before

# OpenKM Hibernate configuration values
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
hibernate.hbm2ddl=none
 
# Logback configuration file
logback.config=logback.xml
 
# LibreOffice configuration
system.openoffice.program=D:/Joget/QA/OpenKM/OKM/tomcat-8.5.69/extras/LibreOffice/App/libreoffice/program/soffice.exe

After

# OpenKM Hibernate configuration values
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
hibernate.hbm2ddl=create //change in this line from "none" to "create"
 
# Logback configuration file
logback.config=logback.xml
 
# LibreOffice configuration
system.openoffice.program=D:/Joget/QA/OpenKM/OKM/tomcat-8.5.69/extras/LibreOffice/App/libreoffice/program/soffice.exe

4. OpenKM server and shutdown port changes

OpenKM Server and Shutdown Port needs to be changed since Joget's default ports will populate the same ports which prevents OpenKM from running. Thus, we need to configure the ports in the server.xml file.

Go to Tomcat folder > conf > server.xml

Server Port

<Connector port="8180" address="0.0.0.0" protocol="HTTP/1.1"
               connectionTimeout="20000" redirectPort="8443"/>

Shutdown Port

<Server port="8006" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener"/>
Tomcat Service
Restarting the Tomcat Service is necessary for changes made in the server.xml file to be reflected before launching the OpenKM browser.

OpenKM in runtime

To access the OpenKM browser, ensure that the service is running as outlined in Step 1. Open OpenKM in the browser with http://localhost:{Port}/OpenKM.

The following page shows that your OpenKM has been successfully hosted. The default login credentials are okmAdmin with the password admin.

After logging in, you will see the homepage of OpenKM.

Set up OpenKM plugin

  1. First, drag a select box and use the OpenKM DMS Form Options Binder to load the folder paths from OpenKM.
  2. Fill in the required credentials for the plugin to work as intended. 
    The Root Folder UUID can be retrieved from the OpenKM folder that you want to configure as the root folder.

  3. Drag and drop the OpenKM DMS File Upload tool into the form as a form element. Enter the OpenKM Configurations with the necessary details. If the OpenKM credentials are invalid, an Authentication ERROR will be shown in the element.

    When configuring the Field Mapping, the Field for OpenKM Folder Path Upload must point to the file path created in the above image; if no fields are mapped, the default file path will be /okm:root.
  4. In the List Builder, you can format the file upload column using the OpenKM DMS Datalist Formatter. Similar configurations can be key in to enable users to download the file directly from datalist. Ensure the file path fields are in the datalist (can be configured to be hidden if we do not wish to show, but it must be there). If field mapping is not configured, the default file path is /okm:root.
  5. If you do not wish to type the credentials multiple times, they can be easily added to environment variables. Then, you can use a hash variable to refer to the values in environmental variables. For more information, see App Variable.

OpenKM plugin demo

Upload file
  1. After all the configurations have been done, the user can retrieve the folder paths from OpenKM in the select box and choose a file to upload.
  2. After uploading, you can view the latest file path to which the file has been uploaded and also download the file retrieved from OpenKM.
  3. You can view the file being uploaded at OpenKM DMS. If we modify the file here, you can also get the modified newest file in Joget.
  4. To upload multiple files and other file upload features, see File Upload for further information.
Delete file
  1. If the "Delete Actual File During Overwrite or Removal?" checkbox is checked, when a file is overwritten or removed, the actual file in OpenKM will be deleted.
    This was the existing record in OpenKM.
  2. Edit the existing record.
  3. Click on remove and save the record.
    The file has been removed from the record. Note that if you remove the entire record, it does not count as removing the file.
    In OpenKM, the file has also been removed.
  4. To remove the folder generated automatically, "When actual file is deleted, also delete actual folder created by form ID? Please note that this action will delete all items within the folder in OpenKM." checkbox has to be checked.
  5. Upload a file to OpenKM again to test this. Repeat the steps above similarly to remove the file. Below shows the file uploaded in OpenKM.
  6. Remove the file and save the form. 
    The file has been removed together with the folder. Please note that if you have other items under the folder, it will get removed as well.
Update file version
  1. If "Create New Version" for Same File Upload Action is selected, a new version of the file will be uploaded to OpenKM instead of replacing the old file.
  2. Now we try to upload some files into OpenKM.
    The files are uploaded at Version 1.0 each.
  3. Update one of the files, in the example it is joget_logo.jpeg.
    Now you can see the Version has increased from 1.0 to 1.1.
Lock File
  1. If "Lock File in OpenKM" is checked, the file will be locked when uploading to OpenKM.
  2. Go to the same form and upload "joget_logo.jpeg" again.
    The file is now locked in OpenKM.

OpenKM setup troubleshooting

1. Database Cannot Open Connection

The issue was cause due to the authentication method when setting up MySQL.
Troubleshooting Steps

  1. Run MySQL installer.
  2. Click Reconfigure for MySQL Server.
  3. In the Authentication Method change the default settings to Use Legacy Authentication Method.
  4. Restart MySQL80 Service in Computer System Services and retry running OpenKM in browser.
    To read more about the error, see this link: https://188.40.247.219/viewtopic.php?t=23368.

2. Windows could not start the OpenKM on Local Computer.

The root can't be pinpointed because the issue differs for each machine. Thus, only workarounds can be provided.

Troubleshooting Steps.

  1. Open Command Prompt.
  2. Open Tomcat Folder > Bin > type in catalina.bat run > press Enter.
  3. Wait for the server to startup.
  4. Access http://localhost:[port]/OpenKM.
  5. Use netstat -ano | findstr [port] to ensure the service is running.
  6. The user should be able to see the OpenKM login page when trying to access the browser.

Configure openKM DMS form options binder properties

Credentials

  • Username (Required): OpenKM username.
  • Password (Required): OpenKM password.
  • OpenKM URL (Required): The URL where OpenKM is hosted.
    • Example: http://localhost:[port]/OpenKM
  • Root Folder UUID (Required): The UUID of the folder retrieved from OpenKM to start from a specific folder level.

Configure openKM DMS file upload properties

Credentials

  • Username (Required): OpenKM username.
  • Password (Required): OpenKM password.
  • OpenKM URL (Required): The URL where OpenKM is hosted.
    • Example: http://localhost:[port]/OpenKM

Field mappings

  • Form: The current form to bind with the field.
  • Field for OpenKM Folder Path Upload: The selected form field that contains the OpenKM file path value.
  • Same File Upload Action: Action to perform when a file with the same name is uploaded
    • Replace File
    • Create New Version
  • Delete or Update Actual File During Overwrite or Removal: Checkbox field. If checked, the actual file in OpenKM will be deleted or updated when it is overwritten or removed. Otherwise, only the file links in Joget will be removed.
  • Automatically Create Folder by Form ID: Checkbox field. If checked, files will be uploaded to a newly created folder based on the form ID in OpenKM. If unchecked, files will be uploaded directly into the OpenKM file path.
    Important:
    • Unchecking this field will result in using the default path (/okm:root).
    • Checking the field will create a different path in OpenKM using a unique ID, which could cause an HTTP Status 500 Error when downloading from Joget.
  • Delete Folder Created by Form ID When File is Deleted: Checkbox field. If checked, the folder created by the form ID will be deleted when the file is removed, including all items within the folder. If unchecked, the folder will not be deleted when the file is removed.

Configure openKM DMS datalist formatter

Credentials

  • Username (Required): OpenKM username.
  • Password (Required): OpenKM password.
  • OpenKM URL (Required): The URL where OpenKM is hosted.
    • Example: http://localhost:[port]/OpenKM

Field mappings

  • Form: The current form to bind the field with.
  • OpenKM Path for File Upload: The current column field that contains the OpenKM file path value.
OpenKM on Cloud
To utilize the OpenKM DMS Plugin on Joget Cloud, it's essential to deploy OpenKM on the cloud as well to ensure online accessibility.
If the OpenKM DMS Plugin is hosted on the cloud while OpenKM remains on a local server, Joget won't be able to access OpenKM, resulting in an Authentication Error being displayed.
File Delete
In OpenKM DMS File Upload >  Advanced Settings > "Delete Actual File During Overwrite or Removal?" Checkbox.
This feature will not affect an OpenKM file when an existing file is deleted in Joget; thus, deleting the same file from both OpenKM and Joget must be done manually.

Expected outcome

Upon successful integration, Joget will be able to upload files into OpenKM browser based on the directory set by users.

Related documentation

Download plugin

Created by Julieth Last modified by Aadrian on Nov 19, 2024
Tags:
Previous Mayan EDMS NextTwilio Message Tool Plugin