# Migrate to Data Rules

If your app is currently using [sync rules v2](https://docs.journeyapps.com/legacy-docs/sync-rules-v2-legacy-docs), this document outlines how to migrate your app to [data rules](https://docs.journeyapps.com/reference/build/data-model-configuration/data-rules).

{% hint style="success" %}
**Note**: New apps created after 26 July 2022 will automatically have data rules enabled. The below migration steps are not applicable for these apps.
{% endhint %}

{% hint style="warning" %}
**Important Note**

Data rules is an advanced feature where implementation details can have a significant impact on [app performance](https://docs.journeyapps.com/reference/technical/improving-app-performance) and in certain cases, app functionality. Further details are presented below.

*Please be sure to understand the* [*implications*](#undefined) *of implementing to data rules before deploying them to an environment with active users.*
{% endhint %}

### Migration process

{% hint style="warning" %}
**Migrating from sync rules v1**

If your app still uses [sync rules v1](https://docs.journeyapps.com/legacy-docs/other-features/sync-rules-v1-deprecated), it is necessary to upgrade your app to [sync rules v2](https://docs.journeyapps.com/legacy-docs/sync-rules-v2-legacy-docs) before migrating to data rules.
{% endhint %}

For apps using [sync rules v2](https://docs.journeyapps.com/legacy-docs/sync-rules-v2-legacy-docs), a "Migrate to Data Rules" button will be visible at the top-right corner of the `sync_rules.xml` file in OXIDE. Alternatively, you can call the **Migrate to Data Rules** action via the command palette.

![Migrate to Data Rules button](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FKyD1MoMaIeoKHOR0KU0S%2Fsync-rules-migrate-to-data-rules.png?alt=media\&token=3b821c0e-1416-4e97-a463-626c544e4fc6)

Once you confirm the migration by following the on-screen prompts, the following will occur automatically in the background:

* Your app's `sync_rules.xml` file will be replaced with a `data_rules.xml` file.
* Your existing sync rules will remain unchanged, however additional data rules will automatically be added to your `data_rules.xml` file to continue to support existing functionality in your app. Please see [more details below](#automatically-created-data-rules).
* "Sync rules"/"sync bucket" terminology will be updated to "data rules"/"data bucket" throughout OXIDE. For example, to open the data rules XML file, type "data\_rules" into the command palette.

A dialog will appear when the migration is completed. Deploy your app to testing to test the data rules.

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2F6VCHmRsk7x43O7zCemWZ%2Fmigrate-to-data-rules-complete.png?alt=media\&token=72f0e16a-0ed2-4ff6-87ca-39e9df144cde)

{% hint style="warning" %}
**Known limitation**

Currently, comments in `sync_rules.xml` (e.g. `<!-- This is a comment -->`) will not be migrated to the `data_rules.xml` file. We suggest that you keep a copy of the sync rules file prior to migrating to data rules, and then manually adding back the comments afterwards.
{% endhint %}

{% hint style="info" %}
**Reverting the data rules migration**

It is safe to revert the data rules migration in your app by reverting to a previous revision, or by discarding your draft or individual file changes in git-enabled apps.
{% endhint %}

### Automatically created data rules

Certain data rules are automatically created when migrating your app from sync rules to data rules. Namely, these are rules to support `OnlineDB` queries and write operations, to mimic the previous behavior of sync rules. See the following sections for details about these implications when implementing data rules:

* [`OnlineDB` access is disabled by default](https://docs.journeyapps.com/reference/build/data-model-configuration/data-rules/..#onlinedb-access-is-disabled-by-default)
* [Object writes are only performed if the user has access before and after an update](https://docs.journeyapps.com/reference/build/data-model-configuration/data-rules/..#object-writes-are-only-performed-if-the-user-has-access-before-and-after-an-update)

The data rules migration will add a `global-bucket` with `read="online"` and `write="any"` rules for all models in your app.&#x20;

For example, taking an app with the following data model:

{% code title="schema.xml" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data-model>
    <model name="user" label="User">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="district" />

        <display>{name}</display>
    </model>

    <model name="country" label="Country">
        <field name="name" label="Name" type="text:name"/>

        <has-many model="district" name="districts" />
        
        <display>{name}</display>
    </model>

    <model name="district" label="District">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="country" />
        <has-many model="customer" name="customers" />
        <has-many model="contact" name="contacts" />
        
        <display>{name}</display>
    </model>

    <model name="customer" label="Customer">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="district" />
        <has-many model="contact" name="contacts" />
        
        <display>{name}</display>
    </model>

    <model name="contact" label="Contact">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="customer" />
        <belongs-to model="district" />

        <display>{name}</display>
    </model>

</data-model>
```

{% endcode %}

And the following sync rules:

{% code title="sync\_rules.xml" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sync version="2">
    <!-- Sync the user object itself, required to access 'user' in the app. -->
    <bucket via="self" />
    
    <bucket via="self/district">
        <has-many name="customers" />
        <has-many name="contacts" condition="name != null"/>
    </bucket>

    <global-bucket>
        <model name="country" />
    </global-bucket>

</sync>
```

{% endcode %}

After the migration, the app's data rules will look as follows:

{% code title="data\_rules.xml" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data-rules version="3">
    <bucket via="self"/>
    
    <bucket via="self/district">
        <has-many name="customers"/>
        <has-many name="contacts" condition="name != null"/>
    </bucket>
    
    <global-bucket>
        <model name="country"/>
    </global-bucket>
    
    <!-- Created during data rules migration: -->
    <global-bucket>        
        <model name="user" read="online" write="any"/>
        <model name="country" read="online" write="any"/>
        <model name="district" read="online" write="any"/>
        <model name="customer" read="online" write="any"/>
        <model name="contact" read="online" write="any"/>
    </global-bucket>
    
</data-rules>
```

{% endcode %}

The data rules migration created global `OnlineDB` access and explicitly added unrestricted write permissions for all models in the app: `user`, `country` (in this case, a rule was already defined for `country`, so it was left unchanged), `district`, `customer`, `contact`. You can remove or update these rules as necessary.

{% hint style="info" %}
**Notes**:&#x20;

* Having two global buckets defined in data rules, such as in the example above, has no functional impact. Feel free to merge the rules into one `global-bucket`.
* Data rules are "additive", meaning all sync/read/write rules will be applied. In the example above, the data rules migration created an essentially duplicate rule for `country` - the automatically created rule would be safe to remove in this case, as the existing rule is already allows unrestricted access to the `country` model.
  {% endhint %}