April 23rd, 2021

This page contains

• Introduction to OpenEMIS features
• How to install OpenEMIS with Docker
• The three parts of the OpenEMIS Docker application
• How to configure OpenEMIS for the first time

If you already have an installation of OpenEMIS up and running and you just want to configure it, skip to the section titled Configuring OpenEMIS.

What is OpenEMIS?

OpenEMIS is an open-source data-management software package for education management. It was developed with support from UNESCO. It is a tool that be used to build sustainable education data-management systems. It can be implemented in many different ways, and this enables it to be configured for various different contexts, in both the global North and the global South. The software has many useful features that make life easier for system administrators and education authorities.

Bulk importing of data

The bulk-importer lets you import student and teacher data from an Excel spreadsheet or a csv file. This enables you to quickly migrate data from an old system without needing to manually type the data.

Managing user permissions for administrators, schools and donors

With the User/Group/Role module, the administrator can easily manage access permissions for each user. This enables them to grant access to specific schools, and specific types of student information. This can let them make school-statistics available to donors, while keeping personal student information only available to school managers.

The software is open-source

Since the community edition of the software is open-source, it is free to install and use. This helps to make the system financially accessible for low-resource projects.

Insufficient documentation for OpenEMIS configuration

The problem I found with it was that it’s very difficult to configure for first use. The project has a website https://support.openemis.org/core/en/home-en where you can find documentation explaining how to work with the software once it’s installed and configured. The documentation is quite good for this, but I found that there isn’t enough documentation explaining how to install the system, and how to configure it so that it is ready for you to enter school data and student data. If it’s not configured correctly, it gives cryptic 404 error messages, which quickly gets very frustrating.

OpenEMIS as part of a sustainable data-management system

I recently built a sustainable data-management platform for a regional education authority in Thailand. Change is inevitable in software systems and information systems, so a sustainable system must be able to be adapted and modified easily without relying on external support. The goal for this system was to create a secure online system that could then be handed over to the local IT team, who would maintain it and change it as the education-system changes.

In order to maintain the system, the local IT team needed to easily see how the platform was configured. To help make it easier for them to maintain, I wrote documentation so they could see the steps for how to configure OpenEMIS. The documentation is below. Hopefully it will be helpful for another low-resource education project and it’ll help more people to collect high-quality data and make it easier for them to show the impact.

How to install OpenEMIS

Warning: The following steps will install the OpenEMIS system on a local development server using port 80. To use the system on a production server, you will also need to configure an SSL certificate to encrypt the data.

For this project, I carried out the OpenEMIS installation using a Docker container available through Docker hub. This is an official release maintained by the OpenEMIS team, so it is likely that the project will continue to be maintained for the long-term.

Install Docker

Docker is a technology that lets you run an application inside your computer. It makes life a lot easier for developers because you can set server configurations in one file and quickly get a project up and running. Once you have docker installed, you can use it to install OpenEMIS.

The OpenEMIS Docker project has instructions for how to install Docker on your computer/server, and how to use Docker to get the OpenEMIS app: https://hub.docker.com/r/openemis/core

With Docker installed, run docker pull openemis/core This will pull the OpenEMIS application from the docker-hub repository and install it on your server. You can see the application running by typing docker-compose up -d and visiting http://localhost:8082 By default, the OpenEMIS docker container runs on port 8082.

To stop the application, type docker-compose down

You can change the port to port 80 by editing the <project-directory>/core/docker-compose.yaml file. You should only use port 80 for a development server. When you deploy to a production server, you will need to use port 443 and an SSL certificate before deploying OpenEMIS to a production server.

You can quickly set the application to listen on port 80 by changing the docker-compose.yaml to the following (you’ll need to turn off Apache2 if it’s installed, so that it’s not listening on port 80):

ports:
    - "80:80"

A better way to set it up is to make an Apache virtual host with port forwarding, forwarding port 80 to port 8082, the default port for docker.

First, install mod_proxy and other requirements

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod lbmethod_byrequests

Next, update the virtual host to forward port 80 to port 8082.

#/etc/apache2/sites-available/openemis.conf
<VirtualHost *:80>
    ServerAdmin webmaster@localhost

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8082/
    ProxyPassReverse / http://127.0.0.1:8082/

    <Directory /var/www/html/>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

    <IfModule mod_dir.c>
        DirectoryIndex index.php index.pl index.cgi index.html index.xhtml index.htm
    </IfModule>
