BriefcaseDefinition Metadata Type in SFDX

Architectural Overview#

Mobile workforces using the Salesforce Field Service mobile app or Mobile App Plus (Offline LWC) frequently operate in environments with zero cellular connectivity—such as basements, utility substations, rural sites, or hospitals. The BriefcaseDefinition metadata type powers Briefcase Builder, Salesforce’s declarative offline data priming engine.

Architecturally, a BriefcaseDefinition defines a directed graph of object rules (BriefcaseRule), field filters (BriefcaseRuleFilter), and relationship traversals (relatedRules) coupled with user/group assignments. When a mobile user syncs their device while online, the Briefcase engine evaluates the active BriefcaseDefinition rules and caches the matching records locally on the device’s encrypted offline store so offline Lightning Web Components and Field Service flows can read and mutate records seamlessly.

SFDX Directory & File Suffix#

Key Metadata Fields#

The BriefcaseDefinition metadata type and its nested BriefcaseRule elements include the following configuration fields:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<BriefcaseDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <briefcaseRules>
        <briefcaseRuleFilters>
            <filterOperator>Equals</filterOperator>
            <filterSeqNumber>1</filterSeqNumber>
            <filterValue>High</filterValue>
            <targetEntityField>Priority</targetEntityField>
        </briefcaseRuleFilters>
        <briefcaseRuleFilters>
            <filterOperator>Equals</filterOperator>
            <filterSeqNumber>2</filterSeqNumber>
            <filterValue>New</filterValue>
            <targetEntityField>Status</targetEntityField>
        </briefcaseRuleFilters>
        <filterLogic>1 AND 2</filterLogic>
        <isAscendingOrder>false</isAscendingOrder>
        <orderBy>CreatedDate</orderBy>
        <recordLimit>500</recordLimit>
        <relatedRules>
            <relationshipField>AccountId</relationshipField>
            <relationshipType>ChildToParent</relationshipType>
            <targetEntity>Account</targetEntity>
        </relatedRules>
        <targetEntity>WorkOrder</targetEntity>
    </briefcaseRules>
    <description>Primes high-priority open WorkOrders and parent Accounts for offline Field Service technicians.</description>
    <isActive>true</isActive>
    <masterLabel>Field Tech Daily Dispatch</masterLabel>
</BriefcaseDefinition>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Field_Tech_Daily_Dispatch</members>
        <name>BriefcaseDefinition</name>
    </types>
    <version>68.0</version>
</Package>

Querying via Tooling API & SFDX CLI#

You can inspect active BriefcaseDefinition records and their rules via the Tooling API:

SELECT Id, DeveloperName, MasterLabel, IsActive, Description, LastModifiedDate
FROM BriefcaseDefinition
ORDER BY DeveloperName ASC

Retrieve and deploy BriefcaseDefinition components using Salesforce CLI:

# Retrieve BriefcaseDefinition metadata
sf project retrieve start --metadata BriefcaseDefinition:Field_Tech_Daily_Dispatch

# Deploy BriefcaseDefinition metadata to target org
sf project deploy start --metadata BriefcaseDefinition:Field_Tech_Daily_Dispatch

Senior Architect Best Practices & Gotchas#

• Selectivity & Indexed Filter Fields: Briefcase priming queries execute whenever mobile users connect and sync. Ensure every targetEntityField used in briefcaseRuleFilters on high-volume objects (>100,000 rows) is indexed (standard index or custom index on CustomField) to prevent sync query timeouts.
• Relationship Depth Limit: relatedRules can traverse up to 3 levels deep in the object hierarchy. Avoid wide ParentToChild fan-outs without strict filters, as they can rapidly exhaust the 50,000-record briefcase ceiling.
• Environment-Specific User Assignments: If you assign specific User or Group IDs to a briefcase in the UI, note that user assignments vary across sandboxes. Assign briefcases to public groups with consistent DeveloperNames across environments.

Frequently asked questions

What is the architectural purpose of BriefcaseDefinition?

It defines offline data priming rules in Briefcase Builder, specifying which object records and related parent or child records are downloaded to mobile devices for offline access.

Where are BriefcaseDefinition files stored in SFDX source format?

They are stored in the force-app/main/default/briefcaseDefinitions/ directory with the .briefcaseDefinition-meta.xml extension.

How many records can a single BriefcaseDefinition prime for offline mobile users?

A briefcase can prime up to 50,000 total records across its rules, with each individual top-level rule returning up to 2,000 records by default.

Can BriefcaseDefinition rules filter records dynamically based on the logged-in user?

Yes. BriefcaseRuleFilter supports dynamic value references to the running User ID so mobile technicians only download records assigned to them.