Using Sync Names

Mobile SDK provides a collection of APIs for using and managing named sync operations. You can programmatically create and delete named syncs at runtime, run or rerun them by name, and manage named syncs in memory.

Name-Based APIs (iOS)

Most of these methods are new. Updated methods use the same parameters as their existing analogs for target, options, and updateBlock.

Get sync status by name

Swift

1var syncStatus = syncManager.getSyncStatus(syncName: syncState.syncName)

Objective-C

1- (nullable
2       SFSyncState*)getSyncStatusByName:(NSString*)syncName;

Check for an existing sync by name

Swift

1var syncExists = syncManager.hasSync(syncName: syncState.syncName)

Objective-C

1- (BOOL)hasSyncWithName:(NSString*)syncName;

Delete a sync configuration by name

Swift

1syncManager.deleteSync(syncName: syncState.syncName)

Objective-C

1- (void)deleteSyncByName:(NSString*)syncName;

Create, run, or rerun a named sync configuration

See Syncing Down and Syncing Up.

Call cleanResyncGhosts with a named sync configuration

See Calling cleanResyncGhosts Methods by Sync Name.

Name-Based APIs (Android)

Most of these methods are new. Overridden methods use the same parameters as their existing analogs for target, options, and callback.

Get sync status by name

1public SyncState getSyncStatus(String name);

Check for an existing sync by name

1public boolean hasSyncWithName(String name);

Delete a sync configuration by name

1public void deleteSync(String name);

Create, run, or rerun a named sync configuration

See Syncing Down and Syncing Up.

Call cleanResyncGhosts with a named sync configuration

See Calling cleanResyncGhosts Methods by Sync Name.

Name-Based APIs (Hybrid)

Most of these methods are existing legacy APIs. Wherever a sync ID is accepted, you can pass the sync name instead.

Get sync status by name

You can use this function to determine if a sync configuration exists. It returns null if the sync configuration doesn’t exist.

1getSyncStatus(storeConfig, syncIdOrName, successCB, errorCB)

Delete a sync configuration by name

1deleteSync(storeConfig, syncIdOrName, successCB, errorCB)

Create and run a named sync configuration

The legacy syncDown() function now includes a syncName parameter. If the name is provided, Mobile SDK creates a configuration with the given name. This function fails if the requested sync name already exists.

1syncDown(storeConfig, target, soupName, options, syncName, successCB, errorCB)

1syncUp(storeConfig, target, soupName, options, syncName, successCB, errorCB)

Run (or rerun) any sync by name

This existing method now has an overload that accepts either a sync ID or name.

1reSync(storeConfig, syncIdOrName, successCB, errorCB)

Name-Based APIs (React Native)

Most of these methods are existing legacy APIs. Wherever a sync ID is accepted, you can pass the sync name instead.

Get sync status by name

This existing method now has an overload that accepts either a sync ID or a sync name.

getSyncStatus(storeConfig, syncIdOrName, successCB, errorCB)

Delete by name

This method, new in Mobile SDK 6.0, accepts either a sync ID or a sync name.

deleteSync(storeConfig, syncIdOrName, successCB, errorCB)

Create and run a sync with a name - new optional parameter syncName

This existing method now has an optional parameter that accepts a sync name.

1syncDown(storeConfig, target, soupName, options, syncName, successCB, errorCB)
2syncUp(storeConfig, target, soupName, options, syncName, successCB, errorCB)

Run (or rerun) any sync by name - overloaded to accept id or name

This existing method now has an overload that accepts either a sync ID or a sync name.

reSync(storeConfig, syncIdOrName, successCB, errorCB)

Invoking the Resync Method in Native iOS Apps

Excerpt from SObject.swift from MobileSyncExplorerSwift template app. In this example, updateRemoteData calls reSync with a sync up configuration (kSyncUpName). If that operation succeeds, it then calls refreshRemoteData with a sync down configuration (kSyncDownName). This follow-up step ensures that the soup reflects all the latest changes on the server:

