About KPI Balanced Scorecard


KPI Balanced Scorecard is an Odoo app, which 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 by 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 that were used in the documentation.

KPI (KPI Formula, Key Performance Indicator) - the formula/instruction for Odoo that defines the way 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. These are the examples of KPI: Total Sales in Europe, 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 (2024, 2023), quarterly (Q1 2024, Q2 2024), monthly (Jan 2024, Feb 2024) approach is applied. KPI Targets are calculated for each specific period.

KPI Targetactual company goal based on specific KPI and KPI period. It allows setting a planned KPI value, so it will automatically calculate a real value based on Odoo data and the KPI formula for this KPI period. KPI targets are set regularly for each analytic period by responsible managers and might be shared among interested users to control results continuously. These are the examples of KPI Targets: Total Sales in Europe in 2024 (target: $1,000,000; actual: $800,000); Done Tasks per Day by John Brown in July 2024 (target: 1,5; actual: 2).

Basic measurement - the core configuration object used for retrieving actual KPI values from Odoo data. Although basic measurements are not used for formula constructions, they are required to prepare any sort of 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, which 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 unlimitedly use it for 'Sales Europe', 'Sales John Brown', 'Website Sales', etc. Measurements are used to prepare KPI formulas (available for drag and drop).

Constant - the special type of 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 - is a special object to structure KPI targets, used for convenient management and search.

KPI History – the special interface of a specific KPI target to control its KPI values by all periods, including a graph of similar periods.

Closing KPI period – the special action to stop KPI re-calculations and finalize the period results (can be compared with closing a fiscal year).

KPI User - any internal user, that has access either to see or edit one or several KPIs or KPI Categories.

KPI Manager - the assigned user or users, that have full rights for all KPIs disregarding 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...), or even particular employees.

The company's performance based on a particular formula is stated in the Single View Interface in the 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). 

KPI Target is put manually, by the responsible for that person. 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) - are measurements that aim to evaluate the organizational or personal success of a definite activity. 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 it is to write down a mathematical expression: just 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. 'Sell as much as you can' is not a goal, while 'Generate 100,000 Euro Revenue in the year 2024' is a good aim for a salesperson, for example. 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 those to the actual 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 measurement is the core object used for retrieving actual KPI values from Odoo data. Although Basic measurements are not used themselves for formula constructions, they are required to prepare any sort of Variables.

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, while a narrower 'Number of Quotations of the Sales Team Europe' is recommended to be a precision of that basic measurement - Variable. Each Basic measurement might have an unlimited number of 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. Chose 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 are fields, that will be taken into consideration 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 2 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 so, 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 certain 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 fields, 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 sort of 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 define 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 the calculation of the KPI types 'Average' and 'Sum'. It defines which figure you use for calculations. For example, 'total amount' of Sales Analysis Report or 'work hours of tasks'. It is a 'Column' in the database table related to the model above.

Depending on the model that you choose, the list of fields varies. For example, the model - 'Articles' has such measure fields as likes or dislikes number, referred to in emails; and the model - 'Sale Order' has such fields as 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, so, 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 its 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 2024'), order date for a sale order, revision date for an article, and reserved time for an appointment. 

For example, you create a Basic measurement 'Total Sales' for the model 'Sales Order'. In the field 'Date Fields' 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 2024'. The module will get the instructions, to consider only the sale orders, which were created during this particular period. Those sale orders, within the period, will be used for calculations of the actual value.

It is also possible to apply a few date fields, so matching to ALL of those date objects will be considered(e.g. 'Opportunities opened and won in January 2024').

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 sale orders disregarding the period will be used for calculations.


The fifth field 'Company Field' would be needed for a multi-company environment. This field gives instructions to the module, where to search for the related to a 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 choose the field, from 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, which relate to the chosen module and will be used for getting 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, which correspond to both move type and invoice status will be considered for further calculations. Click on the button '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 then you will be required to change dates every time you create a KPI Target for a new Period. If you don't add dates' 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 sort of 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 any more specified, 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 to use in different KPIs (see Measurements (Variables)). Here are some Basic Measurement Examples, that you can create:

Leads and Opportunities Count


The Purpose of the Basic Measurement is to count all Leads and Opportunities. This way you can find out the exact number of all Leads and Opportunities that your salespeople processed.

Confirmed/Done Sale Orders Total


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. In order to consider only 'done' orders, add 2 Filters: Status = Sales Order; Status = Sales Done. Make sure that records should match Any of those filters. This way you can find out how much did the company earned on sales. 

Posted Customer Invoices Count


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 way you will know how good the sales process goes.

Purchase Order Total


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.

Product Types


Count all the products types in stock. This way you can find out how many product types are available for sale.

Working Days to Close


The Basic Measurement to count for what number of days all tasks were completed. This way you can find out how much time your workers needed to finish their work.

Average Duration of an Appointment (for the module Universal Appointments)


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 find out what services require more time and therefore introduce interesting discounts to make other appointments last longer.