Winners Selection Module

Overview

The Winners (Premiados) module enables random selection of winners from participants who have completed dilemmas. This feature is ideal for prize giveaways, incentive programs, and recognition campaigns to boost engagement and motivation.

Purpose & Use Cases

Prize Giveaways

Randomly select winners from top performers for prizes, gift cards, or rewards

Recognition Programs

Highlight standout participants in team meetings or company communications

Incentive Campaigns

Create gamified competitions with random winner selection to drive completion rates

Fair Selection

Ensure unbiased, transparent winner selection with automated randomization

How It Works

Select Client

Choose the client organization from the dropdown (uses TomSelect for easy search)

Select Dilemma

Pick the specific dilemma from which to draw winners (dropdown populates based on selected client)

Set Winner Count

Specify how many winners you want to select (minimum: 1)

Apply Score Filters (Optional)

Set minimum and/or maximum score thresholds to filter eligible participants

Generate Winners

Click the “Generar” button to randomly select winners from eligible participants

Export Results

Download the winner list as an Excel-compatible CSV file

Selection Criteria & Filters

Required Filters

Client: The organization whose participants are eligible
Dilemma: The specific game/dilemma to draw winners from
Winner Count: Number of winners to select (default: 1)

Optional Score Filters

Filter the eligible participant pool by performance:

Filter	Description	Example Use Case
Min Score	Minimum score required to be eligible	Only select from participants who scored ≥70
Max Score	Maximum score allowed for eligibility	Select from mid-performers (exclude top 10%)
Combined	Both min and max	Select from 50-80 score range

Score filters help you target specific performance tiers. For example:

Top Performers: min_score=80
Mid-Tier Participants: min_score=50&max_score=79
All Participants: Leave both blank

Winner Selection Algorithm

The system uses random selection from eligible participants:

// Selection logic (winners.php:19-24)
if ($_SERVER['REQUEST_METHOD'] === 'POST' || (isset($_GET['generate']) && $selectedGame)) {
    $winners = get_random_winners($selectedGame, $winnerCount, [
        'min_score' => $minScore,
        'max_score' => $maxScore
    ]);
}

Eligibility Requirements:

Must have started the selected dilemma
Must meet score threshold criteria (if specified)
Each user can only win once per selection (no duplicates)

Winner Display Table

Once generated, winners are displayed in a comprehensive table:

Columns Displayed

Column	Information	Notes
Puesto	Winner position (1, 2, 3…)	Auto-numbered
Usuario	User display name or ID	With avatar initial
Estado	Completion status	🟢 Terminado or 🟡 En curso
Puntaje	Final score	Displayed with “pts” badge
Fecha Actividad	Date/time of activity	Shows finish date if completed, otherwise start date
Feedback / Estrellas	Feedback status	Shows if user left feedback and star rating (1-5)

Status Indicators

Terminado (Finished):

<span class="bg-green-50 text-green-700">✓ Terminado</span>

En curso (In Progress):

<span class="bg-yellow-50 text-yellow-700">⏱ En curso</span>

Feedback Integration

The winner table shows whether each winner provided feedback:

Feedback OK: Green badge with star rating (⭐⭐⭐⭐⭐)
Sin Feedback: Gray badge indicating no feedback submitted

This helps you identify engaged participants beyond just completion.

CSV Export Functionality

Export winners before leaving the page or changing filters, as the winner selection is not saved to the database.

Export Process

Click “Descargar Ganadores a Excel” button
System generates CSV with UTF-8 BOM for Excel compatibility
File downloads as ganadores_YYYYMMDD_HHMMSS.csv

CSV Structure

Puesto,Nombre,Estado,Puntaje,Fecha Actividad
1,Juan Pérez,Terminado,95,2024-03-15 14:32:00
2,María García,Terminado,88,2024-03-15 16:45:00
3,Carlos López,En curso,72,2024-03-14 10:20:00

Export Implementation:

// Export form (winners.php:140-148)
<form action="export_winners" method="POST">
    <input type="hidden" name="game_id" value="<?php echo htmlspecialchars($selectedGame); ?>">
    <input type="hidden" name="winner_ids" 
        value="<?php echo htmlspecialchars(implode(',', array_column($winners, 'id'))); ?>">
    <button type="submit">Descargar Ganadores a Excel</button>
</form>

The export script (export_winners.php) fetches fresh data for the winner IDs and generates the CSV.

Empty State Handling

If no participants meet the criteria:

“Sin participantes” Message:No se encontraron usuarios que hayan completado este dilema para realizar el sorteo.Possible Reasons:

No users have finished the selected dilemma
Score filters are too restrictive
The dilemma has no active participants

Client Filter with TomSelect

The client dropdown uses TomSelect for enhanced UX:

new TomSelect("#client-select", {
    create: false,
    sortField: { field: "text", direction: "asc" },
    placeholder: "Buscar cliente...",
    maxOptions: 50,
    onChange: function (value) {
        // Auto-submit form to load dilemmas for selected client
        document.getElementById("client-select").form.submit();
    }
});

Features:

Searchable dropdown with type-ahead
Auto-sorted alphabetically
Auto-submits on selection to populate dilemma dropdown

Workflow Examples

Example 1: Monthly Top Performer Raffle

Client: "Acme Corporation"
Dilemma: "Q1 Ethics Challenge"
Winner Count: 3
Min Score: 80
Max Score: (blank)

Result: 3 random winners selected from participants who scored ≥80

Example 2: Mid-Tier Engagement Boost

Client: "TechCorp"
Dilemma: "Data Privacy Training"
Winner Count: 5
Min Score: 50
Max Score: 75

Result: 5 winners from the 50-75 score range to encourage mid-performers

Example 3: Completion Incentive (All Finishers)

Client: "Global Industries"
Dilemma: "Compliance Fundamentals"
Winner Count: 10
Min Score: (blank)
Max Score: (blank)

Result: 10 random winners from all participants who completed the dilemma

Best Practices

Fair Score Thresholds

Set minimum scores that are achievable (e.g., 60-70) to maintain fairness while ensuring quality

Announce Ahead

Tell participants about the prize drawing before they start to maximize engagement

Export Immediately

Download the CSV right after generation - results are not persisted

Transparent Communication

Share the selection criteria with participants to build trust

Important Limitations:

Winner selections are not saved in the database
Refreshing the page or changing filters generates a new random selection
Export the CSV immediately to preserve results
Each click of “Generar” creates a completely new random selection

Access Control

Access Level: All authenticated users (no explicit restrictions in the code) However, in practice:

Typically used by administrators and HR/training coordinators
Client users may have access but see only their own client’s data
Requires authentication (redirects if not logged in)

Feedback Management - View feedback from winners
User Management - Manage participant accounts
Dilemma Games - View dilemma completion statistics

Get Started

Core Features

Configuration

User Guides

Overview

Purpose & Use Cases

Prize Giveaways

Recognition Programs

Incentive Campaigns

Fair Selection

How It Works

Selection Criteria & Filters

Required Filters

Optional Score Filters

Winner Selection Algorithm

Winner Display Table

Columns Displayed

Status Indicators

Feedback Integration

CSV Export Functionality

Export Process

CSV Structure

Empty State Handling

Client Filter with TomSelect

Workflow Examples

Example 1: Monthly Top Performer Raffle

Example 2: Mid-Tier Engagement Boost

Example 3: Completion Incentive (All Finishers)

Best Practices

Fair Score Thresholds

Announce Ahead

Export Immediately

Transparent Communication

Access Control

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

User Guides

​Overview

​Purpose & Use Cases

Prize Giveaways

Recognition Programs

Incentive Campaigns

Fair Selection

​How It Works

​Selection Criteria & Filters

​Required Filters

​Optional Score Filters

​Winner Selection Algorithm

​Winner Display Table

​Columns Displayed

​Status Indicators

​Feedback Integration

​CSV Export Functionality

​Export Process

​CSV Structure

​Empty State Handling

​Client Filter with TomSelect

​Workflow Examples

​Example 1: Monthly Top Performer Raffle

​Example 2: Mid-Tier Engagement Boost

​Example 3: Completion Incentive (All Finishers)

​Best Practices

Fair Score Thresholds

Announce Ahead

Export Immediately

Transparent Communication

​Access Control

​Related Features

Build docs developers (and LLMs) love

Overview

Purpose & Use Cases

How It Works

Selection Criteria & Filters

Required Filters

Optional Score Filters

Winner Selection Algorithm

Winner Display Table

Columns Displayed

Status Indicators

Feedback Integration

CSV Export Functionality

Export Process

CSV Structure

Empty State Handling

Client Filter with TomSelect

Workflow Examples

Example 1: Monthly Top Performer Raffle

Example 2: Mid-Tier Engagement Boost

Example 3: Completion Incentive (All Finishers)

Best Practices

Access Control

Related Features