How To Build a Hospital Doctor’s Appointment System in Django using Africa’s Talking USSD API

Introduction

The project looks into how you can use Africa’s Talking USSD to create a Hospital Doctor’s Appointment System; this can be done when a hospital would like its patients or walk-ins to book doctor appointments via USSD thereby increasing the patient’s convenience to access to healthcare.

This will allow a hospital to have an efficient way to book doctor appointments and the system could also be modified to send SMS shortcodes to the patients informing them of an upcoming doctor’s appointment.

Intended audience: Who the article is for

This article targets python/Django developers who would want to build a web-based hospital appointment system that allows patients to book appointments and extend this project to use Africa’s Talking SMS shortcodes to send reminders to patients, especially those that need urgent monitoring.

Case Study: What the article is going to cover

The project will display two use cases, building a web-based Django hospital appointment system and building an API that will interact with Africa’s Talking USSD API

The application is built using python programming language in Django Framework.

Requirements:

  1. Some knowledge of Python and Django
  2. A website domain name for your Django project
  3. Africa’s Talking USSD API

Acquiring a website domain name for your Django project

The reason we need a website domain for the Django project is that the USSD API requires us to set the URL of the Django web app that’s hosting the A.P.I. to be used as a call back when a user initiates the USSD call.

Since the Django project will be developed and hosted on our local computer, it is only accessible via the URL http://127.0.0.1:8000; with this URL, the Django project in your local computer cannot be accessed on the internet. So we need to find a way for our Django project API to be accessible via the web. To do so, we will use a free downloadable software called Ngrok. i.e. http://127.0.0.1:8000 is the same as http:// localhost:8000

Ngrok is an application that creates a dummy http URL that we will use to map to http://127.0.0.1:8000 (where the Django project is running), e.g. Ngrok could create a dummy URL http://hbshvbhwhbeh.io and map it to http://127.0.0.1:8000, so when any user online enters the dummy URL on their browser, they will be able to view the Django project. Its A.P.I. can also be accessed via Africa’s Talking online U.S.S.D. A.P.I.

To learn more about Ngrok, you can check out this article that we published recently.

Steps:

  1. Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup; You will then be prompted to sign up to download the application, go ahead and do so.
  2. After signing up, you will see the page below:
  1. Download and start/run the application
  2. After running the Ngrok application, you will see the terminal below:
  1. Go back to the Ngrok web page that is displayed above and navigate to the section labelled “Connect your account.”
  2. Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal; this is so that the dummy URL you will create does not expire after a short period, after which you will have to create another dummy U.R.L.
  3. Since we want to map the localhost port 8000 to a dummy URL, go back to the Ngrok terminal and type the command “ngrok http 8000”, this will open the ngrok shell below with the name of the newly created dummy http URL, e.g. http://21f3bf1b511a.ngrok.io that maps -> to the http://localhost:8000 port where your Django project will be running from.
  1. You will need the generated dummy ngrok URL while creating Africa’s Talking USSD API

Creating Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sign up if you don’t have an account with Africa’s Talking.
  2. While on that page, click on the link labelled “create a channel” to create a USSD code
  3. You will be prompted with the pop up below:
  1. Enter a unique dummy channel, e.g. 58965
  2. Your U.S.S.D. Code is now, e.g. *384*58965#
  3. In the callback URL, paste the ngrok http URL you created above; after appending “/api/ussd_callback/” at the end of the URL, e.g. http://21f3bf1b511a.ngrok.io/api/ussd_callback/, we will create this “/api/ussd_callback/” A.P.I. later on in the Django project.
  4. Click on Create Channel

Getting started with the Web App

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 “djangohospitalappointment”, type the command: django-admin startproject djangohospitalappointment
  3. From the terminal, navigate into the created project folder, where you will create and activate your project’s virtual environment by typing in the terminal the command “python –m venv venv”
  4. In windows, type “venv\Scripts\activate” in the terminal
  5. In Mac/Linux, type ”source venv/bin/activate” in the terminal
  6. After your virtual environment has been activated, run the code below in the terminal to install the following python packages
    • “pip install requests”: python package used in managing HTTP requests
    • “pip install django”: python package to be used in building the web app
    • “pip install django-crispy-forms”: to be used rendering bootstrap styles in HTML templates
    • “pip install djangorestframework”: python package used in creating REST A.P.I.s
  7. Create your first Django app by typing in the terminal the command: “python manage.py startapp users”
  8. Create your first Django app by typing in the terminal the command: “python manage.py startapp hospital”
  9. Create an SQLite database that the project will use by typing in the terminal the command: “python manage.py makemigrations”
  10. Apply database changes by typing in the terminal the command: “python manage.py migrate”
  11. Start your server by typing on the terminal the command: “python manage.py runserver”
  12. If the server starts successfully, there should be a webpage up and running on the location: http://127.0.0.1:8000
  13. While in the terminal, type Ctrl+C to stop the server
  14. Everything from now on will be performed inside this python activated environment.

