KPI Tracking
Audience: Strategy Manager, Unit Leaders, KPI responsibles, Admin
Page Type: How-To Guide + Reference
Menu: Goals & Tracking → KPI Tracking (/kpis)
What is a KPI now?
In COS a KPI is a record that is defined once in your tenant and lives continuously. Reports and analyses do not hold their own copy of a KPI; they use the same KPI.
- Continuous series: Each KPI has a single measurement series. The series continues when the planning period changes; you do not recreate the KPI in the new cycle.
- Owner unit (required): The organization unit the KPI belongs to. Measurement authority is derived from this unit and its parent units.
- Responsible (optional): The person who keeps the KPI measured. Must be an active member of the tenant.
- Code (optional): A short code to tell KPIs with the same title apart (e.g.
FIN-REV-IST). When set it is unique within the tenant and stored in upper case. - Usages: The same KPI can be used in several reports (e.g. Status Report, SWOT and a Focus Area). All of them show the same measurement series. The only report-specific settings are the report weight and, for BSC and Focus Areas, the perspective.
- Status:
ActiveorRetired. A retired KPI accepts no measurements and cannot be added to a new report; its history stays readable.
Previously every report kept its own KPI copy and measurement series, which is why "linked KPI" and "performance indicator" screens existed. These concepts are gone. You manage KPIs in one place: this screen.
Access
- The menu item is visible to every role with the
KPI:VIEWpermission: Super Admin, Group Admin, Admin, Strategy Manager, Team Lead and Member. - A tenant administrator can hide the KPI Tracking module (group Goals & Tracking) in the tenant menu configuration.
- The list only shows KPIs in your scope:
- Admin, Strategy Manager, Group Admin (in tenants of their group) and Super Admin see every KPI of the tenant.
- Other users see the KPIs in the company of the units they belong to or lead, and the KPIs they are responsible for.
- A user who can view a report can open that report's KPIs from the report. Those KPIs are not added to the KPI Tracking list.
- Opening the address of an out-of-scope KPI shows "KPI not found"; no information about the KPI is disclosed.
KPI list
The list shows: title, code, owner unit, responsible, library source, last measurement and its measurement date, success level, usage count, status.
Filters
| Filter | Description |
|---|---|
| Search | Title or code |
| Owner unit, Responsible | By unit or person. Selecting a unit also lists the KPIs of its sub-units; clear Include sub-units to see that unit only. |
| Theme | KPIs actively used on a given strategic theme. Shown only when the themes module is enabled. |
| Success level | By the success level shown in the list (1–5, from the latest measurement). Not evaluated selects KPIs without criteria or not evaluable yet. This filter works on at most 5000 KPIs; for a larger list you are asked to narrow it by unit, theme or cycle. |
| Library item | KPIs created from the same library item. The KPIs created from this item link on the library page opens this filter. |
| Status | Active / Retired |
| Used in report type, Used in cycle | By the report type and planning period that actively use the KPI. When both are set, the same usage must match both. |
| Measurement overdue | Active KPIs whose last measurement date + the KPI's measurement frequency + grace days is before today (UTC). A KPI without measurements is never overdue. The grace period defaults to 7 days and can be changed by the installation administrator. |
| No measurements | KPIs without any measurement |
Filters are kept in the address bar, so you can share a filtered list as a link.
With Group by unit, the list is grouped by owner unit in organization tree order. Each group header shows the number of KPIs on that page.
Bulk actions
Select several KPIs in the list to:
- Assign responsible: sets the same responsible on the selected KPIs.
- Retire / Reactivate: changes the status of the selected KPIs.
Authority is checked for each KPI separately. KPIs you cannot change stay as they are and are shown as "Not applied" per row in Bulk action results. The number of KPIs per request is limited (default 50).
Creating a KPI
The New KPI button offers two methods.
From library
- Choose From library and the library: KPI & IPF library or Product KPI library.
- Select the library item, the owner unit and optionally the responsible and a code.
- Click Create.
Rules:
- Every pull from the library creates a new KPI. The definition, breakdown template and the tenant's default success criteria template (when defined) are copied once. Later changes to the library item do not affect the KPI.
- If the same unit already has KPIs created from the same library item, a duplicate warning appears. The existing KPIs are listed (retired ones labelled "Retired, can be reactivated") with two options:
- Use existing
- Create a new KPI anyway: a distinct title or code is recommended.
- The warning does not block creation. A KPI created from the same item in a different unit does not trigger the warning.
Manual
You enter the title, unit, direction and other fields without a library item. Manual creation requires a plan whose KPI library tier allows it. There is no duplicate warning for manual KPIs.
Who can create
- Admin, Strategy Manager, Group Admin (in tenants of their group) and Super Admin in any unit.
- Team Lead only in the unit they lead or its sub-units.
- The Member role cannot create KPIs.
Plan limit
The plan's maximum number of KPIs (max_kpis) counts active KPIs only. When the limit is reached, creating a KPI is rejected everywhere: this screen, the From library tab of the "Add KPI" dialog in reports, and the AI assistant. Retiring a KPI frees a slot; reactivating a retired KPI checks the limit again.
KPI detail
Clicking a KPI opens a detail view with 7 tabs. Tabs you cannot edit open read-only.
1. Definition
Title, code, description, unit, direction (higher/lower is better), measurement frequency (daily, weekly, monthly, quarterly, yearly; default monthly), IPF dimension, default BSC perspective and formula. The measurement frequency drives the suggested measurement date and the overdue warning.
- Before saving, a "This change affects N active usages" warning is shown. A definition change applies to every active report that uses the KPI.
- Version conflict: If someone else saved the KPI while you were editing, your save is rejected and you are asked to load the current version and try again. Changes are never silently overwritten.
- Owner unit and responsible are changed with separate buttons (see Responsible handover and owner unit).
2. Breakdown
The breakdown configuration for measuring the KPI by category (e.g. sales by region): dimension name, total method and categories. Categories are identified by code; an unused category is archived rather than deleted.
- Sum of categories (default): the total is the sum of the category values and is calculated in the form. If you enter a value in one category you must enter it in every active category; the actual is required in every category. Pie, donut and stacked charts are available only with this method.
- Manually entered total: for KPIs that do not add up, such as rates. You enter the actual total (required); category values are optional.
- Remove breakdown: archives every category and the KPI returns to uncategorized entry. Earlier categorized measurements stay in the list and the chart with their totals. A category added again with the same code is restored from the archive.
- Changing the total method affects only new and edited measurements.
3. Measurements
Measurement history, chart and new measurement entry. Categorized and uncategorized measurements appear in one list; the Add measurement button in the header opens the form for the KPI's current breakdown.
- Fields: measurement date, target, actual, forecast, status note. KPIs with a breakdown add category rows.
- Measurement date: there is no period selection. The suggested date is the last measurement date + the measurement frequency (month end is kept: 31.10 + 1 month = 30.11); for the first measurement it is today. A future date is allowed (for forecasts).
- A KPI can have one measurement per date. Entering the same date again shows an error on the date field. You can change the date when editing.
- The target is prefilled with the target of the closest earlier measurement; you can change it. In a categorized measurement each category takes its own earlier target.
- Every row has edit and delete icons. A categorized row shows a "Categorized · n" tag; expanding it shows the category table (target, actual, colored achievement %, forecast). Category colors are informational only.
- To save an older measurement that contains archived categories, delete those rows or reactivate the category on the Breakdown tab. If the breakdown was removed, an older categorized measurement can only be deleted.
- The chart draws every measurement in date order as one continuous total series. Category series are drawn only on dates with categorized measurements.
Who can enter measurements?
| Who | Note |
|---|---|
| The KPI's responsible | Even with the Member role |
| Leader of the owner unit | |
| Leaders of the owner unit's parent units | Every parent up to the root |
| Admin, Strategy Manager | Every KPI in the tenant |
| Group Admin | Only in tenants of their group |
| Super Admin | Platform-wide |
- The chain is resolved from the unit tree at the time of writing. If a unit is moved, the new parent leaders gain authority and the old ones lose it. If a unit in between is inactive, leaders above it get no authority.
- Report edit permission does not grant measurement authority. A user who can edit a report but is not in the chain does not see the measurement form.
- A retired KPI accepts no measurements; existing measurements stay readable.
- A closed report or planning period does not block measurement entry. Report screens in a closed cycle show the closing snapshot read-only; enter measurements on this screen.
- Every measurement write appears in the History tab with who wrote it, the channel (UI, AI assistant, Push API, Pull integration) and the authority path.
4. Integration
Connects the KPI to external systems: Push (the external system sends to COS) and Pull (COS fetches from an external API). Creating a binding requires edit authority on this KPI. Bindings of a retired KPI are inactive; reactivating the KPI does not reactivate them automatically. See Push Measurement API and KPI API Integration (Pull).
5. Success criteria
Success criteria belong to the KPI: every report, dashboard card, Goal Alignment Matrix row and AI answer that uses the KPI shows the same criteria and the same level. If you need a different evaluation, create a separate KPI. Closed-cycle reports are the exception: they show the criteria as of closing.
Who can edit? The same people who can enter measurements (the KPI's responsible, the leaders of the owner unit and its parent units, Admin, Strategy Manager, Group Admin in tenants of their group, Super Admin) plus the KPI edit permission (KPI:EDIT). Without authority the editor opens read-only. Criteria of a retired KPI cannot be edited.
Editor fields
| Field | Rule |
|---|---|
| Evaluation basis | Achievement rate (%): target/actual ratio computed by direction. Actual value: the raw measured value. |
| 5 levels | Scores 1–5 are fixed. Each level's label (up to 60 characters) and color are free. |
| 4 thresholds | Must be increasing. A boundary value always belongs to the better level. With the actual-value basis on "lower is better" KPIs the mapping is inverted: a value equal to or below the threshold is the better level. The editor shows a range preview by direction. |
- Apply tenant default replaces basis, levels and thresholds with the tenant's success criteria template; you can review before saving.
- Before saving you confirm "This change affects the level and report scores of N active usages". Closed reports keep their snapshot.
- If someone else saved the criteria while you were editing, your save is rejected and you are asked to load the current version.
- You can remove the criteria entirely; the KPI then shows "No criteria".
- Every change is written to the History tab.
How the level is computed
- Only the actual value is evaluated; forecasts are ignored.
- The level is always calculated from the total: the latest-dated measurement with an actual value is used. KPIs with and without a breakdown are evaluated the same way.
- The value is rounded to 2 decimals before comparing with the thresholds.
- In a report or planning period the evaluation uses the latest measurement inside that period's date range. Without one, the badge is grey "No measurement in this period" and names the last earlier value and level (e.g. "last: 30.06.2026 · Good"); the KPI is not counted in the report score.
- A decimal score is rounded to a level half up: 3.49 → 3; 3.50 → 4.
- Without criteria no success indicator is shown ("No criteria", neutral grey). Without an actual value or with a zero/empty target (rate basis), the result is "Not evaluable".
The level badge always shows its label text (not color alone). It appears in the Level column of the KPI list, the KPI detail header, the report KPI list, KPI cards, dashboard cards and the Goal Alignment Matrix. Its tooltip shows the value, the measurement date (e.g. "Measured: 30.09.2026") and the level ranges. KPI values are no longer colored by fixed 80%/100% thresholds; color comes only from the KPI's own criteria. OKR health scores and colors are unchanged.
6. Usages
Shows which reports and analyses use the KPI: type, report name (with a link to the report), planning period, weight, perspective and usage status. Usages in a closed cycle are labelled.
-
Reports you cannot view are not named; only "N more usages you cannot access" is shown.
-
For KPIs with very many usages the list can be limited; a warning appears in that case.
-
Opening the report of a closed-cycle usage shows the report's closing snapshot (see Reports in a closed cycle).
7. History
The audit trail of every change on the KPI: time, action (creation, definition, responsible, owner unit, status, breakdown, measurement, added to/removed from report, weight), channel, authority path and changed fields.
Responsible handover and owner unit
- Change responsible: Anyone in the KPI's measurement chain can change the responsible. The responsible person can also hand over (even with the Member role) to another active member of the tenant, e.g. to a successor after a job change. The handover is written to the audit trail.
- When a member is removed from the tenant, the responsible field of their KPIs is cleared and the change is recorded with the "System" channel.
- Change owner unit: Requires authority on both the current and the target unit (unit or parent-unit leader, or an administrator role). Being the responsible is not enough.
- An organization unit used as the owner unit of KPIs cannot be deleted; move the KPIs to another unit first.
Retiring and reactivating
Retire stops a KPI that is no longer tracked without losing its history:
- A retired KPI accepts no measurements from any channel (UI, AI, Push, Pull) and cannot be added to a new report.
- Existing usages, measurements and dashboard cards stay readable; the card shows a Retired label.
- Integration bindings are deactivated.
- It frees a slot in the plan limit.
Reactivate lets the KPI accept measurements again. The plan limit is checked again. Bindings stay inactive; re-enable them in the Integration tab if needed.
Both actions require authority on the owner unit: leader of the owner unit or a parent unit, or an administrator role. A Team Lead can do this only for KPIs in their chain. Being the responsible is not enough.
Delete rules
- Only a KPI with no usages and no measurements can be deleted, typically a KPI created by mistake.
- A KPI used in reports or with measurements cannot be deleted; the button is disabled and the reason is shown. Use Retire instead.
- Delete permission is held by Admin, Strategy Manager and the higher administrator roles; Team Lead and Member cannot delete.
- Dashboard cards that showed a deleted KPI are not removed; they stay as a "Source unavailable" placeholder.
- Delete and retire ask for confirmation.
Adding KPIs to reports
The detail pages of Status Report, SWOT, PESTLE, Porter, BCG, Focus Area and Product Scorecard have a KPIs section. The Add KPI button opens a dialog with 4 tabs:
| Tab | What it does |
|---|---|
| From library (new KPI) | Creates a new KPI from a library item and adds it to the report. When the owner unit is left empty, the report's unit (for a Product Scorecard, the product's first owner unit) is used. The duplicate warning is shown. Requires KPI creation authority in the owner unit and the plan limit in addition to the report edit permission. |
| From KPI register | Adds an existing KPI from your scope. Retired KPIs and KPIs already in the report cannot be selected. |
| From another report | Pick a report type and a report you can access, then select from its KPIs. The same KPI is added to this report; measurements are shared. (Replaces the former "add from current state" flow and works with every report type.) |
| From previous cycle | Lists the KPIs of the same kind of report of the same unit (for a Product Scorecard, the same product) in a closed planning period (by default the most recently closed one). The selected KPIs are added and their weights are copied from the previous usage. Change the weights afterwards with Weights. |
Every tab shows the KPI's success criteria read-only, as they are; criteria do not vary by report.
Report weights
The Weights button shows the weight of every KPI in the report and the computed percentage share.
- A weight is specific to the report and must be greater than 0 (default 1).
- All weights are saved together. If one was changed meanwhile, none is applied and you are asked to load the current values.
Report score
A report score summary is shown above the report's KPI list:
- Report score = the weighted average of the evaluated KPIs' decimal scores, weighted by report weight. The score is rounded half up to a level and shown with its label.
- Coverage = the weight of the evaluated KPIs divided by the weight of all active KPIs. Coverage is informational and does not cancel the score.
- The level distribution (1–5) and the counts of "Not evaluable" and "No criteria" KPIs are shown separately.
- Without any evaluated KPI, no score is shown.
- Period selection: with the report's Period date picker you can view levels and the report score as of a given day (UTC calendar day). The default is Latest period; Back to latest returns to it. An invalid date falls back to the latest period. In a closed report the selection is limited to the cycle's closing window.
- Example: one KPI with weight 1 and score 3.5 plus one KPI with weight 1 and no criteria → report score 3.5 (level 4), coverage 50%.
- Views combining several reports use the unweighted average of report scores. There is no BSC perspective weight.
Removing a KPI from a report
Remove from report deletes the usage only; the KPI and its measurements stay in the KPI register. A Focus Area KPI linked to an OKR key result cannot be removed; you are asked to remove the key-result link first, and the linked key results are listed (those you can see by name, the others as a count).
Reports in a closed cycle
When the report's planning period is Closed or Completed:
- Adding, removing, perspective and weight changes are not possible; the Add KPI button is hidden and an information note is shown.
- The KPI detail opens read-only. Use Open in KPI Tracking to enter measurements.
- A Product Scorecard without a planning period is not locked.
Closing snapshot. When a planning period is closed, the KPI usages and report scores of all its reports are recorded as of the closing moment. A closed report is read only from that snapshot:
- The report's KPI section shows a "Closing snapshot — date" badge, the report score at closing and the KPI count.
- Each KPI shows its value, criteria and level at closing. If the KPI's definition, criteria or measurements changed after closing, a "Changed since closing" label appears; the values shown are still those at closing. Current values appear in KPI Tracking and active reports.
- A KPI detail opened from a closed report is read-only and hides the tabs that carry live data (Integration, Usages, History).
- Entering measurements after closing is allowed (in KPI Tracking) and does not change the closed report. A measurement written in the same seconds as the close may or may not be included; measurements written after closing never are.
- A report in a closed cycle cannot be deleted, reports cannot be created in or moved into or out of a closed cycle. Name and description can still be edited. A product with a closed scorecard cannot be deleted.
- For cycles closed before the upgrade, the snapshot is produced during the upgrade; those reports show a note that the snapshot was produced after closing.
- Cycle status rules: Planning Periods.
New status reports start empty
When you create a new status report, library KPIs are not added automatically. The report starts empty; add KPIs with the dialog above. To carry over the previous period's KPIs, use the From previous cycle tab.
Success criteria template
Settings → Success criteria template (/settings/success-criteria) defines the tenant's default criteria: basis, 5 levels (label, color) and 4 thresholds.
- Admin, Strategy Manager, Group Admin in tenants of their group and Super Admin can edit it. Other roles do not see the page.
- The template is copied once into a new KPI when it is created (KPI Tracking, the "From library" tab in reports, the AI assistant). Later template changes do not affect existing KPIs; there is no live inheritance.
- A new company starts with a copy of the platform default template managed by Super Admin, as it is at that moment. English labels are copied when the language is English, otherwise Turkish (on sign-up the interface language used during sign-up, on the other paths the creating user's language preference). Later changes to the platform default never change existing companies' templates or KPIs.
- With 0.5.40, companies without a template received the built-in Turkish template, and active KPIs with empty criteria (except those cleared on purpose) received their company's template. If a company still has no template, it is created from the platform default when its first KPI is created.
- In the sample tenants the template is predefined: achievement-rate basis, thresholds 60/80/100/110, Turkish labels Çok Kötü / Kötü / Orta / İyi / Çok İyi (Very Poor … Excellent); labels are free text you can change.
- If someone else saved the template while you were editing, your save is rejected and you are asked to load the current version.
Dashboards and other screens
- My dashboards: A card shows a KPI directly and keeps following the same KPI's current series across cycles. See Reports › My dashboards.
- Goal Alignment Matrix: The Status Report KPI → Focus Area KPI → key result chain is built on the same KPI records. See Reports.
- OKR: A key result is linked to a Focus Area KPI of the same planning period.
- AI assistant: Tools to search, create, measure and add KPIs to reports follow the same authority rules. See AI Assistant.
FAQ
Can I use the same KPI in two reports with two different success criteria?
No. Criteria belong to the KPI. If you need a different evaluation, create a second KPI from the library and tell them apart with a code.
I can edit the report but cannot enter measurements. Why?
Measurement authority comes from the KPI, not the report. You must be the KPI's responsible, the leader of the owner unit or a parent unit, or hold an administrator role.
The cycle is closed. Can I still enter last period's measurement?
Yes, in KPI Tracking, with an earlier measurement date. The closed report keeps showing the value at closing; the new measurement appears in the KPI's current series and in active reports.
I want to delete a KPI but the button is disabled.
The KPI has usages or measurements. Use Retire to keep its history.