Page Replication

Last modified by Mohamed Boussaa on 2025/01/22 12:42

The point of the page replication feature is to allow selectively replicate wiki pages between linked instances.

A controller decides by configuration (the standard controller) or dynamically (some custom controller) to which instances a page is being replicated and to which extent.

There are two levels of replication for a page:

  • ALL: the whole page is replicated (including class, objects and attachments)
  • REFERENCE: only the reference of the page is replicated, meaning that an empty placeholder is created on the other instances

Each page is assigned an instance owner which, by default, is the instance which started replicating the page. Beside being the initiator of the replication, the instance owner is also the one in charge of automatically fixing conflicts when several instances modify the same page at the same time. When this happens the owner will merge all the versions of the page, notify all the authors involved in the conflict and add a banner above the page explaining that a conflict happen and someone should verify the merged version is accurate and validate it. It will also send back the new document, with its whole history this time, to other instances to make sure that everyone has the exact same things.

Standard document controller (the default and only provided controller)

On each page, it's possible to control if the page alone or the page and its children should be replicated and with which instances.

You can configure this in the page administration.

pageadmin.png

InformationSince version 2.2.1 of Replication Application it is possible to indicate the direction of the replication on the page administration. For a given page the replication could be done in 3 directions:

  • Both: The replication is enabled in both direction.
  • Send only: Only send updates about that document and refuse messages.
  • Receive only: Never send updates about that document but accept messages.

replication-direction.png

Document status

Below each page, you get information about the replication status of that page (which replication configuration is associated with this page, etc.).

docextra.png

readonly.png

Messages

The page replication use case is relying on the following messages:

Allowed from any instance by default:

  • entity_update: send to other instance either a complete version of the page (in case of page creation of when a page starts to be replicated) or the latest version (when a page which was already replicated has been modified)
  • entity_delete: indicate to other instances that a page should be deleted
  • entity_reference: indicate to other instances which are only allowed to see the reference of a page that it's just been created (or just started to be replicated)
  • entity_conflict: message used to update the conflict status of a page (generally to indicate that the document is not in conflict anymore)
  • entity_controller: indicate to other instances the replication configuration for a given page
  • entity_like: send to other instances the like status for a given user on a given page

Only allowed from the owner instance by default:

  • entity_unrepicate: indicate to other instances that a page should be delete, the difference with ENTITY_DELETE being that it's also removed from the trash bin. That's the message used when the owner instance of a page decide that the page should not be replicated anymore to a given instance (maybe the previous status was actually a mistake, etc.)
  • entity_history: indicate to other instances modifications made to the page history

Global option

It's possible to control through xwiki.properties properties several behaviors:

  #-# The maximum number of previous versions metadata to send with each update message.
  #-# The default is:
  # replication.entity.ancestorMaxCount=50

  #-# Control who is allowed to send each type of message in case of full replication.
  #-# By default all instances are allowed to send all types of message except for entity_unrepicate and entity_history.
  #-#
  #-# To modify a given message type, use the format "replication.entity.who.<message_type>" for the key and one of the following values:
  #-# * "NOONE": no instance is allowed to send this type of message, not even the owner instance
  #-# * "OWNER": only the owner instance is allowed to sent this type of messages
  #-# * "EVERYONE": all instances are allowed to send this type of messages
  #-#
  #-# For example:
  # replication.entity.who.entity_history=EVERYONE

Get Connected