Leaderboards

Leaderboards rank members or companies by performance data and display results on your program website. Connect a Data Bucket for live KPI rankings, or upload a CSV for one-off or external data. Configure columns, winner icons, and home-page cards, then publish so members see standings in Progress components on your site.

For bucket setup (Category Keys, targets, imports, and save), see Data Buckets—this guide focuses on the Leaderboards app itself.

Overview

From Apps → Leaderboards you can:

• Create and manage leaderboards (Active, Inactive, Archive)
• Connect a data source — linked Data Bucket (recommended) or uploaded CSV
• Rank participants by any numeric column, with ascending or descending order
• Map columns for the header row and main ranking table
• Highlight winners with icons and configurable winning places
• Filter who is ranked by member or company tag
• Control visibility on the member site with member and company tags
• Preview home cards — prefix, suffix, and rank display for Progress widgets

Inside a Leaderboard

Where to find it

• List route: /leaderboards/{programId}
• Leaderboard detail: /leaderboards/{programId}/leaderboard/{leaderboardId}
• Side navigation: Apps → Leaderboards

Prerequisites

• An open program with program administrator access
• Editor role (or higher) — required to create, edit, and save leaderboards; Observer can view the list
• For Data Bucket leaderboards:
  • An Active Data Bucket with saved results (targets and/or progress data uploaded and Save Data Bucket completed at least once)
  • Members or Companies on file with Data Keys matching bucket rows — see Members and Companies
• For CSV leaderboards:
  • A CSV file with a column that matches participant Data Keys
  • Same member or company records on file for matching
• To show leaderboards on your program website, add a Progress component in Design Studio (leaderboards with status Active appear automatically when tag rules match)

List page

The list has three tabs:

Each card shows the leaderboard name, last updated date, status, and a data-source indicator:

Use Search to filter cards by name. Click a card or the arrow button to open the leaderboard.

Step-by-step

Create a leaderboard

1. On the Leaderboards tab, click Create a Leaderboard (or the + button).
2. Enter Leaderboard Name.
3. Choose Data Source:
   • Data Bucket — rankings sync from a saved bucket (recommended for ongoing programs)
   • CSV — upload your own file; you manage updates manually
4. Choose Data Type — Members or Companies (must match whose rows are in the source data).
5. If Data Bucket is selected, pick the bucket from Select data bucket.
6. Click Save.

You are returned to the list. Open the new leaderboard to configure columns and ranking.

Connect data (Data tab)

Open the Data tab to wire the leaderboard to its source and control who is included in rankings.

Data Source

Data Type — Members or Companies. Rows are matched to records on file by Data Key. Unmatched rows are excluded from rankings; download unmatched records from the link at the bottom of the tab to fix Data Keys or source data.

Data Filter — Optionally filter which participants appear in the ranking:

• Member leaderboards: Filter the leaderboard by Member Tag
• Company leaderboards: Filter results by Company Tag

Leave filters empty to include all matched participants. Tag filters here affect rankings only, not site visibility (see Tags tab).

The connection status line shows whether the source is connected. Summary counts show total records, matched records, and unmatched records, plus Last Import date.

Configure ranking (Winners tab)

Set how participants are ordered and which rows count as winners.

The winner Icon column (added on Builder) displays the medal for rows in the top Winning Places when all Qualifier columns pass (if configured).

Map columns (Builder tab)

The Builder tab has two sections—Header (top row for a selected participant) and Main Body (full ranked table).

Add a column

1. Click + on the Columns bar for Header or Main Body.
2. Choose Column Content from:
   • System Fields — Rank, Icon, Full Name, Avatar, First Name, Last Name, Company Title, etc.
   • Data Bucket Fields or CSV Columns — Target, Actual, Difference, Percentage, Total Points, and other source columns
3. Enter a Column Label (member-facing header text).
4. For data columns, choose Column Format:
   • Text — display as-is
   • Number — set prefix/suffix ($, %, etc.) and decimal rounding
   • Qualifier — show a tick/cross icon based on a rule (True/False, Yes/No, or numeric threshold)
