Nonprofit NextGen Commitment Processing - Configuration and Processing Guide

Batch Job Configuration

Batch Size Settings

Batch Job Definition

Processing Order and Record Changes

Gift Commitment Processor

Default Designation Processor

Default Soft Credit Processor

Commitment Transaction Processor

Transaction Soft Credit Processor

Gift Transaction Designation Processor

Error Handling

Monitoring and Logs

Best Practices

Batch Job Configuration

Batch Size Settings

The NextGen Commitment Processing batch job uses two configurable settings that control how records are processed:

1. Batch Execution Size

This setting controls the number of commitment records processed in each batch execution event.

• Default Value: 10,000 records

• Location: FundraisingConfig object

• Field Name: NextGenCmtPrcsBatchSize

When the batch job runs, it retrieves all commitment records that are not Status=Closed and processes them in chunks of 10,000 (controlled by NextGenCmtPrcsBatchSize value). Each 10,000-record chunk is further divided into job parts of 1,000 records — as defined in the batch job definition file — which are processed one at a time within that chunk. If NextGenCmtPrcsBatchSize is not set or is set to 0, the system defaults to 10,000.

2. Parallel Processing

This setting determines whether batch job parts can be executed in parallel or must run sequentially.

• Default Value: True (parallel execution enabled)

• Location: FundraisingConfig object

• Field Name: IsNextGenCmtPrcsParallel

When enabled, multiple batch parts can process simultaneously across multiple batch job events, potentially improving performance for large commitment volumes. When disabled, batch parts process one at a time in sequence.

How batch processing works (example: 100K records)

• Batch chunk size: 10K records (NextGenCmtPrcsBatchSize)

• Job part size: 1K records

Phase 1 — Serial warm-up

The first 10K records are split into 10 job parts (1K each) and processed one at a time.

Phase 2 — Parallel processing

Once the warm-up completes, up to 5 chunks of 10K records run in parallel. Within each chunk, the 10 job parts (1K each) still run serially.

The net effect: At peak, there are up to 5 job parts of 1K records running simultaneously — but only after the first 10K records have finished.

Batch Job Definition

The default batch job process type is named NextGen Commitment Batch Processing. This definition includes:

• A default batch part size of 1000

• Input parameters including an optional processing date override

• Automatic enforcement that only one instance of this batch job type can run at a time

• Filters the job to only select GiftCommitment records where

  • Status != “Closed” AND ScheduleType = “Recurring”

Custom Batch Jobs: Organizations can create their own custom batch job definitions using the Commitment Processing Next Gen Batch Job Handler (NextGenCommitmentBatchProcessingJob process type). This allows you to customize batch sizes and scheduling to meet your specific needs.

Processing Order and Record Changes

When the batch job runs, it processes commitments through a series of processors that run in the following order:

1. Gift Commitment Processor

Purpose: Updates the commitment record itself based on the current schedule and status.

Record Changes:

• Updates the commitment Status field based on schedule evaluation and payment status

• Sets Current Gift Commitment Schedule to the active schedule for the processing date

• Updates Next Transaction Date to reflect the next expected gift date (or clears it for Failing/Lapsed/Closed)

• Updates Next Transaction Amount to reflect the next expected gift amount (or clears it for Failing/Lapsed/Closed)

• Calculates and updates projected revenue fields by combining schedule-generated installments with existing transactions:

  • Total Current Month

  • Total Current Quarter

  • Total Current Year

  • Total Next Year

• For commitments marked as paid and complete, automatically changes Status to "Closed"

• For commitments with failed or lapsed payment methods, updates Status accordingly

Status Transition Logic: The processor analyzes recent transactions (in reverse chronological order, most recent first) to determine status:

• Active: Set when the current schedule type is "Create Transactions", OR when recent transactions show the commitment is performing well (has paid/refunded transactions)

• Paused: Set when the current schedule type is "Pause Transactions"

• Failing: Set when consecutive failed transactions (counting backwards from most recent) reach the threshold configured in Fundraising Config field FailedTransactionCount

• Lapsed: Set when consecutive unpaid past-due transactions (counting backwards from most recent) reach the threshold configured in Fundraising Config field LapsedUnpaidTrxnCount

• Closed: Set when auto-close conditions are met (see below)

Important Status Behavior:

• If the processor finds ANY paid or refunded transaction in recent history (except on current date where unpaid is acceptable), the status returns to Active

• If failed and unpaid transactions are mixed in recent history, the status returns to Active

• When a commitment becomes Failing or Lapsed, the Next Transaction Date and Next Transaction Amount are cleared

• The processor only analyzes the most recent N transactions where N is the maximum of the two threshold settings

Auto-Close Conditions (ALL must be true):

• Schedule type is "Recurring" (not Custom)

• Current status is NOT "Draft"

• Current Gift Commitment Schedule is null (no active schedule)

• Next Transaction Date is null

• No future schedules exist beyond the current date

• No unpaid transactions exist

• The ShouldClosePaidRcrCmt flag in Fundraising Config is set to true

Branching Logic:

• Only updates commitment fields when values actually change from their current state

• Skips status evaluation if commitment is already Closed or Paused

• Skips projected revenue calculation if commitment has no schedules

• Skips next transaction calculation if commitment is Failing, Lapsed, or Closed

2. Default Designation Processor

