Migrating to Sync Rules v2

Documentation

This document describes the differences between v1 and v2, as well as the migration process. For details on v2, see Sync Rules v2.

Version 2 of sync rules was introduced to:

1. Provide more flexibility in specifying what is synchronized to each user.

2. Better match our internal implementation.

Sync rules v2 is centered around a system of buckets, which group objects together to be synchronized to one or more users.

The flexibility of v2 comes in with how developers can specify which buckets must be synchronized to each user, by using the via field. For details, see the Sync Rules v2 documentation.

Migration

Migrating from v1 to v2 Sync Rules is a manual process for developers. Please follow the reference documentation below to migrate your sync rules.

Note that the v2 syntax is compatible with all v4 container versions. Sync performance improvements have been implemented in version 4.24, which does affect how sync rules can be used in practice. See the section on changing bucket roots for details.

Note that the sync rules have to be deployed to take effect. Since this will require full reprocessing, it is advisable to do this after business hours. Contact JourneyApps Support if you are unsure about this process.

Migration reference

Global objects

Version 1

<user type="user">
    <object type="material_type" condition="archived != true" />
    <object type="joint_element" />
    <object type="joint_area" />
</user>

Version 2

<global-bucket>
    <model name="material_type" condition="archived != true" />
    <model name="joint_element" />
    <model name="joint_area" />
</global-bucket>

Single has-many

Version 1

<user type="user">
    <relationship has_many="sites" condition="active == true" />
</user>

Version 2

<bucket via="self">
    <has-many name="sites" condition="active == true" />
</bucket>

Nested has-many/has-many

Version 1

<user type="user">
    <relationship has_many="sites">
    <relationship has_many="areas" />
    <relationship has_many="sub_areas" />
    <relationship has_many="element_groups" />
    </relationship>
</user>

Version 2

<bucket via="sites">
    <has-many name="areas" />
    <has-many name="sub_areas" />
    <has-many name="element_groups" />
</bucket>

Nested belongs-to/has-many

Version 1

<user type="user">
    <relationship belongs_to="region" condition="archived != true">
    <relationship has_many="areas" />
    <relationship has_many="sub_areas" />
    <relationship has_many="element_groups" condition="type == 2" />
    </relationship>
</user>

Version 2

<bucket via="region[archived != true]">
    <has-many name="areas" />
    <has-many name="sub_areas" />
    <has-many name="element_groups" condition="type == 2" />
</bucket>

User conditions

Version 2

<user type="user" condition="role != 'admin'">
    <relationship has_many="sites" />
</user>

Version 2

<bucket via="self[role != 'admin']">
    <has-many name="sites" />
</bucket>

Synchronize everything

Version 1

<sync>
</sync>

Version 2

<?xml version="1.0" encoding="UTF-8"?>
    <sync version="2">
    <global-bucket>
    <all-models />
    </global-bucket>
</sync>