im_livechat.rating_percentage

Open Livechat's report on session ratings and you will see a Rating (%) measure showing values like 75 or 87.5. Under the hood, ratings are stored on a 1 to 5 scale. im_livechat.rating_percentage is the piece that converts one into the other, and it is a different animal from everything else in this widget encyclopedia.

The source file is seven lines. It registers a single function in registry.category("formatters"): take the value, subtract 1, clamp at zero, multiply by 100, divide by 4, round to one decimal. A rating of 1 (the minimum) becomes 0 percent, 3 becomes 50, 5 becomes 100.

Why does this show up in a widget list at all? Because pivot and graph views resolve the widget attribute on a measure against the formatters registry, not the field widgets registry. The same attribute name, a completely different lookup, which is why this "widget" works in reports but does nothing if you put it on a form field.

The practical lesson for your own reporting is the pattern, not this specific formatter.

Averaging a 1 to 5 scale produces numbers like 4.2 that mean little to anyone outside the support team. Percentages are instantly readable in a management dashboard, and this is Odoo's own way of doing that conversion at display time rather than storing a duplicate percentage field. The stored data stays clean, the report stays readable, and there is no risk of the two drifting apart.

If your team scores anything on a scale, NPS-style surveys, supplier evaluations, quality checks, the same seven-line pattern gives you percentage measures in every pivot and graph without touching the database schema. It is one of the cheapest reporting wins we implement.

How core uses it (pivot measure)

<field name="rating" string="Rating (%)" type="measure" widget="im_livechat.rating_percentage"/>

The same measure in a graph view

<field name="rating" string="Rating (%)" type="measure" widget="im_livechat.rating_percentage"/>

Roll your own formatter for any scale

// my_module/static/src/my_formatter.js
import { registry } from "@web/core/registry";

registry.category("formatters").add("my_module.score_percentage", (value) => {
    return Math.round((value / 10) * 100);
});

Then reference widget="my_module.score_percentage" on any pivot or graph measure. Prefix the name with your module to avoid registry collisions, exactly as core does here.

The formula rewards a closer look: (max(value - 1, 0) * 100) / 4.

The - 1 and / 4 mean the scale is anchored at 1, not 0. Odoo's rating widget stores 1 for the worst rating and 5 for the best, so the usable range is 4 points wide, and a customer who rates 1 contributes exactly 0 percent, not 20. The max(..., 0) clamp exists because aggregated measures can average records with no rating into values below 1, which would otherwise produce negative percentages in the report.

The rounding line, Math.round((percentage + Number.EPSILON) * 10) / 10, keeps one decimal and uses the epsilon nudge to avoid the classic floating point half-down surprise on values like 87.35.

Because the function receives already-aggregated values, the conversion happens after averaging, not per record. Averaging 1-to-5 ratings and then rescaling is mathematically identical to rescaling first, so the numbers are sound; it just means you cannot use this formatter to change the aggregation itself.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The notes below are read from the public development branch and are not final until release.

The formatter file is currently deleted on master, and we could not find the registration re-added anywhere else in the im_livechat module, while the channel report XML still references widget="im_livechat.rating_percentage" in three places. On the development branch as it stands, those measures would fall back to default number formatting. That is the kind of inconsistency that usually gets resolved before release, either by restoring the formatter or rewriting the report, so treat the 20.0 row in the version table as provisional. We re-verify this page against the shipped release.