5. Click add.

Drag column chips to reorder. Remove a column with the chip close control.

Preview

• Header — use Preview Data Of to pick a participant and see one header row.
• Main Body — shows the full ranked table using current sort and row-limit settings from Winners.

Include a Rank column in Header mappings if you use the Card tab home-page preview.

Preview home card (Card tab)

The Card tab shows how this leaderboard appears as a summary tile on the member site (Progress component).

• Preview Data Of — select a participant to preview their rank
• Prefix / Suffix — optional text above or below the rank (for example, "You are" / "in Q1 Sales")
• The preview card shows rank (ordinal), prefix/suffix, and Display Title

Configure a Rank column on the Builder → Header section so the card can show placement (e.g. "3rd").

Set titles (Titles tab)

Both fields are required before you can save.

Control visibility (Tags tab)

Member Tags and Company Tags control who sees this leaderboard on the program website, not who is included in rankings.

Both member-tag and company-tag rules must pass when tags are set on both lists. Use the Data tab filters when you need to limit which participants appear in the ranking table.

Status and order (Other tab)

Save leaderboard

Configuration changes are staged until you save. When pending changes exist, save leaderboard activates in the sticky footer.

1. Confirm Title and Display Title are filled in (Titles tab).
2. Confirm a data source is connected (Data tab — no "No data source connected" alert).
3. Click save leaderboard.

Saving persists mappings, ranking rules, and calculated headerData / columnData used on the member site. For CSV leaderboards, the uploaded file is saved with the leaderboard. For Data Bucket leaderboards, raw CSV is stored on the bucket—leaderboard save updates display configuration and recalculates from the current bucket snapshot.

How Data Buckets sync leaderboards

When a leaderboard uses Data Bucket mode:

1. You link the leaderboard to a bucket on the Data tab.
2. Bucket results (totals per participant) load from the bucket's saved total result document.
3. Each time you Save Data Bucket on that bucket, the system finds all linked leaderboards and recalculates their rankings automatically. A sync log lists each leaderboard processed.

You do not need to re-upload targets or progress data in the Leaderboards app—that workflow lives entirely in Data Buckets, Targets, and Data imports.

Tips and limitations

• Editor role required — Only Editor (or Admin) can create and save leaderboards; Observer can browse the list.
• Data Keys are essential — Source rows match participants by Data Key (Account Id for buckets; your chosen column for CSV). Fix unmatched rows before relying on rankings.
• Participant type must match — A Member leaderboard expects member Data Keys; Company expects company Data Keys. Align with your bucket Data Type when using Data Bucket mode.
• Rank column needs numeric data — Rank Leaderboard By must be a column with numeric values; text columns will not sort correctly.
• Two kinds of tags — Data Filter (Data tab) limits who is ranked; Member Tags / Company Tags (Tags tab) limit who sees the leaderboard on the site.
• Header Rank for cards — Add Rank to Builder → Header columns for home-page card previews to show ordinal placement.
• Winning icon logic — The Icon column shows the medal only for rows in the top Winning Places where all Qualifier columns pass (when qualifiers are mapped).
• Demo programs — Create, upload, and save actions are disabled on demo programs.
• Inactive and Archive — Set status to Inactive or Archive instead of deleting when you want to retain history.
• CSV updates — Re-upload a replacement file on the Data tab, then save leaderboard; bucket-driven leaderboards update via Save Data Bucket instead.

Related

• Data Buckets — Central data source; saving syncs linked leaderboards
• Targets — Upload goal CSVs to buckets
• Data imports — Upload progress/actual CSVs to buckets
• Target Points Rules — Point columns available in bucket-driven rankings
• Members — Member Data Keys and member tags
• Companies — Company Data Keys and company tags
• Target Trackers — KPI tables from the same bucket data
• Design Studio — Add Progress components that display leaderboard cards on your site