Building an Exam Enrollment and Grade Notification System using Africa’s Talking SMS Shortcode API in Django

Introduction

This article explores the application of SMS shortcodes to create transparency and improve the quality of education in learning institutions. Shortcodes are often used by businesses to allow customers to opt-in to their SMS campaigns, alert services, or to enter SMS competitions, but they can also be used by learning institutions to provide meaningful information promptly to their stakeholders.

Intended audience: Who the article is for

This piece targets python developers who would want to incorporate Africa’s Talking SMS APIs into their projects or into more robust applications such as those built on the Django Framework

Case Study: What the article is going to cover

The application to be developed is an online exam portal where students are enrolled to sit for an exam and their grades are uploaded on the same portal.

The portal will integrate with Africa’s Talking SMS Shortcode API in order to inform the student’s guardian, when the student is enrolled to sit for an exams as well as the grades uploaded.

This can be used by universities to resolve issues dealing with missing marks exams or publishing of national exam grades where the parents/students can be notified as soon as their grades are out. The application will be built using python programming language using Django Framework.

Requirements:

  1. Some knowledge of Python and Django
  2. Africa’s Talking Account
  3. Africa’s Talking API Key
  4. Africa’s Talking SMS Short Code
  5. Python3 in your computer

Acquiring Africa’s Talking Credentials

  1. Head over to Africa’s talking and create an account or login if you already have one.
  2. Using the navigation bar on the left side
  3. Select SMS, then Select “Shortcodes“
  4. Inside “Shortcodes” menu click “Create Shortcode”
  5. Click “My Shortcodes” to verify your shortcode has been created
  6. On the same navigation bar select the “Settings” menu
  7. Inside “Settings” drop down menu, click on API Key to get your API Key
  8. Save the SMS Shortcode and API key as you will need them later on

Creating a Django Project

  1. From your terminal navigate to the folder/location your project is to reside
  2. We will create a Django project called “ExamGradingSMS”, type the command: django-admin startproject ExamGradingSMS
  3. From the terminal navigate into the created project folder, where you will create and then activate your project’s virtual environment
  4. Type “python3 -m venv venv” in the terminal to create the virtual environment
  5. In windows, type “venv\Scripts\activate” in the terminal
  6. In Mac/Linux, type ”source venv/bin/activate” in the terminal
  7. After your virtual environment has been activated install the following python packages
    • Pillow python package (to be used in managing images), on the terminal type the command: “pip install Pillow
    • Django python package (the web platform to be used to develop the website), on the terminal type the command: “pip install Django”
    • Requests python package (to be used in managing HTTP requests), on the terminal type the command: “pip install requests
    • Crispy Forms (to be used rendering bootstrap styles), on the terminal type the command “pip install django-crispy-forms
    • Django python package: “pip install Django”
  8. Create your first Django app by typing in the terminal the command: “python manage.py startapp users
  9. Create a second Django app by typing in the terminal the command: “python manage.py startapp exams
  10. Create a SQLite database that will used by the project by typing in the terminal the command: “python manage.py makemigrations
  11. Apply database changes by typing in the terminal the command: python manage.py migrate
  12. Start your server by typing on the terminal the command: “python manage.py runserver
  13. If the server starts successfully there should be a webpage up and running on the location: http://127.0.0.1:8000
  14. While in the terminal type Ctrl+C to stop the server
  15. Everything from now on will be performed inside this python activated environment
  16. We are stopping the server so that we can create the database tables first and then apply the changes before restarting the server

Creating CSS File

  1. Open your project folder in Visual Studio code or whichever code editor you are using
  2. Open the “exams” app folder
  3. In the “exams” app folder, create a folder labeled “static”
  4. Inside the created “static” folder create another folder labeled “exams”
  5. Inside the “exams” folder just created inside the “static” folder, create a css file labeled “main.css”
  6. Copy the code below into the “main.css” file

Creating Database Tables

  1. Open your project folder in Visual Studio code or whichever code editor you are using
  2. We will start by creating database tables related to the “exams” app we created, which are:
    • Course: This table will have the following fields, name (for the course name) and description (for a brief description of the course)
    • Subject: This table will have the following fields, name (for the subject name) and description (for a brief description of the subject)
    • Exam: This table will have the following fields, start_date (the day and time the exam will start), end_date (the day and time the exam will end) and subject (the subject with an exam on the stated date)
  3. To create the above “exams” tables, in your project folder navigate into the “exams” folder and open a file labeled “models.py” and paste the code below:
  • 4. We will now create database tables related to the “users” app we created, which are:
    • 1. Student Table – To hold Student Data
    • 2. Teacher Table – To hold Teacher Data
    • 3. Parent Table – To hold Parent Data
    • 4. Exams Enrolled Table – To hold the student, the exam enrolled, their marks/grade, examiners comment and date of enrollment
    • 5. Profile Table – To hold the image paths of the users’ profile picture
  • 5. To create the above “users” tables, in your project folder navigate into the “users” folder and open a file labeled “models.py” and paste the code below:

Create Database Signals

These are signal that will be raised when a particular database operation is performed

Creating Exam Signals

These are signals that will be raised in the “exams” app when a particular action is performed. We want a student’s parent to be informed via text when their student/child is enrolled to sit for an exam. This can be registered as a database signal where immediately the student is enrolled/added into the “ExamEnrolled” database table, a signal is raised and message is sent to the parent using Africa’s Talking SMS API.

To do this:

  1. Open the “exams” app folder
  2. Locate/create a python filed labeled “signals.py”, paste the code below

3. Within the same directory, locate a python labeled “apps.py” and paste the code below

Creating Users Signals

These are signals that will be raised in the “users” app when a particular action is performed. We want a student, parent and teacher profiles to be created once any of these users are created. This can action can be registered as a database signal.

To do this:

  1. Open the “users” app folder
  2. Locate/create a python filed labeled “signals.py” and paste the code below

3. Within the same directory, locate a python labeled “apps.py” and paste the code below

Africa’s Talking API Integration

  1. You first start by creating Africa’s Talking API Key
  2. Create an Africa’s Talking SMS short code
  3. Open the “exams” app folder
  4. Create a python filed labeled “send_message.py” and paste the code below

Configure Project Settings

  1. In order to apply the database changes we just made we need to register the apps we have created on the projects settings. Here is how to do so:
  2. Open your Django project folder
  3. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “exams” app folder, “users” app folder and “venv” folder
  4. Inside this folder is a python file labeled “settings.py”
  5. Open the “settings.py” file and locate the variable INSTALLED_APPS
  6. The variable INSTALLED_APPS is a list where you will insert the apps we just created
  7. Insert the code below inside the list:

Apply Database Changes

  1. In your terminal ensure you have activate your project’s virtual environment
  2. While in your projects activated virtual environment in your terminal
  3. Create database changes to be made by typing in the terminal the command: python manage.py makemigrations
  4. Apply database changes by typing in the terminal the command: python manage.py migrate

Creating “Exams” HTML Templates

  1. On these HTML templates is where the exams data will be displayed
  2. We will start by creating HTML templates related to the “exams” app we created, which are:
    • base.html – This is the page that contains HTML code that will be common or will be used on all templates
    • index.html – This is the home page to displayed
    • subjects_list.html – This is the page that will display a list of all subjects
    • subjects_detail.html – This page will be used to display/edit the subject details/data
    • courses_list.html – This is the page that will display a list of all courses
    • courses_detail.html – This page will be used to display/edit the course details/data
    • exams_list.html – This is the page that will display a list of all exams
    • exams_detail.html – This page will be used to display/edit the exam details/data
    • confirm_delete.html – This page will be used to display a notification to the user to confirm if they want to delete the selected data
  3. To create the above “exams” HTML templates do the following:
    • In your project folder navigate into the “exams” folder
    • Create a folder labeled “templates”
    • Inside the “templates” folder create another folder and label it “exams”
    • Inside the “exams” folder you have just created inside the “templates” folder
    • Create the following blank HTML pages; base.html, index.html, subjects_list.html, subjects_detail.html, courses_list.html, courses_detail.html, exams_list.html, exams_detail.html and confirm_delete.html

Below is a screenshot of the directory tree:

exams app template tree/file directory

Below are the code snippets for each exam templates html file:

Creating “Users” HTML Templates

  1. On these HTML templates is where the different users data will be displayed
  2. We will start by creating HTML templates related to the “users” app we created, which are:
    • students_list.html – This is the page that will display a list of all students
    • student_detail.html – This page will be used to display/edit the student details/data
    • teachers_list.html – This is the page that will display a list of all teachers
    • teacher_detail.html – This page will be used to display/edit the teacher details/data
    • parents_list.html – This is the page that will display a list of all parents
    • parent_detail.html – This page will be used to display/edit the parent details/data
    • profile.html – This page will be used to display the user’s details/data
    • exam_enroll_list.html – This page will be used to display the students enrolled for a specific exam
    • exam_enroll_detail.html – This page will be used to display/edit student grades for a specific exam
  3. To create the above “users” HTML templates do the following:
    • In your project folder navigate into the “users” folder
    • Create a folder labeled “templates”
    • Inside the “templates” folder create another folder and label it “users”
    • Inside the “users” folder you have just created inside the “templates” folder
    • Create the following blank HTML pages; students_list.html, student_detail.html, teachers_list.html, teacher_detail.html, parents_list.html, parent _detail.html, profile.html, exam_enroll_list.html and exam_enroll_detail.html

