sync.md

Synchronization Cases

Terminology:

• SDM: Source Document Manager (e.g. the default manager in Sulu).
• TDM: Target Document Manager (e.g. the live document manager in Sulu).
• synchronize: To copy the state of something to or from a TDM.
• push: Synchronize from the SDM to a TDM.
• pull: Synchronize to the SDM from a TDM.
• draftable: When something MUST be manually synchronized to a TDM.
• non-draftable: When something is automtaically synchronized to a TDM.
• path conflict: When a SDM node is pushed to the TDM, but the path is already occupied on the TDM by an as-of-yet not synchronized node.

General Rules

1. All documents which can be synchronized must (at this stage) implement the SynchronizeBehavior.

Sulu

Routes

Strategy #1 Draftable Routes and Pages

Sulu\Bundle\ContentBundle\Document\BasePageDocument:
    auto_sync: [ "delete", "move" ]
    delete_references: true
    cascade_referrers:
        - Sulu\Bundle\ContentBundle\Document\RouteDocument
Sulu\Bundle\ContentBundle\Document\RouteDocument:
    auto_sync: []
    cascade_referrers:
        - Sulu\Bundle\ContentBundle\Document\RouteDocument

1. Pages MUST not be automatically synched, except on delete and move.
2. When a page is moved, it MUST also be moved in the TDM.
3. When a page is deleted it MUST also be removed from the TDM.
4. When a page is deleted from SDM, any references to this page in the TDM should be removed.
5. Routes MUST not be automatically synched.
6. Pages MUST be immediately deleted from the TDM when deleted from the SDM.
7. Any referring routes which exist in the TDM and do not exist in the SDM should be deleted from the TDM.

8. If there is a path conflict the TDM node name MUST be resolved by adding an

   auto-incrementing integer.
9. Route document "push" operations MUST cascade to any history routes.
10. All other documents should be fully synchronized at all times.

Reasons:

1. Pages are draftable
2. (also 3.) Moving is not within the scope of the document edit page, so user has no control over this. documents are hard-deleted.
3. Because pages are removed automatically.
4. User cannot manually syncronize the deleted status of a document -
5. Othewise we have a garbage problem (and risk of potential conflicts).
6. (applies only when moving is draftable).
7. History routes are dependent upon the "primary" route.
8. Otherwise the site is probably useless.

Issues:

• (when moving is draftable) potential for path conficts (handled by 6).
• Potential to push content to the TDM which references pages that are not synchronized to the TDM (we should probably ask the user if they also want to publish the related page).

Strategy #2 Non-draftable Routes (for reference)

Sulu\Bundle\ContentBundle\Document\BasePageDocument:
    auto_sync: [ "new", "delete", "move" ] # no "update" sync.
Sulu\Bundle\ContentBundle\Document\RouteDocument:
    auto_sync: [ "new", "update", "delete" ]

1. When a RouteDocument instance is deleted, it should be immediately removed from the TDM.
2. When a RouteDocument is created or updated it should be immediately synchronized to the TDM.
3. RouteDocument operations should cascade any history routes (which are instances of RouteDocument).
4. When a PageDocument instance is saved it will NOT need to cascade the routes, as they will already be present.
5. When a PageDocument instance is created it MUST be created in the TDM.
6. All other documents should be fully synchronized at all times.

Issues:

• Drafting history documents are synchronized to the live server as edits are made.
• The user would not intuitively realise that they are changing the URL structure of their site when editing a document, they should be notified that this will happen.

Other Things

History Route Restoration

1. The synchronization manager is not responsible for resetting the synchronization status of the referrered to document when a cascaded relation is persisted independently.
2. The PageDocument should be manually set into a de-syncronized state after a history route has been restored. (either via. the document manager or the SynchronizationManager).