BatchProcessJobDefinition Metadata Guide

Architectural Overview#

The BatchProcessJobDefinition metadata type represents a Batch Management job definition in Salesforce. While standard Schedule-Triggered Flows have strict daily record interview limits (250,000 records per 24 hours or license-multiplied limits), BatchProcessJobDefinition allows architects to declaratively query large sObject datasets, slice them into configurable batchSize chunks, and execute an Autolaunched Flow for each record—complete with built-in retry counts, retry intervals, and row-level failure logging in BatchJobPartFailedRecord.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is a BatchProcessJobDefinition that selects overdue invoices in chunks of 50 and passes each record ID into an Autolaunched Flow named Process_Overdue_Invoice_Dunning, retrying transient locks up to 3 times:

<?xml version="1.0" encoding="UTF-8"?>
<BatchProcessJobDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <batchSize>50</batchSize>
    <description>Chunks overdue invoices and executes the dunning notification flow with automatic retries.</description>
    <filterCondition>1 AND 2</filterCondition>
    <filterCriteria>
        <fieldName>Status__c</fieldName>
        <inputVariable>OverdueStatus</inputVariable>
        <operator>Equals</operator>
        <sequence>1</sequence>
        <value>Overdue</value>
    </filterCriteria>
    <filterCriteria>
        <fieldName>Balance_Due__c</fieldName>
        <inputVariable>MinBalance</inputVariable>
        <operator>GreaterThan</operator>
        <sequence>2</sequence>
        <value>0</value>
    </filterCriteria>
    <flowInputVariable>recordId</flowInputVariable>
    <flowName>Process_Overdue_Invoice_Dunning</flowName>
    <masterLabel>Overdue Invoice Dunning Batch</masterLabel>
    <processGroup>BillingOperations</processGroup>
    <retryCount>3</retryCount>
    <retryInterval>1000</retryInterval>
    <sourceObjectName>Invoice__c</sourceObjectName>
    <status>Active</status>
    <type>Flow</type>
</BatchProcessJobDefinition>

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

Querying BatchProcessJobDefinition and Run Logs via SOQL#

Query the definition or inspect live batch job executions via SOQL:

SELECT Id, DeveloperName, MasterLabel, SourceObjectName,
       FlowDefinition, BatchSize, RetryCount, Status
FROM BatchProcessJobDefinition
ORDER BY DeveloperName

SELECT Id, BatchJob.Name, Status, TotalRecordsCount,
       ProcessedRecordsCount, FailedRecordsCount, StartTime, EndTime
FROM BatchJobPart
ORDER BY CreatedDate DESC
LIMIT 20

Senior Architect Best Practices and Gotchas#

1. Tune batchSize Based on Flow SOQL/DML Footprint: Even though Salesforce bulkifies Autolaunched Flow interviews across a batch chunk, complex subflows or invocable Apex callouts inside the target Flow can hit CPU time limits (10,000 ms) at batchSize 200. Benchmark at 50 or 100 in a Full Sandbox before production cutover.
2. Index All filterCriteria Fields: Because BatchProcessJobDefinition runs a high-volume initial query on sourceObjectName, ensure every field used in filterCriteria is indexed (or has a custom index requested via Salesforce Support) to avoid initial query timeouts on tables exceeding 1 million rows.
3. Deploy the Target Flow Active: Deploying a BatchProcessJobDefinition with <status>Active</status> requires the referenced flowName to already be deployed and active in the target org.

Frequently asked questions

How does BatchProcessJobDefinition differ from BatchCalcJobDefinition?

BatchCalcJobDefinition runs analytical joins and aggregations in Data Processing Engine, whereas BatchProcessJobDefinition chunks Salesforce records and passes each batch into an Autolaunched Flow or Apex action.

Where are BatchProcessJobDefinition files stored in SFDX?

They are stored in the force-app/main/default/batchProcessJobDefinitions/ directory with the file suffix .batchProcessJobDefinition-meta.xml.

Why use BatchProcessJobDefinition instead of a standard Schedule-Triggered Flow?

BatchProcessJobDefinition provides configurable batch sizes, retry policies, execution tracking in Monitor Workflow Services, and scales to millions of records beyond standard Schedule-Triggered Flow limits.

Which SOQL objects track BatchProcessJobDefinition runs?

You can query BatchJob, BatchJobPart, and BatchJobPartFailedRecord in SOQL to inspect chunk progress and retry failed records.