Automated synchronization of JSONStore collections with CouchDB databases

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, 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.

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

This feature is available in Android environment only. Support for iOS and Cordova will be available shortly.
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 using the JSONStoreInitOptions.syncPolicy field. Sync Policy can be one of the following three policies.

    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.



    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.



    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.


This is the adapter name that is deployed.



   initOptions.syncAdapterPath = "JSONStoreCloudantSync"; //Here "JSONStoreCloudantSync" is the name of the adapter.

Deploying the sync adapter

  • Download the JSONStoreSync adapter from here, configure cloudant credentials in path ‘src/main/adapter-resources/adapter.xml’ and deploy it in your MobileFirst server.
  • Configure the credentials to the backend Cloudant database also through the mfpconsole like below :
Configure Cloudant Cloudant credentials

Few points to consider before using this feature

At the time of publishing this post, this feature is available for the Android native environment.

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 :


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.



Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on June 07, 2018