Calculation runs and schedules

A calculation run turns accepted source facts into credits and earnings under a published plan version, for one commission period. You can calculate a single document, run a batch over a whole period, try the numbers first without writing anything, and schedule incremental runs through the job queue.

A batch run calculates a period and reconciles its control totals to the child run ledgers.

Before you start

• Source facts must be accepted. See Business Central sales sources.
• The plan version must be published or active. See Plans, versions, and assignments.
• The period must be open (or reopened) and contain the business date of the facts. See Calendars and periods.
• Participants must be linked to the salespeople on the facts and assigned to the plan.

Choose the right kind of run

Run	Use it when	Writes ledgers
Single calculation run	You want to calculate or recheck one invoice or one linked credit memo.	Yes
Batch run, Full	You calculate every accepted fact of a period that is not yet calculated for the plan.	Yes
Batch run, Incremental	You calculate only facts accepted since the last baseline.	Yes
Trial run	You want to see the numbers first.	No
Run schedule	You want incremental batches to run daily.	Yes

Calculate one document

1. Open Commission Source Facts, select the invoice, and choose Prepare Calculation. Or open Commission Calculation Runs and choose Prepare Calculation.
2. On Prepare Commission Calculation, confirm the Source Entry No., Plan Code, Version No. and Period Code, and choose OK. The run is prepared and validated.
3. On Commission Calculation Runs, select the run and choose Calculate or Resume.
4. Check Status. Completed means the run finished cleanly. Completed with Exceptions means some items raised exceptions that need attention.
5. Choose Earnings to see the result.

For a linked credit memo, choose Preview and Calculate Return instead. You see the projected signed return delta first, with no financial writes, and then confirm it. See Returns and corrections.

Run stages

Each run goes through fixed stages: classify credit, measure attainment, calculate earning, and move eligibility and balances. Return runs add correction delta and correction link stages. Choose Run Stages to open Commission Run Stages and see each stage with its status, input and output counts, checkpoint value and hashes.

If a run is interrupted, Calculate or Resume continues from the last completed stage and reuses the stages already done.

Cancel a run

Choose Cancel Run and enter a Cancellation Reason Code. Existing financial evidence is kept. If a worker was interrupted, Finish Cancellation completes the cancellation once the worker's lease has expired.

Run a batch for a period

1. Open Commission Batch Runs and create a new batch.
2. On Commission Batch Run, fill in the scope:

Field	What it does
Mode	Full calculates every accepted fact in the period not yet calculated for the plan. Incremental calculates facts accepted since the last baseline watermark.
Period Code	An open or reopened period.
Plan Code / Plan Version No.	Leave the version at zero to use the latest published or active version.
Participant No.	Optional. Only facts of that participant's linked salespeople are selected, and the batch does not set a baseline.
Source Entry No. Filter	Optional single fact.
Trace Level	Errors, Summary or Detail for the run log.
Max Facts Per Invocation	How many facts one invocation processes before the batch suspends and resumes later.

1. Choose Start. The batch freezes its scope, captures the source watermark, selects facts and processes the first invocation.
2. If the batch is Suspended, choose Continue, or let the resume job do it.
3. Review the Source Facts part. Each fact shows its status: Pending, Processing, Completed, Completed with Exceptions, Review Required, Skipped or Failed.
4. Choose Retry Failed Items to queue failed and review-required facts again. Choose Skip on a fact that is not commissionable under this plan.
5. Choose Reconcile Control Totals. The batch recomputes its totals from the child run ledgers and stage checkpoints and sets Reconciled.

Cancel stops the batch between facts. Child runs that already finished keep their ledgers.

Baselines and watermarks

A full batch sets the baseline for a plan version and period. Incremental batches then continue from the highest source entry number covered without gaps. Choose Baselines and Watermarks on Commission Batch Runs to see them.

The period pipeline

From a batch you can also run the remaining period stages in order: collect, calculate, roll-up, settle, post, finalize and export. Choose Run Period Pipeline to run them all, or Run Next Pipeline Stage to run one. Settle, post, finalize and export require the finance-all security scope. Pipeline Stages shows each stage with its checkpoint. See Period close and reopen.

Try the numbers first with a trial run

1. Open Commission Trial Runs and create a trial.
2. Fill in Period Code, Plan Code, and optionally Plan Version No., Participant No. or a Source Entry No. Filter.
3. Choose Calculate Trial. The app calculates credit, measure, attainment and earning arithmetic without writing any ledger. Running it again replaces the earlier results.
4. Review Trial Results. Each line shows the participant, component, model, credit, attainment base, entitlement, earning delta and an Explanation. Lines with Modeled off use a model the trial does not calculate. The posted run calculates them.
5. When you are satisfied, choose Promote to Posted Run. This creates and starts a normal full batch run over the same scope, which writes immutable ledger entries.
6. Choose Refresh Posted Comparison to compare the trial total with the posted total in Promotion Difference.

Schedule incremental runs

1. Open Commission Run Schedules and add a schedule with a Code, Plan Code, optional Calendar Code, Plan Version No. and Participant No., and a Run Time.
2. Decide whether to Create Baseline If Missing (run a full batch for a period with no baseline instead of skipping it) and whether to Include Reopened Periods.
3. Choose Enable. The app creates a daily job queue entry for the schedule.
4. Use Run Now to start the batches immediately.

Each run covers the calendar's periods that have started and are open, future-but-started, calculating, in review or approved. Reopened periods are only included when the approved reopen chose the Scheduled Incremental delta policy. Last Run At, Last Batch No. and Last Result show the outcome.

Run operations setup

Open Commission Run Operations Setup to set the defaults for batch processing:

Field	What it does
Max Facts Per Invocation	Facts per invocation before a batch suspends. The ceiling is 10,000.
Max Duration (Seconds), Resume Interval (Minutes)	How long one invocation may run and how often suspended batches resume.
Reconciliation Tolerance	The amount difference tolerated when control totals are reconciled.
Default Trace Level	Errors only, Summary per invocation, or Detail per fact.
Log Retention (Days)	How long run log entries are kept.

Choose Create Resume Job to create the recurring job queue entry that continues unfinished batches and applies log retention.

Troubleshooting

• The run fails before it starts. Check that the period is open and contains the business date, and that the plan version is published. Prepare Commission Calculation refuses missing or duplicate plan and period codes.
• A fact shows Review Required. It is a linked return waiting for a reviewed preview. Open its Calculation Run and choose Preview and Calculate Return.
• The period is frozen or future. New runs are refused. See Period close and reopen.
• Why did a fact fail? Read Last Error Text on the batch item and the entries on Commission Run Log. Exceptions appear on Commission Exceptions. See Exceptions and data quality.

Related pages

• Explain any earning
• Earnings and the commission ledger
• Job queues, monitoring, and diagnostics