We are stopping the server to create the database tables first and then apply the changes before restarting the server.

Creating Project CSS File

  1. Open the Django project folder your code editor
  2. Open the “hospital” app folder
  3. In the “hospital” app folder, create a folder labelled “static”
  4. Inside the created “static” folder, create another folder labelled “hospital.”
  5. Inside the “hospital” folder just created inside the “static” folder, create a CSS file labelled “main.css”
  6. Copy the code below into the “main.css” file.

Configure Django Project Settings

  1. Open your Django project folder: “djangohospitalappointment”
  2. Locate a folder with a similar name to your Django project folder; this folder is in the same directory as your “users” app folder
  3. Inside this folder is a python file labelled “settings.py”
  4. Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file.
  5. Inside the ALLOWED_HOSTS, enter the ngrok URL created as well as the localhost URL, this is a security measure by Django to ensure that the web app can only be accessed via the set URLs. Below is an example of how to do so:
  1. Inside the “settings.py” file, locate the variable INSTALLED_APPS
  2. The variable installed_apps is a list where you will register the apps we just created
  3. Insert the code below inside the list:
  1. We also need to register the Django crispy form python package that we will use to beautify our HTML pages, inside the INSTALLED_APPS python list paste the code below:
  1. We also need to register the Django rest framework app that we will use to manage and create the project A.P.I.s; inside the INSTALLED_APPS python list, paste the code below:
  1. We also need to inform crispy to use bootstrap 4 in its rendering of HTML elements; to do this paste, the code below at the end/bottom of the settings.py file:
  1. Data is sent from Africa’s Talking U.S.S.D. A.P.I. to our Django project A.P.I. in the form “Content-Type: application/x-www-form-urlencoded”. We have to inform our Django A.P.I. to expect data to be sent to it in this format as the default format Django rest framework A.P.I. expects data is JSON format.
  2. Data should also be sent back from our Django A.P.I. to Africa’s Talking USSD A.P.I. in a string format or as plain text. Django rest framework A.P.I. sends data out in JSON format by default, we have to inform or configure our A.P.I. to send data in plain text and not JSON format.
  3. To perform the above actions, paste the code below at the bottom or end of the settings.py file:

Creating Database Tables

  1. Open your Django project folder in your code editor
  2. We will start by creating database tables related to the “users” app we created, which are:

Doctors Table Logic

  • This table will hold the doctors’ details and will inherit from the built-in Django “Users” table but add an extra field not available in the “Users” table, which is:

phone_number –This column will hold the doctor’s mobile number

Patients Table Logic

  • This table will have the patients’ details and will inherit from the built-in Django “Users” table but add an extra field not available in the “Users” table, which is:

phone_number –This column will hold the patient’s mobile number

To create the above “users” tables in your project folder, navigate into the “users” folder and open a file labelled “models.py” and paste the code below:

  1. We now create the database tables related to the “hospitals” app we created, which are:

Services Table Logic

This table will hold the services offered by the hospital details and will inherit from the built-in Django “models.Model” class that is used to convert a python class to a database table. It will have the following fields:

name –This column will hold the name of the service

description –This column will hold a brief description of the service

__str__ –This is a method in the class “Services” class we will create that will be responsible for returning the string representation of objects or table records created in the Services table. The string representation method will return the name of the service

Doctor Services Table Logic

This table will hold the services that each doctor offers in the hospital and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

service –This column will create a relationship with the service table on the specific service the doctor provides

doctor – This column will create a relationship with the doctor’s table on the particular doctor that offers the service

__str__ –This is a method in the class “DoctorServices” class we will create that will be responsible for returning the string representation of objects or table records created in the “DoctorServices” table. The string representation method will return the full name of the doctor and the name of the service they provide.

Doctor Time Slots Table Logic

This table will hold the time slots each doctor has designated to provide consultation for a particular service they offer in the hospital and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

doctor_service –This column will create a relationship with the “DoctorServices” table on the specific service the doctor provides

start_date – The start date of the day they will be available for consultations or appointments

