Overview
The AssignmentService is the main service interface for managing assignments and student submissions in Sakai LMS. Each assignment has associated content and a list of student submissions.
Package: org.sakaiproject.assignment.api
Source: /assignment/api/src/java/org/sakaiproject/assignment/api/AssignmentService.java
Permission Checking
allowAddAssignment
Check if the current user can add an assignment in the specified context.
public boolean allowAddAssignment(String context);
The portlet context (site ID)
true if the user can add assignments, false otherwise
Example:
if (assignmentService.allowAddAssignment(siteId)) {
// Show "Add Assignment" button
}
allowUpdateAssignment
Check if the current user can update a specific assignment.
public boolean allowUpdateAssignment(String assignmentReference);
The assignment’s reference string
true if the user can update the assignment, false otherwise
allowGradeSubmission
Check if the current user can grade submissions for an assignment.
public boolean allowGradeSubmission(String assignmentReference);
The assignment’s reference string
true if the user can grade submissions, false otherwise
allowAddSubmission
Check if the current user can submit to assignments in the specified context.
public boolean allowAddSubmission(String context);
The portlet context (site ID)
true if the user can submit assignments, false otherwise
Assignment Management
addAssignment
Create a new assignment in the specified context.
public Assignment addAssignment(String context) throws PermissionException;
The site ID for this assignment
Assignment object ready for editing
Throws: PermissionException if the user lacks permission
Example:
try {
Assignment assignment = assignmentService.addAssignment(siteId);
assignment.setTitle("Essay Assignment");
assignment.setInstructions("Write a 500-word essay...");
assignment.setMaxGradePoint(100);
assignment.setDueDate(Instant.now().plus(7, ChronoUnit.DAYS));
assignmentService.updateAssignment(assignment);
} catch (PermissionException e) {
log.error("Permission denied creating assignment", e);
}
addDuplicateAssignment
Create a duplicate of an existing assignment.
public Assignment addDuplicateAssignment(
String context,
String assignmentId
) throws IdInvalidException, PermissionException, IdUsedException, IdUnusedException;
The context for the new assignment
The ID of the assignment to duplicate
Assignment object, or null if the original doesn’t exist
Example:
Assignment duplicate = assignmentService.addDuplicateAssignment(
siteId,
originalAssignmentId
);
duplicate.setTitle(duplicate.getTitle() + " (Copy)");
assignmentService.updateAssignment(duplicate);
getAssignment
Retrieve an assignment by its ID.
public Assignment getAssignment(String assignmentId)
throws IdUnusedException, PermissionException;
Assignment object
Throws:
IdUnusedException - If no assignment exists with this IDPermissionException - If the user lacks read permission
Example:
try {
Assignment assignment = assignmentService.getAssignment(assignmentId);
System.out.println("Title: " + assignment.getTitle());
System.out.println("Due: " + assignment.getDueDate());
} catch (IdUnusedException e) {
log.error("Assignment not found: " + assignmentId);
}
updateAssignment
Update an existing assignment.
public void updateAssignment(Assignment assignment) throws PermissionException;
The assignment object with updated properties
PermissionException if the user lacks permission
deleteAssignment
Permanently delete an assignment.
public void deleteAssignment(Assignment assignment) throws PermissionException;
PermissionException if the user lacks permission
softDeleteAssignment
Soft delete an assignment (mark as deleted without removing from database).
public void softDeleteAssignment(Assignment assignment) throws PermissionException;
The assignment to soft delete
PermissionException if the user lacks permission
getAssignmentsForContext
Get all non-deleted assignments for a site.
public Collection<Assignment> getAssignmentsForContext(String context);
Assignment objects
Example:
Collection<Assignment> assignments = assignmentService.getAssignmentsForContext(siteId);
for (Assignment a : assignments) {
System.out.println(a.getTitle() + " - Due: " + a.getDueDate());
}
Submission Management
addSubmission
Create a new submission for an assignment.
public AssignmentSubmission addSubmission(
String assignmentId,
String submitter
) throws PermissionException;
The submitter’s user ID (can be a group ID for group submissions)
AssignmentSubmission, or null if creation failed
Throws: PermissionException if the user lacks permission
Example:
try {
AssignmentSubmission submission = assignmentService.addSubmission(
assignmentId,
userId
);
submission.setSubmittedText("My submission text...");
assignmentService.updateSubmission(submission);
} catch (PermissionException e) {
log.error("Cannot create submission", e);
}
getSubmission
Get a submission by assignment and submitter.
public AssignmentSubmission getSubmission(
String assignmentReference,
String submitterId
) throws PermissionException;
The user or group ID of the submitter
AssignmentSubmission, or null if none exists
Example:
String assignmentRef = assignmentService.assignmentReference(siteId, assignmentId);
AssignmentSubmission submission = assignmentService.getSubmission(
assignmentRef,
userId
);
if (submission != null) {
System.out.println("Submitted: " + submission.getDateSubmitted());
System.out.println("Grade: " + submission.getGrade());
}
getSubmissions
Get all submissions for an assignment.
public Set<AssignmentSubmission> getSubmissions(Assignment assignment);
AssignmentSubmission objects for the assignment
Example:
Assignment assignment = assignmentService.getAssignment(assignmentId);
Set<AssignmentSubmission> submissions = assignmentService.getSubmissions(assignment);
System.out.println("Total submissions: " + submissions.size());
updateSubmission
Update an existing submission.
public void updateSubmission(AssignmentSubmission submission)
throws PermissionException;
submission
AssignmentSubmission
required
The submission with updated properties
PermissionException if the user lacks permission
removeSubmission
Remove a submission and all references to it.
public void removeSubmission(AssignmentSubmission submission)
throws PermissionException;
submission
AssignmentSubmission
required
The submission to remove
PermissionException if the user lacks permission
Grading
getGradeForSubmitter
Get the effective grade for a submitter on a submission.
public String getGradeForSubmitter(
AssignmentSubmission submission,
String submitter
);
submission
AssignmentSubmission
required
The overall submission
The individual submitter ID
for (AssignmentSubmissionSubmitter submitter : submission.getSubmitters()) {
String grade = assignmentService.getGradeForSubmitter(
submission,
submitter.getSubmitter()
);
System.out.println(submitter.getSubmitter() + ": " + grade);
}
getGradeDisplay
Format a grade for display according to the assignment’s grade type.
public String getGradeDisplay(
String grade,
Assignment.GradeType typeOfGrade,
Integer scaleFactor
);
typeOfGrade
Assignment.GradeType
required
The grade type (SCORE_GRADE_TYPE, LETTER_GRADE_TYPE, etc.)
The scale factor for decimal places
getGradesSpreadsheet
Generate a grades spreadsheet for assignments.
public byte[] getGradesSpreadsheet(String ref)
throws IdUnusedException, PermissionException;
Reference to a specific assignment or assignment context
IdUnusedException - If the reference doesn’t existPermissionException - If the user lacks access
getSubmissionsZip
Generate a ZIP file containing all submissions for an assignment.
public void getSubmissionsZip(
OutputStream out,
String ref,
String queryString
) throws IdUnusedException, PermissionException;
The output stream to write the ZIP file to
Optional query string for filtering
Utility Methods
assignmentReference
Get the internal reference for an assignment.
public String assignmentReference(String context, String id);
canSubmit
Check if a user can submit to an assignment.
public boolean canSubmit(Assignment assignment, String userId);
The user ID (blank checks current user)
true if the user can submit, false otherwise
getDeepLink
Get a deep link directly into an assignment.
public String getDeepLink(
String context,
String assignmentId,
String userId
) throws Exception;
Complete Example
import org.sakaiproject.assignment.api.*;
import org.sakaiproject.assignment.api.model.*;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
public class AssignmentExample {
private AssignmentService assignmentService;
public void createAndGradeAssignment(String siteId) {
try {
// Create assignment
Assignment assignment = assignmentService.addAssignment(siteId);
assignment.setTitle("Week 1 Essay");
assignment.setInstructions("Write a 500-word essay on...");
assignment.setTypeOfSubmission(Assignment.SubmissionType.TEXT_AND_ATTACHMENT_ASSIGNMENT_SUBMISSION);
assignment.setTypeOfGrade(Assignment.GradeType.SCORE_GRADE_TYPE);
assignment.setMaxGradePoint(100);
// Set dates
Instant now = Instant.now();
assignment.setOpenDate(now);
assignment.setDueDate(now.plus(7, ChronoUnit.DAYS));
assignment.setCloseDate(now.plus(14, ChronoUnit.DAYS));
assignmentService.updateAssignment(assignment);
// Student submits
String studentId = "student123";
if (assignmentService.canSubmit(assignment, studentId)) {
AssignmentSubmission submission = assignmentService.addSubmission(
assignment.getId(),
studentId
);
submission.setSubmittedText("Here is my essay...");
submission.setSubmitted(true);
submission.setDateSubmitted(Instant.now());
assignmentService.updateSubmission(submission);
}
// Instructor grades
String instructorId = "instructor456";
if (assignmentService.allowGradeSubmission(assignment.getId())) {
AssignmentSubmission submission = assignmentService.getSubmission(
assignment.getId(),
studentId
);
submission.setGrade("85");
submission.setGraded(true);
submission.setGradedBy(instructorId);
submission.setDateGraded(Instant.now());
submission.setFeedbackText("Good work! Consider adding more detail...");
assignmentService.updateSubmission(submission);
}
// List all submissions
Set<AssignmentSubmission> submissions =
assignmentService.getSubmissions(assignment);
for (AssignmentSubmission sub : submissions) {
System.out.println("Submitter: " + sub.getSubmitters());
System.out.println("Grade: " + sub.getGrade());
System.out.println("Submitted: " + sub.getDateSubmitted());
}
} catch (PermissionException e) {
System.err.println("Permission denied: " + e.getMessage());
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
See Also