Troubleshooting rewards

This page helps you find out why an incentive result is missing or different from what you expected, and which input to fix. Incentive scoring is deterministic: xMatix reads the plan, each member's quota and the period's performance, and writes the result onto the member's compensation line. A wrong result always comes from one of those inputs. Fix the input, then run Process Compensation on the period again. Do not edit the result.

Overview

A member's result passes through a fixed chain. Each link can stop it without showing an error:

How xMatix handles it

• Nothing is calculated on a schedule. Results are produced when someone runs Process Compensation on the incentive period. Saving a compensation line also scores that one line again, but never updates the compensation record's Total Incentive Amount.
• Each run starts from scratch. Process Compensation clears the computed figures on every line that is not marked Is Compensation Received, then scores it again from the current plan, quotas and performance. A changed result after a re-run is the current truth, not a fault.
• Paid lines are frozen. A line with Is Compensation Received ticked is never scored again. Its amount still counts in the total.
• Override wins in the total. The total adds each current member's Override Incentive Amount (shown on the line as Overre Incentive Amount) when it is set, and otherwise the Incentive Amount.
• The line shows what was counted. Each target stamps its achieved figure on the line: Sale Amount, Sale Order Amount, No of Sale Orders, No of Invoices, the quantity fields, No Of Unique Invoices, No Of Unique Items, Custom KPI Value, or Achieved Value for a target with a KPI configuration. Use these figures to locate the problem.
• No errors for missing data. Scoring never fails because an input is missing. A missing quota, member key or band simply scores nothing.

Prerequisites

• Read access to the plan, its periods, members, quotas, Performance KPI records and the compensation record.
• To re-run a period: the Process Compensation button on the incentive period page and the server-action grant for it. Out of the box only System Admin has the grant, and the button is not on the seeded page (see Rewards configuration).

Procedure

Use these steps to diagnose one member whose result looks wrong.

Step 1 — Read the line

1. In the Rewards app, select Compensation and open the period's record.
2. In the Compensation Line list, open the member's line.
3. Note the Incentive Amount, the Overre Incentive Amount and whether Is Compensation Received is ticked.
4. Note the achieved figure for each target type on the plan.

If Is Compensation Received is ticked, the line keeps the figures of the run before it was ticked. Untick it only if the payout has not really been made.

Step 2 — Decide which link failed

• An achieved figure is 0 or empty — the problem is in the member, the performance or the target filters. Go to The achieved figure is zero.
• The achieved figures are right but the amount is empty — the problem is in the quota, the slabs or the line criteria. Go to A member earns nothing.
• The amount is there but different from what you expected — go to The amount is not what I expected.
• The record total is different from the sum of the lines — go to The total does not match the lines.

Step 3 — Fix the input

Correct the plan, member, quota or performance record named in the problem below. Never type a correction into an achieved figure: the next run clears it.

Step 4 — Run the period again

1. On the plan's Compensations tab, open the period.
2. Click Process Compensation.
3. Refresh the page and open the compensation record again.

The period's Status becomes Calculated and every unpaid line is re-scored. If the period is Approved or Posted, it is closed and the run is refused (see Common problems).

Business rules

These are the scoring rules behind the problems below.

• Plan status. Only lines of a plan with Status Approved are scored. Process Compensation refuses a plan that is not Approved.
• Member matching. Performance KPI records count for a member when the record carries the member's key: the Resource for a Resource plan, the Partner Account for a Partner plan, and the Branch for a Branch plan. A member with no value in that key matches nothing. Performance KPI records never match a Customer member. For targets with a KPI configuration, a Customer member matches the KPI Data row of the account its contact belongs to.
• Period. Only records of the line's own plan and period count.
• Quota. Achievement is the achieved value divided by the member's quota for the target and period. Two quotas for the same target, member and period are added together. With no quota, or a quota of 0, the target cannot qualify. A target with a KPI configuration uses the target's own Value when the member has no quota above 0, scaled by its Value Percentage.
• Filters. A target's Item, Account and Item Group filters drop every record that does not carry a matching reference.
• Percent rounding. Achievement is rounded down to a whole percent before the bands are checked. 79.99 % is 79 %.
• Bands. Slabs are checked in sequence order, and the first band that holds the achievement wins. From % is inclusive, and so is To %. An empty or 0 To % means no upper limit.
• Absolute bands. When the line has Use Slab Absolute Value ticked, the achieved value itself is compared with the slab's From Value and To Value, and no quota is needed. A To Value of 0 means no upper limit. A slab with neither value never qualifies.
• KPI-restricted slabs. A slab that names a KPI configuration can qualify only through a target with that configuration.
• Line criteria. All Conditions Are Met needs every target to qualify. Any Condition Is Met needs one. Custom Logic Is Met follows the Definition Custom Logic. An empty criteria, or a line with no targets, never qualifies. Always (No Criteria) qualifies, but pays nothing, because slabs pay only through a target.
• Combining. A line's slab rewards are combined by its Reward Applicability. The plan's Compensation Eligibility combines the lines: the largest for Any One Max, the smallest for Any One Min, and the sum when it is empty or Formulae.

