Syncing Down
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.
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:
-
iOS:
- Swift
- Objective-C
[SFSyncOptions newSyncOptionsForSyncDown:SFSyncStateMergeModeOverwrite]
-
Android:
SyncOptions.optionsForSyncDown(MergeMode.OVERWRITE)
-
-
Preserve all local changes and locally modified records. Set the options parameter to the following value:
-
iOS:
- Swift
- Objective-C
[SFSyncOptions newSyncOptionsForSyncDown:SFSyncStateMergeModeLeaveIfChanged]
-
Android:
SyncOptions.optionsForSyncDown(MergeMode.LEAVE_IF_CHANGED)
-
- 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.
- Swift Class Name
- Objective-C Class Name
- Swift
- Objective-C
- Swift
- Objective-C
- Swift
- Objective-C
- Swift
- Objective-C
- Swift
- Objective-C
- Swift
- Objective-C
- To create a sync down operation without running it:
- To create and run a sync down operation that overwrites any local changes:
- To create and run an unnamed sync down operation:
- To create and run a named sync down operation:
- To run or rerun a named sync configuration:
- To rerun a previous sync operation using its sync ID:
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:
In the RootViewController
class, the syncUpDown()
method starts the flow by calling the updateRemoteData(_:onFailure:)
method of SObjectDataManager
.
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:)
. TheonSuccess
argument passed torefreshRemoteData
is the block passed in fromsyncUpDown
.
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
onSObjectsDataManager
. 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.
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.