Automated synchronization of JSONStore collections with CouchDB databases in iOS and Cordova

MobileFirst JSONStore already allows you to write code to be able to pull and push data from/to an external data source, see here.

Starting with iFix 8.0.0.0-MFPF-IF201802201451, MobileFirst Android SDK can be used to automate the synchronization of data between a JSONStore collection on a device with any CouchDB database including Cloudant. Details regarding this can be found in this post. Starting from the CD Update 2 of MFP 8.0, this automated sync is available in iOS and Cordova SDK as well.

If you are an on-premise 8.0 customer or Mobile Foundation Service customer, then read further to learn about the JSONStore here.

Note:
The use of this feature can be extended to any CouchDB instance.

Setting up the synchronization between JSONStore and Cloudant

To setup automatic synchronization between JSONStore and Cloudant complete the following steps:

1. Define the Sync Policy on your mobile app.
2. Deploy the Sync Adapter on IBM Mobile Foundation.

Defining the Sync Policy

The method of synchronization between a JSONStore collection and a Cloudant database is defined by the Sync Policy. You can specify the Sync Policy in your app for each collection.

A JSONStore collection can be initialized with a Sync Policy field. Sync Policy can be one of the following three policies.

1. SYNC_DOWNSTREAM
   Use this policy when you want to download data from Cloudant on to the JSONStore collection. This is typically used for static data that is required for offline storage. For example, price list of items in a catalog. Each time the collection is initialized on the device, data is refreshed from the remote Cloudant database. While the entire database is downloaded for the first time, subsequent refreshes will download only delta, comprising of the changes made on the remote database.

   Usage:

   IOS:

   openOptions.syncPolicy = SYNC_DOWNSTREAM;
   

   Cordova:

   collection.sync = {
       syncPolicy:WL.JSONStore.syncOptions.SYNC_DOWNSTREAM
   }
   

2. SYNC_UPSTREAM
   Use this policy when you want to push local data to a Cloudant database. For example, uploading of sales data captured offline to a Cloudant database. When a collection is defined with the SYNC_UPSTREAM policy, any new records added to the collection creates a new record in Cloudant. Similarly, any document modified in the collection on the device will modify the document on Cloudant and documents deleted in the collection will also be deleted from the Cloudant database.

   Usage:

   IOS:

   openOptions.syncPolicy = SYNC_UPSTREAM;
   

   Cordova:

   collection.sync = {
       syncPolicy:WL.JSONStore.syncOptions.SYNC_UPSTREAM
   }
   

3. SYNC_NONE
   This is the default policy. Choose this policy for synchronization to not take place.

Important: The Sync Policy is attributed to a JSONStore Collection. Once a collection is initialized with a particular Sync Policy, it should not be changed. Modifying the Sync Policy can lead to undesirable results.

syncAdapterPath

This is the adapter name that is deployed.

Usage:

IOS:

 openOptions.syncAdapterPath = "JSONStoreCloudantSync"; 

Cordova:

collection.sync = {
	syncPolicy://One of the three sync policies,
	syncAdapterPath : 'JSONStoreCloudantSync'
}

Note: Details on deploying the adapter can be found here.

Few points to consider before using this feature

The name of the JSONStore collection and CouchDB database name must be the same. Carefully refer to your CouchDB’s database naming syntax before naming your JSONStore collection.

A JSONStoreCollection can be defined with only one of the allowed Sync Policies, i.e., SYNC_DOWNSTREAM, SYNC_UPSTREAM or SYNC_NONE.

If an upstream or downstream sync has to be performed at any time after the initialization explicitly, the following API can be used :

sync()

This performs a downstream sync if the calling collection has a sync policy set to ‘SYNC_DOWNSTREAM’. Else, if the sync policy is set to ‘SYNC_UPSTREAM’, an upstream sync for added, deleted and replaced documents from jsonstore to Cloudant database is performed.

Usage:

IOS:

collection.sync(); //Here collection is the JSONStore collection object that was initialized

Cordova:

WL.JSONStore.get(collectionName).sync();