start_date – The end date of the day they will be available for consultations or appointments

__str__ – This is a method in the class “DoctorTimeSlots” class we will create that will be responsible for returning the string representation of objects or table records created in the “DoctorTimeSlots” table. The string representation method will return the full name of the doctor and the start date of the time slot.

Appointments Table Logic

This table will hold the time slots each doctor has designated to provide consultation for a particular service they offer in the hospital and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

doctor_time_slots –This column will create a relationship with the “DoctorTimeSlots” table on the specific date slot a patient has booked an appointment

patient – This column will create a relationship with the “Patients” table on the specific patient that has booked an appointment for a specific date

__str__ – This is a method in the class “Appointments” class we will create that will be responsible for returning the string representation of objects or table records created in the “Appointments” table. The string representation method will return the full name of the patient and the start date of the time slot booked for the appointment.

To create the above “hospital” tables in your project folder, navigate into the “hospital” folder and open a file labelled “models.py” and paste the code below:

Apply Database Changes

  1. In your terminal, ensure you have activated 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 your business logic for Users App

These are the functions that the web app URLs will execute in order to return a HTML page. They are usually placed in a file called “views.py” that is available in both the”users” app and “hospital” app. Do the following to edit this file in the “users” app:

  1. Open the “users” app folder
  2. Locate a python file labelled “views.py”
  3. Paste the code below:

Views Code Logic

We start by importing the following methods:

  • Reverse – This method is used to return the URL representation of python URL pattern path name
  • CreateView – This is a Django built in class that can be used to create a database table entry by associating it with another class
  • UpdateView– This is a Django built in class that can be used to update a database table entry by associating it with another class
  • ListView – This is a Django built in class that can be used to return a list of records from a specified database table, hence converting the class inheriting from this class to a list view to be used on a HTML page
  • DeleteView – This is a Django built in class that can be used to delete a database record entry by associating it with another class, via inheriting from this class
  • Patients and Doctors – The two database tables or models we created

We now build the views/functions or methods below:

  • Patients Create View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “CreateView” class. In this class, we have to specify the model or database table the class will work with which is the “Patients”, the fields it’s to work with, which are ‘first_name’, ‘last_name’, ‘phone_number’, ’email’, ‘username’, the template that will render the data/form.

The class will also override its superclass method “get_context_data”, what this method does, is that it allows us to get access to the data that will be passed to the template before it’s sent to the template for rendering, the data is passed as a context object. After getting access to the context we add a new object variable with a value in it and return back the context.

We also override a super-class method called “get_success_url” that will be used to return the URL page a user is to be redirected to after they successfully create a patient in the database.

  • Patients List View – This is a class-based view or a class that inherits its functionalities from another class view, in this case django’s built in “ListView” class. In this class we have to specify the model or database table the class will work with which is the “Patients” and the template that will render the data.

The class will also override its super class method “get_context_data”, so as to allow us to get access to the data that will be passed to the template.

  • Patients Delete View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “DeleteView” class. In this class we have to specify the model or database table the class will work with which is the “Patients”, set a success URL which is the URL a user is to be redirected to after successful data deletion and the template that will render the data.

The class will also override its super class method “get_context_data”, to allow us to get access to the data that will be passed to the template.

  • Patients Update View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “UpdateView” class. In this class we have to specify the model or database table the class will work with which is the “Patients”, the fields it’s to work with which are ‘first_name’, ‘last_name’, ‘phone_number’, ’email’, ‘username’, the template that will render the data/form.

The class will also override its super class method “get_context_data”, to allow us to get access to the data that will be passed to the template.

The above views will also be replicated in the creation of the Doctors views table

Creating your business logic for Hospital App

We will now create the business logic in the “views.py” file located in the “hospital” app folder. Below is how to do so:

  1. Open the “hospital” app folder
  2. Locate a python file labelled “views.py”
  3. Paste the code below

Views Code Logic

We start by importing the following methods:

  • Reverse – This method is used to return the URL representation of python URL pattern path name
  • Render – This method is used to return a HTML page to the user
  • CreateView – This is a Django built in class that can be used to create a database table entry by associating it with another class
  • UpdateView– This is a Django built in class that can be used to update a database table entry by associating it with another class
  • ListView – This is a Django built in class that can be used to return a list of records from a specified database table, hence converting the class inheriting from this class to a list view to be used on a HTML page
  • DeleteView – This is a Django built in class that can be used to delete a database record entry by associating it with another class, via inheriting from this class
  • Services, DoctorServices, DoctorTimeSlots and Appointments – The four hospital database tables or models we created