</VirtualHost>

The docker-compose.yaml can stay at its default, listening on port 8082.

#/var/www/openemis/core/docker-compose.yaml
ports:
    - "8082:80"

The OpenEMIS Docker application

There are three parts to the OpenEMIS docker project.

1. The OpenEMIS PHP application
   • This is where the code of the application is stored. You access it by visiting http://localhost and logging in. When you log in for the first time, you can use the default administrator login account.
   • Username: admin
   • Password: demo
2. MySQL database
   • The MySQL database stores the data for your application. It will store the schools, students, and system configurations
3. phpMyAdmin
   • This is an application that lets you connect to your MySQL database using your web-browser. You can use it by visiting http://localhost:8083 and logging in. When you log in for the first time, you can use the default administrator login account.
   • Username: admin
   • Password: demo

Configuring OpenEMIS

If all has gone well, you will see the OpenEMIS login page and you will be able to log in to OpenEMIS using the default administrator login account (username: admin password: demo). You have successfully deployed the system, but you’ll need to configure it in order for it to work correctly.

Below are the steps I took to configure the system for first-time use. They are based on OpenEMIS Version 3.27.0, so they might be a little different if you are using a different version.

Set the Field Options

1. Open Administration > System Setup > Field Options
2. Select Identity Types in the dropdown menu.
3. Create a list of all the identity cards and identity documents that you want to use to identity Students and Staff in the database.
4. Select Nationalities in the dropdown menu.
5. Create a list of all the nationalities of Students and Staff.
6. It looks like you can only select one identity type for each nationality. I’m not sure how to add more, but it would be useful to be able to have multiple IDs for each person.
7. Select Staff Position Grades in the dropdown menu.
8. List the pay-grades for staff. If you are not storing pay-grades in the database, just add one called Pay Scale 1
9. Select Staff Position Titles in the dropdown menu.
10. List the types of roles staff can have.
11. Create Teacher with Type as Teaching
12. Create Director  with Type as Non-teaching

Set up administrative boundaries

• First, you’ll set up the geographical boundaries for your implementation.
• Create Country, Region and District as your levels.

• Your first Area will be the Country. Create a new country and name it Thailand. Expect to be confused when you save it! It won’t show on the list, even though it has been saved to the database.
• Next, create the regions in Thailand. Click on the [+] button to create a new Area. You’ll see that its parent is set as Thailand, which is the country you created earlier.
• To create a District inside the Region, click on the Region name. You’ll see an empty list where you can add the District name. The [parent] will be pre-filled with the name of the Region you chose.

Set up the Academic Periods

Configure the academic periods. These are typically years. In Thailand, these usually run from April to March. It’s easiest if you name them by the year when they started, even though they stretch over two different years.

Configure the Education Structure

Before you can start adding in Schools and Students, you’ll need to set up the education structure with the grades and different education-types that you want the database to store.

I used https://demo.openemis.org/core/Educations/Systems a lot during this to understand how things fit together.

Set up the Field of Study

Open Administration > Education Structures > Setup

Education Programme Orientation

• The purpose of the education programme.
• Create one entry General

Field of Study

• The field that will be studied in the programme
• Create one entry General and select General as the Education Programme Orientation

Certification

• The certificates that the students can earn  
• Create several entries, including one entry for No Certificate

Stages

• The education stages that the student goes through
• I don’t really understand what the difference is between Education Stages here and the Grades that are filled in later on in the Grades tab. In demo.openemis.org they are the same. It probably allows for more flexibility than what’s needed for this implementation.

Subjects

• The list of all the subjects that are taught
• Add each of the subjects

1. Open Administration > Education Structures > Systems
2. Create a new entry: National Education System
3. Click the Levels tab. Select National Education System and enter the list of education levels.
4. Click the Cycles tab. Select an education level and choose the cycles for the level. If the level only has one cycle, just enter one here.
5. Click the Programmes tab. Here you enter information about the programmes that are available for each cycle. In the demo.openemis.org there is only one programme per cycle, and only one cycle per level, so I think this just needs to be one programme per cycle.
6. Click the Grades tab. This is the list of all the grades (usually one grade per year) that students will take while they are in the programme.
7. Click the Grade Subjects tab. This is the list of all the subjects that are studied in each grade. If you have Auto Allocation set as Yes then a student will be automatically enrolled for this subject when they enrol in the Grade.

