evaluations

Learner satisfaction evaluation system — a topic catalog targeting courses, lessons, sessions, questions, or exams, and the paginated rating responses collected against those topics.

Source path: libraries/lms/src/evaluation

Module file: evaluation.module.ts

Introduction

The Evaluations submodule is HedHog LMS's satisfaction-survey layer. An evaluation topic is a question template (e.g. "Was the content clear?") tagged with a `targetType` — course, course_lesson, course_class_session, question, or exam — that determines which kind of entity learners can rate against it. Topics are explicitly orderable (`PATCH /topics/reorder`) so the admin panel can control the sequence learners see when rating, and are protected against deletion once they have collected ratings (`422 Unprocessable Entity`), preserving the integrity of historical survey data.

`GET /lms/evaluations` is the cross-cutting query surface: it returns individual rating responses with rich filtering by course, class, instructor, evaluator, and date range, and enriches each row with a `topicAvgScore`/`topicRatingCount` pair so the admin UI can show an individual response alongside its topic's aggregate for context. `GET /lms/evaluations/filter-options` derives the available dropdown values (courses, classes, instructors, evaluators) directly from topics that already have ratings, so filter menus never show options with zero results.

Notably, `EvaluationService` also implements `getCourseLessonTopics`, `getMyLessonRatings`, and `submitLessonRatings` — the actual learner-facing submission flow — but these are not exposed by `EvaluationController` or by this submodule's MCP tools; they are consumed by the Platforma student portal (`GET/POST /lms/platforma/lessons/:lessonId/evaluation-topics`, `/my-evaluation`, `/evaluate`) instead, since `EvaluationService` is exported from `EvaluationModule` for cross-module use.

HTTP Endpoints

9 endpoints

Overall stats: total evaluations, average score, topics evaluated, total evaluators.

Paginated list of evaluation topics.

Query: page, pageSize, search, targetType

Creates an evaluation topic.

Body

Field	Type	Required	Notes
name	string	yes	Max 255 chars
targetType	'course' \| 'course_lesson' \| 'course_class_session' \| 'question' \| 'exam'	yes	—
description	string	no	—
order	number	no	Min 0
isActive	boolean	no	—

Gets a topic by ID; 404 if missing.

Params: id (int)

Reorders topics to match the index position of each ID in the array.

Body

Field	Type	Required	Notes
ids	number[]	yes	—

Updates a topic (all fields optional).

Params: id (int)

Deletes a topic; 422 if it already has ratings.

Params: id (int)

Paginated list of evaluation rating responses with topic-aggregate context.

Query: page, pageSize, search, courseId, classId, instructorId, evaluatorId, dateFrom, dateTo

MCP Tools

Named tools callable by AI models via the Model Context Protocol (MCP).

lms.evaluations.list
Lists evaluations with optional filters (course, class, instructor, evaluator, date range)
lms.evaluations.stats
Returns aggregate evaluation statistics
lms.evaluations.filter-options
Returns available filter options for the evaluations list (courses, instructors, evaluators)
lms.evaluations.topics.list
Lists evaluation topics with optional pagination and filters
lms.evaluations.topics.get
Returns a single evaluation topic by ID
lms.evaluations.topics.create
Creates a new evaluation topic
lms.evaluations.topics.update
Updates an existing evaluation topic
lms.evaluations.topics.delete
Deletes an evaluation topic by ID
lms.evaluations.topics.reorder
Reorders evaluation topics