Overview
The GradingService is the main API for the Gradebook tool in Sakai LMS. It provides methods for managing gradebook items, recording grades, calculating course grades, and managing categories.
Package: org.sakaiproject.grading.api
Source: /gradebookng/api/src/main/java/org/sakaiproject/grading/api/GradingService.java
Constants
public static final MathContext MATH_CONTEXT = new MathContext(10, RoundingMode.HALF_DOWN);
public static final String[] INVALID_CHARS_AT_START_OF_GB_ITEM_NAME = { "#", "*", "[" };
Permission Checking
currentUserHasGradeAllPerm
Check if the current user has permission to grade all students.
public boolean currentUserHasGradeAllPerm(String gradebookUid);
The gradebook UID (usually the site ID)
true if the user has gradebook.gradeAll permission
currentUserHasGradingPerm
Check if the current user has any form of grading privileges.
public boolean currentUserHasGradingPerm(String gradebookUid);
true if the user has grading privileges (grade all, grade section, etc.)
currentUserHasEditPerm
Check if the current user can edit gradebook settings and items.
public boolean currentUserHasEditPerm(String gradebookUid);
true if the user has gradebook.editAssignments permission
currentUserHasViewOwnGradesPerm
Check if the current user can view their own grades.
public boolean currentUserHasViewOwnGradesPerm(String gradebookUid);
true if the user has gradebook.viewOwnGrades permission
Gradebook Management
getGradebook
Retrieve a gradebook by its UID, creating it if it doesn’t exist.
public Gradebook getGradebook(String uid, String siteId);
The unique identifier of the gradebook
The site ID used for context when creating new gradebooks
Gradebook, or null if it cannot be found/created
Example:
Gradebook gradebook = gradingService.getGradebook(siteId, siteId);
if (gradebook != null) {
System.out.println("Gradebook: " + gradebook.getName());
System.out.println("Grade type: " + gradebook.getGradeType());
}
addGradebook
Create a new gradebook.
public Gradebook addGradebook(String uid, String name);
The unique identifier for the gradebook
The display name for the gradebook
Gradebook
deleteGradebook
Delete a gradebook and all associated data.
public void deleteGradebook(String uid);
The gradebook UID to delete
public GradebookInformation getGradebookInformation(String gradebookUid, String siteId);
GradebookInformation object containing gradebook settings
Example:
GradebookInformation info = gradingService.getGradebookInformation(siteId, siteId);
System.out.println("Grade entry type: " + info.getGradeType());
System.out.println("Categories enabled: " + info.getCategoriesEnabled());
Assignment/Item Management
getAssignments
Get all assignments in a gradebook.
public List<Assignment> getAssignments(
String gradebookUid,
String siteId,
SortType sortBy
);
The sort order for assignments
Assignment objects
Example:
List<Assignment> assignments = gradingService.getAssignments(
siteId,
siteId,
SortType.SORT_BY_DATE
);
for (Assignment a : assignments) {
System.out.println(a.getName() + ": " + a.getPoints() + " points");
}
getAssignment
Get a specific assignment by ID.
public Assignment getAssignment(
String gradebookUid,
String siteId,
Long assignmentId
) throws AssessmentNotFoundException;
Assignment object
Throws: AssessmentNotFoundException if the assignment doesn’t exist
addAssignment
Add a new gradebook item.
public Long addAssignment(
String gradebookUid,
String siteId,
Assignment assignmentDefinition
);
The assignment definition with properties set
Assignment assignment = new Assignment();
assignment.setName("Midterm Exam");
assignment.setPoints(100.0);
assignment.setDueDate(new Date());
assignment.setCounted(true);
assignment.setReleased(true);
Long assignmentId = gradingService.addAssignment(siteId, siteId, assignment);
System.out.println("Created assignment with ID: " + assignmentId);
updateAssignment
Update an existing gradebook item.
public void updateAssignment(
String gradebookUid,
String siteId,
Long assignmentId,
Assignment assignmentDefinition
);
The ID of the assignment to update
The updated assignment properties
removeAssignment
Remove a gradebook item.
public void removeAssignment(Long assignmentId)
throws StaleObjectModificationException;
The assignment ID to remove
StaleObjectModificationException if there’s a concurrent modification
Grade Management
getGradeDefinitionForStudentForItem
Get a student’s grade for a specific item.
public GradeDefinition getGradeDefinitionForStudentForItem(
String gradebookUid,
String siteId,
Long assignmentId,
String studentUid
) throws AssessmentNotFoundException;
GradeDefinition object, or null if no grade exists
Example:
GradeDefinition grade = gradingService.getGradeDefinitionForStudentForItem(
siteId, siteId, assignmentId, studentId
);
if (grade != null) {
System.out.println("Grade: " + grade.getGrade());
System.out.println("Grader: " + grade.getGraderUid());
}
public void saveGradeAndCommentForStudent(
String gradebookUid,
String siteId,
Long assignmentId,
String studentId,
String grade,
String comment
) throws InvalidGradeException, AssessmentNotFoundException;
The grade (must match gradebook’s grade entry type)
InvalidGradeException - If the grade format is invalidAssessmentNotFoundException - If the assignment doesn’t exist
Example:
try {
gradingService.saveGradeAndCommentForStudent(
siteId, siteId, assignmentId, studentId,
"85", "Good work!"
);
} catch (InvalidGradeException e) {
System.err.println("Invalid grade format");
}
public void saveGradesAndComments(
String gradebookUid,
String siteId,
Long assignmentId,
List<GradeDefinition> gradeDefList
) throws InvalidGradeException, AssessmentNotFoundException;
gradeDefList
List<GradeDefinition>
required
List of grade definitions with student IDs and grades
List<GradeDefinition> grades = new ArrayList<>();
for (String studentId : studentIds) {
GradeDefinition gd = new GradeDefinition();
gd.setStudentUid(studentId);
gd.setGrade("85");
gd.setGradeComment("Good work");
grades.add(gd);
}
gradingService.saveGradesAndComments(siteId, siteId, assignmentId, grades);
isGradeValid
Check if a grade string is valid for the gradebook.
public boolean isGradeValid(String gradebookUid, String grade);
true if the grade is valid given the gradebook’s grade entry type
getGradeEntryType
Get the grade entry type for a gradebook.
public Integer getGradeEntryType(String gradebookUid);
Category Management
getCategoryDefinitions
Get all categories for a gradebook.
public List<CategoryDefinition> getCategoryDefinitions(
String gradebookUid,
String siteId
);
CategoryDefinition objects (empty list if no categories)
Example:
List<CategoryDefinition> categories = gradingService.getCategoryDefinitions(siteId, siteId);
for (CategoryDefinition cat : categories) {
System.out.println(cat.getName() + ": " + cat.getWeight() + "%");
}
getCategoryDefinition
Get a specific category by ID.
public Optional<CategoryDefinition> getCategoryDefinition(
Long categoryId,
String siteId
);
CategoryDefinition if found
updateCategory
Update a category.
public void updateCategory(CategoryDefinition category);
category
CategoryDefinition
required
The updated category definition
removeCategory
Remove a category.
public void removeCategory(Long categoryId)
throws StaleObjectModificationException;
The category ID to remove
calculateCategoryScore
Calculate a student’s score for a category.
public Optional<CategoryScoreData> calculateCategoryScore(
Long gradebookId,
String studentUuid,
Long categoryId,
boolean includeNonReleasedItems,
Integer categoryType,
Boolean equalWeightAssignments
);
Whether to include non-released items
Whether assignments are equally weighted
Course Grade
getCourseGradeForStudent
Get the course grade for a student.
public CourseGradeTransferBean getCourseGradeForStudent(
String gradebookUid,
String siteId,
String userUuid
);
CourseGradeTransferBean for the student
Example:
CourseGradeTransferBean courseGrade = gradingService.getCourseGradeForStudent(
siteId, siteId, studentId
);
System.out.println("Course grade: " + courseGrade.getDisplayGrade());
System.out.println("Points earned: " + courseGrade.getPointsEarned());
updateCourseGradeForStudent
Set a course grade override for a student.
public void updateCourseGradeForStudent(
String gradebookUid,
String siteId,
String studentUuid,
String grade,
String gradeScale
);
External Assessment Integration
addExternalAssessment
Add an external assessment (e.g., from Assignments or Tests & Quizzes) to the gradebook.
public void addExternalAssessment(
String gradebookUid,
String siteId,
String externalId,
String externalUrl,
String title,
Double points,
Date dueDate,
String externalServiceDescription,
String externalData,
Boolean ungraded,
Long categoryId,
String gradableReference
) throws ConflictingAssignmentNameException, ConflictingExternalIdException,
AssignmentHasIllegalPointsException, InvalidCategoryException;
The external ID from the source tool
URL to the external assessment
Maximum points for the assessment
externalServiceDescription
Description of the external service (e.g., “Assignments”)
Additional data the external service wishes to store
Whether this is an ungraded item
The category ID (null for no category)
Reference to the gradable object
gradingService.addExternalAssessment(
siteId, siteId,
"assignment-123",
"/direct/assignment/123",
"Essay Assignment",
100.0,
new Date(),
"Assignments",
null,
false,
null,
"/assignment/a/" + siteId + "/123"
);
updateExternalAssessmentScore
Update a score for an external assessment.
public void updateExternalAssessmentScore(
String gradebookUid,
String siteId,
String externalId,
String studentUid,
String points
) throws AssessmentNotFoundException;
The external ID of the assessment
The points earned, or null to remove the score
Complete Example
import org.sakaiproject.grading.api.*;
import java.util.*;
public class GradebookExample {
private GradingService gradingService;
public void manageGradebook(String siteId) {
// Get or create gradebook
Gradebook gradebook = gradingService.getGradebook(siteId, siteId);
// Create a category
CategoryDefinition category = new CategoryDefinition();
category.setName("Exams");
category.setWeight(50.0);
// Add a gradebook item
Assignment assignment = new Assignment();
assignment.setName("Midterm Exam");
assignment.setPoints(100.0);
assignment.setDueDate(new Date());
assignment.setCounted(true);
assignment.setReleased(true);
Long assignmentId = gradingService.addAssignment(siteId, siteId, assignment);
// Grade students
Map<String, String> studentGrades = new HashMap<>();
studentGrades.put("student1", "85");
studentGrades.put("student2", "92");
for (Map.Entry<String, String> entry : studentGrades.entrySet()) {
try {
gradingService.saveGradeAndCommentForStudent(
siteId, siteId, assignmentId,
entry.getKey(),
entry.getValue(),
"Good work!"
);
} catch (InvalidGradeException e) {
System.err.println("Invalid grade for " + entry.getKey());
} catch (AssessmentNotFoundException e) {
System.err.println("Assignment not found");
}
}
// Get course grade
CourseGradeTransferBean courseGrade =
gradingService.getCourseGradeForStudent(siteId, siteId, "student1");
System.out.println("Course grade: " + courseGrade.getDisplayGrade());
}
}
See Also