Custom UI template

Developer information for the sample Spring Boot base project with OpenKM authentication and support for JSP, JSTL & REST.

To learn more about Spring Boot, please visit https://projects.spring.io/spring-boot/

There is also a very good tutorial on Spring Boot at https://spring.io/guides/gs/spring-boot/

Note

Please create a support ticket to ask for this source code.

General description

Properties file

You must create a file called custom.properties inside the $CATALINA_HOME folder.

Note

This file is located in the root folder of the project. However, you can also download it from here: custom.properties

All application properties will be read from this file. If you need to change this path, you must modify the class MainAppConfig.

For more information: https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html (section 24.3)

These properties are:

Property	Description
openkm.url	OpenKM URL
anonymous.user	Anonymous user name Used to access OpenKM web services if no user is provided.
anonymous.password	Anonymous user password
admin.user	Admin user name Used to access OpenKM web services if no user is provided.
admin.password	Admin user password
logback.file	Logback file name

Caution

Other properties in this file should not be modified unless you know what you are doing. More information about properties is available at https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html

Authentication

This project is configured to authenticate against an OpenKM instance. It works using OpenKM SDK through web services.

The OpenKM instance URL is defined in the openkm.url configuration property.

Log file

You must copy the file logback-custom.xml to the $CATALINA_HOME folder. This file is used by the logging system.

Note

This file is located in the root folder of the project. However, you can download it from here: logback-custom.xml.

To change the log level for a particular package:

<?xml version="1.0" encoding="UTF-8"?>
<included>
  <logger name="com.openkm" level="INFO"/>
</included>

Remember me

This sample customization uses an H2 database to store remember-me data. A database file called custom.mv.db will be created in the user’s home directory.

There is a file called import.sql which contains SQL statements that are executed when the application starts. In this particular case, it only contains one statement to create the database table to allow the “remember me” feature.

Roles management

In the file menu.jsp you can see how the roles are managed by the application:

<sec:authorize access="hasRole('CATALOG')">

Using this code, a user may or may not see this menu option, depending on their roles. However, if you do not want to allow a user to access a resource, you can configure it in the WebSecurityConfig file.

Note

Spring Security 4 automatically prefixes any role with ROLE_.

Bootstrap

The application uses Bootstrap to provide a beautiful and responsive design. More information about Bootstrap is available at http://getbootstrap.com/.

Packaging

This application can be packaged as either a jar or a war. In this POM configuration, the artifact will be a WAR.

If you need to change packaging, please see this URL: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#build-tool-plugins-maven-packaging (section 66.2)

Application port

If you package the application as a jar, you can change the port.

To do that, please visit: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#cli-default-import-statements (section 72.4)

Catalog information

Description

This sample contains a catalog system for OpenKM:

• Using OpenKM, a user can upload files to a folder custom.pending.folder (we will see what this folder is)
• An automation will add okg:type metadata to this document
• Using the catalog system of this application, we will add some metadata to this document
• An automation will move this document to another folder

The main classes of the catalog system are:

• CatalogController: application routing for the catalog system
• CatalogServiceImpl: services for the catalog system
• WSCacheDAOImpl: manages the web services to communicate between OpenKM and this app

Installation

You must read the following steps in order to configure the application correctly:

Step 1: Download

Download the application from the OpenKM Download Center Download center.

Note

This will download a zip file containing a Maven project. For more information about Maven: https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

Step 2: Role creation

Create ROLE_CATALOG and add it to the user used by the application.

See the Manage roles section for more information.

Step 3: SQL data needed

In order to execute SQL statements, go to Administration > Utilities > Database query and enter these queries:

CREATE TABLE CP_DOCUMENT_TYPE(ID INT NOT NULL, TYPE VARCHAR(100) NOT NULL, METADATA_GROUP VARCHAR(100) NOT NULL);
CREATE TABLE CP_AGENCY(ID INT NOT NULL, NAME VARCHAR(100) NOT NULL);
INSERT INTO CP_DOCUMENT_TYPE (ID, TYPE, METADATA_GROUP) VALUES (1, 'Consulting', 'okg:consulting');
INSERT INTO CP_DOCUMENT_TYPE (ID, TYPE, METADATA_GROUP) VALUES (2, 'Marketing', 'okg:marketing');
INSERT INTO CP_AGENCY (ID, NAME) VALUES (1, 'Web');
INSERT INTO CP_AGENCY (ID, NAME) VALUES (2, 'Desktop');

Caution

SQL statements could be different depending on your database.

The parameter custom.pending.folder contains the UUID of the folder from which to read documents for the catalog. You also need to create this folder in the Taxonomy manually:

INSERT INTO OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) VALUES ('custom.pending.folder', 'string', '14541d97-f06b-437e-bd59-c294dfaa96fb');
INSERT INTO OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) VALUES ('custom.document.type', 'list', '');

Update the values of the property custom.document.type:

1;okg:consulting;Consulting
2;okg:marketing;Marketing

Step 4: Metadata

<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.10//EN"
"http://www.openkm.com/dtd/property-groups-3.10.dtd">
<property-groups>
 <property-group label="Document type (custom app)" name="okg:custom">
      <select label="Type" name="okp:custom.type" type="simple"
          optionsQuery="select ID, TYPE from CP_DOCUMENT_TYPE order by TYPE asc" />
 </property-group>
 <property-group label="Consulting" name="okg:consulting">
     <input label="Date" type="date" name="okp:consulting.date" />
     <input label="Input label 1" name="okp:consulting.input1" dbColumnSize="256"/>
     <separator label="Separator label" name="okp:consulting.separator" />
     <input label="Input label 2" name="okp:consulting.input2" dbColumnSize="512"/>
 </property-group>
 <property-group label="Marketing" name="okg:marketing">
     <select label="Agency" name="okp:marketing.agency" type="simple"
         optionsQuery="select ID, NAME from CP_AGENCY order by NAME asc" />
     <input label="Date" type="date" name="okp:marketing.date" />
 </property-group>
</property-groups>

Note

Right now only these types are supported: Input, TextArea, Select and Checkbox.

Step 5: Automations

You must create two automations like the following (see the Automation section for more information):

Automation create	Automation definition
Go to OpenKM administration, select the Automation option and New Rule, fill in the name “Move Consulting”, select the event “Add metadata group”, and check the ‘Active’ box.	- Add validation: Select HasPropertyGroup option, activate it, and enter the value “okg:consulting” as the property group. - Add action: Select MoveToFolder option, activate it, and select the folder “/okm:root/consulting”.
Go to OpenKM administration, select the Automation option and New Rule, fill in the name “Move Marketing”, select the event “Add metadata group”, and check the ‘Active’ box.	- Add validation: Select HasPropertyGroup option, activate it, and enter the value “okg:marketing” as the property group. - Add action: Select MoveToFolder option, activate it, and select the folder “/okm:root/marketing”.

Step 6: Catalog documents from UI

• Set the URL in the browser to http://localhost:8080/custom-2.1