Configuring Content Replication between two OpenKM instances

The system follows a source → target model: one OpenKM instance acts as the source (monitors a folder and records changes), while another acts as the target (connects to the source, downloads events, and applies the changes locally).

Configuration

On the source server:

On the target server, you’ll need to follow these steps:

• Start Tomcat
• Log in to OpenKM
• Go to Administration > Utilities > Database query and execute these SQL statements to create the required configuration properties:

insert into OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) values ('content.replication.monitored.folder', 'string', '');

• content.replication.monitored.folder: UUID of the folder to monitor.

On the target server, you’ll need to follow these steps:

• Start Tomcat
• Log in to OpenKM
• Go to Administration > Utilities > Database query and execute these SQL statements to create the required configuration properties:

  insert into OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) values ('content.replication.target.folder', 'string', '');
  insert into OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) values ('content.replication.source.url', 'string', '');
  insert into OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) values ('content.replication.source.username', 'string', '');
  insert into OKM_CONFIG (CFG_KEY, CFG_TYPE, CFG_VALUE) values ('content.replication.source.password', 'string', '');

Set the configuration properties according to their usage:

• content.replication.target.folder: UUID of the local destination folder.
• content.replication.source.url: Base URL of the source instance (e.g. http://source-server:8080/openkm/).
• content.replication.source.username: Username used to authenticate against the source.
• content.replication.source.password: Password for the source.

How it works

In the SOURCE instance (ContentReplicationManager)

Whenever any operation is performed on content inside the monitored folder, an event is recorded in the OKM_CONTENT_REPLICATION_EVENT table. The supported event types are:

• Documents: create, update, delete, purge, rename, move
• Folders: create, delete, purge, rename, move
• Records: create, delete, purge, rename, move
• Mails: create, delete, purge, move
• Property groups: add, set, remove

The monitored folder is identified by UUID (cached in memory after the first lookup).

In the TARGET instance (ContentReplicationScheduler)

The scheduler runs every 5 minutes (0 */5 * * * *) and performs two phases:

Phase 1 — Event Fetch

1. It checks the local state table to determine the timestamp of the last processed event.
2. It calls the source REST endpoint: GET /rest/content-replication/events/since/{timestamp}
3. It stores the new events as PENDING in OKM_CONTENT_REPLICATION_STATE

Phase 2 — Event Processing

1. It marks all events currently in ERROR state as PENDING (automatic retry).
2. It processes each pending event by invoking the corresponding handler (DocumentReplicationHandler, FolderReplicationHandler, etc.).
3. Each handler downloads the actual content from the source via REST (GET /rest/documents/{uuid}/content, etc.) and applies it locally.
4. The event is marked as DONE if successful, or as ERROR (with a message) if it fails.

Database Tables

The replication mechanism relies on the following database tables:

Table	Server	Description
OKM_CONTENT_REPLICATION_EVENT	Source	Stores all replication events generated when content is created, modified, or deleted inside the monitored folder.
OKM_CONTENT_REPLICATION_STATE	Target	Tracks the processing status of replication events (PENDING, DONE, ERROR).

Event States (OKM_CONTENT_REPLICATION_STATE table)

Name	Event
PENDING	Waiting to be processed
DONE	Successfully processed
ERROR	Failed; will be retried in the next scheduler execution