Gamification (Goals, Badges & Challenges)¶
Last Updated: March 2026 Target Audience: Managers, HR, System Administrators
Overview¶
The Gamification module is a native Odoo feature that drives employee engagement through goals, badges, challenges, and karma tracking. Managers define measurable goals (manually updated or auto-computed from any Odoo model), bundle them into challenges with reward badges, and track progress on leaderboards. Employees earn badges -- either granted by peers or awarded automatically when challenge goals are met. The karma system assigns numerical reputation points and ranks to users based on their contributions. At Scott Recycling, this module can be used to incentivize performance metrics across operations, sales, and HR.
Navigation¶
The gamification tools live under the Settings menu. You must have Developer Mode (Debug Mode) enabled to see them, because the menu is restricted to the technical features group.
Settings
└── Gamification Tools
├── Challenges
├── Goals
├── Goal Definitions
├── Badges
├── Karma Ranks
└── Karma Tracking
Enabling Developer Mode
Go to Settings > General Settings, scroll to the bottom of the page, and click Activate the Developer Mode. The Gamification Tools menu will then appear under Settings.
Goal Definitions¶
A Goal Definition is the blueprint that describes what gets measured and how the system calculates it. You create definitions first, then reference them inside challenges.
Goal Definition Fields¶
| Field | What It Means | Example |
|---|---|---|
| Goal Definition (name) | A descriptive label for this metric | "Monthly Invoices Created" |
| Goal Description | Longer explanation shown to participants | "Number of customer invoices validated this month" |
| Computation Mode | How the current value is calculated -- see table below | Count |
| Model | The Odoo model to query (for Count and Sum modes) | account.move |
| Field to Sum | The numeric field to aggregate (Sum mode only) | amount_total |
| Date Field | Field used to filter records into the goal's time period | invoice_date |
| Filter Domain | Odoo domain expression that filters which records count; supports user variable |
[('user_id','=',user.id),('state','=','posted')] |
| Python Code | Custom code executed per user (Python mode only); store result in result variable |
result = len(googled_records) |
| Goal Performance | Whether a higher or lower value means success | Higher is better |
| Displayed as | Show a progress bar or a simple yes/no boolean | Progress |
| Suffix | Unit label appended to the current value | "invoices" |
| Monetary Value | If checked, displays values in company currency | Unchecked |
| Batch Mode | Evaluate the domain once for all users instead of per-user (performance optimization) | Checked |
| Batch Distinctive Field | The field on the model that identifies which user a record belongs to | user_id |
| Batch User Expression | Expression mapping model field to user; uses user variable |
user.id |
| Action | A window action that opens when users click the goal to view underlying records | Invoice List action |
| ID Field of user | Field on res.users containing the res_id for the linked action | partner_id |
Computation Modes¶
| Mode | Description | When to Use |
|---|---|---|
| Manually | User or manager updates the current value by hand | Goals that cannot be tracked automatically (e.g., "attend 3 trainings") |
| Count | Counts records matching the model + domain | "Number of invoices created" |
| Sum | Sums a numeric field on records matching the model + domain | "Total revenue invoiced" |
| Python | Runs arbitrary Python code; store the result in a variable called result |
Complex calculations spanning multiple models |
Python Code mode requires developer knowledge
The Python computation mode executes server-side code. Only administrators with Python experience should create or modify these definitions. Incorrect code can cause errors on the scheduled cron job that updates goals.
Goals¶
A Goal is a specific instance of a Goal Definition assigned to a user, with a target value and time window. Goals are usually generated automatically by challenges, but can also be created manually.
Goal Fields¶
| Field | What It Means | Example |
|---|---|---|
| Goal Definition | Which metric this goal tracks (links to a definition) | "Monthly Invoices Created" |
| User | The employee working toward this goal | Jane Smith |
| Challenge Line | The challenge line that generated this goal (auto-filled) | -- |
| Challenge | The parent challenge (computed from the challenge line) | "Q1 Sales Push" |
| Start Date | When tracking begins (defaults to today) | 2026-03-01 |
| End Date | When tracking ends; blank means the goal is always active | 2026-03-31 |
| To Reach (target) | The numeric target the user needs to hit | 50 |
| Current Value | The latest computed or manually entered progress value | 32 |
| Completeness | Percentage toward the target (computed automatically) | 64% |
| State | Current lifecycle stage: Draft, In Progress, Reached, Failed, or Canceled | In Progress |
| Remind delay | Days after which the system reminds the user to update a manual goal | 7 |
| Last Update | Date the goal value was last refreshed | 2026-03-10 |
Goal States¶
| State | Meaning |
|---|---|
| Draft | Goal created but not yet started |
| In Progress | Actively being tracked; values are recomputed on schedule |
| Reached | The user met or exceeded the target value |
| Failed | The end date passed without the target being met |
| Canceled | Goal was manually canceled |
Goals are usually auto-managed
In most cases you do not need to create or edit goals directly. Challenges generate goals automatically for each participant. You interact with goals mainly to check progress or manually update values for "Manually" computed goals.
Challenges¶
A Challenge is the main orchestration object. It bundles one or more goal definitions together, assigns them to a group of users, sets the schedule, and defines the rewards. Think of a challenge as a "contest" or "campaign."
Challenge Fields -- General¶
| Field | What It Means | Example |
|---|---|---|
| Challenge Name | Descriptive title | "March Sales Sprint" |
| Description | Details about the challenge shown to participants | "Close as many deals as possible this month" |
| State | Draft, In Progress, or Done | In Progress |
| Responsible | The manager who owns this challenge | Dan Scott |
| Periodicity | How often the challenge resets and creates new goals | Monthly |
| Start Date | When the challenge (or its first period) begins | 2026-03-01 |
| End Date | When the challenge (or its last period) ends | 2026-03-31 |
| Display Mode | Individual Goals (private) or Leader Board (group ranking) | Leader Board |
| User Domain | Odoo domain filter that auto-selects participants from res.users | [('department_id.name','=','Sales')] |
| Participants | The resolved list of users currently enrolled | 8 users |
Challenge Fields -- Goals Tab¶
The Goals tab contains Challenge Lines -- each line links a Goal Definition to a target value.
| Field | What It Means | Example |
|---|---|---|
| Sequence | Display and processing order | 1 |
| Goal Definition | The metric being tracked | "Monthly Invoices Created" |
| Condition | Higher is better or Lower is better (inherited from definition) | Higher is better |
| Target Value to Reach | The numeric target for this goal within the challenge | 50 |
| Unit | The suffix from the definition | "invoices" |
Challenge Fields -- Reward Tab¶
| Field | What It Means | Example |
|---|---|---|
| For Every Succeeding User | Badge awarded to every participant who completes all goals | "Sales Achiever" badge |
| For 1st User | Badge awarded to the top performer (Leader Board mode) | "Gold Sales Star" badge |
| For 2nd User | Badge for second place | "Silver Sales Star" badge |
| For 3rd User | Badge for third place | "Bronze Sales Star" badge |
| Reward Bests if not Succeeded? | Award top-3 badges even if nobody met all targets | Unchecked |
| Reward as soon as every goal is reached | Grant the success badge immediately upon completion rather than waiting for the period to end | Checked |
Reward as soon as every goal is reached
When this option is enabled, a user receives the "For Every Succeeding User" badge the moment all their goals are reached -- they do not have to wait until the end date. However, the top-3 placement badges are always awarded at the end of the challenge period. With this option, a user can only receive the same badge once per challenge.
Challenge Fields -- Advanced Options Tab¶
| Field | What It Means | Example |
|---|---|---|
| Suggest to Users | Users who will be invited to join the challenge | -- |
| Report Frequency | How often progress reports are sent to participants | Weekly |
| Report Template | The email template used for progress notifications | Default gamification template |
| Send a copy to | A Discuss channel that receives a copy of every report | #sales-team |
| Non-updated manual goals will be reminded after | Number of days before nagging users who have not updated manual goals | 3 days |
| Appears in | Menu category: HR / Engagement or Settings / Gamification Tools | HR / Engagement |
Periodicity Options¶
| Period | Behavior |
|---|---|
| Non recurring | One-shot challenge. Goals are created once with the start/end dates. |
| Daily | New goals are generated every day. |
| Weekly | New goals are generated every week. |
| Monthly | New goals are generated every month. |
| Yearly | New goals are generated every year. |
Display Modes¶
| Mode | What Participants See |
|---|---|
| Individual Goals | Each user sees only their own goals and progress. Private. |
| Leader Board | All participants see a ranked list of everyone's progress. Competitive. |
Creating a Challenge -- Step by Step¶
- Navigate to Settings > Gamification Tools > Challenges
- Click New
- Enter a Challenge Name (e.g., "April Recycling Volume Contest")
- Set the Periodicity (e.g., Monthly)
- Set the Start Date and End Date
- Choose the Display Mode -- Individual Goals for private tracking, Leader Board for competition
- Optionally set a User Domain to auto-enroll participants, or manually add users to the Participants field
- Go to the Goals tab and click Add a line
- Select a Goal Definition (create one first if needed -- see below)
- Set the Target Value to Reach
- Repeat steps 8-10 for each metric you want to track
- Go to the Reward tab and assign badges for success and/or top placement
- Go to the Advanced Options tab and configure reporting frequency
- Click Start Challenge in the header
Create Goal Definitions before Challenges
You must have at least one Goal Definition created before you can build a challenge. The Goals tab requires you to link each challenge line to an existing definition.
Creating a Goal Definition -- Step by Step¶
- Navigate to Settings > Gamification Tools > Goal Definitions
- Click New
- Enter the Goal Definition name (e.g., "Monthly Pickups Completed")
- Choose the Computation Mode:
- Manually: No auto-computation; users update the value themselves
- Count: Select the Model, Date Field, and Filter Domain
- Sum: Select the Model, Field to Sum, Date Field, and Filter Domain
- Python: Write code in the Python Code field; store the result in
result
- Set Goal Performance to "Higher is better" or "Lower is better"
- Set Displayed as to Progress (bar) or Boolean (yes/no)
- Optionally add a Suffix (e.g., "pickups", "dollars")
- Check Monetary Value if the metric is currency-based
- Save
Testing your domain filter
Before saving, test your Filter Domain in the Odoo developer console or by creating a test goal. A bad domain will cause the cron job to fail silently for that definition. Use the user variable to reference the current participant -- for example, [('user_id', '=', user.id)].
Badges¶
Badges are visual rewards that appear on a user's profile. They can be granted manually by peers or automatically as challenge rewards.
Badge Fields¶
| Field | What It Means | Example |
|---|---|---|
| Badge (name) | Display name of the badge | "Safety Champion" |
| Active | Whether the badge is available for granting | Checked |
| Image | Visual icon shown on profiles and in notifications | Uploaded PNG |
| Description | HTML description of what this badge represents | "Awarded for zero safety incidents in a quarter" |
| Forum Badge Level | Bronze, Silver, or Gold -- used for sorting and display styling | Gold |
| Allowance to Grant | Who is allowed to manually grant this badge | Everyone / Selected Users / Users with Badges / Nobody |
| Authorized Users | Specific users who can grant (when Allowance = "Selected Users") | HR Manager |
| Required Badges | Only users who hold these badges may grant (when Allowance = "Users with Badges") | "Team Lead" badge |
| Monthly Limited Sending | Enable a per-person monthly cap on granting | Checked |
| Limitation Number | Maximum times one person can grant this badge per month | 3 |
| Reward of Challenges | Challenges that award this badge | "Q1 Sales Push" |
Badge Statistics¶
| Stat | What It Shows |
|---|---|
| Total | Total number of times this badge has been granted |
| Number of Users | Unique users who hold this badge |
| Monthly Total | Times granted this month |
| My Total | How many times the current user has received this badge |
| My Monthly Total | Times the current user received it this month |
| My Monthly Sending Total | Times the current user has granted it this month |
| Remaining Sending Allowed | How many more times the current user can grant it this month (if limited) |
Granting Rules¶
| Rule | Who Can Grant |
|---|---|
| Everyone | Any internal user can grant this badge to anyone |
| A selected list of users | Only the users listed in Authorized Users |
| People having some badges | Only users who hold all badges listed in Required Badges |
| No one | Cannot be manually granted -- only awarded via challenges |
Granting a Badge Manually -- Step by Step¶
- Navigate to Settings > Gamification Tools > Badges
- Open the badge you want to grant (or use the Grant this Badge button from the kanban view)
- Click Grant this Badge in the header
- Select the User who should receive the badge
- Add an optional Comment explaining why they earned it
- Click Grant
Monthly sending limits
If a badge has Monthly Limited Sending enabled, you can only grant it up to the Limitation Number of times per month. The remaining allowance is shown on the badge form. Once you hit the cap, the Grant button disappears until the next month.
Badge User Records¶
Every time a badge is granted, the system creates a Badge User record that tracks the details.
| Field | What It Means | Example |
|---|---|---|
| User | The person who received the badge | Jane Smith |
| Sender | The person who granted it (blank if auto-awarded) | Dan Scott |
| Badge | Which badge was granted | "Safety Champion" |
| Challenge | The challenge that triggered the award (if automatic) | "Q1 Safety Goals" |
| Comment | The reason provided when granting | "Zero incidents all quarter" |
| Badge Level | Bronze, Silver, or Gold (inherited from the badge) | Gold |
| Date | When the badge was granted (create_date) | 2026-03-15 |
Karma System¶
Karma is a numerical reputation score assigned to users. It increases or decreases based on tracked activities, and users are assigned ranks based on their karma level. The karma system is primarily designed for community/forum features but can be repurposed for internal engagement tracking.
Karma Ranks¶
Karma Ranks define the tiers that users progress through as they accumulate karma points.
| Field | What It Means | Example |
|---|---|---|
| Rank Name | Display name of the rank | "Recycling Rookie" |
| Description | HTML description shown on the rank | "Just getting started" |
| Motivational | Encouraging message shown on the user's profile to reach this rank | "Keep going -- 50 more points to Silver!" |
| Required Karma | Minimum karma points needed to hold this rank (must be > 0) | 100 |
| Image | Visual icon for the rank | Uploaded PNG |
| # Users | Number of users currently at this rank (computed) | 12 |
Karma Tracking¶
Every karma change is logged in a tracking record for audit purposes.
| Field | What It Means | Example |
|---|---|---|
| User | The user whose karma changed | Jane Smith |
| Old Karma Value | Karma before the change | 150 |
| New Karma Value | Karma after the change | 175 |
| Gain | The difference (computed: new - old) | +25 |
| Description | Reason for the change | "Completed March Safety Challenge" |
| Source | Reference to the originating record | gamification.badge.user,42 |
| Tracking Date | When the change occurred | 2026-03-10 14:30:00 |
| Consolidated | Whether this record has been consolidated in batch processing | No |
User Karma Fields¶
The gamification module adds these fields to every user record:
| Field | What It Means |
|---|---|
| Karma | The user's current karma score (computed from tracking records) |
| Rank | The user's current rank based on karma thresholds |
| Next Rank | The next rank the user can achieve |
| Gold Badges | Count of gold-level badges received |
| Silver Badges | Count of silver-level badges received |
| Bronze Badges | Count of bronze-level badges received |
| Badges | Full list of badge user records |
| Karma Changes | Full karma tracking history (admin only) |
How the Automation Works¶
The gamification module uses a scheduled cron job to keep everything up to date.
Cron Job: Challenge Update¶
The system runs a daily cron job (_cron_update) that performs these steps:
- Start new periods -- If a recurring challenge's current period has ended, a new period is started and fresh goals are generated for all participants
- Recompute participants -- If a challenge uses a User Domain, new matching users are added and non-matching users are removed
- Update goal values -- For Count, Sum, and Python goals, the system recomputes current values from the database
- Check goal completion -- Goals that meet their target are marked as Reached; goals past their end date that did not meet the target are marked as Failed
- Award badges -- If "Reward as soon as every goal is reached" is enabled, badges are granted immediately to qualifying users; top-3 badges are granted when the period ends
- Send reports -- Progress reports are sent according to the configured frequency
Manual goals require user action
Goals with Computation Mode set to "Manually" are never auto-updated. If a user does not update their goal within the configured remind delay, the system sends them a reminder notification. Make sure participants understand they need to update manual goals regularly.
Practical Examples for Scott Recycling¶
Example 1: Monthly Pickup Volume Contest¶
Goal Definition:
- Name: "Monthly Pickups Completed"
- Computation Mode: Count
- Model:
customer.pickups - Date Field:
pickup_date - Domain:
[('driver_id.user_id', '=', user.id), ('state', '=', 'done')] - Goal Performance: Higher is better
- Suffix: "pickups"
Challenge:
- Name: "March Pickup Sprint"
- Periodicity: Monthly
- Display Mode: Leader Board
- Target: 80 pickups
- Reward (Every Succeeding): "Pickup Pro" badge
- Reward (1st place): "Top Driver" badge
Example 2: Safety Streak (Manual Tracking)¶
Goal Definition:
- Name: "Days Without Safety Incident"
- Computation Mode: Manually
- Goal Performance: Higher is better
- Suffix: "days"
Challenge:
- Name: "Q1 Safety Streak"
- Periodicity: Non recurring
- Start Date: 2026-01-01
- End Date: 2026-03-31
- Display Mode: Individual Goals
- Target: 90 days
- Remind delay: 7 days
Example 3: New Customer Acquisition¶
Goal Definition:
- Name: "New Customers Signed"
- Computation Mode: Count
- Model:
res.partner - Date Field:
create_date - Domain:
[('user_id', '=', user.id), ('customer_rank', '>', 0)] - Goal Performance: Higher is better
- Suffix: "customers"
Security¶
Access Control Summary¶
| Model | Internal Users | ERP Managers / Admins | Portal Users |
|---|---|---|---|
| Goal Definitions | Read only | Full access (create, edit, delete) | Read only |
| Goals | Read and write own goals | Full access to all goals | Read and write own |
| Challenges | Read only | Full access | Read only |
| Challenge Lines | Read only | Full access | Read only |
| Badges | Read only | Full access | Read only |
| Badge User (granting) | Read, write, create | Full access | Read, write, create |
| Karma Ranks | Read only | Full access (System group) | Read only |
| Karma Tracking | No access | Full access (System group) | No access |
Record Rules¶
| Rule | Who It Affects | What It Does |
|---|---|---|
| Goal User Visibility | Internal + Portal users | Users can see their own goals, plus goals from challenges they participate in when Display Mode is "Leader Board" |
| Goal Manager Visibility | ERP Managers | Managers can see all goals across all users |
| Goal Multicompany | All users | Goals are filtered by the user's current company -- users only see goals belonging to users in their company |
Badge granting permissions
Even though all internal users can read badges, the ability to grant a badge is controlled by the badge's own Allowance to Grant setting, not by the model access rules. A badge set to "No one" cannot be manually granted regardless of the user's admin status.
Troubleshooting¶
Goals are not updating automatically¶
- Check that the Computation Mode on the Goal Definition is not set to "Manually" -- manual goals require hand-updating
- Verify the Filter Domain is valid -- an invalid domain causes the cron to skip that definition
- Check that the challenge is in In Progress state -- draft challenges do not generate or update goals
- Review the cron job: go to Settings > Technical > Automation > Scheduled Actions and look for the gamification challenge update action; confirm it is active and check its last execution date
Badge grant button is missing¶
- The user may have hit the Monthly Sending Limit for that badge -- wait until next month or ask an admin to increase the limit
- The badge's Allowance to Grant may be set to "No one" (auto-only badges)
- The badge may be Archived (Active = unchecked)
Challenge participants are not being added¶
- Check the User Domain filter syntax -- an invalid domain silently fails
- Confirm the target users are Internal Users (not portal or public)
- Make sure the challenge is In Progress -- participant recomputation only runs for active challenges
Common Tasks Summary¶
| Task | Where to Go |
|---|---|
| Create a new goal definition | Settings > Gamification Tools > Goal Definitions > New |
| Create a new challenge | Settings > Gamification Tools > Challenges > New |
| Start a challenge | Open challenge > click Start Challenge |
| Check challenge progress | Open challenge > click Related Goals or Participants |
| Manually update a goal value | Settings > Gamification Tools > Goals > open goal > update Current Value |
| Create a new badge | Settings > Gamification Tools > Badges > New |
| Grant a badge to someone | Open badge > Grant this Badge > select user > Grant |
| View a user's badges | Open user's profile > Badges section |
| Configure karma ranks | Settings > Gamification Tools > Karma Ranks |
| View karma history | Settings > Gamification Tools > Karma Tracking |
| Force-refresh all challenges | Open a challenge > click Refresh Challenge |
| Send a manual progress report | Open a challenge > click Send Report |
Questions? Contact your system administrator or HR manager.