We now build the views/functions or methods below:

  • Home – This is a method or function view that accepts a web request and returns the index HTML page render
  • Services Create View – This is a class-based view or a class that inherits its functionalities from django’s built in “CreateView” class. In this class we have to specify the model or database table the class will work with which is the “Services”, the fields it’s to work with which are ‘name’ and ‘description’, the template that will render the data/form.

The class will also override its super-class method “get_context_data”, what this method does, is it allows us to get access to the data that will be passed to the template before it’s sent to the template for rendering; the data is passed as a context object. After getting access to the context, we add a new object variable with a value in it and return the context back.

We also override a super-class method called “get_success_url” that will be used to return the URL page a user is to be redirected to after they successfully create a patient in the database.

  • Services List View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “ListView” class. In this class we have to specify the model or database table the class will work with which is the “Services” and the template that will render the data.

The class will also override its super class method, “get_context_data”, to allow us to get access to the data that will be passed to the template.

  • Services Delete View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “DeleteView” class. In this class we have to specify the model or database table the class will work with which is the “Services”, set a success URL which is the URL a user is to be redirected to after successful data deletion and the template that will render the data.

The class will also override its super class method “get_context_data”, to allow us to get access to the data that will be passed to the template.

  • Patients Update View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “UpdateView” class. In this class we have to specify the model or database table the class will work with which is the “Services”, the fields it’s to work with which are ‘name’ and ‘description’, the template that will render the data/form.

The class will also override its super class method “get_context_data”, to allow us to get access to the data that will be passed to the template.

The above views will also be replicated in the creation of the Doctor Services, Doctor Time Slots, Doctor Time Slots and Appointments views.

Creating the Django Project A.P.I.

This is the A.P.I. that will interact with Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Inside your Django project folder: “djangohospitalappointment”
  2. Create a folder called “api” which will be in the same directory as your “users” app folder and “hospital” app folder
  3. Inside this ”api” folder create the following files:
    • __init__.py –  an empty python file to inform Django that “api” folder is a python package
    • renders.py – a python file that will be used to inform Django rest framework how to render or send data back to Africa’s Talking U.S.S.D. A.P.I. below is the code to paste inside this file:
    • urls.py – a python file that will be used to map the Django project A.P.I. inside the views.py file to a URL that the Africa’s Talking USSD API will access; below is the code to paste inside this file:
    • views.py – a python file that will hold the A.P.I. method that is responsible for sending back data; below is the code to paste inside this file:

Creating “Users” HTML Templates

  1. On these HTML templates are 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:
    • confirm_delete.html – This is the page to be used for asking a user to confirm that they want to delete a specific data record
    • user_detail.html – This is the page where user details will be displayed, it will be used to create or update user data, i.e. patients and doctors
    • users_list.html – This page will be used to display a list of either patients or doctors
  3. To create the above “users” HTML templates, do the following:
    • In your project folder, navigate into the “users” folder.
    • Create a folder labelled “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; confirm_delete.html, user_detail.html and users_list.html.
  4. Below is a screenshot of the “users” directory tree:

Creating “Hospital” HTML Templates

  1. On these HTML templates are where the different users’ data will be displayed.
  2. We will start by creating HTML templates related to the “hospital” app we created, which are:
    • index.html – The default home page for the web app with brief instructions on how the web app works
    • base.html – This is the page that will be inherited/extended by all other HTML template pages
    • appointments_detail.html – This page will be used to display the details of the doctor appointments made
    • appointments_list.html – This page will be used to display a list of appointments made
    • doctor_services_detail.html – This page will be used to display the details of a specific service a doctor provides
    • doctor_services_list.html – This page will be used to display a list of the services each doctor provides
    • doctor_time_slots_detail.html – This page will be used to display the details of the time slots the doctor will offer the service
    • doctor_time_slots_list.html – This page will be used to display a list of time slots set aside by doctors for consultations or appointments
    • services_detail.html – This page will be used to display the details a specific service
    • services_list.html – This page will be used to display a list of services offered by the hospital
  3. To create the above “hospital” HTML templates, do the following:
    • In your project folder, navigate into the “hospital” folder.
    • Create a folder labelled “templates.”
    • Inside the “templates” folder, create another folder and label it “hospital.”
    • Inside the “hospital” folder you have just created inside the “templates” folder.
    • Create the following blank HTML pages; index.html, base.html, appointments_list.html, doctor_services_detail.html, doctor_services_list.html, doctor_time_slots_detail.html, doctor_time_slots_list.html, services_detail.html, services_list.html and appointments_detail.html
  4. Below is a screenshot of the “hospital” directory tree:

Creating the “Users” App URLs

These are the URLs that the user will use to navigate the “users” web app. They are usually placed in a file called “urls.py”. Do the following to create/edit this file:

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

Creating the “Hospital” App URLs

These are the URLs that will be used by the user to navigate the “hospital” web app. They are usually placed in a file called “urls.py”. Do the following to create/edit this file:

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

Configure Project URLs

This is where the URLs that point to each Django app and A.P.I. are placed to be accessible from a browser. They are usually placed in a file called “urls.py”. Do the following to create/edit this file:

  1. Open your Django project folder: “djangohospitalappointment”
  2. Locate a folder with a similar name to your Django project folder; this folder is in the same directory as your “users” app folder
  3. Open the “djangohospitalappointment” folder that is inside the Django project folder
  4. Locate/create a python file labelled “urls.py”
  5. Paste the code below

Project Tree

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

Run the server

  1. cd/navigate into the “djangohospitalappointment” Django project via the terminal
  2. Activate the virtual environment by typing the command: “venv\Scripts\activate”
  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. Go to the web page address, e.g. http://127.0.0.1:8000, or to the ngrok URL you had created.
  3. Follow the instructions on the home page on how to test the system.

NB: If you had quit or closed the ngrok terminal, after creating the URL, restarting the ngrok app terminal will lead to the creation of a new ngrok URL. You will need to update Africa’s Talking U.S.S.D. A.P.I. call back with this new URL, and you will also need to update the python variable ALLOWED_HOSTS inside the settings.py file located inside the folder labelled “djangohospitalappointment”

Conclusion

You should now have a basic understanding of how Africa’s Talking U.S.S.D. A.P.I. works and how to implement them in Python, while working in Django. The article not only provides a guide on how to implement U.S.S.D. APIs on web applications but also on other applications that Python can be applied to.

Further improvements could be done on the project such as allowing doctors to create specific times in a day for consultations instead of only a day; new “walk-in” patients can use the U.S.S.D. to register themselves to a hospital and book an appointment etc.

Finally, 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:

  1. Clone it:
    • git clone https://bitbucket.org/dans0l/djangohospitalappointment.git
  2. Cd into it:
    • cd djangohospitalappointment
  3. Create a venv:
    • python3 -m venv venv
  4. Activate venv:
    • Mac/Linux: source venv/bin/activate
    • Windows: 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. Create a Ngrok URL:
    • Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup; you will then be prompted to sign up to download the application, go ahead and do so.
    • Download and start/run the application
    • After running the Ngrok application, you will see the ngrok terminal window.
    • Go back to the Ngrok web page where you downloaded the application (the link is displayed above) and navigate to the section labelled “Connect your account”
    • Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal
    • Inside the Ngrok terminal, type the command “ngrok http 8000”
    • A ngrok shell window will be displayed, with the name of the newly created ngrok http URL e.g. http://21f3bf1b511a.ngrok.io
    • Do not close or quit this ngrok shell
  9. Configure your Africa’s Talking U.S.S.D. A.P.I.:
    • Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sign up if you don’t have an account with Africa’s Talking.
    • While on that page, click on the link labelled “create a channel” to create a USSD code
    • Enter a unique dummy channel, e.g. 58965
    • Your U.S.S.D. Code is now, e.g. *384*58965#
    • In the callback URL paste the ngrok http URL you created above; after appending “/api/ussd_callback/” at the end of the URL e.g. http://21f3bf1b511a.ngrok.io/api/ussd_callback/ this “/api/ussd_callback/” A.P.I. has already been created in the Django project.
    • Click on Create Channel
  10. Configure the Django Project to use the created ngrok url:
    • Open your Django project folder: “djangohospitalappointment”
    • Locate a folder with a similar name to your Django project folder; this folder is in the same directory as your “users” app folder
    • Inside this folder is a python file labelled “settings.py”
    • Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file.
    • Inside the ALLOWED_HOSTS list, enter the ngrok URL you created as well as the localhost URL; it should resemble something like this: ALLOWED_HOSTS = [‘127.0.0.1′,’21f3bf1b511a.ngrok.io’]
  11. Run the server:
    • python manage.py runserver
  12. Navigate to the site: http://127.0.0.1:8000
  13. Follow the instructions on the home page to start using the site

Please Let me know how your experience was, Thank you.

1 Shares:
You May Also Like