Rewards configuration reference

This page is the administrator's single checklist for the Rewards module: who can reach it, what the shipped setup leaves out, which buttons and jobs to switch on, what the platform validates and locks, and exactly what each target type measures. Each task links to the page that covers it in full. Read Incentive plans first if you are new to the concepts.

Overview

Rewards works almost entirely from records rather than settings screens. An administrator tailors it in six places:

• Security profiles: who sees the Rewards app and who may run its actions.
• Picklists: values the incentive engine understands but the shipped picklists leave out.
• Document numbering: the number series of plans, members, targets, lines and compensation.
• Record-page buttons: actions the platform supports but the shipped page layouts do not show.
• Background jobs: member enrolment, quota generation and KPI configuration accrual.
• Performance sources: the Perform KPI Calculation action on documents, and KPI configurations.

Setup → Feature Hub → Rewards has no settings screens, and the Settings tab inside the Rewards app ships with no tiles. Everything below is done on records, in Setup → Design Studio, in security profiles or on the Jobs screen.

How xMatix handles it

Four kinds of work happen without anyone pressing a button, and one needs a button:

Scoring reads only plans whose Status is Approved. Process Compensation refuses a period whose plan is not Approved, a period that is Approved or Posted, and a plan with no members. It never touches a compensation line already marked as paid (Is Compensation Received).

Performance reaches the engine from one of two sources. Targets linked to a KPI configuration read that configuration's KPI Data. All other targets read Performance KPI records, which only the Perform KPI Calculation action on an order or invoice writes.

Prerequisites

• A System Admin profile, or a profile with access to Setup → Design Studio and to the Jobs screen.
• Active resources, partner accounts or branches for the people you plan to reward. See Resources.
• Familiarity with Design a form layout and Entity behaviour if you are adding buttons.

Procedure

Work through these steps once per tenant, before the first plan goes live.

Step 1 — Give users the app

1. Open Setup → Access Control → Profiles and open the profile.
2. In its app permissions, make sure Rewards is granted. The shipped Sales Executive, Sales Manager, Standard User and System Admin profiles already have it.
3. Decide who may change plans and quotas. The four shipped profiles have full access to every Rewards entity, so a sales rep can edit their own quota. Reduce Incentive Plan, Incentive Target, Incentive Resource Target and Compensation Line to read-only on profiles that should only look.

The Rewards app is a web app. Its menu lists Scheme, Incentive Plan, KPI Configuration, Compensation, Resource and Resource Group, then Reports, Dashboards and Settings. Only System Admin sees the Settings tab.

Step 2 — Add the picklist values you need

Open Setup → Design Studio → Entities, open the entity, and use Manage PickList Values on the field's row. Type each value exactly as shown in Picklist values the engine understands.

Step 3 — Check document numbering

For each Rewards entity, open Setup → Design Studio → Entities, open the entity, then Logic → Document Settings. Confirm the setting is active and the series suits you. See Document numbering and the numbering table below.

Step 4 — Add the buttons the shipped pages leave out

The shipped record pages show none of the Rewards server actions. Add the ones your team needs:

1. Process Compensation on the incentive period page. The entity action already exists. Add ProcessCompensation to the page header of the Incentive Period View layout, then grant it to the profiles that run incentives (out of the box only System Admin has it).
2. Enrol members on the incentive plan page. Under Setup → Design Studio → Entities → Incentive Plan → Logic → Actions, add a server action named EnrolMembers, place it on the Incentive Plan View page header, and grant it.
3. Regenerate quotas on the incentive target page. Add a server action named GenerateResourceTargets to Incentive Target the same way.
4. Recalculate KPI Data on the KPI configuration page. Add a server action that runs RecalculateKpiData to KPI Configuration the same way.
5. Perform KPI Calculation on orders and invoices. The action exists on Order and Invoice. Add PerformKPICalculation to the OrderView and Invoice View page headers and grant it. See Performance KPI.

After each change, sign in as a user of that profile and confirm the button appears.

Step 5 — Schedule the KPI configuration accrual (optional)

For KPI configurations whose Trigger Event is Scheduled:

1. Open Setup → Platform → Monitoring → Jobs.
2. On the Schedules tab, add a schedule with Job type Accrue KPI configuration data, a Frequency and a Time.
3. Enter the Payload JSON {"Mode":"Scheduled"} and save.

