Migrating your project from the hierarchical location fixture to the flat location fixture.
Why might you want to do this? The flat fixture is much simpler to use and understand, and it's faster!
I'm making a new domain and want to use the flat fixture
We got you covered, all new domains use the flat fixture by default.
I have an existing domain that I want to upgrade to the flat fixture
Go to "Project Settings" then on the left, under "Pre-Release Features" click "Location Fixture". If you don't see this link, you're probably already on the flat fixture. That page lets you configure which version to send to the phone. If the flat fixture is enabled here, your forms will automatically try to reference the flat fixture in new builds of your app.
We expect that the migration will go something like this:
Starting off, you may have an existing app which references the old fixture, and this app may have active users. The idea is to be able to migrate your app without disrupting active users.
Go to the aforementioned "Location Fixture" page and check "Sync the flat location fixture". Do not uncheck the other box yet.
Begin converting your app to use the flat fixture as described on https://dimagi.atlassian.net/wiki/x/DArKfw. You can make new app versions to a phone and test them out, and your existing users won't be affected (As usual, don't release any new builds until it's working so your users don't accidentally update).
Once you're confident that it's working, star the new app version and get your users to update.
Once none of your users are using the old app version, you can uncheck "Sync the hierarchical location fixture" to reduce the size of the restore payload that must be synced to the phones.
I have an existing domain with multiple apps that I want to upgrade to the flat fixture incrementally
Go to "Project Settings" then on the left, under "Pre-Release Features" click "Location Fixture".
Ensure that the option "Sync the hierarchicial location fixture (legacy format)." is already selected. If it is not selected, then you are already on the flat fixture format.
On the application that you want to upgrade, go to the applications settings page by selecting the gear in the app builder.
Go to the "Advanced Settings" tab. Under the "Advanced" section select "Both Hierarchical and Flat Fixture" from the "App Aware Location Fixture Format" dropdown. This will allow you to reference both the hierarchical fixture and flat fixture in this app.
To reference both fixtures you need to add the instance references in your form appropriately. In your form that references them both you must add:
<instance src="jr://fixture/locations" id="locations" />
<instance src="jr://commtrack:locations" id="locations_old" />
When writing your xpath references, to refer to the new flat file you use "instance('locations')" to refer to the old format you can use "instance('locations_old')"
Note: you can put anything you want in the id= section above. That is how you'll refer to it in your app.
Begin converting your app to use the flat fixture as described on https://dimagi.atlassian.net/wiki/x/DArKfw. You can make new app versions and publish them to a phone and test them out, and your existing users won't be affected (As usual, don't release any new builds until it's working so your users don't accidentally update).
Once you're confident that it's working and all location references have been converted to the flat fixture, select the "Only Flat Fixture" from the "App Aware Location Fixture Format" dropdown. This will disallow any references to the hierarchical fixture in this app.
Test your application again with this option selected.
Once you're confident that it's working, release a new app version and get your users to update to the new version.