Common problems

A member earns nothing

Work down this list. Scoring stops silently at the first missing piece.

1. Plan status. The plan's Status is Approved.
2. The line exists. The period has a compensation record with a line for this member. A member added after the last run gets a line on the next run of Process Compensation.
3. Quota. The member has a quota above 0 for each target, in this period. A — in the plan's Targets by Resources grid means no quota. See Member quotas.
4. Achieved figure. The line shows a figure for the target. If it is 0, see The achieved figure is zero.
5. Band coverage. The achievement, rounded down to a whole percent, falls inside a slab's From % – To % band. Gaps between bands qualify nothing: with bands of 50–78 and 80–100, an achievement of 79 % is unpaid.
6. Line criteria. With All Conditions Are Met, one target that reaches no band fails the whole line. With custom logic, {N} is the Nth target in sequence order, AND and OR must be in capitals, and brackets are not supported. See Incentive lines.
7. Slab type. The slab that qualified pays money. Gifts, Discount Group and Scheme Rewards write a gift, discount group or scheme on the line with no amount. Reward Points; pays nothing. A type the engine does not recognise qualifies but pays nothing. See Compensation slabs.
8. Slab value. The slab's value is filled: Incentive Fixed Amount for Fixed Amount, Incentive Amount Per Unit for the two per-unit types, and Amount Percentage (shown in the builder as Incentive Percentage on Value) for Percentage On Value, Slab Reward Percentage and KPI Reward Value Percentage. An empty value pays nothing.

The achieved figure is zero although the member sold something

• Performance was never captured. Performance KPI records exist only for orders and invoices on which someone ran Perform KPI Calculation. Saving a document does not capture it. See Performance KPI.
• The document was captured before the plan was Approved or the target was added. It never reaches the new target. Correct the Performance KPI records by hand.
• Member key mismatch. The records name a different resource, partner account or branch than the member, or the member has no value in the key for the plan's Member Type. A Customer member never matches Performance KPI records. See Plan members.
• A target filter excludes the records. An Item, Account or Item Group on the target drops records that do not carry a matching reference. See Incentive targets.
• The target type is not measured. Only some values in the Incentive Target Type picklist are counted. See What each target type counts.
• The target has a KPI configuration. Then the figure comes from KPI Data, not Performance KPI. Check that the KPI Data row for the member exists. See KPI configurations.
• Custom KPI. A Custom KPI target reads the Performance KPI field named in Custom KPI Field Name. The name must match the field's internal name exactly, including capitals, and the field must hold a number. Otherwise it reads 0. For a custom measure, link the target to a KPI configuration instead.

The achieved figure is higher than expected

• Sale Amount and Sale Order Amount include tax. Compare with Total Sale Invoice Amount or Total Sale Order Amount on the Performance KPI record.
• Extra records. The figure is the sum of every record that matched in the period. Look for duplicate, misdated or hand-entered Performance KPI records.
• Cancelled or changed documents. Perform KPI Calculation counts a document once. A later change or cancellation does not reach the Performance KPI record. Correct the record by hand, then run the period again.

The amount is not what I expected

• Rounded-down percent. 80.9 % is scored as 80 % and lands in a band that ends at 80, not one that starts at 81.
• First band wins. If bands overlap, the slab with the lower sequence number pays, even when a later one pays more.
• Open-ended band. A To % left empty or 0 has no upper limit, so it catches every achievement above its From %.
• Per-unit types multiply. Amount Per Unit pays the per-unit amount × the achieved value of the target that qualified the slab. Amount Per Unit Incremental pays it only on the part above the quota, never less than 0. On a value target such as Sale Amount, "per unit" means per unit of currency.
• Several slabs add up. Each target can qualify its own slab. The line combines them by its Reward Applicability, and the plan combines the lines by its Compensation Eligibility. Empty values on both add everything up.
• Duplicate quotas. Two quotas for the same target, member and period are added together, so the member's achievement is halved. See Member quotas.
• The line was saved by hand after the run. A save scores the line again from current data without clearing its earlier figures first, so a gift or scheme from an earlier result can remain. Run Process Compensation to get a clean result.