Purpose: Ensures each commitment has default designation records that specify how gifts should be allocated.

Record Changes:

• Copies default designations from a parent record (Opportunity or Campaign)

• Associates designations with the commitment

Branching Logic:

• Only processes commitments that do not already have default designations

• Determines the campaign to use by:

  • First checking if the commitment already has a campaign

  • If not, looks up the current schedule (of type "Create Transactions") that is active for the processing date and uses that schedule's campaign

• Determines which parent record to copy designations from with this priority:

1. 1. First choice: If the commitment has a related Opportunity with default designations, copy from the Opportunity

   2. Second choice: If no Opportunity or Opportunity has no designations, copy from the Campaign if it has default designations

• Does NOT create organization-wide default designations if none exist on the parent records

• Skips commitments that already have at least one default designation

3. Default Soft Credit Processor

Purpose: Ensures soft credits from the related opportunity are copied to the commitment as defaults.

Record Changes:

• Creates new Gift Default Soft Credit records for unique soft credits from the parent opportunity

• Copies recipient, role, partial amount, and partial percent from opportunity soft credits

Branching Logic:

• Only processes commitments that have a related opportunity

• Automatically deduplicates - only creates soft credits that don't already exist on the commitment

• Identifies duplicates by comparing ALL of these fields:

• Recipient (Contact)

• Role (picklist value)

• Partial Amount

• Partial Percent

• A soft credit is only considered a duplicate if ALL four fields match an existing soft credit on the commitment

• Skips creation if the opportunity has no soft credits

4. Commitment Transaction Processor

Purpose: Creates new gift transaction records for recurring commitments when they are due.

Record Changes:

• Creates new Gift Transaction records for upcoming payments

• Sets transaction fields from the active schedule:

  • Gift Commitment: Link to parent commitment

  • Gift Commitment Schedule: Link to the schedule that generated this transaction

  • Donor: From commitment's account

  • Donor Organization Name: From commitment

  • Original Amount / Current Amount: From schedule's transaction amount

  • Transaction Date: Calculated next due date from schedule recurrence pattern

  • Transaction Due Date: Same as transaction date

  • Schedule Transaction Period: Period identifier from schedule

  • Status: Unpaid (initial status)

  • Payment Method: From schedule

  • Campaign: From schedule

  • Outreach Source Code: From schedule

  • Payment Instrument: From schedule

  • Currency: From schedule (or commitment if schedule doesn't specify)

• Only runs if the ShouldCreateRcrSchdTrxn flag in Fundraising Config is enabled
• Only processes commitments with recurring schedules — not custom schedules
• Skips commitments with "Failed" or "Lapsed" status
• Creates at most one transaction per commitment per batch run — the next upcoming unmatched installment
• Skips commitments that don't have an active "Create Transactions" schedule for the current date
• Calculates transaction due dates based on the schedule's frequency (Daily, Weekly, Monthly, Quarterly, Annually) and recurrence pattern

5. Transaction Soft Credit Processor

Purpose: Applies default soft credits to newly created transactions.

Record Changes:

• Creates Gift Soft Credit records for each newly created transaction

• Copies all default soft credits from the commitment to the new transaction

• Sets recipient, role, amount, and percentage from the default soft credit template

Branching Logic:

• ONLY runs if ShouldCreateRecurringScheduleTransaction is enabled

• ONLY processes commitments that have both:

  • At least one default soft credit record

  • At least one newly created transaction (from Processor #4)

• Creates one soft credit record per default soft credit per new transaction

• Skips commitments without default soft credits

6. Gift Transaction Designation Processor

Purpose: Applies default designations to newly created transactions.

Record Changes:

• Creates Gift Transaction Designation records for each newly created transaction

• Copies designation allocation from the commitment's default designations

• Distributes the transaction amount across designations based on percentages or fixed amounts

Branching Logic:

• ONLY runs if ShouldCreateRecurringScheduleTransaction is enabled

• ONLY processes commitments that have newly created transactions (from Processor #4)

• Uses the commitment's default designations to determine allocation

• If multiple designations exist, splits the transaction amount accordingly

• Creates a Gift Transaction Designation from the org wide default for any remaining balance unclaimed by the other designations

Error Handling

The batch job includes comprehensive error handling:

• Individual Record Errors: If a single commitment fails during processing, the error is logged on the commitment's LastNextGenCmtProcError field and processing continues for other commitments

• Processor Failures: If certain processors fail (soft credits, transaction designations), the entire batch part is rolled back to maintain data consistency

• Load Failures: If the batch cannot load commitment data, all commitments in that batch part are marked as failed

Monitoring and Logs

Processing results are tracked through:

• Batch Job Status: Available in Batch Management objects

• Individual Commitment Status: Check LastNextGenCmtProcError field on Gift Commitment records. Populated when there was an error processing this commitment

• Individual Commitment Process Date: Check LastNextGenCmtProcDtTm field on Gift Commitment records. Populated with the date this commitment was last processed through NextGen Commitment Processing

Best Practices

1. Batch Size Tuning: Start with the default 10,000 batch size and adjust based on your org's data volume and performance

2. Parallel Processing: Enable parallel processing for better performance in orgs with large commitment volumes. This is on by default.

3. Scheduling: Run the batch job during off-peak hours to minimize impact on users

4. Monitoring: Regularly review failed commitments and their error messages to identify systematic issues