Create a new school

1. In OpenEMIS, schools are called ‘Institutions’. Select Institutions and click [+].
2. The Area Education field needs to have a Country selected at this point. I’m not really sure why it doesn’t allow me to select a region or district.
3. The Area Administrative field needs to be left blank. I’m not sure why.
4. The other fields are clear.
5. Click [Save] and the school will be saved.
6. Click on the new school. You’ll see empty graphs and a list on the left.

Set the programmes, subjects and classes available at the school

1. Click on your new school and select Academic > Programmes on the left sidebar.
2. Fill in the Level, Programme and Start Date and select the grades that students take at the school.
3. Click on Shifts and select the times when lessons are taught at the school. I’m not sure exactly how to fill this in correctly, but I think it would be First Shift from morning till lunch, and Second Shift from lunch till finish. I don’t understand why it’s asking for Location here, but I just selected This Institution.
4. Click on  Classes and fill in the number of different classes of students for each of the Grades. If there are two Kindergarten 1 classes, choose Number of classes as 2. You can then give each of the classes a unique name.

Create a student

1. Select your school and click Student in the left sidebar.
2. To add a Staff member or a Student, you must first search for them. This ensures that you aren’t creating a duplicate entry for someone who is already in your database.
3. Type the first name of the student and click Filter. The Create New Student button will appear in the upper right corner. Click it. Fill in the student details, assign the student to a class and click [Complete].  

Set up Security permissions for different Users

OpenEMIS give fine-tuned permissions in the Roles module. You assign certain permissions to a role (for example, view Institution, add Student, but do not edit Institition). Think of the Role as a set of permissions, and the Group as a set of schools. When you assign the User to the Group, you then give them a Role to give them a set of permissions that they can do within that Group. You can assign the same user to different Groups, and give them a different Role in each group. That way, you can give User1 permissions (Role) to view and edit schools in Group1, but only view schools in Group2 without being allowed to edit schools in Group2.

It take a little bit of time to get used to the way it works, but once you understand it it’s quite easy to work with.

How to create a new user and grant access to view all students in ThaiSchool1 and ThaiSchool2 but not MyanmarSchool1 or MyanmarSchool2.

First, create the user

1. Administration > Security > Users > +
2. Create a new user with a username and password

Now, you set the permissions by creating a Role. (Remember, Role is the OpenEMIS term for permissions).

• Administration > Security > Roles > System Roles > +
• Create a Role with a sensible name. Since this user can view some of the schools but not all, I created a role called District Partner

• In the Actions column beside your new role, select Permissions. In the grid, you see red crosses. These are permissions that are currently revoked. To grant permissions to view institutions that are assigned to the user’s group, click the edit (pencil) button and check the [Institutions > View] checkbox. Click [Save].

You will see a green check to show that the permission has been granted.

Next, you create a Group of schools for the user. Remember, a Group is the OpenEMIS term for a collection of schools.

Create a group for users who can see ThaiSchool1 and ThaiSchool2 but not MyanmarSchool1 or MyanmarSchool2.

1. Administration > Security > Groups > User Roles > +
2. Create a new group with a sensible name. In this example, the users in the group can see the Thai schools (ThaiSchool1 and ThaiSchool2) but not the Myanmar schools (MyanmarSchool1 and MyanmarSchool2). Therefore, I created a group called ThaiSchools.
3. Add the schools to the list that the user is allow to see:
   • Add Institutions > [Type ThaiSchool1] > Select ThaiSchool1 from list
   • Add Institutions > [Type ThaiSchool2] > Select ThaiSchool2 from list
4. Finally, with the User, Role and Group created, you add the User to the Group, give them a Role and you’re done!
   • Add the user to the group and select their role as ‘District Partner’
   • Add User > [Type User Name] > Select User from list > [Select ‘District Partner’ from the Roles dropdown list]

Conclusion

OpenEMIS is a flexible software suite that you can use to build a sustainable data-management system. It’s particularly useful for a low-resource setting, such as refugee data-management in a developing country. While it involves some technical expertise to set up the server with a virtual host, Docker container and an SSL certificate, it’s relatively easy to configure and maintain once the software has been installed. This empowers IT teams to maintain systems themselves without needing external support whenever a new feature needs to be added. With this article, I hope that you were able to start testing OpenEMIS to see if it would be a good fit for your data-management system. Hopefully it makes it easier for you to collect better, more-reliable data.