The full options are on KPI configurations.

Step 6 — Run a dry cycle

Create a small Monthly Resource plan with one line, one Sale Amount target (Target Value Type Fixed Value) and one slab, and approve it. Record one invoice for a member and run Perform KPI Calculation on it, then run Process Compensation on the period. A line with the invoice amount in Sale Amount proves the chain works. Running an incentive cycle describes the routine.

Reference tables

Access and permissions

The Rewards app is granted to the same four profiles. The Settings page inside it is granted to System Admin only.

Server actions

Every Rewards entity also has the standard New, Edit and Delete actions. Whether a user can use them follows the entity access on their profile.

Document numbering

Because the counter is kept per date part, these numbers start again at 1 on each new day. See Document numbering.

Picklist values the engine understands

The shipped picklists leave out values the engine supports, and include some it ignores:

The KPI configuration picklists have their own list on KPI configurations.

Background jobs

All three appear in the Incentives category under Setup → Platform → Monitoring → Jobs, and each can be run by hand from there.

Plan validation rules

Enforced every time an incentive plan is saved:

xMatix does not check that Period End Date is after Period Start Date. A plan saved with the dates the wrong way round gets no periods (a Yearly plan gets one period with inverted dates).

Period generation

Periods are generated once, when the plan is first saved, from its Period Type and dates:

A Period Type the generator does not know produces no periods. Changing the dates later adds or removes nothing. Add a missing period by import, as described in Incentive periods.

Target types

What each target type adds up from the member's Performance KPI records, and where the result is stamped on the compensation line:

No Of Invoices and Invoice Quantity are not in the shipped picklist; the shipped Sale Invoice Quantity scores nothing. A target linked to a KPI configuration ignores its type and reads the configuration's KPI Data instead. Incentive targets explains the item and account filters.

Performance KPI records are matched to a member by the plan's Member Type:

• Resource plans match the record's resource.
• Partner plans match its partner account.
• Branch plans match its branch.
• Customer plans never match a Performance KPI record. Customer plans score only targets linked to a KPI configuration.

A member enrolled without the key their member type matches on (for example a Resource member with no resource) matches nothing.

Business rules

• Approved plans only. Accrual, scoring and Process Compensation all ignore plans in any other status. Moving a plan back out of Approved stops all three.
• Achievement. The reached value divided by the member's quota, times 100, rounded down to a whole percent. No quota, or a quota of zero, never qualifies. A line with Use Slab Absolute Value compares the reached value directly with the slab's From and To values.
• First slab wins. Slabs are checked in sequence order, and the first band that holds the percentage qualifies the target.
• One scorer. Process Compensation and a hand-saved compensation line use the same engine, so both give the same result.
• Closed periods. Periods with Status Approved or Posted are never re-processed and never get regenerated quotas.
• Paid lines. Process Compensation leaves lines marked Is Compensation Received untouched.
• Enrolment only adds. Enrolment never removes a member and never adds one twice.

Example

An administrator prepares a tenant for a quarterly partner contest:

1. They add Quarterly to Incentive Plan → Period Type, and Invoice Quantity to Incentive Target → Incentive Target Type.
2. They add ProcessCompensation to the Incentive Period View header and grant it to the Sales Manager profile.
3. They add PerformKPICalculation to the Invoice View header and grant it to the profile of the billing team.
4. They switch the Sales Executive profile to read-only on Incentive Resource Target, so partners' quotas can only be changed by managers.
5. A sales manager creates a Partner plan from 1 April 2026 to 31 March 2027 with Period Type Quarterly. Four periods appear, and the partners are enrolled within a few minutes.
6. After the first quarter, the manager opens the April–June period and clicks Process Compensation. The period shows Calculated, and each partner has a compensation line.

Training

Practice exercise

In a sandbox, as System Admin:

1. Add Daily to Incentive Plan → Period Type.
2. Create a Resource plan for the next seven days with Period Type Daily, and save it.
3. Try to change the plan's end date to more than a year after the start date.

Expected result: Step 2 generates seven periods, one per day, each named after its date. Step 3 is refused with "Period should not be more than 1 year for daily, weekly and bi-weekly period types."

Quick reference

