Context
Schools have used ManageBac's powerful Attendance module to allow teachers to mark students as present, absent, and any other school-defined custom attendance category. With the release in July 2024 of the new endpoint "Set Student Homeroom Attendance" it is now possible to integrate homeroom attendance records recorded by external providers. For example, a card system located in school entrances can automatically populate ManageBac with the details, marking the student as "Present" for that day, and will be shown to the student's classroom teachers.
This article provides some guidelines on usage and examples of common patterns.
Please note that integrating homeroom attendance data with ManageBac requires some programming knowledge and understanding of APIs to accomplish.
Getting Started
Formal documentation for the "Set Homeroom Attendance" endpoint is located in ManageBac's "API Documentation" and can be found under the "Students" category. (Note that retrieving homeroom attendance is found under the "Year Group" category.)
The endpoint is per-student, where `id` is the internal database ID of the student:
PUT /v2/students/:id/set_homeroom_attendance
Note that the PUT signifies that the call must use the PUT verb (not the default GET) and it expects a JSON payload that includes an single object with `id` and a `date`.
{
"id": 1234567890,
"date": "2024-08-01",
"status": 1,
"notes": "Optional string — a comment"
}
The above would set the student represented by the id `1234567890` in ManageBac's database to "Present" for August 1st, 2024.
The status field
The `status` is the ID of the attendance category, where for all schools, two of them are always the same:
- Status ID of `0` represents the default category "Absent", and an attendance record of this kind indicates that the student was not physically present, and should be counted against the student when tabulating attendance records.
- Status ID of `1` represents the default category "Present," and this attendance record is the most common record, indicating that the student was physically present.
All remaining category IDs have a suggested meaning in ManageBac, as indicated in the documentation:
Please note that the strings "Present," "Late" and "Dress Code" are the default presets and can be changed and customized by ManageBac administrators at any time. The exact semantic meaning of categories from 2 for all programs and above are context-dependent and up to the school to decide.
What counts as "Absent"?
Schools that use Attendance Module and Reporting Module together use the `0` attendance category as the only attendance record that is counted against a student. Some schools change the `0` category to be "Unexcused Absence," and create a custom category "Excused Absence" in order to differentiate between "The student was not physically at school with permission" and "The student was absent."
Also in that case, all other categories above `0` are not to be counted against when tabulating final attendance records. However, some attendance records, such as "Late" or "Dress Code" may carry negative connotations. As stated, however, all categories above `1` are custom to each school, and can be different across curricula.
About Attendance Categories
When integrating homeroom attendance, it may be necessary to understand attendance categories at a deeper level, although the endpoint itself just accepts an integer from 0 to 18, inclusive.
The attendance categories are defined in ManageBac's Attendance Settings, and can be different per curriculum program. For example, the attendance categories for Middle School, High School, IB Diploma, and Cambridge can either be identical (when the settings are set to be identical) or be changed on a per-curricula basis.
Students are associated to academic programs, which determines the category sets that apply to a given student.
Validation of attendance records
ManageBac does not validate the submitted attendance records, except to ensure that the date passed is a real date. For example, ManageBac will reject a submitted attendance record for May 32nd, because that is not a valid date. If date is invalid, the API will respond with `422` response code.
The endpoint will not reject an attendance record for dates outside of the school calendar. Also note that, in the frontend, attendance records are filtered by ManageBac by when applicable term begins and ends, according to the school settings. In other words, the endpoint accepts any valid date, and whether or not it is displayed to users on the front-end depends on school settings and term begin and end dates, which can change at any time.
It also does not reject an attendance record for `status` or attendance categories that are disabled.
Retrieving the records
The attendance records added via the above endpoint can be fetched at the following endpoint:
`GET /v2/year-groups/:id/homeroom/attendance/date/:date`
Note that this endpoint retrieves all attendance records for the given date in the given year group. The attendance records themselves will include the status string, i.e. "Present" or "Late".
Cumulative attendance for an entire term can be obtained at the following endpoint:
`GET /v2/year-groups/:id/homeroom/attendance/term/:term_id`
And the response will include an attendance record that reports that total for each category for which there is a record with a given status.