Configuring Content Replication between two OpenKM instances

The system follows a source → target model: one OpenKM instance acts as the source (monitors one or more folders and records changes), while another acts as the target (connects to a source, downloads events, and applies the changes locally). A folder is always replicated in a single direction; if you need content to flow both ways between two instances, configure two independent pairs, one for each direction, each on a different pair of folders.

Each Replication Pair carries its own connection to a source server, so a single target instance can centralize content coming from several different source servers at once (for example, several satellite instances replicating selected folders into one central instance) - not just several folders on the same source.

Configuration

On each source server, go to Administration > Utilities > Content Replication > Monitored Folders and create one entry per folder you want to monitor, giving its UUID. The folder’s path is resolved and validated automatically.

On the target server, go to Administration > Utilities > Content Replication > Replication Pairs and create one entry per folder you want to receive:

• Source Folder UUID: the monitored folder’s UUID, as registered on its source server.
• Target Folder UUID: the local folder under which to replicate it.
• Source URL: base URL of that folder’s source instance (e.g. http://source-server:8080/openkm/).
• Source Username / Source Password: credentials to authenticate against that source.

Each pair keeps its own polling cursor and its own source connection, so several pairs can run independently - whether they point at the same source server or at different ones. The password is stored encrypted with a key derived from this instance’s cluster UUID; leave it blank when editing a pair to keep the current password unchanged.

How it works

In the SOURCE instance (ContentReplicationManager)

Whenever any operation is performed on content inside a monitored folder, an event is recorded in the OKM_CONTENT_REPLICATION_EVENT table, tagged with the UUID of the monitored folder it belongs to. 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

Moving content between two different monitored folders on the same source is split into a PURGE event on the folder being left and a CREATE event on the folder being entered.

In the TARGET instance (ContentReplicationScheduler)

The scheduler runs every 5 minutes (0 */5 * * * *) and, for each configured pair, performs two phases:

Phase 1 — Event Fetch

1. It reads the pair’s own cursor (the timestamp of the last event it fetched).
2. It calls the source REST endpoint for that pair’s folder: GET /rest/content-replication/events/since/{timestamp}?folderUuid={uuid}. The source checks that the calling user has read access to that folder before returning anything.
3. It stores the new events as PENDING in OKM_CONTENT_REPLICATION_STATE and advances the pair’s cursor.

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_FOLDER	Source	The folders monitored for replication (one row per folder).
OKM_CONTENT_REPLICATION_EVENT	Source	Stores all replication events generated when content is created, modified, or deleted inside a monitored folder, tagged with the folder they belong to.
OKM_CONTENT_REPLICATION_PAIR	Target	The configured source-folder to target-folder pairs, each with its own source connection and polling cursor.
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