Mobile Sync Plugin Methods
The Mobile Sync plug-in exposes two methods: syncDown()
and syncUp()
. When you use these methods, several important guidelines can make your life simpler:
- To create, update, or delete records locally for syncing with the plug-in, use
Force.SObject
frommobilesync.js
. Mobile Sync expects some special fields on soup records thatmobilesync.js
creates for you. - Similarly, to create the soup that you’ll use in your sync operations, use
Force.StoreCache
frommobilesync.js
. - If you’ve changed objects in the soup, always call
syncUp()
before callingsyncDown()
.
Downloads the sObjects specified by target
into the SmartStore soup specified by soupName
. If sObjects in the soup have the same ID as objects specified in the target, Mobile Sync overwrites the duplicate objects in the soup.
Mobile Sync also supports a refresh sync down target, which simplifies the process of refreshing cached records. See Using the Refresh Sync Down Target.
Syntax
Parameters
isGlobalStore
(Optional) Boolean that indicates whether this operation occurs in a global or user-based SmartStore database. Defaults to false.
storeConfig
(Optional) StoreConfig object that specifies a store name and whether the store is global or user-based.
target
Indicates which sObjects to download to the soup. Can be any of the following strings:
-
Downloads the sObjects returned by the given SOQL query.
-
Downloads the sObjects returned by the given SOSL query.
-
Downloads the specified fields of the most recently used sObjects of the specified sObject type.
-
Downloads the records specified by the given custom targets. If you use custom targets, provide either
androidImpl
oriOSImpl
, or, preferably, both.See Using Custom Sync Down Targets.
-
soupName
Name of soup that receives the downloaded sObjects.
options
Use one of the following values:
- To overwrite local records that have been modified, pass
{mergeMode:Force.MERGE_MODE_DOWNLOAD.OVERWRITE}
. - To preserve local records that have been modified, pass
{mergeMode:Force.MERGE_MODE_DOWNLOAD.LEAVE_IF_CHANGED}
. With this value, locally modified records are not overwritten.
- To overwrite local records that have been modified, pass
callback
Function called once the sync has started. This function is called multiple times during a sync operation:
- When the sync operation begins
- When the internal REST request has completed
- After each page of results is downloaded, until 100% of results have been received
Status updates on the sync operation arrive via browser events. To listen for these updates, use the following code:
The
event.detail
member contains a map with the following fields:syncId
: ID for this sync operationtype
: “syncDown”target
: Targets you providedsoupName
: Soup name you providedoptions
: “{}”status
: Sync status, which can be “NEW”, “RUNNING”, “DONE” or “FAILED”progress
: Percent of total records downloaded so far (integer, 0–100)totalSize
: Number of records downloaded so far
Uploads created, deleted, or updated records in the SmartStore soup specified by soupName
, and then updates, creates, or deletes the corresponding records on the Salesforce server. Updates are reported through browser events.
Syntax
Parameters
isGlobalStore
(Optional) Boolean that indicates whether this operation occurs in a global or user-based SmartStore database. Defaults to false.
storeConfig
(Optional) StoreConfig object that specifies a store name and whether the store is global or user-based.
target
JSON object that contains at least the name of one native custom target class, if you define custom targets.
A Salesforce object can require certain fields that can’t be updated by apps. With these objects, a target that uses a single field list for both create and update operations can fail if it tries to update locked fields. Past versions of Mobile Sync required the developer to create a custom native target to differentiate between create and update field lists.
As of Mobile SDK 5.1, you no longer have to define custom native targets for these scenarios. Instead, to specify distinct field lists for create and update operations, add the following JSON object to the
target
object:If you provide
createFieldlist
andupdateFieldlist
arguments, the native custom target uses them where applicable. In those cases, the target ignores the field list defined in its “sync options” settings.See the
syncDown()
method description for more information ontarget
metadata.soupName
Name of soup from which to upload sObjects.
options
A map with the following keys:
fieldlist
: List of fields sent to the server.mergeMode
:- To overwrite remote records that have been modified, pass “OVERWRITE”.
- To preserve remote records that have been modified, pass “LEAVE_IF_CHANGED”. With this value, modified records on the server are not overwritten.
- Defaults to “OVERWRITE” if not specified.
callback
Function called multiple times after the sync has started. During the sync operation, this function is called for these events:
- When the sync operation begins
- When the internal REST request has completed
- After each page of results is uploaded, until 100% of results have been received
Status updates on the sync operation arrive via browser events. To listen for these updates, use the following code:
The
event.detail
member contains a map with the following fields:syncId
: ID for this sync operationtype
: “syncUp”target
: “{}” or a map or dictionary containing the class names of iOS and Android custom target classes you’ve implementedsoupName
: Soup name you providedoptions
:fieldlist
: List of fields sent to the servermergeMode
: “OVERWRITE” or “LEAVE_IF_CHANGED”
status
: Sync status, which can be “NEW”, “RUNNING”, “DONE” or “FAILED”progress
: Percent of total records downloaded so far (integer, 0–100)totalSize
: Number of records downloaded so far