Application configuration

OpenKM configuration file

OpenKM.cfg file is the main OpenKM configuration file. You can find this file in your server in $TOMCAT_HOME/OpenKM.cfg. In older OpenKM released based on JBoss the configuration file is located at $JBOSS_HOME/OpenKM.cfg.

A full listing of available configuration options can be found when logged into OpenKM as administrator role. You only will see the Administration tab if the logged user has the ROLE_ADMIN (OpenKM 6.2) or AdminRole (OpenKM 5.1) role, depending on the OpenKM version installed.

Each time you make some change in the OpenKM.cfg file application server must be restarted to take effect.

Starting with OpenKM 5.1 these configuration properties are located in the database to ease their management. To change the configuration properties, go to Administration > Configuration.

Changing uploading max file size

The default limit is 64MB. If you want to increase to 100MB:

max.file.size=100.

Since OpenKM relies on InputStream.available() method which returns an Integer, and according to Java Primitive Data Types, you should not upload files bigger than 2GB.

Since OpenKM 5.1.10 you can disable file size checking by setting max.file.size to 0.

Since OpenKM 6.0 by default this option is set to 0, so file size check is disabled by default.

Changing repository.xml configuration filename and path

repository.config=repository.xml

Changing default repository home

OpenKM 6.2

By default, the OpenKM document repository is located at $TOMCAT_HOME/repository. To change the repository folder to another location, use the configuration property in OpenKM.cfg file at $TOMCAT_HOME:

repository.home

If you want to fine tunning the contents of the document repository you can also use these configuration properties:

hibernate.search.index.home
repository.datastore.home
repository.cache.home

OpenKM 5.1 and before

By default repository is stored in $JBOSS_HOME/repository folder but you can change it with:

repository.home=repotest

Changing default user role

By default, the role required to connect to OpenKM is called ROLE_USER. You can change this to another role name. Go to Administration > Configuration and set:

default.user.role=ROLE_OTHER

Changing default admin role

By default, connection role to OpenKM is called ROLE_ADMIN. Go to Administration > Configuration and set:

default.admin.role=ROLE_OTHER_ADMIN

You can change this to another role name. This change also needs some changes in the file located at $TOMCAT_HOME/webapps/OpenKM/WEB-INF/applicationContext.xml:

<security:intercept-url pattern="/admin/**" access="ROLE_ADMIN" />

Change max results in UI

This option limits the search results in the UI.

max.search.results=25

Since: OpenKM 4.0

Change access URL

By default OpenKM sets the access URL to http://localhost:8080/OpenKM/index.jsp, but obviously you don't want to access your OpenKM installation only from localhost. This URL is used in mail notifications and the copy-to-clipboard feature. To change this default URL use this property:

application.url=http://your-server.com/OpenKM/index.jsp

Since: OpenKM 4.0

Change principal adapter

OpenKM can handle user access using the Spring Security framework. OpenKM needs an available method for reading users and roles, so when users are stored in database (as default), the class DatabasePrincipalAdapter does this job. If you configure OpenKM to authenticate against an LDAP server, you need to configure another principal adapter like LdapPrincipalAdapter. For more information take a look at OpenKM authentication and Active Directory.

principal.adapter=com.openkm.core.DatabasePrincipalAdapter

Since: OpenKM 4.0

Switch OpenKM to demo mode

In demo mode some options are disabled by default.

system.demo=on

Since: OpenKM 4.0

Enabling OCR

To enable OCR you must set the path of your OCR engine

system.ocr=/usr/local/bin/tesseract

Starting with OpenKM 5.1 you can select between 3 OCR engines:

• Tesseract 2.x
• Tesseract 3.x
• Cuneiform 0.7.x

See Third-party software integration: OCR for more info.

Setting default language of OpenKM UI

OpenKM by default guesses the language depending on the browser user language configuration, but you can set a language for all OpenKM users to use by default:

default.lang=es-ES

Force username to lowercase

You can force all usernames to be written in lower case. It's useful for example when you integrate with microsoft active directory where the username is not case sensitive

system.login.username.lowercase=on

Since: OpenKM 4.0

System read only

You can force the whole repository to be read only. This is useful when you're doing maintenance tasks, while doing migration and you want to continue to have the system running but you want to be sure any user will not be able to upload or change documents, etc...

system.readonly=true

Since: OpenKM 5.0

Enable document preview

Several applications are used by OpenKM to generate the document preview: OpenOffice.org, pdf2swf and convert. Read Enable PDF to SWF conversion, Enable image preview and Enable OpenOffice.org service. Also take a look at Random errors in preview in case of problems.

