Wiki source code of Page Replication
Last modified by Thomas Mortagne on 2026/04/28 15:38
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | The point of the page replication feature is to allow selectively replicate wiki pages between linked instances. | ||
| 6 | |||
| 7 | 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. The way it works is by associating a replication configuration to a location (generally a whole location, with all its children, but it's also possible to target a specific page without its children) which may or may not exist yet (when something is saved in that location, it will automatically be replicated). | ||
| 8 | |||
| 9 | There are two levels of replication for a page: | ||
| 10 | |||
| 11 | * ##ALL## ("Everything" in the UI): the whole page is replicated (including class, objects and attachments) | ||
| 12 | * ##REFERENCE## ("Placeholder in the UI"): only the reference of the page is replicated, meaning that a placeholder is created on the other instances (as an hidden empty page) | ||
| 13 | |||
| 14 | 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. | ||
| 15 | |||
| 16 | == Limitations == | ||
| 17 | |||
| 18 | * renames: since the replication configuration is focusing on location, and not actual pages, it does not follow renames. This might change in the future when [[REPLICAT-211>>https://jira.xwiki.org/browse/REPLICAT-211]] is implemented. | ||
| 19 | |||
| 20 | == Standard document controller (the default and only provided controller) == | ||
| 21 | |||
| 22 | 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. | ||
| 23 | |||
| 24 | You can configure this in the page administration. | ||
| 25 | |||
| 26 | {{image reference="pageadmin.png"/}} | ||
| 27 | |||
| 28 | {{info}}Since version 2.2.1 of Replication Application{{/info}} 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: | ||
| 29 | |||
| 30 | * **Both:** The replication is enabled in both direction. | ||
| 31 | * **Send only:** Only send updates about that document and refuse messages. | ||
| 32 | * **Receive only:** Never send updates about that document but accept messages. | ||
| 33 | |||
| 34 | {{image reference="replication-direction.png" width="800"/}} | ||
| 35 | |||
| 36 | == Document status == | ||
| 37 | |||
| 38 | Below each page, you get information about the replication status of that page (which replication configuration is associated with this page, etc.). | ||
| 39 | |||
| 40 | {{image reference="docextra.png"/}} | ||
| 41 | |||
| 42 | |||
| 43 | {{image reference="placeholder.png"/}} | ||
| 44 | |||
| 45 | == Messages == | ||
| 46 | |||
| 47 | The page replication use case is relying on the following messages: | ||
| 48 | |||
| 49 | Allowed from any instance by default: | ||
| 50 | |||
| 51 | * ##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) | ||
| 52 | * ##entity_delete##: indicate to other instances that a page should be deleted | ||
| 53 | * ##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) | ||
| 54 | * ##entity_conflict##: message used to update the conflict status of a page (generally to indicate that the document is not in conflict anymore) | ||
| 55 | |||
| 56 | * ##entity_controller##: indicate to other instances the replication configuration for a given page | ||
| 57 | |||
| 58 | * ##entity_like##: send to other instances the ##like## status for a given user on a given page | ||
| 59 | |||
| 60 | Only allowed from the owner instance by default: | ||
| 61 | |||
| 62 | * ##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.) | ||
| 63 | * ##entity_history##: indicate to other instances modifications made to the page history | ||
| 64 | |||
| 65 | == Global option == | ||
| 66 | |||
| 67 | It's possible to control through ##xwiki.properties## properties several behaviors: | ||
| 68 | |||
| 69 | {{code language="properties"}} | ||
| 70 | #-# The maximum number of previous versions metadata to send with each update message. | ||
| 71 | #-# The default is: | ||
| 72 | # replication.entity.ancestorMaxCount=50 | ||
| 73 | |||
| 74 | #-# Control who is allowed to send each type of message in case of full replication. | ||
| 75 | #-# By default all instances are allowed to send all types of message except for entity_unreplicate and entity_history. | ||
| 76 | #-# | ||
| 77 | #-# To modify a given message type, use the format "replication.entity.who.<message_type>" for the key and one of the following values: | ||
| 78 | #-# * "NOONE": no instance is allowed to send this type of message, not even the owner instance | ||
| 79 | #-# * "OWNER": only the owner instance is allowed to sent this type of messages | ||
| 80 | #-# * "EVERYONE": all instances are allowed to send this type of messages | ||
| 81 | #-# | ||
| 82 | #-# For example: | ||
| 83 | # replication.entity.who.entity_history=EVERYONE | ||
| 84 | {{/code}} |