The total does not match the lines

• Overrides. A line with an Overre Incentive Amount counts with that figure in the total, even 0.
• The total was not refreshed. Saving a line, or changing an override, does not update the total. Run Process Compensation again.
• Former members. Lines of people who are no longer on the plan are left unchanged and are not counted in the total.
• Line status. A line's Status, including Rejected, does not affect the total. Use an override of 0 to exclude someone.

A member is paid twice

The plan has two members for the same person, branch or partner, usually because one was added by hand after enrolment. Remove one of them. See Plan members.

"The incentive plan must be Approved before its compensation can be processed."

Set the plan's Status to Approved, then run Process Compensation again.

"The incentive plan has no members (Incentive Resources) to compensate."

The plan has no members. Check its enrolment on Plan members, then run again.

"The period is Approved; a closed period cannot be re-processed."

The period's Status is Approved or Posted, which closes it. If it really must be recalculated, an administrator sets its Status back to Calculated or Draft.

"The period is not linked to an incentive plan."

The period has no Incentive Plan, which can happen with imported periods. Set the plan on the period, or import it again with the plan.

I can't find Process Compensation or Perform KPI Calculation

Neither button is on the seeded pages, and only System Admin is granted the actions. An administrator adds them; see Rewards configuration.

A paid line still shows old figures after a re-run

The line has Is Compensation Received ticked, so the run left it as it was. That is intended: the money has gone out.

Training

Practice exercise

In a sandbox with a monthly, Approved Resource plan that has one member, one line with All Conditions Are Met, one Sale Amount target with a quota of 10,000, and slabs of 50–79 % paying 500 and 80 % and above paying 1,000:

1. Record and capture invoices for the member worth 7,990 in the first period, and run Process Compensation.
2. Add a captured invoice of 20 and run Process Compensation again.
3. Enter an Override Incentive Amount of 0 on the line, save, and look at the total. Then run Process Compensation once more.

Expected result: after step 1 the achievement is 79 % (79.9 rounded down) and the line pays 500. After step 2 it is 80 % and the line pays 1,000. In step 3 the total stays at 1,000 after the save and becomes 0 only after the run, while the line's Incentive Amount still shows 1,000.

Quick reference

• Fix the input, never the result, then run Process Compensation again.
• Saving a line never updates the record's total.
• Paid lines (Is Compensation Received) are never re-scored.
• Achievement is rounded down to a whole percent; the first matching band wins.
• No quota or a quota of 0 means the target cannot qualify.
• A 0 achieved figure points to capture, member key or target filters.
• Performance KPI records never match Customer members.
• Always (No Criteria) and an empty criteria pay nothing.
• Override Incentive Amount wins in the total; line Status does not count.

Permissions

See Rewards configuration.

Common questions

How do I force a recalculation?

Run Process Compensation on the incentive period. It re-scores every line that is not marked Is Compensation Received from the current plan, quotas and performance, and refreshes the compensation record's Total Incentive Amount. Saving a single line also re-scores that line, but leaves the total as it was and does not clear earlier figures first, so it is not a reliable way to recalculate. There is no cache to clear and no job to wait for. A closed period (Approved or Posted) cannot be processed again until an administrator reopens it.

Nothing at all has been calculated for a period — why?

Because nobody has run Process Compensation on it. Nothing runs on a schedule, so a period stays without a compensation record until someone runs the action. Open the period on the plan's Compensations tab and click Process Compensation. It creates the record and a line for each member. If the button is missing, ask your administrator to add it. See Running an incentive cycle.

Who should fix a plan-level problem — the user or the administrator?

Quotas, Performance KPI records and compensation lines can be corrected by the people who run the cycle. Plan structure — Member Type, Period Type and the plan's scope — is locked once the plan has members or targets ("Key fields are not editable once the related objects are added."). A structural mistake needs an administrator and usually a new plan. Adding Process Compensation, Perform KPI Calculation and picklist values is also an administrator task. See Rewards configuration.

Can I see what a run did?

Yes. Each run writes a summary to the period's Process Log: when it ran, how many members were scored, lines created and recalculated, paid lines skipped, lines of former members, and the total. Each line also gets its own Process Log with the time (in UTC) and its amount. Neither Process Log is on the seeded pages; an administrator can add them to the layouts. See Incentive periods.

Related topics

• Running an incentive cycle
• Incentive plans
• Incentive lines
• Incentive targets
• Compensation slabs
• Member quotas
• Plan members
• Performance KPI
• KPI configurations
• Compensation records
• Incentive periods
• Rewards configuration