Enable PDF to SWF conversion

To enable the preview UI tab, OpenKM needs to convert PDF files to SWF. You also must have OpenOffice installed as a service.

system.pdf2swf=/usr/bin/pdf2swf

Starting from OpenKM 5.1 this configuration property has changed to system.swftools.pdf2swf.

Since OpenKM 5.1.9 the pdf2swf command line parameters should be added in the configuration property, for example: system.swftools.pdf2swf=/usr/bin/pdf2swf -T 9 -f ${fileIn} -o ${fileOut}

Note: Read Third-party software integration: SWFTools for more complete documentation.

Since: OpenKM 4.1

Enable PS to SWF conversion

To enable postscript document preview, OpenKM needs to convert PS files to SWF using the ps2pdf utility from Ghostscript:

system.ghostscript.ps2pdf=/usr/bin/ps2pdf

Since: OpenKM 5.1.2

Enable image preview

To enable image preview, you need to install the ImageMagick convert utility and configure it:

system.convert=/usr/bin/convert

Starting from OpenKM 5.1 this configuration property has changed to system.imagemagick.convert.

Since: OpenKM 4.1

Enable OpenOffice.org integration

OpenOffice.org is used by OpenKM to convert files to PDF and generate the preview.

system.openoffice=on

Starting with OpenKM 5.0 this properties was changed to:

system.openoffice.path=/usr/lib/openoffice
system.openoffice.tasks=5
system.openoffice.port=2222

Where you should specify an OpenOffice.org installation path, the maximum number of conversion tasks before restarting the service and a port where the OpenOffice.org conversion service will be attached. Only the first property is mandatory.

If you have problems with OpenOffice / LibreOffice integration, take a look at OpenOffice configuration issues.

Note 1: Read Third-party software integration: OpenOffice.org for more up-to-date documentation.

Note 2: You can enhance OCR results by configuring an OpenOffice.org dictionary. See OpenKM 5.1 OCR configuration for more info.

Since: OpenKM 4.0

Configuring email

To configure email service you must enable subscription and notification properties. View a complete example in Notification and subscription messages.

subscription.message.subject=OpenKM - {0} - {1};
subscription.message.body=Document: <a href=\"{0}\">{1}</a>
notify.message.subject=OpenKM - NOTIFICATION - {0}
notify.message.body=Document: <a href=\"{0}\">{1}</a>

Since: OpenKM 4.1

Configuring password validation

To configure password validation you have several properties. CompletePasswordValidator is the default password validator class that comes by default with OpenKM. By default, this validator is not enabled. You can also create your own Create password validator .

You can select which validation rules you want to enable, for example if you only enable validator.password.min.length property, the validator will only validate minimum length.

validator.password=com.openkm.validator.password.CompletePasswordValidator
validator.password.min.length=numeric value greater than 0
validator.password.max.length=numeric value greater than 0
validator.password.min.lowercase=numeric value greater than 0
validator.password.min.uppercase=numeric value greater than 0
validator.password.min.digits=numeric value greater than 0
validator.password.mini.special=numeric value greater than 0
validator.password.error.min.length=Your message error
validator.password.error.max.length=Your message error
validator.password.error.min.lowercase=Your message error
validator.password.error.max.uppercase=Your message error
validator.password.error.min.digits=Your message error
validator.password.error.min.special=Your message error

Since: OpenKM 4.1

Configuring chat service

By default chat and chat autologin are enabled. In order to enable or disable them, values can be "on" or "off".

chat.enabled=off
chat.autologin=off

Since: OpenKM 5.0

Configuring schedulers

There are some schedulers that OpenKM uses. Some internally, like mail importer and getting repository news, and others used by the user interface like dashboard refresh time and keepalive.

Values are in minutes.

OpenKM enquires for repository news ( by default every 24 hours i.e. 1440 minutes )

schedule.repository.info=1440

OpenKM imports emails from an imap server ( by default set to 0, that is disabled )

schedule.mail.importer=0

In OpenKM 4.1 and before, the default value was 60 and cannot be disabled.

KeepAlive is used by the user interface to mantain the browser connected to OpenKM even when a user stays for some time without performing any operation. For this reason, it should never be lower than server session timeout ( by default set to 15 minutes ).

schedule.session.keepalive=15

Dashboard data is refreshed by default every 30 minutes.

schedule.dashboard.refresh=30

Since: OpenKM 4.1

Configuring wizard

