| Table of Contents |
|---|
Introduction
The OpenKM Document Management System (DMS) plugin facilitates the seamless integration of OpenKM and Joget. This integration currently utilises two plugin types:
- Form Options Binder - Retrieve folder paths from OpenKM.
- 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 folder that follows Joget form ID when uploading.
- Datalist Formatter - Format datalist file upload column to download file from OpenKM directly.
The plugin is created with the use of RESTful Guide - OpenKM Documentation to perform RESTful API calls on OpenKM.
Plugin Info
Plugin Available in the Bundle:
OpenKM DMS Plugin.
This plugin bundle is compatible with Joget DX 8.
Expected Outcome
Upon successful integration, Joget will be able to upload files into OpenKM browser based on the directory set by users.
Figure 1: Example of successful integration.
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
OpenKM Community Version can obtain it by downloading directly from the Official OpenKM Website. This official source ensures users access the most up-to-date and authentic version of the software, 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, we will be using MySQL as the OpenKM database.
Link to MySQL download and installation:
4. OpenKM DMS Plugin
To integrate Joget with OpenKM, we will use the OpenKM DMS Plugin from https://github.com/jogetoss/openkm-dms.
Setting up OpenKM DMS
1. OpenKM Installer Setup
To setup 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.
For this example, OpenKM will run on Java 8 and MySQL8.0.
When you see the following page, it shows that your openKM has been successfully hosted. Login with the default credentials "okmAdmin" with password "admin".
Figure 1: OpenKM Login Page
After logging in, you will see the homepage of OpenKM.
Figure 2: OpenKM Homepage
Troubleshooting OpenKM DMS
List of Troubleshooting
Database Connection
When this application error occurs, there is a problem with the database connection due to lack of User's privileges in database.
Figure 3: OpenKM Database Connection Error
Database Connection Solution
- Open MySQL root instance.
- Go to Server tab > Users and Privileges.
- Give full permission to user "openkm".
Figure 4: OpenKM Database Connection Error
Database Unable to Execute Query
This is a follow up error after solving the previous.
Figure 5: Database could not execute query
Error in Figure 5 occurs because there is no existing openKM UUID in the database. In order to resolve the problem we need to create a UUID when accessing openKM page.
Database Unable to Execute Query Solution
After entering the command, it will display the output as image below and we can enter the configuration we prefer.
Figure 2: OpenKM Configuration.
OpenKM installation will install Tomcat automatically 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 Figure 2.
Figure 3: Successful Installation.
As a confirmation of a successful installation, open Services in the computer's system and search for OpenKM:
Figure 4: OpenKM Services.
2. MySQL setup
Access the root database to execute the query in Figure 3 to create "okmdb" database.
Figure 5: Access Root Database.
Figure 6: Creating okmdb Database.
Go to Server > Users and Privileges and select the newly created User and check all the following boxes to give the User full privilege of the database. Not doing so will create an error when trying to access OpenKM browser.
Figure 7: Set Users Privileges.
Figure 8: Select User and Check All the Roles.
Create a new connection and enter all the information set in Figure 3.
Figure 9: Create New Connection.
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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
# 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 |
| Code Block | ||||
|---|---|---|---|---|
| ||||
# OpenKM Hibernate configuration values
|
Change a line of codel:
| title | Command Prompt |
|---|
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
| Code Block | ||||
|---|---|---|---|---|
| ||||
<Connector port="8180" address="0.0.0.0" protocol="HTTP/1.1"
connectionTimeout="20000" redirectPort="8443"/> |
| Code Block | ||||
|---|---|---|---|---|
| ||||
<Server port="8006" shutdown="SHUTDOWN">
<Listener className="org.apache.catalina.startup.VersionLoggerListener"/> |
OpenKM in Runtime
To access the OpenKM browser, make sure the service is running as in Figure 4.
Open OpenKM in browser with http://localhost:8180/OpenKM.
When you see the following page, it shows that your OpenKM has been successfully hosted. Default login credentials are "okmAdmin" with password "admin".
Figure 10: OpenKM Login Page
After logging in, you will see the homepage of OpenKM.
Figure 11: OpenKM Homepage
Restart OpenKM service.Configuring the OpenKM Plugin
First, drag a select box and use the OpenKM DMS Form Options Binder to load the folder paths from OpenKM. Fill in the required credentials for the plugin to work as intended (Figure 6). The Root Folder UUID can be retrieved on the OpenKM folder that we intend to configure as root folder (Figure 7).
Figure 6: Joget Form Builder (Select Box with OpenKM DMS Form Options Binder)
Figure 7: Retrieve OpenKM Root Folder UUID
Then, the OpenKM DMS File Upload tool can be drag and drop to attach into the form as a form element. Fill in the OpenKM Configurations with necessary details. If the credentials of OpenKM is invalid, "Authentication ERROR" will be shown in the element (Figure 8).
We can now map the select box field in the Field Mappings section. Field mappings is an optional configuration.
When configuring the Field Mapping, "Field for OpenKM Folder Path Upload" must point to the file path created in Figure 6, if no fields are mapped, the default file path will be "/okm:root".
Figure 8: Joget Form Builder (OpenKM DMS File Upload Element)
In the datalist builder, we can format the file upload column by using the OpenKM DMS Datalist Formatter. Similar configurations can be key in to enable users to download the file directly from datalist. Make sure 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 will be "/okm:root".
Figure 9: Joget Form Builder (OpenKM DMS Datalist Formatter)
If we do not wish to type the credentials multiple times, the credentials can also be easily added into environment variables, and then use a hash variable to refer to the values in environmental variables. For more information, please refer to Environment Variable - Knowledge Base for DX 7 - Joget | COMMUNITY.
Using the OpenKM Plugin
After all the configurations has been done, the user can retrieve the folder paths from OpenKM in the select box, then choose a file to upload.
Figure 10: OpenKM DMS UI (Form)
After uploading, we can view the latest file path that the file has been uploaded to, and also download the file retrieved from OpenKM.
Figure 11: OpenKM DMS UI (List)
At OpenKM DMS, we can view the file being uploaded. If we modify the file here, we can also get the modified newest file in Joget.
Figure 12: OpenKM DMS 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.
OpenKM DMS Form Options Binder Properties
Configure OpenKM DMS Form Options Binder
Name | Description |
|---|---|
Credentials | Header field. |
Username * | OpenKM username. |
Password * | OpenKM password. |
OpenKM URL * | The URL that OpenKM is hosted at. Example: http://localhost:8180/OpenKM |
Root Folder UUID * | The folder UUID retrieved from OpenKM folder. The UUID can be configured depending on desired folder level to start with. |
OpenKM DMS File Upload Properties
Configure OpenKM DMS File Upload
More details on default configurations for file upload: File Upload - Knowledge Base for DX 8 - Joget | COMMUNITY
Below are configurations for section "OpenKM Configurations":
Name | Description | ||
|---|---|---|---|
Credentials | Header field. | ||
Username * | OpenKM username. | ||
Password * | OpenKM password. | ||
OpenKM URL * | The URL that OpenKM is hosted at. Example: http://localhost:8180/OpenKM | ||
Field Mappings | Header field. | ||
Form | The current form to bind the field with. | ||
Field for OpenKM Folder Path Upload | The selected form field that contains the OpenKM File Path value. | ||
Automatically Create Folder by Form ID | Checkbox field. If true, file will be uploaded inside a newly created folder using submitted form ID in OpenKM. If false, file will be directly uploaded into the OpenKM File Path.
|
OpenKM DMS Datalist Formatter Properties
Configure OpenKM DMS Datalist Formatter
Name | Description |
|---|---|
Credentials | Header field. |
Username * | OpenKM username. |
Password * | OpenKM password. |
OpenKM URL * | The URL that OpenKM is hosted at. Example: http://localhost:8180/OpenKM |
Field Mappings | Header field. |
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. |