Syncing Up by External ID

Mobile SDK enhances its sync-up functionality by adding the ability to sync up by external ID. To use this feature, you specify an external ID field name in the sync up target definition. If a soup record is marked as locally created, updated, or deleted and has an external ID value, Mobile Sync syncs it up using upsert instead of create. If the record also has a valid Id value, however, Mobile Sync updates the indicated Salesforce record.

You can configure the external ID field name in Mobile Sync configuration files or in code. External IDs are supported for standard sync up targets and parent-child sync up targets.

Upserts are useful for avoiding record duplication. When your sync target supports an external ID field name and a locally created record has a value for that field, Mobile Sync upserts, rather than creates, the server record.

True upsert behavior allows the app to deal with network disconnection gracefully. If the network disconnects during a sync up, the app typically doesn’t know whether its last request reached the server. In this case, the app’s logical reaction when connectivity returns is to resync.

However, consider what happens if the server did in fact received your request and created the record. In this case, resyncing without using upsert creates a duplicate record. If you’ve configured external ID field names in the sync up target, the resync can run safely: upsert finds the recently created record and merely rewrites the record’s fields with their existing values.

In parent-child scenarios, you can specify the external ID field name for parent or children, or both. For a graceful offline experience, it’s best to define the external ID field name in parent and children sync configurations.

Here are examples of specifying an external ID field name declaratively for a target in sync configuration files.

Standard Sync Up Target

Parent-Child Sync Up Target

Extended Example

For a “one-stop” example of many types of sync configurations, see shared/example.usersyncs.json in the github.com/forcedotcom/SalesforceMobileSDK-Shared GitHub repo.

For standard sync up targets:

Swift

Set the externalIdFieldName property in your SyncUpTarget or BatchSyncUpTarget class.

Objective-C

Set the externalIdFieldName property in your SFSyncUpTarget or SFBatchSyncUpTarget class.

For parent-child sync up targets:

Swift

Objective-C

Pass a non-nil value to the externalIdFieldName parameters of these factory methods (new in Mobile SDK 9.0):

For standard sync up targets:

• : Create your target with one of these constructors:

  For parent-child sync up targets: - : Pass a non-nil value to the externalIdFieldName parameters of these factory methods (new in Mobile SDK 9.0):