KPI Dictionary for BI: how to create a unified metrics catalog

Why teams argue about numbers in BI

The same KPI in BI often shows different values not because someone made a mistake, but because each team calculates it differently. Marketing looks at leads, sales at deals, finance at payments. On a dashboard it can appear as a single metric, but its meaning differs.

Most disputes start not over the chart itself, but over details that the chart doesn't show: the formula, filters, period, data source. For example, "revenue" can be counted by shipment or by payment. An "active customer" could mean any purchase in 12 months or an order in the current quarter. "Delivery time" — from request date or contract date.

Usually a conflict is caused by a combination of four reasons: different formulas and rounding (include VAT or not, count returns or not), different filters and segments (only B2B or all channels), different periods and slicing rules (calendar month or 4 weeks), different sources (CRM vs ERP, a data mart vs a one-off extract).

The cost of misunderstandings grows fast. Plans get recomputed, bonuses are disputed, budget and project decisions are delayed. Leaders lose trust in BI and, instead of a single source of truth, parallel spreadsheets and "their" reports appear.

Unified definitions eliminate most disputes before the meeting begins. When a metric has a fixed formula, default filters, period, source and an owner, the discussion shifts from "which number is right" to "what to do about it." This saves time and makes comparisons between teams fair.

What is a KPI dictionary and why you need it

A KPI dictionary for BI is a single source of truth about metrics: how they are named, what they measure, and how they are calculated. It's not for show — it's to ensure the same KPI in different reports produces the same number and meaning.

The main difference from a simple list of metrics is that a dictionary records decisions, not just names. It pre-agrees what to count, when to count it and where to get it from. Then a dispute becomes a straightforward check: does the report match the approved definition.

