Getting Started with the ManageBac API and Students

ManageBac is a powerful CMS (Curriculum Management System) that offers a lot of structure to the delivery of the IB program. Thankfully, it also includes a fairly comprehensive API system, which, while not as capable as you may like, it is still powerful enough to drive certain tasks forward.

Building a Local Database

In order to work with the ManageBac API, you need to pull the ManageBac IDs from their system. These IDs are unique to ManageBac and do not correlate to the other unique IDs you may have already provided, including student number and email.

Originally, I wrote the integration in Python with a MySQL database, however, when developing the Houses APP, I rewrote the API integration in Node.js and MongoDB, utilizing Mongoose.

As student information and fields can be want to change, as a result of the adoption of new platforms, as well as new demands from the government, I felt that MongoDB was a positive solution, allowing the flexibility to further develop the Student Model as needed.

At the moment, I’m unsure on ManageBac’s policy for sharing API reference materials. Therefore, I’ve left out the specific API calls.

Mongoose Student Schema

Below, I’ve included the schema used for students. The fields yeargrouID, homeroomID (this is actually the Homeroom teacher’s ID), and mbID are unique to ManageBac.

const StudentSchema = mongoose.Schema({
  firstName: {
    type: String,
    required: true
  },
  lastName: {
    type: String,
    required: true
  },
  otherName: {
    type: String
  },
  email: {
    type: String,
    required: true,
    unique: true
  },
  mbID: {
    type: Number,
    required: true,
    unique: true
  },
  studentID: {
    type: String,
    required: true,
    unique: true
  },
  archived: {
    type: Boolean,
    required: true
  },
  classGrade: {
    type: String
  },
  gender: {
    type: String
  },
  photoURL: {
    type: String
  },
  homeroomID: {
    type: Number
  },
  yeargroupID: {
    type: Number
  }
});

The UTF-8 Conundrum

International schools frequently have student names in non-Roman script, requiring a UTF-8 document to properly encode their information. Unfortunately, ManageBac’s student import CSV is plain text, it is not compatible with UTF-8, and attempts to use UTF-8 result in the document being rejected because of how the headings are formatted. As a result, it is not possible to upload Chinese names by CSV file directly into ManageBac.

Therefore, one frequent application is to upload/update fields in MB through the API. In fact, it is quite convenient to do so through this method, as you don’t need to edit the full student list and handpick students. Rather, you can choose one unique field, either student ID or email, and then populate the other columns with the fields that you would like to update.

Updating Student Info

Here is a quick segment of code that will call MB and update the student’s nicknames. A simple next step is to read the headings and patch in the updated values. This would offer greater flexibility to the program and simplicity of use for the end user. As it is – it is not particularly difficult to use and manipulate.

const axios = require("axios");
const csv = require("csv-parser");
const fs = require("fs");
const Student = require("../models/Student");

const nameUpdate = async () => {
  try {
    const mbConfig = {
      responseType: "stream",
      headers: {
        "auth-token":
          "**************************************************",
        "content-type": "application/json",
      },
    };
    const results = [];
    fs.createReadStream("srv/tmp/nicknames.csv")
      .pipe(csv())
      .on("data", (data) => results.push(data))
      .on("end", async () => {
        for (let x = 0; x < results.length; x++) {
          let stu = await Student.find({ email: results[x].EMAIL });
          console.log(
            `${results[x].EMAIL} will have their nickname set to ${results[x].NICKNAME}`
          );
          await axios.patch(
            `**************************************************`,
            {
              nickname: results[x].NICKNAME,
            },
            mbConfig
          );
        }
      });
  } catch (err) {
    console.error(err.message);
  }
};

module.exports = nameUpdate;

I hope that this was useful and interesting – offering some insight in how to begin development around the ManageBac API.