To download sObjects from the server to your local Mobile Sync soup, use the appropriate “sync down” method.
For sync down methods, you define a target that provides the list of sObjects to be downloaded. To provide an explicit list, use JSONObject on Android, or NSDictionary on iOS. However, you can also define the target with a query string. The sync target class provides factory methods for creating target objects from a SOQL, SOSL, or MRU query.
You also specify the name of the SmartStore soup that receives the downloaded data. This soup is required to have an indexed string field named __local__. Mobile SDK reports the progress of the sync operation through the callback method or update block that you provide.
Merge Modes
Sync down methods support an option that lets you control how incoming data merges with locally modified records. Choose one of the following behaviors:
Overwrite modified local records and lose all local changes. Set the options parameter to the following value:
If you use a version of syncDown that doesn’t take an options parameter, existing sObjects in the cache can be overwritten. To preserve local changes, always run sync up before running sync down.
Sync down payloads don’t reflect records that have been deleted on the server. As a result, the update operation doesn’t automatically delete the corresponding records in the target soups. These records that remain in the soup after deletion on the server are known as ghosts. To delete them, call one of the cleanResyncGhosts methods after you sync down.
Important
iOS Sync Manager Methods
Swift Class Name
1SyncManager
Objective-C Class Name
1SFMobileSyncSyncManager
To create a sync down operation without running it:
The MobileSyncExplorerSwift sample app demonstrates how to use named syncs and sync configuration files with the Salesforce Contact object. In iOS, this sample defines a ContactSObjectData class that represents a contact record as a Swift object. The sample also defines several support classes:
ContactSObjectDataSpec
SObjectData
SObjectDataSpec
SObjectDataFieldSpec
SObjectDataManager
To sync Contact data with the SmartStore soup, this app defines the following named sync operations in the Resources/usersyncs.json file:
For the first argument of updateRemoteData, which represents success, syncUpDown passes a block that calls the refreshList() method of RootViewController. This method filters the local contacts according to customer input and refreshes the view.
updateRemoteData performs a sync up ensures that allowed soup changes are merged into the Salesforce org. If sync up succeeds—that is, if the SyncState status indicates “done”—then updateRemoteData does the following:
Retrieves all raw data from the freshly updated soup.
Transforms the soup’s data to ContactSObjectData objects and stores these objects in an internal array.
Passes control to refreshRemoteData(_:onFailure:). The onSuccess argument passed to refreshRemoteData is the block passed in from syncUpDown.
In refreshRemoteData, the app again calls reSync but with the syncDownContacts model—aliased as kSyncDownName—to update the soup. If sync down succeeds, refreshRemoteData “closes the circle” by executing the block that’s passed to it from syncUpDown via updateRemoteData.
To summarize everything that happens in the syncUpDown call stack:
Sync up: It syncs soup changes up to the server by calling updateRemoteData on SObjectsDataManager. This step ensures that all allowable local and offline changes are merged into Salesforce.
Sync down: After the soup records are merged with server data, it syncs server data down to the soup through a call to refreshRemoteData. This step ensures that the soup reflects changes originating on the server and also changes merged from sync up. Remember: The sync up merge mode determines which soup edits are allowed on the server.
Finally, it updates its UI with the updated contact records from the soup.
When you’re syncing records, always call sync down after sync up as demonstrated by the MobileSyncExplorerSwift sample app.
Important
Android Example
The native MobileSyncExplorer sample app demonstrates how to use Mobile Sync named syncs and sync configuration files with Contact records. In Android, it defines a ContactObject class that represents a Salesforce Contact record as a Java object. To sync Contact data down to the SmartStore soup, the syncDown() method resyncs a named sync down configuration that defines a SOQL query.
In the following snippet, the reSync() method loads the following named sync operations from the res/raw/usersyncs.json file:
If the sync down operation succeeds—that is, if sync.getStatus() equals Status.DONE—the received data goes into the specified soup. The callback method then fires an intent that reloads the data in the Contact list.
1public synchronized void syncDown(){2 try{3 syncMgr.reSync(SYNC_DOWN_NAME /* see usersyncs.json */, new SyncUpdateCallback(){4 @Override5 public void onUpdate(SyncState sync){6 if(Status.DONE.equals(sync.getStatus())){7 fireLoadCompleteIntent();8}9}10});11}catch(JSONException e){12 Log.e(TAG, "JSONException occurred while parsing", e);13}catch(MobileSyncException e){14 Log.e(TAG, "MobileSyncException occurred while attempting to sync down", e);15}16}
1private void handleSyncUpdate(SyncState sync){2 if(Looper.myLooper() == null){3 Looper.prepare();4}5 if(sync.isDone()){6 switch(sync.getType()){7 case syncDown:8 Toast.makeText(MainActivity.this,9 "Sync down successful!",10 Toast.LENGTH_LONG).show();11 break;12 case syncUp:13 Toast.makeText(MainActivity.this,14 "Sync up successful!",15 Toast.LENGTH_LONG).show();16 syncDownContacts();17 break;18 default:19 break;20}21}22}
We've Moved
Welcome to the new home of the Mobile SDK Developer Guide! For now, the Japanese guide can be found in PDF form.
j