About KPI Balanced Scorecard
KPI Balanced Scorecard is an Odoo app that allows users to set up KPI targets and control their fulfillment by periods. The app introduces a convenient KPI dashboard to manage companies and personal targets. It helps to organize work as a set of periodic goals and to control those goals in any business or functional area. For that purpose:
- The app introduces a clear system to get Odoo storable details: a count of records, a sum or an average of numeric fields, or even pure Python code.
- Actual values are re-calculated using the special Odoo cron job. So, it is always possible to understand which KPIs require more attention in real-time at first glance.
- You can share KPI targets with interested users to organize a transparent dashboard of goals, from global to particular ones.
- It is possible to consider only those KPIs that are of interest: for example, only sales-related or of a definite user. Hierarchy allows highlighting targets with indicative padding for an instant overview of sub-KPIs.
- Help hints are available for most objects to simplify KPIs setup (turn on/off help tabs through the app configuration page)
- The module supports the multi-company environment, and, therefore, all KPI calculations and settings are configured for each company separately.
Set KPI Targets by periods
Drag and drop interface for KPI formulas
Use any Odoo data to calculate KPIs
Auto and regularly updated KPIs
Concepts and terms
Here, you can find all the terms used in the documentation.
KPI (KPI Formula, Key Performance Indicator) – the formula/instruction for Odoo that defines how to calculate figures based on existing Odoo data and settings. This central configuration object introduces the tool to construct mathematical expressions in a user-friendly manner through drag and drop. Examples of KPIs are 'Total Sales in Europe' and 'Done Tasks per Day of John Brown'.
A KPI Period – a time frame for which companies set their targets to control performance (in a similar way as financial performance is controlled within accounting/fiscal periods). You can set periods of any length and for any date, usually some yearly (2025, 2024), quarterly (Q1 2025, Q2 2025), or monthly (Jan 2025, Feb 2025) approach is applied. KPI Targets are calculated for each specific period.
KPI Target – actual company goal based on specific KPI and KPI period. It allows setting a planned KPI value to automatically calculate a real value based on Odoo data and the KPI formula for this KPI period. Responsible managers set KPI targets regularly for each analytic period and might share them among interested users to continuously control results. These are the examples of KPI Targets: Total Sales in Europe in 2025 (target: $1,000,000; actual: $800,000); Done Tasks per Day by John Brown in July 2025 (target: 1,5; actual: 2).
Basic measurement – the core configuration object for retrieving actual KPI values from Odoo data. Although basic measurements are not used for formula constructions, they are required to prepare any formula variables. These are the examples of basic measurements: Aggregated Sum by Done Sales Orders (the period is defined according to a sale order date); The Total Number of Tasks in the State ‘Done’ (the period is defined according to the last stage update date).
Python code measurement – a specific type of basic measurement, that requires technical knowledge and allows the creation of instructions for the module on how to get the data from Odoo.
Measurements (Variables) – a specification of a basic measurement. The key idea of distinguishing KPI Variables from Basic measurements is to simplify data preparation. You define 'Total Sales' once and then use it unlimitedly for 'Sales Europe', 'Sales John Brown', 'Website Sales', etc. Measurements are used to prepare KPI formulas (available for drag and drop).
Constant – the specific KPI Variables used when data can not be retrieved from modules, and/or when figures remain the same during the whole period. For example, 'Total Investments' or 'Number of Employees' are often frozen for a specific period. Constants are used to prepare KPI formulas (available for drag and drop).
KPI Scorecard – the special interface to configure and control targets, which are shown according to a chosen period. The interface allows you to choose, close, and re-open periods; set, substitute, and filter KPI Targets (see KPI History).
A KPI Category – KPIs storage, which is used for convenient navigation over KPIs and managing access rights to them. To control KPIs related to specific areas, combine them into corresponding categories. For example, 'Sales KPIs' and 'Team Europe KPIs'.
A KPI Tag – a special object to structure KPI targets for convenient management and search.
KPI History – the special interface of a specific KPI target to control its KPI values for all periods, including a graph of similar periods.
Closing KPI period – the special action to stop KPI re-calculations and finalize the period results (it can be compared with closing a fiscal year).
KPI User – any internal user who can see or edit one or several KPIs or KPI Categories.
KPI Manager – the assigned user or users with full rights for all KPIs, regardless of the settings.
The difference between KPI and KPI Target
Two important concepts are used in the module: KPI and KPI Target. They have significant differences.
KPI, or Key Performance Indicator, is a formula that represents a measurable value that demonstrates how effectively a company is achieving key business objectives. It is used to evaluate the success of reaching a company's goals. It may focus on the overall performance of the business, of some smaller departments (sales, appointments, HR, etc.), or even particular employees.
The company's performance based on a particular formula is stated in the Single View Interface column 'Actual Value' (see Single View Interface).
A KPI Target is a goal, a particular number/amount. It has guidelines and requires a formula to be calculated. Therefore, we can imagine it as Formula (KPI) + Period.
In the Single View Interface, KPI Targets are stated in the column 'Target Value'(see Single View Interface).
A KPI Target is set manually by the person responsible. To be valid, the goal should be SMART. The letter in the abbreviation SMART stands for:
1) Specific (related to a particular Odoo model)
2) Measurable (see Measurements)
3) Achievable (possible to fulfill)
4) Relevant (acute for the company development)
5) Time-specific (see Periods).
KPIs (key performance indicators) - measurements that evaluate a specific activity's organizational or personal success. Different companies have different KPIs depending on their strategy and business area. However, all KPIs have a common core attribute: they must be measurable within a target period. To that end, KPIs allow the construction of formulas to retrieve Odoo data sets and process those into real figures. Formula preparation is as simple as writing down a mathematical expression: drag and drop formula parts in the right order with correct operators. KPIs, KPI periods, and KPI targets. KPIs represent the list of success figures you may use to plan your company activities. Simultaneously, measurements are almost senseless unless you have target values for those KPIs. That is possible only within a time-constrained period. For example, 'Sell as much as you can' is not a goal, while 'Generate 100,000 Euro Revenue in the year 2025' is a good aim for a salesperson. To that end, KPI periods are introduced.
A combination of a KPI and a KPI period results in a KPI target. Exactly with those targets, you work on the scorecard interface. For each KPI you would like to manage in this period, you should define a planned value to compare to the actual value at the end of the period.
So, a KPI itself defines how to compute the actual value for a period and how to estimate the result ('the more, the better' or 'the less, the better'), but does not assume setting targets. The latter should be done for each period.
Basic Measurements
Basic measurements are the core object for retrieving actual KPI values from Odoo data. Although Basic measurements are not used for formula constructions, they are required to prepare any Variable.
A Basic measurement represents the most general instructions for the module to find the data, while Variables specify those. For example, 'Total Number of Sale Orders' should be a Basic measurement. In contrast, a narrower 'Number of Quotations of the Sales Team Europe' is recommended as a precision of that basic measurement - Variable. Each Basic measurement might have unlimited linked Measurements (Variables).
By default, the KPI module contains some Basic measurements, which you can use to create Variables.
To create a Basic measurement:
1. Go to Measurements > Basic Measurement
2. Click 'New'
3. Type a name and optionally add a model type before it (for example, [purchase]) to find the measurement quickly
4. Choose a KPI Type to activate a set of further fields and define the way the module will get the information for calculations (for example, the records can be counted, or the value of particular record fields will be counted)
5. Choose a Model, an Odoo object from which the data will be taken (for example, Sale Orders, Purchases, Quotations)
6. Based on the KPI Type, you will see a set of other fields
7. Add a 'Measure field' for the analysis (the fields from which the module will take the data to count, to calculate the sum of records or count the average value of the fields (Only for types: 'Sum of records field', 'Average of records field')
8. Add one or several date fields (those will be considered in the calculations when the period is stated, for example, order date or delivery date). If you choose several fields, then for the record to be considered for calculations, both of those fields should be within the period
9. Add a company field for the analysis if you work in a multi-company environment (for example, if you have two or more companies, you may want to calculate KPI for each of them, so for the app to be able to distinguish companies, the field should be added as you create a Basic measurement)
10. It is possible to add some filters, but it is recommended to add only basic ones and then specify them while creating a Measurement (Variable) (thus, your Basic measurement will be more general, and you will have more possibilities for creating a Variable. For example, you created a Basic measurement 'Sales Total', which you can use to create Variables: Sales Total Team America, Sales Total Team Europe, Sales Total John White...).
The first field, 'KPI Type', defines how Odoo data should be calculated:
1) Choose the KPI Type 'Count of records' if you want to count all matching records, for example, the number of registered leads or the number of posted customer invoices
2) Choose the KPI Type 'Sum of records field' if you want to sum up a particular number field of records, for example, the sum of the total amount of all orders, or the sum of paid taxes by invoices
3) Choose the KPI Type 'Average of records field' to get the average of record's number of records, for example, average planned hours per task or average days to assign a lead
4) Choose the KPI Type 'Executing Python code' to compute any figures based on any Odoo data. This type requires technical knowledge (see Executing Python code)
The second field, 'Model', defines an object from which the information is taken. It assumes that you determine how records should be searched and which record fields should be used for computations. For example, 'Sales Order', 'Task', 'Lead/Opportunity'. You can also rely on standard or custom objects (including those created in the Odoo studio)
The third field, 'Measure field', is required only for calculating the KPI types 'Average' and 'Sum'. It defines which figure you use for calculations, such as the 'total amount' of the Sales Analysis Report or the 'work hours of tasks'. It is a 'Column' in the database table related to the model above.
The list of fields varies depending on the model you choose. For example, the model 'Articles' has measure fields such as the number of likes or dislikes referred to in emails, and the model 'Sale Order' has total, delivery orders, and invoice count.
The fourth field, 'Date fields', is required to understand whether a specific document type relates to a considered period and how to distribute objects by time intervals. It assumes that you define how records should be searched and which record fields should be used for computations.
Each model has a list of available date fields. The object's fields, which contain information about time, can be chosen. For example, for tasks, you might use the create date to analyze jobs registered within this KPI period (e.g., 'Total number of tasks created in January 2025'), the order date for a sale order, the revision date for an article, and the reserved time for an appointment.
For example, you create a Basic measurement 'Total Sales' for the model 'Sales Order'. In the 'Date Fields' field, you choose 'order date'. Then, after creating the corresponding Variable and KPI Formula, you set a KPI Target to receive 100000$ for the Period 'The Year 2025'. The module will get the instructions to consider only the sale orders created during thicreated during this period. Those sale orders within the period will be used to calculate the actual value.
It is also possible to apply a few date fields, so matching ALL those date objects will be considered(e.g., 'Opportunities opened and won in January 2025').
If date fields are not specified, the calculation will consider all records for all times, regardless of the period. For example, you created the Basic measurement 'Total Sales' and left the date field empty. After setting the KPI Target, the module won't get any instructions on how to filter objects by dates or where to get the information about the date. That means the KPI Period would not influence this Basic measurement. Therefore, all existing sales orders, regardless of the period, will be used for calculations.
The fifth field, 'Company Field,' would be needed for a multi-company environment. This field instructs the module where to search for the related company model.
Even after choosing this field on the Basic measurement level, you can create a global Variable that will count the result, disregarding the company. For that, leave the field 'Company' empty.
For example, you create a Variable 'Total Sales Chicago' based on the Basic measurement 'Total Sales' and in the field 'Company' choose the Company Chicago. If you didn't select the field on which the module will decide to which company an object relates (while creating the Basic measurement), then as you set the KPI Target, you still will see the global result - the total sales of all teams.
The section 'Filters' shows you records related to the chosen module, which will be used to get the value for calculations. 'Filters' also allow you to restrict records set by any stored field. For example, you may calculate the count of only won opportunities based on stage settings or only posted customer invoices based on journal entry type and state.
Let's add some filters to create a Basic measurement 'Posted Customer Invoice'. In this case, we need to filter records by type and status. The first filter is 'Move Type = Customer Invoice', and the second one is 'Invoice Status = Open'. Above the filtering options, we can choose whether the records should match ALL or ANY of our filters. As we chose ALL, only records that correspond to both move type and invoice status will be considered for further calculations. Click on 'N records' to see all the matching invoices.
It is recommended to use 'Filters' for low-level filtering in Basic measurements and then specify them in KPI Variables. This way, you avoid double work and create more Variables based on one Basic measurement.
Also, avoid adding dates to the filtering options, as you will be required to change dates every time you create a KPI Target for a new Period. If you don't add date restrictions as a filter, you will be able to simply 'Substitute Targets', and records will be analyzed based on the fields chosen in the fourth field, 'Date Fields' (for example, 'Create Date') (see KPI Scorecard).
Executing Python code
'Python code' is a special type of basic measurement This type requires technical knowledge but lets you compute any figures based on any Odoo data without restrictions. Such measurement might be any Python basic script with the possibility of SQL queries (through using 'env.cr') In calculations, you may rely upon the special variables: 'period_start' (the first date of the period), 'period_end' (the last date of the period), 'period_company_id' - res.company object for which Odoo makes calculations at the moment (according to a KPI period under consideration) Correct Python code assumes saving the value into the special variable 'result'.
Basic measurements of the type 'Execute Python code' can't be specified anymore since they do not relate to any records. However, such measurements should have a single KPI variable linked.
Basic Measurements Examples
Based on one Basic Measurement, you can create multiple Variables for different KPIs (see Measurements (Variables)). Here are some Basic Measurement Examples that you can create:
The Purpose of the Basic Measurement is to count all Leads and Opportunities. This way, you can find the exact number of Leads and Opportunities your salespeople processed.
The Basic Measurement that sums the total value of All done Sale Orders. Choose the 'Measure field' - 'Total', so the module will sum the value from it. To consider only 'done' orders, add 2 Filters: Status = Sales Order; Status = Sales Done. Make sure that records match Any of those filters. This way, you can determine how much the company earned on sales.
The Purpose of the Basic Measurement is to count all posted customer invoices. In the field Filters, choose Type = Customer Invoice and Status = Posted. This will tell you how well the sales process goes.
The Basic Measurement that sums the total value of All Purchases. Choose the 'Measure field' - 'Total', so the module will sum the value from it. This way you will know how much money was spent on the vendors products for a particular period of time.
Count all the product quants in stock. This way, you can find out how many products are available for sale.
The Basic Measurement can count the number of days for which all tasks were completed. This way, you can find out how much time your workers need to finish their work.
When the time of the appointment isn't set and can vary, create this Basic Measurement to track the Average time of an appointment. For example, what is the average time, that users book to rent a car. This way you can determine what services require more time and therefore introduce interesting discounts to make other appointments last longer.
Use the Basic Measurement 'The Total Number of Likes' to assess the quality of the articles in general. To consider only popular articles, add a Filter Views > 10. This way, you can see the users activity on the article's page and whether the articles are successful.
Constants
KPI Constants are a special type of KPI Variable used when data can not be retrieved from modules and/or when figures remain the same throughout the period. For example, 'Total Investments' or 'Number of Employees' are often frozen for a specific period.
In comparison to measurements, KPI Constants are fixed and do not depend on actual Odoo data. This allows the introduction of figures that can not be retrieved from modules and/or which should remain the same throughout the whole period. For example, you might set the 'Total Size of Investments' to calculate return on investments or the 'Number of Salesmen' to get sales revenue per person.
To create a Constant:
1. Go to Measurements > Constants
2. Click 'New'
3. Type the constant's title
4. Put the global value (the number, which will be used for all periods except for the specified ones)
KPI Constant value might be defined for each period.
Besides, for each period, the app automatically calculates a parent period. If one period is fully inside another, the latter is considered a parent for the former. For example, Y2025 (01/01/2025 - 12/31/2025) is a parent of Q3 (07/01/2025 - 09/30/2025); Q3 is a parent of July (07/01/2025 - 09/30/2025); but for 06/30/2025 - 07/31/2025, the parent would be Y2025, since this period is not fully inside Q3.
The global value would be applied if there is none for this period or for its parent.
To define a value for a particular time frame:
1. Start creating or editing a Constant
2. Find the tab 'By periods' and click 'Add a line'
3. Choose an existing period and type the value for this period that will be used for calculations instead of the global value
As an example, let's create a constant 'Number of Employees'.
The Global Value - the general number of employees - is 20. This value will be used for all calculations containing the constant 'Number of employees'.
For example, let's create a constant 'Number of Employees'.
However, during the year, we experienced some changes. In the first quarter of 2025, the company had 18 employees. During the second quarter, one more employee was hired, so we had 19 employees. So, let's add the values for these periods. Now, 18 is used for calculations for the first quarter of 2025 and 19 for the second.
As we don't state the number of employees for the third quarter, the value for its parent - Y2025-'21' will be used for calculations.
Quarter 1 of 2025 doesn't have a value and doesn't have a parent value, so the global value - '20' - would be applied.
Measurements (Variables)
Measurement (Variable) - is a specification of a basic measurement. The key idea is to simplify data preparation. You define 'Total Sales' once and then use it unlimitedly for 'Sales Europe', 'Sales John Brown', 'Website Sales', etc.
Specify Basic measurements through the Odoo built-in domain constructor, which lets you filter by any storable attributes. Create a variable to add more filters to Basic measurements.
For example, create a Basic measurement 'Sales Count' for the Model 'Sale Order', which counts the number of sale orders. The Basic measurement uses the KPI Type 'Count of records'. Apply filters 'Status = 'sale'; Status = 'done'' to the Basic measurement. Based on the Basic measurements, you can create other Variables: Sales Count America and Sales Count Europe using the filter 'Sales Team > Sales Team contains 'Europe'/ 'America'. You can also create a variable to count sales of a particular salesperson by the filter 'Salesperson ID = 2'.
Another example is based on the Basic measurement 'Opportunities: Average Expected Revenue' for the Model 'Lead/Opportunity', which calculates the average revenue and uses KPI Type 'Average of records field'. Based on this measurement, you can create a Variable to count the average expected revenue only on the 'Won' stage. For that purpose, use the Filter 'Is Won = Won'. You can also create a Variable to see the expected revenue of a particular salesperson with opportunities only on the Won stage. You can use the same filter, 'Is Won = Won', and add one more filter, 'Salesperson ID = 2'.
Based on one Basic measurement, you may create as many Variables as you need. You can also create a Variable by linking it to a Basic measurement (Basic measurements are not used to create a formula by themselves). For example, create a Basic Measurement 'Total Sales' and link it to a Variable 'Total Sales'.
An exception is Basic measurements of the type 'Execute Python Code'. As they work on the code level, they cannot be specified anymore. So, there can be only one linked Variable (see Execute Python Code).
There are two default Variables that you can use to create formulas within the time frame. You can find them in the formula wizard (see KPI Scorecard). Those are:
1. 'Period Days' (the number of days in the period). KPIs with this Variable calculate the result based on the number of days in the current period. For example, Q3 (07/01/2025-09/30/2025) Period Days would be 92 days.
2. 'Days Passed' (the number of passed days in the period). KPIs with this Variable calculate the result based on the number of days passed in the current period. For example, Q3 2025 on the 15th of July would be 15 days, on the 1st of September - 62 days, and on the 30th of September - 92 days.
For example, you can see the Total Sales per Day. Both Variables apply to this KPI, but in the first case, you will see the accurate result only on the last day of the period, as it will compare the actual value with the total number of days in the period, even if the period is a month. And, at the moment, only a few days have passed. The Variable 'Days Passed', on the contrary, will always show a more accurate result as it will compare the actual value with the number of currently passed days. And each day, the number of days will change (+1).
Let's create a KPI 'Total Sales' with the Variable 'Period Days' to determine how much you earn per day. Set the KPI Target for the third quarter of 2025. The period is 92 days long so that the Total Sales will be compared with the number of days in the period. The results will not be accurate at the beginning of the period, as a few days or weeks have passed, and the period is not yet over.
Now, let's create the same KPI with the Variable 'Days Passed'. Here, the Total Sales will be compared with the days already passed. This number is dynamic and changes as time goes by. So, we set a KPI Target for the 3rd quarter of 2025. Today is the 15th of August; therefore, only 46 days have passed. Today, the total sales will be compared to 46 days. Tomorrow, with 47 days. So, the result is much more accurate than when we use the Variable 'Period Days'(which is accurate only on the last day of the period).
Variables are used to create a KPI. The KPI may relate to a particular company. As you create a Variable, choose the company it relates to, so only the objects related to the company will be considered for calculations. Therefore, you can calculate, for example, the 'Total Sales' of each of your companies separately. For instance, create a Variable 'Sale Team America > company USA' and 'Sales Team Europe > company Belgium' and assign each to the corresponding company. If you don't specify the company, then KPI Variables would be available for all users of all companies. Otherwise, users would only be able to see those related to company objects under a certain company.
To create a Variable:
1. Go to Measurements > Measurements (Variables)
2. Click 'New'
3. Type the name of the Variable
4. In the field 'Measurement', choose a Basic measurement
5. Choose a company or leave the field empty to make this Variable global
6. Optionally add some filters.
From a Basic measurement form view, you can access all linked variables:
1. Go to Measurements > Basic measurements
2. Open any Basic measurement
3. In the top right corner of the Basic measurement, you will see the number of Variables based on it
4. Click on the button to see the list of Variables
5. Click on any Variable to see its card.
Variables Examples
Here, you can find some possible Variables that specify useful Basic Measurements (see Basic Measurements Examples).
1. Basic Measurement - Leads and Opportunities Count
You can separate Leads from Opportunities to see the results for each separately. To do so, add the extra filter Type = Lead or Type = Opportunity.
See only Leads and Opportunities with high probability. You can manually set how high it should be. Add the extra filter Probability >= 70, where 70 is the percentage number.
See only won Opportunities to compare their number by periods and track work effectiveness. Add the extra filter Is Won = Won.
2. Basic Measurement - Confirmed/Done Sale Orders Total
Even if there is no need to specify the Basic measurement, match it to a Variable so it is visible in the formula wizard. Basic measurements are not used to create a formula (see Basic Measurements). Create a Variable 'Total Sales' to see the amount of money earned on sales.
Specify the Basic measurement to see the total that a particular team earned. For that, add the extra filter with the name of the team Sales Team > Sales Team contains 'Europe'. If you have several teams and want to see the Total result by team, you need to create a Variable for each team separately.
You can also see the result per each salesperson to stimulate employees to sell more and get some benefits. Add the extra filter with the person's ID Salesperson > ID = 9 for that.
3. Basic Measurement - Customer Invoices Count
Specify the invoices by their status. Add the extra filter Status = Posted to count all the posted invoices.
Track the number of cancelled invoices to take timely measures and determine the problem if too many were cancelled. Add the extra filter Status = Cancelled.
Find out how many invoices with the high Total amount were created. For that, add the extra filter Total > 100.
4. Basic Measurement - Purchase Order Total
Even if there is no need to specify the Basic measurement, match it to a Variable so it is visible in the formula wizard. Basic measurements are not used to create a formula (see Basic Measurements). Create a Variable 'Purchase Order Total' to see the amount of money spent on products.
If you have vendors from various countries and pay them in different currencies, you can add, for example, the extra filter 'Currency contains US'. This way, only purchases in US dollars will be considered.
Simultaneously, it is also possible to convert all currencies to the default company one to see the result. In this case, to calculate the purchase total regardless of the currency, you can set another Basic measurement and Variable.
To that end, edit the Basic measurement or create a new one and change the Model to 'Purchase Report'. This kind of Model and similar ones (like Sale Report, etc.) are insensitive to currency. So, the total will already be summed in the default company currency.
For example, create a Basic measurement 'Purchase orders total in default currency' and choose the Model 'Purchase Report'. Add an extra filter by country or vendor (e.g., Country contains America), and after the calculations, the result will be shown in the default currency.
Specify the Basic measurement to calculate the money spent on the products of a particular vendor. Add the extra filter Vendor = 'Azure Interior'.
5. Basic Measurement - Working Days to Close
Connect the Basic measurement to a Variable with the same name to see the number of days the company spent finishing all the projects.
Create a Variable to see the number of days that Anita Oliver needed to finish the projects assigned to her. For that, use the extra filter with the worker ID 'Assigned To > ID = 9'.
Create a Variable to see the number of days the company spent finishing the particular project. For that, use the extra filter with the Project's title 'Project > Name = 'Software Continuous Development'.
6. Basic Measurement - Products in Stock
Specify the Basic measurement to count stocks of the products that have incoming inventories to a particular warehouse in a specified period. For that, add the extra filter with the location title Location contains WH/Stock.