Below is a screenshot of the directory tree:

users app template tree/file directory

Below are the code snippets for each users templates html file:

Create User Profile Forms

These are the forms used to render user data onto their profile pages

  1. Open the “users” app folder
  2. Locate/create a python filed labeled “forms.py”
  3. Paste the code below

Creating your backend/business logic for Exams App

These are the methods that will take data from your “exams” database/Models and populate on the “exams” HTML pages/template. Do the following to create the business logic:

  1. Open the “exams” app folder
  2. Locate a python filed labeled “views.py”
  3. Paste the code below

Creating your backend/business logic for Users App

These are the methods that will take data from your “users” database/Models and populate on the “users” HTML pages/template. Do the following to create the business logic:

  1. Open the “users” app folder
  2. Locate a python filed labeled “views.py”
  3. Paste the code below

Creating the Exams App URLs

These are the URLs that will be called to execute the exams “view” functions/methods that will then return the exams HTML template pages with the relevant data. Do the following to create the “exams” URLs:

  1. Open the “exams” app folder
  2. Locate/create a python filed labeled “urls.py”
  3. Paste the code below

Creating the Users App URLs

These are the URLs that will be called to execute the users “view” functions/methods that will then return the users HTML template pages with the relevant data. Do the following to create the “users” URLs:

  1. Open the “users” app folder
  2. Locate/create a python filed labeled “urls.py”
  3. Paste the code below

Creating the Project URLs

This is where the “exams” app URLs and “users” app URLs will be registered. Do the following to register the URLs:

  1. Open the “ExamGradingSMS” folder which is in the same directory as the “exams” app and “users” app
  2. Locate a python filed labeled “urls.py”
  3. Paste the code below

Configure Media Settings

This requires creation of the folder where user profile images will be placed.

  1. In your Django project folder
  2. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “exams” app folder, “users” app folder and “venv” folder
  3. Inside this folder is a python file labeled “settings.py”
  4. Open the “settings.py” file and paste code below at the very end of the file

  1. In your Django project folder
  2. In the same directory as your “exams” app folder, “users” app folder and “venv” folder
  3. Create a folder called “media”
  4. Inside the “media” folder save the image bellow as “default.png”
  5. Inside the “media” folder create a folder called “profile_pics”

Project Tree

Below is a screenshot of how your project tree should look like, assuming the name of your Django project is “ExamGradingSMS”:

django project tree

Run the Server

  1. cd/navigate into the Django project via the terminal
  2. Activate the virtual environment
  3. Start the server by typing the command: python manage.py runserver
  4. If there’s nothing wrong, the server should be up on http:127.0.0.1:8000

Testing the System

  1. Once the server is up
  2. Navigate to http://127.0.0.1:8000/
  3. Create a course
  4. Create a subject
  5. Create a teacher
  6. Create a student
  7. Create a parent
  8. Create an Exam
  9. Open the Africa’s Talking Simulator and register the Parent’s mobile number into the emulator
  10. The simulator is found here click on the “Launch Simulator” menu on the left navigation bar
  11. Open the messages app on the emulator
  12. On the Django project enroll a student into an exam, a message should pop up on the emulator
  13. Enter the student grades, by clicking edit on the enrolled students’ exam list
  14. After entering the students’ grade, a message should pop up on the emulator

Conclusion

You should now have a basic understanding of how SMS shortcode applications work and how to implement them in python, while working in with Django. The article not only provides a guide on how to implement SMS shortcode APIs on web applications but also on other applications that Python can be applied to. You can find the code snippets in this repo.

Quick Guide

If you just want to clone the project and get it up running, below is how to do so in minutes from your terminal:

  1. Clone it:
    • git clone https://bitbucket.org/dans0l/examgradingsms.git
  2. Cd into it:
    • cd examgradingsms
  3. Create a venv:
    • python3 -m venv venv
  4. Activate venv:
    • If you are using Mac/Linux type this: source venv/bin/activate
    • If you are using Windows type this: venv\Scripts\activate
  5. Install the requirements:
    • pip install -r requirements.txt
  6. Create DB
    • python manage.py makemigrations
  7. Apply DB Changes:
    • python manage.py migrate
  8. Configure your Africa’s Talking SMS Shortcode and API Key:
    • Open the cloned project
    • Open the “exams” folder
    • Open a python file labeled “send_message.py”
    • Enter the credentials in the file
  9. Run the server:
    • python manage.py runserver
  10. Navigate to the site: http://127.0.0.1:8000
  11. Follow the instructions on the home page to start using the site
  12. Navigate to Africa’s Talking Simulator to view Messages Sent

Thank you.

0 Shares:
You May Also Like