A dictionary typically captures: a plain-language definition of the metric, the formula, rounding rules, calculation frequency, default filters and applicability boundaries (where the KPI makes sense and where it doesn't). It's useful to list related metrics so similar measures aren't confused — for example, "revenue" vs "receipts."

The dictionary links business goals, reports and source data. A simple example: the goal is to reduce overdue payments. A BI report for finance and sales appears, and the dictionary records that "share of overdue receivables" is calculated by specific account statuses, on a cut-off date, and from specific ERP/CRM tables. Then departments don't start calculating the same thing differently.

The format can vary: a table, a page in the corporate wiki or a metadata catalog in the BI platform. What matters is not where it is stored, but that the dictionary is accessible, has owners and is updated by rules — not "by phone call."

KPI card structure: what to record

A KPI card is a short passport for a metric. If cards are filled in consistently for all metrics, a KPI dictionary stops being a list of dashboard names and becomes a source of common rules.

Make the minimal set of fields consistent. Usually the following is enough:

• Name and a short plain-language description.
• Calculation formula (including exact fields and operations).
• Frequency and update timing.
• Units and rounding.
• Where the KPI is displayed (specific report/dashboard and widget).

Then remove ambiguities. The card should record inclusion and exclusion rules: what counts as a "sale", whether returns are included, how to handle cancellations, internal movements and test records. Also describe default filters: which document statuses are used, which dates count (order date or shipment date), and which currency the calculation uses.

If the KPI is used in breakdowns, don't stop at vague terms like "by branches" or "by channels." Define the segments: what is a "branch" (legal entity or warehouse), how is "channel" defined (lead source or contract type), and which reference data sets are authoritative.

Example: "Margin, %" often causes disputes. Without a card one team counts by shipment and excludes logistics, another by payment and includes delivery. One field "cost inclusion rules" and a list of exclusions resolve the dispute before a meeting.

Roles and responsibilities: owners and approvals

To prevent a KPI turning into a meeting fight, assign owners. This isn't bureaucracy — it's a clear answer to who is responsible for meaning, who is responsible for data, and who implements it in BI.

Usually three roles suffice:

• KPI owner (business) — approves the meaning: what we measure, why, period, and target values used in reporting.
• Data owner — responsible for the source, quality, availability, update rules and restrictions.
• Calculation owner (BI/analytics) — translates the definition into an exact formula, implements it in the data model and ensures the calculation is reproducible.

Approvers join according to clear triggers. Finance is needed if the KPI affects bonuses, budgets or management reporting. Risk and security if sensitive data or access rules change. HR if the metric concerns people. The earlier they are involved, the fewer reworks after publication.

Example: in a manufacturing company there's a dispute over "plan fulfillment." Production counts by warehouse shipments, sales by invoices, finance by payments. The KPI owner fixes the meaning (for example, "by paid invoices"), the data owner confirms the source (ERP/accounting), and the BI owner implements the formula and tests it.

If there is no agreement, set an escalation rule: first a meeting of owners, then a decision by the process leader (e.g., the CFO for financial metrics) and a final entry in the KPI card with date and responsible person. This stops endless "but our report showed otherwise."

Data sources and rules for trusting numbers

KPI disputes often start not with the formula but with the question: "Which system did you take this from?" That's why it's important to fix the source and data level in the KPI card. The dictionary becomes an agreement on which figures are official.

List the source systems and their role. For example: ERP as the primary source for shipments and balances, CRM for funnel and deals, Service Desk for tickets and SLAs, accounting for actual income and expenses, the data warehouse (DWH) as the place where data is consolidated and cleaned. If a metric is computed from multiple systems, state which one "wins" when they disagree.

Also record the data level: transactions (raw events), aggregates (sums and averages), marts (ready tables for reporting) or manual files. Manual files should be a temporary solution with a deadline to replace them with a system source.

Timing rules often break trust in numbers. Record timezone, period close date and loading delay. Simple example: sales look at "revenue for the month" by invoice date, while finance uses payment date and only after period close. The dictionary should choose one approach for the KPI or split into separate KPIs like "revenue by invoices" and "revenue by payments."

Before publishing a KPI define minimal data quality checks: check completeness (no gaps by date or branch), duplicates, current reference data and statuses, correctness of keys for joining systems (ID, tax numbers, contract), and freshness of loads. When these rules are described and followed, the question "why is your number different from ours" occurs much less often.

KPI formulas: how to describe them without ambiguity

A KPI formula must be understood the same way by a manager and an analyst. It's convenient to keep two layers: a business formula (plain language) and a technical implementation (how to calculate it exactly in data). Then the dispute quickly reduces to one question: which version is accepted.

Start with calculation boundaries. Explicitly list what goes into the numerator and denominator. If a KPI is a ratio, set rules for zeros and missing data: what to do if the denominator is zero (return 0, null or exclude from aggregation) and how to treat a missing value (no event or no data).

Separately record rules for cases that most often break comparability: cancellations, returns, duplicates, test records. Don't write "exclude canceled" without clarifying. State which statuses count as cancellation, at what step they are excluded and what to do if cancellation occurred after the period closed.

To make the formula repeatable, use a shared dictionary of terms within it. For example, define what a "request" is, what "closed" means, which dates are used (created, closed, paid) and the timezone. These definitions should match those in source systems.

Example of documentation

Business formula: "Share of closed requests per day = number of requests closed that day divided by number of requests created that day. Exclude canceled and test records."

Technical implementation: list tables and fields (entity, status field, list of statuses considered "closed", test record flag, cancellation rule), then division rules (what to do on zero denominator) and aggregation level (by day, department, branch).

How to plan and collect the KPI dictionary: steps

Start not with "all company metrics" but with those that already cause disputes in reports. This produces quick wins and shows how the process will work.

Practical 2–4 week plan

First gather a short list of KPIs where values diverge between teams or reports. Then prioritize by impact: what affects money, deadlines and fines, what is part of management KPIs, what is most frequently discussed in meetings.

Next conduct short interviews with business owners and analysts: how they use the KPI, what decision it supports and where it "breaks." In the KPI card record a plain-language definition, frequency, needed dimensions (branches, products) and success criteria.

Separately document sources: specific systems, tables or marts, and trust rules (which source is primary, which is backup). At this stage check access and quality: gaps, duplicates or late updates.

Then agree on formulas so nothing remains ambiguous. Discuss edge cases: division by zero, days without data, returns, cancellations and backdated adjustments.

When the first KPIs are ready, publish the dictionary as the single source and link it to reports and marts. Near each chart it should be clear what is counted. For maintenance, agree on a regular review cadence, e.g., quarterly.

Change process and versioning

KPI formulas must not be changed "quietly." Any edit changes the meaning of the metric and affects plans, bonuses, management reports and period comparisons. Changes should follow a clear process and be recorded in the KPI dictionary.

Change requests usually appear in three cases: business policy changes (for example, returns are counted differently), source or system changes (fields updated in ERP/CRM), or a discovered error in formula or filters. If the reason is unclear, first clarify the business logic the KPI should reflect.

How to submit a change request

A good request is short but complete. Record:

• The reason and expected effect.
• Which reports/dashboards and teams are affected.
• Effective date (from which period the new logic applies).
• How to handle history (recalculate or keep as-is).

Version, history and release

Each edit gets a new version: number, date, author (initiator and implementer), description of "what changed" and "why." Keep the current formula and change log in the KPI card. It's then easy to explain why January and February numbers diverged.

The main compatibility question is what to do with old periods. Common options: recalculate history (if the KPI is needed for trends) or "freeze" the past and apply the new formula only from the effective date. The decision must be recorded explicitly; otherwise comparisons will be incorrect.

Before release test the formula on a control sample: compare with sources, check edge cases (empty values, canceled deals, duplicates), then conduct acceptance with the KPI owner. After approval notify data owners, the BI team, financial control and key report users so the new numbers don't look like "BI broke."

Typical mistakes when maintaining a KPI dictionary

The most frequent problem: the same KPI exists under different names. In one report it's "Revenue," in another "Sales," in a third "Revenue (English)." Without a unified definition and a list of synonyms people discuss different things thinking they're arguing about the same metric.

Second mistake — confusing goal and fact. KPIs are turned into "monthly targets" or "standards," while the metric should measure data: what happened, when and under what conditions. Target and fact can be related but are different entities and usually come from different sources.

Trust is often broken by small, undocumented details: filters and exclusions. For example, count "new customers" without test records, excluding canceled orders, only with status "paid." If these rules are not fixed, each team adds its own filters and numbers diverge.

Another pain point is lack of an owner and change history. A formula quietly changes "to be more correct," and a month later no one can explain a spike in the chart. The KPI dictionary must have accountability and a log: who changed it, when, why and from which report it applies.

A further risk is reliance on manual files without a refresh schedule and quality control. When a KPI is calculated from Excel but no one knows who updates it or what to do if it is missing, BI will show a yesterday's view.

Signs the dictionary is managed poorly: a KPI differs by 1–5% across dashboards without explanation; new hires can't reproduce the calculation from the description; "temporary" exceptions become permanent; formulas live in chats instead of the KPI card; KPIs are published without testing on real cases.

Quick checklist before publishing or changes

Before publishing a new KPI or changing an existing one, run a short check. It takes 10–15 minutes and often saves weeks of disputes after numbers have already spread across reports.

Make sure the metric has assigned responsibles: a meaning owner (business) and a source owner (data). If the same person covers both, record that.

Test the calculation for edge cases: zeros, empty fields, missing rows for a period, returns, negative values. If rules for these cases are not described, different reports will interpret them differently.

Short release checklist:

• Units, rounding and calculation period (day/week/month; by event date or by system posting date).
• Edge case test: division by zero, empty values, incomplete periods.
• Source freshness: last load time and completeness check.
• All usages of the KPI: dashboards, marts, extracts, management reports.
• Version, effective date and a short description of the change.

Even a small change can be sensitive. For example, switching rounding from integers to one decimal sometimes affects sales plans and bonuses. Therefore version and effective date must be visible in the KPI card and in the release note.

Example scenario: aligning a KPI across teams

The call center, back office and finance look at the same dashboard but argue about the KPI "request processing time." The call center considers a request processed when an operator sets status "Done." Back office — when verification is complete and a document is formed. Finance — when payment is received. Numbers diverge though everyone believes they're right.

First step — describe the measured object in plain language: what exactly is a "request." For example: "a unique CRM record of type 'New request' with lead_id." Also fix the start moment: "date and time of first status 'Accepted' assignment" or "record creation time," but not both.

Next agree the end moment. To separate operations and money, introduce two metrics: "operational time" (until "Closed by operator") and "financial time" (until "Paid"). If exactly one metric is required, choose a single event and name the KPI accordingly, e.g., "time to payment."

To prevent recurring disputes, predefine edge cases:

• Reopening: count the first closure or the last.
• Pauses: include client wait time or exclude it.
• Cancellation: exclude from the calculation or count separately.
• Duplicates: deduplication rule (by phone, tax ID, email).
• Partial payment: what counts as completion.

Also fix the mart and the period: is the metric counted by creation date or by close date? This affects weekly plan-fact and month-end tails.

Publish KPI version 1.0: formula, sources (e.g., CRM table and statuses), exact timestamp fields, and filters. Plan the migration to a new CRM: version 2.0, effective date, status mapping (old "Closed" = new "Resolved") and a one-month parallel calculation window to compare differences and update dashboards without surprises.

Next steps: maintain the dictionary and scale BI

So the KPI dictionary doesn't become a one-off file, it needs a simple enforceable cycle: who owns it, how changes are made, how checks are done and where it's stored.

Start with accountability. Each metric must have a business owner (what the KPI means and why it exists) and a technical owner (where the data comes from and how it's calculated). Add a short regulation: how often metrics are reviewed, who approves changes and what counts as a critical change (e.g., source or logic change).

A practice that often works: a small metrics committee (2–4 people from finance, business and data). They meet monthly to resolve accumulated requests and ensure new dashboards don't appear without KPI cards.

For a minimal setup you need three things: a KPI card template, a change log and acceptance rules (how we validate numbers before publishing). The key is that these materials are the same across departments.

If BI, the data warehouse and the number of sources grow faster than agreements are made, consider engaging a system integrator. For example, GSE.kz (gse.kz) as a producer and system integrator in Kazakhstan helps design BI and data warehouse infrastructure, build metric and data management processes (roles, regulations, quality control) and provide 24/7 support across the country.