Apex Trigger Framework and Custom Metadata Types: Zero-Downtime Logic Switching

Direct answer

Use one Apex trigger per object that delegates to a handler. The handler reads a versioned Custom Metadata feature flag once per transaction and selects the logic path. Any asynchronous job—Future, Queueable, or Batchable—should receive that version from the enqueuing transaction and use it for the entire job, rather than re-reading the live flag mid-execution. Salesforce orders triggers on the same object by creation or deployment sequence, not by metadata values, so a flag switch does not reorder triggers. The main inconsistency risk is an async job that starts before the switch but reads the flag after it, or vice versa.

Trigger order is fixed, not metadata-driven

Salesforce executes multiple triggers on an object in a deterministic order based on when they were created. Deployments through the Metadata API follow the order in the deployment manifest. Custom Metadata values do not influence this sequence. That means a feature-flag toggle cannot change which trigger runs first; it only changes what each trigger does. If you have multiple triggers today, consolidate them into a single trigger before relying on metadata for logic switching, because the platform gives you no ordering guarantee tied to configuration.

Snapshot the flag version for async work

The likely explanation for overlapping old and new logic is a timing gap: the synchronous trigger enqueues a job, the transaction commits, the metadata is updated, and the job then reads the new flag. To close that gap, add an integer Version__c to the metadata record. The trigger handler reads the flag, captures the version, and passes it to the async constructor. The job stores that value in a private final field and never re-queries the metadata during execution.

public class LogicJob implements Queueable {
    private final Integer pinnedVersion;
    public LogicJob(Integer v) { this.pinnedVersion = v; }
    public void execute(QueueableContext ctx) {
        // Branch on pinnedVersion only.
        // Do not call FeatureFlag__mdt.getInstance() here.
    }
}

For Batchable jobs, snapshot the version in start() and pass it to execute() through the scope or a stateful field, keeping the payload small to respect heap limits. If you cannot change the job signature, read the flag exactly once on the first line of execute() and cache it locally, but understand that this still leaves a narrow window if the switch happens between enqueue and execution.

Bulk-safe state practices

• Read the metadata record once per transaction with getInstance(). Do not query or re-read it inside record loops.
• Keep the flag configuration in a small immutable DTO. Avoid caching large metadata collections in static variables across trigger invocations.
• Use a second Boolean field such as InTransition__c to block new async enqueues while you flip the version, preventing a flood of jobs from straddling the change.
• Ensure the handler is bulkified: process all records in the trigger with the same pinned version and enqueue a single job when possible.

Verification sketch

Deploy a metadata record with NewLogic__c and Version__c. Create one Account trigger that calls a handler, writes different fields based on the flag, and enqueues a Queueable that also writes based on the pinned version. Insert records, update the metadata in Setup, and inspect debug logs: jobs enqueued before the update should finish with the old version, and jobs enqueued after should use the new one.

Assumptions and one diagnostic

This assumes your Apex API level supports Custom Metadata getInstance() and Queueable constructor arguments. It also assumes you can modify the async job classes; if they are managed-package code you cannot change, the recommendation shifts from version pinning to suspending enqueues during the switch. One diagnostic would change the advice: do your async jobs currently receive the version from the enqueuing transaction, or do they read the live flag inside execute()? If they read live mid-job, snapshotting at start is mandatory rather than optional.