• Rewards has no settings screen. Configure it through profiles, picklists, numbering, layouts and jobs.
• Only Approved plans accrue, score or process.
• Process Compensation and Perform KPI Calculation exist but are not on any page — add and grant them.
• EnrolMembers, GenerateResourceTargets and RecalculateKpiData need an entity action before they can be used.
• Add Quarterly, Bi Weekly, Daily, Customer, Custom Logic Is Met and Always (No Criteria) to the picklists if you need them.
• The structural plan fields lock once the plan has members or targets.
• Customer plans score only KPI configuration targets.

Permissions

• App and records. The Rewards app and full access to all Rewards entities are granted to Sales Executive, Sales Manager, Standard User and System Admin. A user without read access to Incentive Plan sees no plans.
• Approving a plan. No approval process is seeded. Anyone who can edit a plan can set it to Approved. To control approval, reduce edit access to Incentive Plan on the profiles that should not approve.
• Process Compensation and Perform KPI Calculation. Granted to System Admin only. Grant them on the Actions tab of any other profile that needs them.
• Actions you add. A new server action (EnrolMembers, GenerateResourceTargets, RecalculateKpiData) must be granted on each profile that should see it.
• Jobs and Setup. The Jobs screen and Design Studio need the matching Setup access on the profile. See Security profiles.

Configuration

Everything an administrator can change, in one list:

• Picklists: see Picklist values the engine understands.
• Numbering: see Document numbering. Switch on the KPI Configuration setting before anyone creates a configuration.
• Record-page buttons: see Step 4.
• Plan header actions. The shipped Incentive Plan page has no Edit button. To let users change a plan after saving, add Edit to the Incentive Plan View page header. Leave out the three Create actions, which do nothing.
• Jobs and schedules: see Background jobs and Step 5.
• Measures: to score anything the built-in target types do not cover, create a KPI configuration.
• Performance KPI in the menu. Performance KPI is in no app menu. To give administrators a list, add the entity to the Rewards app under Setup → Design Studio → Apps with Manage Items.
• Account groups. Plan and target account-group filters need groups of type Scheme. See Account groups.

Common problems

I can't find Process Compensation

The action exists but the shipped Incentive Period page does not show it, and only System Admin is granted it. Add it to the page header and grant it (Step 4).

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

The plan's Status is Draft, Pending Approval or empty. Move the plan to Approved, then run Process Compensation again.

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

Enrolment found nobody, or the plan is a Customer, Dealer or Role plan. Check the Member Type and filters, and look for a failed Enrol incentive plan members run on the Jobs screen.

"Key fields are not editable once the related objects are added."

The plan already has members or targets. Its structural fields are locked. Create a new plan with the right settings.

A plan saved with Quarterly has no periods

Quarterly was typed in the picklist with different spelling or spacing. The generator matches Quarterly, Bi Weekly and Daily exactly (capital letters do not matter). Fix the value, then import the plan's periods or create the plan again.

Saving a new KPI configuration says "Name is required"

The KPI Configuration numbering setting is switched off as shipped. Switch it on, or add Name to the create form.

Common questions

Is there a Rewards settings screen?

No. Setup → Feature Hub → Rewards has no screens, and the Settings tab in the Rewards app ships empty. Rewards is set up through its records, security profiles, picklists, numbering settings, page layouts and the Jobs screen. This page lists each of them. Behaviour that other modules switch on in settings — such as when performance is measured — is in Rewards decided by the plan's Status and by when documents are calculated and compensation is processed.

Does anything run on a schedule by default?

No. Enrolment and quota generation run after saves, and scoring runs when a compensation line is saved or a period is processed. Process Compensation never runs on its own at the end of a period. The only schedulable work is the KPI configuration accrual, and you add that schedule yourself on the Jobs screen.

Why can't a user edit member type or period type on a plan?

Once a plan has members or targets, its periods, member assignments and performance matching all depend on these fields, so they are locked. The fix is a new plan, not an edit.

Can field-app users work with Rewards?

The Rewards app is web only. In the field app, the visit plan's Day end and Progress scores read a rep's revenue quota from a KPI configuration target, as described on KPI configurations.

Related topics

• Incentive plans
• Incentive periods
• Incentive targets
• KPI configurations
• Performance KPI
• Running an incentive cycle
• Rewards troubleshooting
• Document numbering
• Security profiles
• Incentive Plan — entity reference