1func updateRemoteData(_ onSuccess: @escaping ([SObjectData]) -> Void, onFailure:@escaping (NSError?, SyncState?) -> Void) -> Void {
2    do {
3        try self.syncMgr.reSync(named: kSyncUpName) { [weak self] (syncState) in
4            guard let strongSelf = self else {
5                return
6            }
7            switch (syncState.status) {
8            case .done:
9                do {
10                    let objects = try strongSelf.queryLocalData()
11                    strongSelf.populateDataRows(objects)
12                    try strongSelf.refreshRemoteData({ (sobjs) in
13                        onSuccess(sobjs)
14                    }, onFailure:  { (error,syncState) in
15                        onFailure(error,syncState)
16                    }
17                    )
18                } catch let error as NSError {
19                    MobileSyncLogger.e(SObjectDataManager.self, message: "Error with Resync \(error)" )
20                    onFailure(error,syncState)
21                }
22                break
23            case .failed:
24                MobileSyncLogger.e(SObjectDataManager.self, message: "Resync \(syncState.syncName) failed" )
25                onFailure(nil,syncState)
26                break
27            default:
28                break
29            }
30        }
31    } catch {
32        onFailure(error as NSError, nil)
33    }
34}

1func refreshRemoteData(_ completion: @escaping ([SObjectData]) -> Void,
2                          onFailure: @escaping (NSError?, SyncState) -> Void)
3                          throws -> Void {
4    try self.syncMgr.reSync(named: kSyncDownName) { [weak self] (syncState) in
5        switch (syncState.status) {
6        case .done:
7            do {
8                let objects = try self?.queryLocalData()
9                self?.populateDataRows(objects)
10                completion(self?.fullDataRowList ?? [])
11            } catch {
12                MobileSyncLogger.e(SObjectDataManager.self, message: "Resync \(syncState.syncName) failed \(error)" )
13            }
14             break
15        case .failed:
16             MobileSyncLogger.e(SObjectDataManager.self, message: "Resync \(syncState.syncName) failed" )
17             onFailure(nil,syncState)
18        default:
19            break
20        }
21    }
22}

Invoking the Resync Method in Native Android Apps

Excerpt from SObjectSyncableRepoBase.kt from MobileSyncExplorerKotlinTemplate.

1private suspend fun doSyncUp(): SyncState {
2    try {
3        return syncManager.suspendReSync(syncUpName)
4    } catch (es: SyncManager.ReSyncException.FailedToStart) {
5        throw SyncUpException.FailedToStart(cause = es)
6    } catch (ef: SyncManager.ReSyncException.FailedToFinish) {
7        throw SyncUpException.FailedToFinish(cause = ef)
8    }
9}

Excerpt from ContactListLoader.java from Android MobileSyncExplorer native sample app:

1public synchronized void syncUp() {
2    try {
3        syncMgr.reSync(SYNC_UP_NAME /* see usersyncs.json */, new SyncUpdateCallback() {
4        @Override
5            public void onUpdate(SyncState sync) {
6                if (Status.DONE.equals(sync.getStatus())) {
7                    syncDown();
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 up", e);
15    }
16}

1public synchronized void syncDown() {
2    try {
3        syncMgr.reSync(SYNC_DOWN_NAME /* see usersyncs.json */, new SyncUpdateCallback() {
4        @Override
5            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}

Invoking the Resync Method in Hybrid Apps

Excerpt from MobileSyncExplorer.html from MobileSyncExplorerHybrid sample app:

1syncDown: function() {
2    cordova.require("com.salesforce.plugin.mobilesync").reSync("syncDownContacts" /* see usersyncs.json */,
3                     this.handleSyncUpdate.bind(this));
4},
5syncUp: function() {
6    cordova.require("com.salesforce.plugin.mobilesync").reSync("syncUpContacts" /* see usersyncs.json */,
7                    this.handleSyncUpdate.bind(this));},

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.