Using the Briefcase Sync Down Target

If your org uses Briefcases for your mobile users, the Briefcase sync down target was introduced in Mobile SDK 10.1. This sync target is an efficient way to load many records at a time. Sync is constrained to the records included in all Briefcases assigned to the current user and made accessible in the mobile client’s Connected App. You can limit the sync target to specific objects and fields included in those Briefcases. This target takes an array of BriefcaseObjectInfo objects, which include sObject type, fields, and the soup to add them to.

SOQL sync down targets can only get one type of record at a time, and Parent Children sync down targets support only getting parent records with their children. In contrast, Briefcase sync down targets are more flexible. Briefcases can be defined to include many different kinds of objects, including related objects up to three levels deep. Your sync target definition can include any or all of these objects.

Tip

A briefcase is a set of queries that together select a cohesive collection of related records, optimized for the current user. Briefcases are defined in advance using Briefcase Builder, but execution of briefcase queries is delayed until the briefcase is accessed by a client application. Briefcases can be used to select records for data priming in advance of going offline, and for other general data loading purposes.

Briefcases are assigned to specific users, and queries can include the current user in their criteria. Briefcases are made accessible to your mobile app via the mobile client’s Connected App. The objects, records, and fields available via this sync target are automatically constrained by these configuration details.

Additionally, because briefcases are defined and managed by your org’s admin, your admin can change the sync behavior of client apps without requiring any code changes.

For briefcase sync targets, Mobile Sync uses Salesforce APIs that are optimized for loading large numbers of records in a single session. If you need to load hundreds or thousands of records at a time, especially in preparation for going offline, this target can be more efficient than other options.

Configuration File Usage

For the "target" property, specify the following values.

Target Properties

"type":"briefcase"

"infos": array of <BriefcaseObjectInfo> items

An array of objects that describe the specific sObjects and fields to retrieve, along with the soup to place them in.

BriefcaseObjectInfo Properties

"soupName": <string>: Name of the soup to store records of this object type into during sync.
"sobjectType": <string>: Name of a Salesforce object to sync.
"fieldlist": array of <string>: List of fields to sync for this object.
"idFieldName": <string>: (Optional) Name of a custom ID field. If you provide "idFieldName", Mobile Sync uses the field with the given name to get the ID of the record. For example, if you specify "idFieldName":"AcmeId", Mobile Sync obtains the record’s ID from the AcmeId field instead of the default Id field.
"modificationDateFieldName": <string>: (Optional) Name of the field containing the last modification date for the record. If you provide modificationDateFieldName, Mobile Sync uses the field with this name to compute the maxTimestamp value that startFetch uses to resync the records. Default field name is lastModifiedDate.

Required: “soupName”, “sobjectType”, “fieldlist”

iOS APIs

Create BriefcaseObjectInfo objects as needed, and then use them to create a sync down target object.

Swift

Class: BriefcaseSyncDownTarget

1let briefcaseAccountInfo = BriefcaseObjectInfo(
2    soupName: "soup_for_accounts", 
3    sobjectType: "Account", 
4    fieldlist: ["Name", "Description"])
5let briefcaseContactInfo = BriefcaseObjectInfo(
6    soupName: "soup_for_contacts", 
7    sobjectType: "Contact", 
8    fieldlist: ["LastName"])
9let target = BriefcaseSyncDownTarget(
10    infos: [briefcaseAccountInfo, briefcaseContactInfo])

Objective-C

Class: SFBriefcaseSyncDownTarget

1SFBriefcaseObjectInfo *briefcaseAccountInfo = [[SFBriefcaseObjectInfo alloc] 
2    initWithSoupName:@"soup_for_accounts" 
3         sobjectType:@"Account" 
4           fieldlist: @[@"Name", @"Description"]];
5SFBriefcaseObjectInfo *briefcaseContactInfo = [[SFBriefcaseObjectInfo alloc] 
6    initWithSoupName:@"soup_for_contacts" 
7         sobjectType:@"Contact" 
8           fieldlist: @[@"LastName"]];
9SFBriefcaseSyncDownTarget *target = [[SFBriefcaseSyncDownTarget alloc] 
10    initWithInfos:@[briefcaseAccountInfo, briefcaseContactInfo]];

Android APIs

Create BriefcaseObjectInfo objects as needed, and then use them to create a sync down target object.

Java

Class: BriefcaseSyncDownTarget

1BriefcaseSyncDownTarget target = new BriefcaseSyncDownTarget(
2    Arrays.asList(
3        new BriefcaseObjectInfo(
4            "soupForAccounts",
5            "Account",
6            Arrays.asList("Name", "Description")),
7        new BriefcaseObjectInfo(
8            "soupForContacts",
9            "Contact",
10            Arrays.asList("LastName"))
11    )
12);

Example

1{
2  "syncs": [
3    {
4      "syncName": "myBriefcaseSyncDown",
5      "syncType": "syncDown",
6      "soupName": "does-not-matter",
7      "target": {
8        "type": "briefcase",      
9        "infos": [
10          {
11            "sobjectType": "Account",
12            "fieldlist": [
13              "Name",
14              "Description"
15            ],
16            "soupName": "accounts"
17          },
18          {
19            "sobjectType": "Contact",
20            "fieldlist": [
21              "LastName"
22            ],
23            "soupName": "contacts"
24          }
25        ]
26      },
27      "options": {
28        "mergeMode": "OVERWRITE"
29      }
30    }
31  ]
32}

Mobile SDK Development Guide

Using the Briefcase Sync Down Target

Configuration File Usage

iOS APIs

Android APIs

Example

See Also