View Categories

Lottery Management

10 min read

Introduction

The Lottery Module automates the process of determining school allotments for students based on their preferences and the availability of seats in the selected schools. This system ensures fairness and transparency in the allocation process, allowing administrators to efficiently manage student placements. The module includes tools for overseeing lotteries, tracking ongoing processes, and accessing detailed logs of previous actions. It also supports role-based access control, protecting sensitive data. With customization options, the Lottery Module simplifies the decision-making process while maintaining compliance with regulatory standards.

Prerequisites

  • Access to a Drupal 10+ environment with appropriate permissions.
  • Check the requirement sheet for more details – RTE-MIS: Requirements_Documents
  • Installation of necessary modules
    • Contrib Modules: simple_oauth, maxlength, views_custom_table, pdf_serialization, views_data_export.
    • Custom Modules: rte_mis_core,  rte_mis_student, rte_mis_lottery.

Installation and Configuration

  • Please ensure the modules mentioned in the Prerequisites are installed and enabled.
  • The path for custom modules is docroot/profiles/contrib/rte-mis/modules/rte_mis_student_tracking
    docroot/profiles/contrib/rte-mis/modules/rte_mis_allocation
  • To enable a module in the Drupal instance using Drush, use

                       drush en module_name

Replace the module name with the actual name of the module. For example

To enable the password policy module use.


                      drush en rte_mis_student_tracking

Usage of the Lottery Module (Internal & External)

The Lottery Module has been designed to function both internally within the system and externally via APIs, allowing seamless integration for administrators.

Configuration Setup:

Once the Lottery Module is enabled, a configuration form is provided where the app admin can set key parameters for running the lottery. This configuration includes two main sections:

  1. Time Interval:
    Administrators can specify the time duration after which the lottery results will be automatically cleared, helping to maintain system performance by removing outdated results.
  2. SMS Settings:
    The app admin can enable the option to send SMS notifications to students regarding their allotment status after the lottery is completed. If enabled, the state admin can send SMS alerts to students about their results.

Internal Usage:

Starting the Lottery:

The state admin can initiate the lottery process through the dedicated panel accessible at /lottery.

  1. Fetching Data:
    Before starting the lottery, the state admin must click a button to fetch the eligible student data from the database. This data is randomized upon retrieval to ensure an unbiased selection process.
  2. Viewing Eligible Students:
    After fetching the data, the state admin can view a list of eligible students along with their corresponding school preferences.
  3. Initiating the Lottery:
    By clicking the “Start Lottery” button, the lottery process begins.
Lottery in Progress:

While the lottery is running, a message is displayed on the screen stating “Lottery in progress.” Administrators can navigate away from the page, but if they revisit the /lottery link during the ongoing process, they will see the same message until the lottery completes.

Viewing Lottery Results:

Once the lottery is finished, administrators can view the results at /lottery-result. This page displays the list of both allotted and unallotted students, providing a clear summary of the outcome.

External API Usage:

The Lottery Module is also accessible via an API, offering flexibility for external integration.

API Endpoints:
  • POST:
    /oauth/token – Used to obtain an authentication token.
    /api/v1/lottery-data – Used to initiate the lottery process.
  • GET:
    /api/v1/lottery-status – Used to check the current status of the lottery.
Access & Scope:
  • Access: Only the state admin can use these API endpoints.
  • Scope: The API is restricted to managing the lottery process.
API Testing Steps:
  1. Prepare the Data:
    Ensure all relevant data is created in the required format.
  2. Obtain the Authentication Token:
    • Send a POST request to /oauth/token with valid credentials for a state admin.
    • Use the token from the response for the following steps.
  3. Initiate the Lottery:
    • Send a POST request to /api/v1/lottery-data with the token included in the Authorization header as a Bearer token.
    • A successful response should indicate “Lottery started.”
  4. Check the Lottery Status:
    • Send a GET request to /api/v1/lottery-status, again including the token in the Authorization header.
    • Verify the response to check the current status of the lottery.

By offering both internal and external functionality, the Lottery Module provides administrators with flexibility and control, whether they are managing the lottery directly through the interface or integrating with external systems via API.

Development Process

The Lottery Module leverages core Drupal features such as QueueWorker and Batch Processing to handle the potentially large dataset involved in school allotment. The system ensures both internal and external processes work seamlessly through batch processing and an API interface for external systems. Below is an overview of the development process.

Queue Worker & Batch Process

To efficiently manage large datasets, the module uses Drupal’s Batch API and QueueWorker system to divide processing into manageable chunks.

  • Randomization Process:
    When the state admin clicks on the “Randomize” button on the lottery form, an internal function named rteMisLotteryFetchStudent() is triggered. This function retrieves eligible schools and students from the database.
    Since large datasets are involved, this data is processed in batches of 100 records at a time to ensure the system performs efficiently, even under heavy loads.
Triggering the Lottery Process

