A Performance KPI record is a running total of what one party has sold or bought in one incentive period or trade-scheme period. Incentive targets that have no KPI configuration are scored from these totals, and Per Period trade schemes read them too. Records are written when the Perform KPI Calculation action runs on a sale order or an invoice. Each later document with the same keys adds to the same record. The figures are then read when compensation is processed for an incentive period, and when a Per Period trade scheme is evaluated.
Overview
Each record holds two things:
- Keys. Who performed (account, partner account, supplier account, branch, resource), optionally which item, and what the figures count towards. That is either an incentive plan, incentive period and incentive target, or a scheme and scheme period.
- Totals. Document counts (Number Of Orders, Number Of Invoices and so on), quantities and amounts, added up across every document that landed on the same keys. Records for a resource's incentive target can also carry that resource's quota as Target Value.
Performance KPI records are one of two sources of performance in Rewards. A target linked to a KPI configuration is scored from that configuration's KPI Data instead, and never reads Performance KPI records.
When to use it
- Incentive targets without a KPI configuration. Sale Amount, Sale Order Amount, No Of Sale Orders, Purchase Order Amount and the other built-in target types read these records.
- Per Period trade schemes. A scheme of type Per Period Sale Order or Per Period Sale Invoice measures the account's performance over the period from these records.
- Checking what was counted. When a compensation line or a scheme benefit looks wrong, the Performance KPI records show exactly which totals the engine saw.
- Dashboards and the field app. The Incentives & Targets dashboard and other sales dashboards chart these records. In the field app, the target pace card reads them for a rep's actuals and falls back to the rep's orders when there are none.
For a measure the built-in target types don't cover, use a KPI configuration instead.
How xMatix handles it
- Written by one action. Records are created and updated only by the Perform KPI Calculation action on a document. Saving a document does not write them, even when its Perform KPI Calculation field is ticked. Nothing runs on a schedule.
- Which documents. Out of the box, the action exists on Order and Invoice only. Purchase orders, bills, service orders and opportunities can also be calculated, but only after an administrator adds the action to them (see Configuration).
- Two kinds of record. One run writes up to two kinds of record:
- Incentive records are written for each target of each Approved incentive plan that the document can move. The document's date must fall inside one of the plan's incentive periods and inside the plan's validity. The plan's and target's filters must also match.
- Scheme records are written for each Approved Per Period scheme of the matching type. The scheme's validity and filters must match. If the scheme has periods, the document date must fall inside one of them.
- Header and item records. Each kind gets one header record (no item) with the document counts and totals. A target or scheme that is limited to items or item groups also gets one record per matching item, with that item's quantity and line amount.
- Accumulating. A record is identified by its keys. A second document for the same customer, partner, branch, resource, plan, period and target adds to the existing record rather than creating a new one.
- Once per document. After a successful run, the document's KPI Calculated field is set and its Perform KPI Calculation field is cleared. A calculated document is never counted again, so later changes to it never reach its records.
- Failures don't block the document. If the calculation fails, the document is still saved without records and stays eligible for another run.
Prerequisites
- An Approved incentive plan with incentive periods whose dates cover the document dates, and targets whose types the document can move. See Incentive plans and Incentive targets.
- For quotas on the records, member quotas for the plan's resource members. See Member quotas.
- For schemes, an Approved Per Period scheme with back-to-back periods. See Trade schemes.
- The Perform KPI Calculation action on the document's record page, and permission to run it. Out of the box neither is in place for ordinary users (see Configuration and Permissions).
- A Document Date on the document. A document without one is skipped.
Procedure
Step 1 — Calculate KPIs for a document
- Open the sale order or invoice.
- Select Perform KPI Calculation in the page header.
- When the action finishes, the document's KPI Calculated field is set, and the button no longer appears on an order.
The action does nothing to a document that is already calculated or has no Document Date, and shows no message. On an order, the button shows only while the order still has quantity pending fulfilment and has not been calculated.
Run the action once each document is final. Changes made to the document after it has been calculated are not counted.
Step 2 — Check the records
- Open the Reports of the Rewards app and run New KPIs Report. It lists Performance KPI records grouped by partner account, with the KPI name, incentive period, Total Amount and Target Value.
- To see which target each record feeds, run New KPIs with Incentive Target Report. KPIs with Incentive Plan Report groups the records by incentive period with their plan.
- Open a record to see all its fields (see Fields). Performance KPI is in no app's navigation, so open it from a report or ask an administrator to add it to an app.
Step 3 — Score the period
Run Process Compensation on the incentive period, or re-save the compensation lines. The engine sums the matching records for each member and target. See Running an incentive cycle.
Compensation lines don't recalculate on their own when new records land, so process the period again after a late document is calculated.
Step 4 — Correct a record
A calculated document can't be calculated again, and nothing subtracts a cancelled or changed document. To correct the totals:
- Open the Performance KPI record.
- Change the figure in place (the page header offers Edit and Delete), or delete the record.
- Process the period's compensation again.
You can also load or correct records in bulk with Import data.
Fields
The record page groups its fields in the panels below. The page header shows Resource, Posting Type, Total Quantity, Total Amount and Total Tax Amount.
Key Information
| Field | What it means | Notes |
|---|---|---|
| KPI Name | The record's name | A number from the Performance KPI numbering series (PKPI) |
| Posting Type | Which engine reads the record | The calculation writes INCENTIVE or SCHEME. The seeded picklist lists KPI and Scheme Ledger, which nothing writes, so the stored value may show without a matching picklist entry |
| Resource | The rep on the document | Order: Executive. Invoice: Executive, otherwise Executive Resource. Matches Resource-type plan members |
| Branch | The document's branch | Matches Branch-type plan members |
Account Information
| Field | What it means | Notes |
|---|---|---|
| Account | The customer on the document | Empty for purchase orders and bills |
| Partner Account | The document's partner account | Matches Partner-type plan members |
| Supplier Account | The document's supplier account | Used by schemes |
Product
| Field | What it means | Notes |
|---|---|---|
| Item | The item an item record counts | Empty on header records |
| SKU | A SKU | Never set by the calculation |
Scheme & Incentive
| Field | What it means | Notes |
|---|---|---|
| Scheme, Scheme Period | The Per Period scheme and period the record counts towards | Scheme records only. Scheme Period is empty when the scheme has no periods |
| Incentive Plan, Incentive Period, Incentive Target | The plan, period and target the record counts towards | Incentive records only |
| Target Value | The resource's quota for this period and target | Set only for documents with a resource who has a quota. Replaced, not added, on each document |
Document Counts, Amount Summary and totals
| Field | What it means | Notes |
|---|---|---|
| Number Of Orders, Number Of Invoices | Documents counted | Header records only |
| Number Of Purchase Orders, Number Of Bills, Number Of Repair Orders | Documents counted | Only when the action has been added to those documents |
| Number Of Service Requests, Number Of Opportunities | Opportunities counted | Both go up by one per opportunity |
| Number Of Quotes, Number Of Leads | Not written by the calculation | Available for imported records |
| Total Quantity | Quantity counted | Header: the sum of the positive line quantities. Item record: the line quantity |
| Total Amount | Amount without tax | Header: the document's line total. Item record: the line amount |
| Total Tax Amount | The document's tax | Header records only. Zero for purchase orders and bills |
| Total Sale Order Quantity, Total Sale Order Amount | Sale order figures | Header amount includes tax |
| Total Sale Invoice Quantity, Total Sale Invoice Amount | Invoice figures | Header amount includes tax |
| Total Purchase Order Quantity, Total Purchase Order Amount | Purchase order figures | Without tax |
| Total Bill Quantity, Total Bill Amount | Bill figures | Without tax |
| Total Repair Order Quantity, Total Repair Order Amount | Service order figures | Parts plus labour, including tax on the header |
| Total Service Request Quantity, Total Service Request Amount | Opportunity figures | Header amount includes tax |
| Total Quote Quantity, Total Quote Amount | Not written by the calculation | Available for imported records |
Business rules
- Approved only. Only incentive plans and Per Period schemes with Status Approved receive records. A plan approved after a document was calculated never receives that document.
- Periods by date. An incentive record goes into every period of the plan whose Date From and Date To contain the document date. A period's status is not checked, so a closed period still receives records.
- Plan and target filters. The plan's Account, Partner Account, Supplier Account, Branch, Account Group and Partner Account Group, and the target's Account and Account Group, must match the document. Account groups count only when their type is Scheme.
- Which targets. A document moves only the target types it can measure. Orders move No Of Sale Orders, Sale Order Amount, Sale Order Quantity, Percentage of Unique Outlets and No Of Unique Items. Invoices move No Of Invoices, Sale Amount, Sale Invoice Quantity, Invoice Quantity, Percentage of Unique Outlets, No Of Unique Invoices and No Of Unique Items. Targets of other types, including Custom KPI, get no records from documents.
- Scoring. The engine sums the records of the compensation line's plan, period and target that match the member. Resource plans match on Resource, Partner plans on Partner Account, Branch plans on Branch. Customer members never match, because the member stores a contact and the record stores an account.
- Item filters. A target with an item or item group filter reads only item records, so header totals are not counted twice.
- Quotas on the record. Target Value is set only for members linked to a resource. A changed quota reaches the record only when another document for that rep, period and target is calculated.
- No reversal. Cancelling, changing or deleting a calculated document leaves its records as they are.
- Clone. A cloned order or invoice starts with KPI Calculated and Perform KPI Calculation cleared, so the copy can be calculated on its own.
- Opportunities. Calculating an opportunity that is already calculated is refused with "KPI has already been calculated for this opportunity." Other documents are skipped without a message.
Example
A distributor runs a monthly Resource plan for its field reps. Its approved target "Monthly sales" has type Sale Amount and no KPI configuration, and each rep has a quota of 300,000 for October.
- On 6 October, a rep's invoice for 50,000 plus 9,000 tax is finalised. The sales coordinator selects Perform KPI Calculation. xMatix creates a Performance KPI record with Posting Type INCENTIVE, the rep as Resource, the October period and the "Monthly sales" target. It shows Number Of Invoices 1, Total Amount 50,000, Total Tax Amount 9,000, Total Sale Invoice Amount 59,000 and Target Value 300,000.
- On 20 October, a second invoice for the same customer comes to 30,000 plus 5,400 tax. After its calculation, the same record shows Number Of Invoices 2 and Total Sale Invoice Amount 94,400.
- At month end, the administrator runs Process Compensation on the October period. The rep's line shows an achieved value of 94,400 against the quota of 300,000.
Training
Practice exercise
In a sandbox with an approved Resource plan, a Sale Amount target with no KPI configuration, and an October period:
- Ask an administrator to add Perform KPI Calculation to the invoice page header and grant it to your profile.
- Create an invoice dated in October with a Sales Executive who is a member of the plan.
- Select Perform KPI Calculation, then run New KPIs Report.
Expected result: one record for the plan's target and the October period, with Number Of Invoices 1 and Total Sale Invoice Amount equal to the invoice total including tax. The invoice shows KPI Calculated. Running the action again changes nothing.
Quick reference
- Records are written only by Perform KPI Calculation, not by saving.
- Out of the box the action exists on Order and Invoice, and is not on their page headers.
- Each document is counted once. Later edits and cancellations are not counted.
- Only Approved plans and schemes, and documents dated inside a period, get records.
- Sale Amount and Sale Order Amount include tax. Total Amount does not.
- Targets with a KPI configuration ignore these records.
- Process the period again after late calculations.
Permissions
- Viewing and editing records follows the Performance KPI entity permissions on each security profile. In the seeded profiles, Sales Executive, Sales Manager, Standard User and System Admin have full access (read, create, edit and delete). A rep could therefore change their own totals. If only administrators should, reduce Performance KPI to read-only on the other profiles.
- Running Perform KPI Calculation needs the action granted on the profile. Out of the box only System Admin has it, on Order and Invoice.
Configuration
- Add the button. The seeded Order and Invoice record pages list their header actions explicitly and leave Perform KPI Calculation out. Add PerformKPICalculation to the page header of the OrderView or Invoice View layout, as described in Design a form layout. The order layout already hides it once the order is calculated or has nothing pending fulfilment.
- Grant it. Grant the action to the profiles that finalise documents, on the profile's actions settings. See Security profiles.
- Other documents. Purchase orders, bills, service orders and opportunities have no Perform KPI Calculation action out of the box. To calculate them, add an entity action named PerformKPICalculation (server action PerformKPICalculation) to the entity, place it on the record page header and grant it. See Entity behaviour. Of the target types these documents move, the incentive engine scores only Purchase Order Amount and Purchase Order Quantity. The bill, repair-order and service-request types record figures for reports, but no target scores them (see What each target type counts).
- Numbering. Record names come from the Performance KPI document name setting (series PKPI, active by default). See Configure document numbering.
- Show records in an app. Performance KPI is in no app's navigation. To give administrators a list, add the entity to the Rewards app under Setup → Design Studio → Apps with Manage Items (see Create an entity). The standard list view is All Performance KPI.
- Posting Type picklist. To show the stored values as labels, add INCENTIVE and SCHEME to the Posting Type picklist.
- Account groups. Plan, target and scheme account-group filters need groups of type Scheme. See Account groups.
Common problems
Nothing changes when I save an invoice with Perform KPI Calculation ticked
Saving never calculates. The field is only a marker that the action clears. Run the Perform KPI Calculation action. If it isn't on the page, ask an administrator to add it (see Configuration).
I can't find Perform KPI Calculation on the order or invoice
The seeded page headers leave it out, and only System Admin is granted it. On an order the button also hides once the order is calculated or has no quantity pending fulfilment.
The action ran but no record appeared
Check, in order:
- The document has a Document Date, and wasn't already calculated (KPI Calculated is not set).
- The plan is Approved, and one of its periods and its validity contain the document date.
- The plan has a target of a type the document can move, without a KPI configuration.
- The plan's and target's account, partner, supplier, branch and account-group filters match the document.
A plan approved, or a target added, after the calculation never receives the document.
The achieved value is higher than the invoice amounts
Sale Amount and Sale Order Amount include tax. Compare with Total Sale Invoice Amount or Total Sale Order Amount on the record, not Total Amount.
A cancelled invoice still counts
Nothing reverses a calculation. Correct or delete the record by hand, then process the period again (see Step 4).
A member's line reads zero although records exist
The record must carry the member's key: Resource for Resource plans, Partner Account for Partner plans, Branch for Branch plans. Customer members never match. Also check the target's item filter: a target limited to an item reads only item records.
Common questions
Is Performance KPI the same as KPI Data?
No. KPI Data is the result of a KPI configuration, with one row per configuration, plan, period and member, and a detail line per source record. Performance KPI records are running totals written by the Perform KPI Calculation action, with no per-document detail. A target linked to a KPI configuration reads KPI Data only. A target without one reads Performance KPI records only. KPI configurations accrue on their own trigger events, so they need no action on the document.
Can I recalculate a document after changing it?
No. Once KPI Calculated is set, the calculation skips the document, and nothing clears the flag from the standard screens. Correct the Performance KPI record by hand or by import, then process the period again. If documents are often changed after they are final, a KPI configuration may suit you better, because its data can be rebuilt.
Why do I see two records for one invoice?
One run can write several records: one per target and period it counts towards, one per matching item for item-limited targets, and separate scheme records for Per Period schemes. Posting Type tells incentive records (INCENTIVE) from scheme records (SCHEME). Add them up only within one posting type and target.
Does the field app calculate KPIs?
No. The field app reads Performance KPI records for its target pace card and falls back to the rep's orders when there are none. The calculation runs only from the web action.