You can configure a wizard to be used each time a user uploads a document. The wizard can be a sequence of property groups, keywords ( including thesaurus ) and categories. By default, wizard is disabled.

Property groups can be configured as a list of property group names separated by ","

wizard.property.groups=okg:consulting,okg:technology

To enable keywords, wizard keywords value must be "on". Default value is "off".

wizard.keywords=on

To enable categories, wizard categories value must be "on". Default value is "off".

wizard.categories=on

Since: OpenKM 5.0

Customizing application logo

You can replace the default OpenKM logo in the login page and reports.

logo.login
logo.mobile
logo.report

Recommended image size:

• logo.login: 316px × 74px (background #F1F3F5)
• logo.mobile: 161px × 38px (background #F1F3F5)
• logo.report: 150px × 35px (background #FFF)

You can also set a message on the login page with:

logo.text

Since: OpenKM 5.1 (configuration stored in database)

Configuring WebDAV access

In recent OpenKM releases, WebDAV is disabled by default. If you want to enable it, set the property system.webdav.server to on. The okm:root path may cause problems with some WebDAV clients. For this reason there is another configuration parameter system.webdav.fix which replaces a path like okm:root with okm_root. See WebDAV access for more info.

Since: OpenKM 5.1

Disable document name mismatch check

By default OpenKM will check the document name on check-in to ensure you upload another version of the same document. You can disable this behaviour with this configuration property:

system.document.name.mismatch.check=false

Since: OpenKM 5.0.1

Force keywords lowercase conversion

By default keywords are stored as is, but you can force a lowercase conversion using this configuration property:

system.keyword.lowercase

Since: OpenKM 5.1

Disable user assign on document creation

By default when a user creates a document or folder, he is added to the node with full permissions. You can disable this behaviour this way:

user.assign.document.creation=off

Since: OpenKM 5.0.2

Improve OpenKM performance

If you experience a slowndown of OpenKM when the number documents grows, you can disable user quotas or make use of the user items size cache.

To enable user items size cache:

user.item.cache=on

Starting from 5.1 user.item.cache is set to on by default.

To disable user quotas, go to User Profiles (Administration -> Profiles) and set Quota limit to 0 (This field is in megabytes). This feature of disabling quotas is available from OpenKM 5.1.6.

Since: OpenKM 5.0.3

Change conversion cache home

In case you have little space in your application server partition, you can configure to store the conversion cache folder somewhere else. For this, use the repository.cache.home configuration property. By default, this is set to $TOMCAT_HOME/repository/cache.

Since: OpenKM 5.1.8

Re-indexing the whole repository

To re-index the whole document repository (document content will be extracted again and indexed by Lucene), follow these steps, depending on your OpenKM version:

OpenKM 6.2

• Log as administrator.
• Go to Administration > Utilities > Rebuild indexes.
• Select "Lucene indexes" option and click on "Execute".
• A progress will be shown and repository will be on read-only mode until completed.

OpenKM can use two different ways of rebuilding Lucene indexes: sequential or parallel. By default sequential re-indexing is enabled, but you can select the using the hibernate.indexer.mass.indexer configuration property.

In sequential mode or you can use the hibernate.indexer.batch.size.load.objects configuration property to indicate to Hibernate how many object should handle every time. To avoid OutOfMemory problems the repository need to be re-indexed in batch. If the value of this property is too low, the performance will be bad but if is too high you can have OutOfMemory problems.

In parallel mode you have several configuration properties to tune its performance:

• hibernate.indexer.batch.size.load.objects: batch size used to load the root entities. Defaults to 30.
• hibernate.indexer.threads.subsequent.fetching: number of threads used to load the lazy collections related to the indexed entities. Defaults to 8.
• hibernate.indexer.threads.load.objects: number of threads to be used to load the root entities. Defaults to 4.
• hibernate.indexer.threads.index.writer: number of threads to be used to analyze the documents and write to the index. Defaults to 3.

OpenKM 5.1

Keep in mind that the next time you start JBoss, a process which runs the text extraction for every document in the repository will be launched and you can't use OpenKM until this process is finished.

• Stop JBoss.
• Delete the $JBOSS_HOME/repository/repository/index and $JBOSS_HOME/repository/workspaces/default/index directories.
• Start JBoss again.

Batch document text extraction

In OpenKM 6.0 the text extraction can be delayed every few seconds or at a specific cron like definition. This can be configured in the applicationContext.xml Spring definition. Take a look at the textExtractorWorker bean definition. Every time the text extraction worker wakes up, a bunch of pending documents are processed. You can configure the number of documents with the experimental.text.extraction.batch configuration property.

Since: OpenKM 6.0

Security configuration

Starting with OpenKM 6.0 you can make use of these configuration properties:

• security.access.manager: You can switch between "simple" and "recursive". This is the way the security is evaluated. With "recursive", the security is evaluated starting with the selected node until the repository root. The "simple" option only evaluates the selected node. By default, this is set to "simple".

• security.search.evaluation: Here you can choose between several search result security evaluation strategies. The fastest one is called "lucene", because it is the Lucene search engine which restricts the search results based on the node security. The others are "am_more", "am_window" and "am_limited", which make use of the AccessManager (see previous property) to restrict the search results. By default, this is set to "lucene".

By default OpenKM 6 is configured this way:

 security.access.manager = simple
 security.search.evaluation = lucene

Which provides great performance by only evaluating a single node. But if you want to evaluate every parent you can change this behavior with these settings:

 security.access.manager = recursive
 security.search.evaluation = [ am_more | am_window | am_limited ]

This will reduce OpenKM performance (at least in search) but will match customer requirements. Performance can be improved customizing com.openkm.cache.parentNodePermissions cache region definition.

Also provided a new AccessManager: read_recursive used to prevent showing documents in search results when any folder in the path has not read access for the user who run the query. Should be used in combination with am_more.

 security.access.manager = read_recursive
 security.search.evaluation = am_more

Difference between "simple" and "recursive"

Give this repository structure:

• okm:root
  • level-1a
    • level-2a
      • level-3a
        • alpha.doc
        • beta.doc
        • gamma.doc
      • level-3b
  • level-1b
  • level-1c

When using simple if you revoke permission from level-2a folder and user is viewing level-3a folder, OpenKM still be showing the documents to this user. When user search, OpenKM will return these document as search results. User can't access the documents because when OpenKM try to access the document, it will open every path location and will fail to open level-2a because the user has no grants. You need to apply revoke recursively to prevent the user to access these document, so they won't be shown in the search results.

When using recursive if you revoke permission from level-2a folder and user is viewing level-3a folder, OpenKM will five an error because Access Manager also evaluates the permission of the level-2a ancestor node. When user search, OpenKM won't show these documents in the search results. Keep on mind that this Access Manager implementation is slower because need to evaluate more nodes: the more node depth the more parents nodes need to evaluate.

Since: OpenKM 6.2

Extended security

Starting with OpenKM 6.0 you can extend security to download files, start workflows, add, remove or modify property groups ( metadata ) or compact history.

The possible values are:

• DOWNLOAD = 1024;
• START_WORKFLOW = 2048;
• COMPACT_HISTORY = 4096;
• PROPERTY_GROUP = 8192;

• security.extended.mask: Here you can activate which kind of extended security you want in your OpenKM. For example to enable download and property groups you should put the mask 9216 ( 1024+8192 )

Since: OpenKM 6.0.1

Available only in OpenKM Professional.

Managing security

By default when you change the security of a node (document or folder) in OpenKM, every time you click to grant or revoke a permission, the action is performed by OpenKM. This means that if you want to change the security of 10 users, 10 commands are sent to the server to be performed. The case is worse when every change affect several hundred (or even thousands) of nodes.

In OpenKM 6.2.9 you can configure an alternative security mode where only the changes are applied at the end, so it is faster. To enable this new mode you need to use the security.mode.multiple configuration property. Also, we have included an improvement in OpenKM Professional which can send these security changes in background task if this take too long to complete. You can fine tuning this behaviour using the security.live.change.node.limit configuration property.

Since OpenKM 6.2.11 you can check the progress of these pending task from Administration > Statistics > Pending tasks queue.

Since: OpenKM 6.2.9 Professional and 6.2.3 Community

Autocad previewer

If you have problems with autocad previewer text, you should configure some url to indicate an extra fonts repository used in autocad files. Simply copy the files to some url that can be resolved by desktop users and take into consideration that font file names should be in lower case ( rename if you have uppercase font file names). You can also enable Autocad previewer debug mode.

dxf.applet.debug.window=false
dxf.applet.default.bigfont=arial
dxf.applet.default.font=arial
dxf.applet.fontdir=http://fonts.openkm.com

Since: OpenKM 6.0

Available only in OpenKM Professional.

Minimum search characters

You can set the minimum characters required to execute a search. If less characters are available the search button will not be enabled. By default the minimum search characters is set to 3.

min.search.characters = 3

Since: OpenKM 6.0.0

Execution timeout

The maximum permitted time to execute a command like OCR, Antivirus, etc. After this time the child process is killed. Time given in minutes.

system.execution.timeout=5

Since: OpenKM 6.0.1

Restrict by file name

You can avoid uploading document by name or extension. For example, don't permit upload AVI multimedia videos.

restrict.file.name=*.avi

You can also configure several filename rules:

restrict.file.name=*~;*.bak;*.avi

Since: OpenKM 6.2

Managed text extraction

In previous OpenKM releases, the text extraction was a transparent process where you can't do anything with the configuration. Since OpenKM 6.0 you have several configuration options to adapt the document text extraction to your needs. Let's see these parameters:

• managed.text.extraction.batch: Integer. How many documents are processed every time the text extractor worker is awoken.
• managed.text.extraction.pool.size: Integer. How many threads are launched concurrently every time. This number should be smaller or equal to the number of CPUs in the server.
• managed.text.extraction.pool.threads: Integer. How many threads will be executed in every time. If managed.text.extraction.pool.size is 8 and managed.text.extraction.pool.threads is set to 16 then all these 16 threads will be launched using this pool. If every task take the same time to complete, in theory every pool thread will execute two tasks. Of course this is not true in the real world.
• managed.text.extraction.pool.timeout: Minutes. How many minutes should the worker wait for the text extraction pool to complete the tasks. After these minutes, the remaining pool threads are interrupted.
• managed.text.extraction.schedule: Minutes. How often the text extractor worker is awoken.
• managed.text.extraction.concurrent: Boolean. If the concurrent text extraction should be enabled. By default the text extraction is serial, but you can improve the extraction performance if you have several CPUs.

Since: OpenKM 6.0.1

Available only in OpenKM Professional.

Document version numeration

Since OpenKM 6.2 we support different numeration schemas. By default OpenKM uses com.openkm.vernum.MajorMinorVersionNumerationAdapter which is similar to Jackrabbit implementation. But also have some other already implemented:

Numeration Adapter	First Version	Next Versions
PlainVersionNumerationAdapter	1	2, 3, 4, etc.
MajorMinorVersionNumerationAdapter	1.0	1.1, 1.2, 1.3, etc.
BranchVersionNumerationAdapter	1	2, 3, 2.1, 2.2, etc.

You can canche the default Numeration Adapter using the version.numeration.adapter configuration property. You need to restart OpenKM every time you change this property. Also note that if already there are documents in the repository, changing Numeration Adapte may cause problems because they are not compatible between them.

Some Numerations Adapters like PlainVersionNumerationAdapter may have additional configuration parameters like version.numeration.format which is used to define the numeration number format. By default is "%d" but you can change to "%02d" to create versions like "01", "02", etc.

If you change the version numeration adapter you also need to update the existing numerations:

update NodeDocumentVersion ndv set ndv.name = '01' where ndv.name='1.0';
update NodeDocumentVersion ndv set ndv.name = '02' where ndv.name='1.1';
update NodeDocumentVersion ndv set ndv.name = '03' where ndv.name='1.2';
...

Since: OpenKM 6.2

Session keep alive

Some administration task are long time like repository checker and rebuild Lucene indexes. This implies that user session may be lost. For this reason these king of operations are forced to maintain the session alive. You can configure the keep alive interval using the configuration property keep.session.alive.interval. By default is set to 5 minutes.

Since: OpenKM Professional 6.2.9

Activity log actions

Table where activity log is stored may grow quickly. OpenKM can log a lot of information related to the activity of the uses, but sometimes these actions are not needed to be logged and fill your activity log table. For this reason there is a configuration property called activity.log.actions where you can define which actions to log. By default is set to most common interesting actions. You can use regular expressions to define these actions. Read Java Regex Tutorial for more info about Java regular expressions.

Since: OpenKM Professional 6.2.10

Safe trash purge

When you delete a document or folder from OpenKM, it goes to user trash. If the user empty the trash the documents are definitively lost. But now you can configure a place where the documents will go after being purge from trash. You you can configure a directory in the server filesystem where an export of the trash be placed, using the repository.purgatory.home configuration property.

Since: OpenKM Professional 6.2.10

Tomcat Connector encoding

Default Tomcat Connector encoding is set to "ISO-8859-1" but you can change it with the property:

 URIEncoding="UTF-8"

OpenKM should meet this encoding for a proper input. So, you have the tomcat.connector.uri.encoding configuration property. By default is set to "ISO-8859-1" but if you set the "URIEncoding" parameter to "UTF-8", also need to set to "UTF-8".

Since: OpenKM Professional 6.2.12