When the user clicks the Start Lottery button, the system moves into the core lottery processing phase.

  • Internal Triggering:
    The submitForm() method inside the LotteryForm.php handles the initiation of the lottery process. This method:
    • Adds the student data to a custom Queue for further processing.
    • Stores a copy of the dataset in a folder named lottery-files located outside the docroot for file system management and external access.
  • External API Triggering:
    For external requests, the system exposes a POST API endpoint. When data is sent via a POST request, the same process occurs:
    • The template for data upload via the api can be found at format.json
    • A file is created in the lottery-files folder containing the dataset.
    • The system then queues the data for processing through the same custom queue, ensuring consistency between internal and external usage.
Queue Processing

A custom queue named Student Data Lottery Queue is responsible for processing the data once it has been added. The queue works as follows:

  • Data Processing:
    The queue worker processes the student data by checking their preferences and the seat availability in each school. The system allots schools to students based on these criteria.
  • Seat Status & Lottery Results Storage:
    Once the lottery process is complete, the system updates:
    • Seat status for each school, academic session, class, and medium in the custom table rte_mis_lottery_school_seats_status.
    • Lottery results, including allotted and unallotted students, in the rte_mis_lottery_results table.
  • Allocation Entity creation:
    As the lottery process continues the data is passed on to another queue which handles the allocation entity creation from the lottery queue, In the queue also, the data is passed in a chunk of 100 and accordingly allocation entity is created. On the lottery result page there is an configurable option for the statue to send an sms to each student regarding the status of their allocation. That is configurable from the config form – SMS settings.
External API Usage & Integration

External systems can integrate with the lottery system using the provided API endpoints:

  • API Authentication:
    External systems must authenticate via OAuth to access the API. To do this, they must obtain the necessary client_key and secret_key configured using the OAuth module. A consumer must be defined with specific details to set up API access.
  • API Endpoints:
    • POST /oauth/token: Obtain the authentication token required for API access.
    • POST /api/v1/lottery-data: Trigger the lottery process by sending school and student data via this endpoint.
    • GET /api/v1/lottery-status: Fetch the status of the ongoing or completed lottery using this endpoint.

Once external data is submitted via the POST request, it creates a file in the lottery-files folder. The queue processes the file and follows the same internal logic, allotting schools based on student preferences and seat availability. External systems can use tools like Postman to send requests to the API and fetch results.

Database Management

Two custom database tables are vital to the module’s functioning:

  • Seat Status:
    The rte_mis_lottery_school_seats_status table holds real-time seat availability across schools, categorized by academic session, class, and medium.
  • Lottery Results:
    The rte_mis_lottery_results table stores all results, including which students were allotted seats and which were not.

When the Lottery Module is uninstalled, all data in the rte_mis_lottery_school_seats_status table is automatically cleared, ensuring no leftover data remains.

Controller Functions
  • The LotteryController.php file houses the data collection & result status logic for external lottery processes.
    • The handlePost() function processes POST requests by reading data uploaded by the user storing it in the lottery-files folder and initiating the lottery.
    • The getStatus() function provides the current status of the lottery through the status API, allowing administrators and external systems to track progress.

For the lottery to run smoothly two cron jobs need to be set up during the site setup process.

This development process ensures both internal users and external systems can interact with the lottery module efficiently. The use of QueueWorker, Batch Processing, and a flexible API makes the system scalable and capable of handling complex scenarios involving large datasets and real-time status updates.

Customization and Extensibility

  •  Developers can modify the code within custom modules for advanced customization to meet specific project requirements.

Troubleshooting 

     Lottery Not Starting:
  • Check Database Connectivity: Ensure the database is accessible and data is being fetched properly.
  • Randomized Data Missing: If the fetched data is not appearing on the panel, verify the randomization process and confirm there are eligible students for the lottery.
  • Permissions: Confirm the state admin has the necessary permissions to start the lottery.
     ‘Lottery in Progress’ Message Persists:
  • Refresh the Page: If the “Lottery in progress” message remains after the lottery is completed, try refreshing the page or clearing the cache.
  • Process Overload: If the lottery takes unusually long, check server logs for any errors that may indicate overload or performance issues.
     SMS Not Sent:
  • Check SMS Settings: Ensure the SMS setting is enabled in the configuration.
  • SMS Gateway: Verify that the SMS gateway is functioning correctly and that there are no connectivity

Best Practices

  • Ensure Current Academic Session Entry:
    Verify that the current academic session has an entry for the lottery event to ensure the process runs smoothly.
  • User Role Permissions:
    Confirm that the user roles have the necessary permissions to access lottery-related data. Only the app admin and state admin should be allowed to view and manage lottery data.
  • Data Format for External Lottery:
    For external lottery processing via API, ensure that the data format adheres to the required specifications to prevent errors during the process.
  • Cronjob Monitoring:
    Check that the relevant cronjobs are functioning correctly on the server to automate tasks such as clearing lottery results and sending SMS notifications.
  • Make sure the table clearing time is set correctly or else the allotment results will get deleted.

References 

  • Detailed information about custom modules can be found in the documentation provided for  Custom Modules.