org.sakaiproject.service.gradebook.shared

Interface GradebookService

public interface GradebookService

This is the externally exposed API of the gradebook application. This interface is principally intended for clients of application services -- that is, clients who want to "act like the Gradebook would" to automate what would normally be done in the UI, including any authorization checks. As a result, these methods may throw security exceptions. Call the service's authorization-check methods if you want to avoid them.

WARNING: For documentation of the deprecated methods, please see the service interfaces which own them.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	GradebookService.PointsPossibleValidation An enum for defining valid/invalid information for a points possible/relative weight value for a gradebook item.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CATEGORY_TYPE_NO_CATEGORY
static int	CATEGORY_TYPE_ONLY_CATEGORY
static int	CATEGORY_TYPE_WEIGHTED_CATEGORY
static String	enableLetterGradeString
static int	GRADE_TYPE_LETTER Deprecated.
static int	GRADE_TYPE_PERCENTAGE Deprecated.
static int	GRADE_TYPE_POINTS Deprecated.
static String	gradePermission Deprecated.
static String[]	INVALID_CHARS_AT_START_OF_GB_ITEM_NAME Array of chars that are not allowed at the beginning of a gb item title
static Comparator<String>	lettergradeComparator Comparator to ensure correct ordering of letter grades, catering for + and - in the grade This is duplicated in GradebookNG.
static MathContext	MATH_CONTEXT
static String	noPermission Deprecated.
static String[]	validLetterGrade
static String	viewPermission Deprecated.

Method Summary

Modifier and Type	Method and Description
Long	addAssignment(String gradebookUid, Assignment assignmentDefinition) Create a new Gradebook-managed assignment.
Optional<CategoryScoreData>	calculateCategoryScore(Long gradebookId, String studentUuid, Long categoryId, boolean includeNonReleasedItems, int categoryType, Boolean equalWeightAssignments) Calculate the category score for the given gradebook, student and category, looking up the grades.
Optional<CategoryScoreData>	calculateCategoryScore(Object gradebook, String studentUuid, CategoryDefinition category, List<Assignment> categoryAssignments, Map<Long,String> gradeMap, boolean includeNonReleasedItems) Calculate the category score for the given gradebook, category, assignments in the category and grade map.
boolean	checkStudentsNotSubmitted(String gradebookUid) Check if there are students that have not submitted
boolean	currentUserHasEditPerm(String gradebookUid)
boolean	currentUserHasGradeAllPerm(String gradebookUid) Check if the current user has the gradebook.gradeAll permission
boolean	currentUserHasGradingPerm(String gradebookUid)
boolean	currentUserHasViewOwnGradesPerm(String gradebookUid)
boolean	currentUserHasViewStudentNumbersPerm(String gradebookUid)
void	finalizeGrades(String gradebookUid) Finalize the gradebook's course grades by setting all still-unscored assignments to zero scores.
Assignment	getAssignment(String gradebookUid, Long assignmentId) Get an assignment based on its id
Assignment	getAssignment(String gradebookUid, String assignmentName) Deprecated. Use getAssignment(String,Long) instead.
Assignment	getAssignmentByNameOrId(String gradebookUid, String assignmentName) Get an assignment based on its name or id.
List<Assignment>	getAssignments(String gradebookUid)
List<Assignment>	getAssignments(String gradebookUid, SortType sortBy)
CommentDefinition	getAssignmentScoreComment(String gradebookUid, Long assignmentId, String studentUid) Get the comment (if any) currently provided for the given combination of student and assignment.
String	getAssignmentScoreString(String gradebookUid, Long assignmentId, String studentUid) Get student's assignment's score as string.
String	getAssignmentScoreString(String gradebookUid, String assignmentName, String studentUid) Deprecated. See getAssignmentScoreString(String, Long, String)
String	getAssignmentScoreStringByNameOrId(String gradebookUid, String assignmentName, String studentUid) Get student's assignment's score as string.
String	getAverageCourseGrade(String gradebookUid) Computes the Average Course Grade as a letter.
List	getCategories(Long gradebookId) Deprecated.
List<CategoryDefinition>	getCategoryDefinitions(String gradebookUid) Get the categories for the given gradebook
CourseGrade	getCourseGradeForStudent(String gradebookUid, String userUuid) Get the course grade for a student
Map<String,CourseGrade>	getCourseGradeForStudents(String gradebookUid, List<String> userUuids) Get the course grade for a list of students
Map<String,CourseGrade>	getCourseGradeForStudents(String gradebookUid, List<String> userUuids, Map<String,Double> schema) Get the course grade for a list of students using the given grading schema
Map<String,String>	getEnteredCourseGrade(String gradebookUid) Get a Map of overridden CourseGrade for students.
Assignment	getExternalAssignment(String gradebookUid, String externalId)
Object	getGradebook(String uid) Get the Gradebook.
Set	getGradebookGradeMappings(Long gradebookId) Return the GradeMappings for the given gradebook.
Set	getGradebookGradeMappings(String gradebookUid) Return the GradeMappings for the given gradebook.
GradebookInformation	getGradebookInformation(String gradebookUid)
GradeDefinition	getGradeDefinitionForStudentForItem(String gradebookUid, Long assignmentId, String studentUid)
int	getGradeEntryType(String gradebookUid)
List<GradeDefinition>	getGradesForStudentsForItem(String gradebookUid, Long assignmentId, List<String> studentIds) Get the grade records for the given list of students and the given assignment.
Map<Long,List<GradeDefinition>>	getGradesWithoutCommentsForStudentsForItems(String gradebookUid, List<Long> gradableOjbectIds, List<String> studentIds) This method gets grades for multiple gradebook items with emphasis on performance.
String	getGradeViewFunctionForUserForStudentForItem(String gradebookUid, Long assignmentId, String studentUid) Check to see if current user may grade or view the given student for the given item in the given gradebook.
List	getGradingEvents(List<Long> assignmentIds, Date since) Return the grade changes made since a given time
List	getGradingEvents(String studentId, long assignmentId) Gets the grading events for the given student and the given assignment
boolean	getIsAssignmentExcused(String gradebookUid, Long assignmentId, String studentUid)
String	getLowestPossibleGradeForGbItem(String gradebookUid, Long assignmentId)
List<Assignment>	getViewableAssignmentsForCurrentUser(String gradebookUid)
List<Assignment>	getViewableAssignmentsForCurrentUser(String gradebookUid, SortType sortBy)
List	getViewableSections(String gradebookUid) Get a list of CourseSections that the current user has access to in the given gradebook.
Map<String,String>	getViewableSectionUuidToNameMap(String gradebookUid) Using the grader permissions, return map of section uuid to section name that includes all sections that the current user may view or grade
Map<String,String>	getViewableStudentsForItemForCurrentUser(String gradebookUid, Long assignmentId)
Map<String,String>	getViewableStudentsForItemForUser(String userUid, String gradebookUid, Long assignmentId)
List<String>	identifyStudentsWithInvalidGrades(String gradebookUid, Map<String,String> studentIdToGradeMap)
boolean	isAssignmentDefined(String gradebookUid, String assignmentTitle) Check to see if an assignment with the given name already exists in the given gradebook.
boolean	isGradableObjectDefined(Long gradableObjectId) Check if a gradeable object with the given id exists
boolean	isGradebookDefined(String gradebookUid) Checks to see whether a gradebook with the given uid exists.
boolean	isGradeValid(String gradebookUuid, String grade)
GradebookService.PointsPossibleValidation	isPointsPossibleValid(String gradebookUid, Assignment assignment, Double pointsPossible)
boolean	isUserAbleToGradeItemForStudent(String gradebookUid, Long assignmentId, String studentUid) Check to see if the current user is allowed to grade the given item for the given student in the given gradebook.
boolean	isUserAbleToViewItemForStudent(String gradebookUid, Long assignmentId, String studentUid) Check to see if the current user is allowed to view the given item for the given student in the given gradebook.
boolean	isUserAllowedToGrade(String gradebookUid, String userUid)
boolean	isUserAllowedToGradeAll(String gradebookUid, String userUid) Check if the given user is allowed to grade all students in this gradebook
boolean	isValidNumericGrade(String grade) Determines if the given string contains a valid numeric grade.
void	removeAssignment(Long assignmentId) Removes an assignment from a gradebook.
void	removeCategory(Long categoryId) remove category from gradebook
void	saveGradeAndCommentForStudent(String gradebookUid, Long assignmentId, String studentId, String grade, String comment) Save a student score and comment for a gradebook item.
void	saveGradeAndExcuseForStudent(String gradebookUid, Long assignmentId, String studentId, String grade, boolean excuse)
void	saveGradesAndComments(String gradebookUid, Long assignmentId, List<GradeDefinition> gradeDefList) Given a list of GradeDefinitions for students for a given gradebook and gradable object, will save the associated scores and comments.
void	setAssignmentScoreComment(String gradebookUid, Long assignmentId, String studentUid, String comment) Provide a student-viewable comment on the score (or lack of score) associated with the given assignment.
void	setAssignmentScoreString(String gradebookUid, Long assignmentId, String studentUid, String score, String clientServiceDescription) Set student's score for assignment.
void	setAssignmentScoreString(String gradebookUid, String assignmentName, String studentUid, String score, String clientServiceDescription) Deprecated. See setAssignmentScoreString(String, Long, String, String, String)
Map<String,String>	transferGradebook(GradebookInformation gradebookInformation, List<Assignment> assignments, String toGradebookUid, String fromContext) Transfer the gradebook information and assignments from one gradebook to another
void	updateAssignment(String gradebookUid, Long assignmentId, Assignment assignmentDefinition) Modify the definition of an existing Gradebook item.
void	updateAssignmentCategorizedOrder(String gradebookUid, Long categoryId, Long assignmentId, Integer order) Updates the categorized order of an assignment
void	updateAssignmentOrder(String gradebookUid, Long assignmentId, Integer order) Update the ordering of an assignment.
void	updateCourseGradeForStudent(String gradebookUid, String studentUuid, String grade) Allows an instructor to set a course grade override for the given student
void	updateGradebookSettings(String gradebookUid, GradebookInformation gbInfo) Update the settings for this gradebook

Field Detail

GRADE_TYPE_POINTS

@Deprecated
static final int GRADE_TYPE_POINTS

Deprecated.

See Also:

Constant Field Values

GRADE_TYPE_PERCENTAGE

@Deprecated
static final int GRADE_TYPE_PERCENTAGE

Deprecated.

See Also:

Constant Field Values

GRADE_TYPE_LETTER

@Deprecated
static final int GRADE_TYPE_LETTER

Deprecated.

See Also:

Constant Field Values

CATEGORY_TYPE_NO_CATEGORY

static final int CATEGORY_TYPE_NO_CATEGORY

See Also:

Constant Field Values

CATEGORY_TYPE_ONLY_CATEGORY

static final int CATEGORY_TYPE_ONLY_CATEGORY

See Also:

Constant Field Values

CATEGORY_TYPE_WEIGHTED_CATEGORY

static final int CATEGORY_TYPE_WEIGHTED_CATEGORY

See Also:

Constant Field Values

validLetterGrade

static final String[] validLetterGrade

gradePermission

@Deprecated
static final String gradePermission

Deprecated.

viewPermission

@Deprecated
static final String viewPermission

Deprecated.

noPermission

@Deprecated
static final String noPermission

Deprecated.

enableLetterGradeString

static final String enableLetterGradeString

See Also:

Constant Field Values

MATH_CONTEXT

static final MathContext MATH_CONTEXT

INVALID_CHARS_AT_START_OF_GB_ITEM_NAME

static final String[] INVALID_CHARS_AT_START_OF_GB_ITEM_NAME

Array of chars that are not allowed at the beginning of a gb item title

lettergradeComparator

static final Comparator<String> lettergradeComparator

Comparator to ensure correct ordering of letter grades, catering for + and - in the grade This is duplicated in GradebookNG. If changing here, please change there as well. TODO combine them

Method Detail

isGradebookDefined

boolean isGradebookDefined(String gradebookUid)

Checks to see whether a gradebook with the given uid exists.

Parameters:

gradebookUid - The gradebook UID to check

Returns:

Whether the gradebook exists

isUserAbleToGradeItemForStudent

boolean isUserAbleToGradeItemForStudent(String gradebookUid,
                                        Long assignmentId,
                                        String studentUid)

Check to see if the current user is allowed to grade the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

Parameters:

gradebookUid -

assignmentId -

studentUid -

isUserAbleToViewItemForStudent

boolean isUserAbleToViewItemForStudent(String gradebookUid,
                                       Long assignmentId,
                                       String studentUid)

Check to see if the current user is allowed to view the given item for the given student in the given gradebook. This will give clients a chance to avoid a security exception.

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

getGradeViewFunctionForUserForStudentForItem

String getGradeViewFunctionForUserForStudentForItem(String gradebookUid,
                                                    Long assignmentId,
                                                    String studentUid)

Check to see if current user may grade or view the given student for the given item in the given gradebook. Returns string representation of function per GradebookService vars (view/grade) or null if no permission

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

GradebookService.gradePermission, GradebookService.viewPermission, or null if no permission

getAssignments

List<Assignment> getAssignments(String gradebookUid)
                         throws GradebookNotFoundException

Returns:

Returns a list of Assignment objects describing the assignments that are currently defined in the given gradebook.

Throws:

GradebookNotFoundException

getAssignments

List<Assignment> getAssignments(String gradebookUid,
                                SortType sortBy)
                         throws GradebookNotFoundException

Returns:

Returns a list of Assignment objects describing the assignments that are currently defined in the given gradebook, sorted by the given sort type.

Throws:

GradebookNotFoundException

getAssignment

Assignment getAssignment(String gradebookUid,
                         Long assignmentId)
                  throws AssessmentNotFoundException

Get an assignment based on its id

Parameters:

gradebookUid -

assignmentId -

Returns:

the associated Assignment with the given assignmentId

Throws:

AssessmentNotFoundException

getAssignment

@Deprecated
Assignment getAssignment(String gradebookUid,
                                     String assignmentName)
                              throws AssessmentNotFoundException

Deprecated. Use getAssignment(String,Long) instead.

Get an assignment based on its name. This is provided for backward compatibility only.

Parameters:

gradebookUid -

assignmentName -

Returns:

the associated Assignment with the given name

Throws:

AssessmentNotFoundException

getExternalAssignment

Assignment getExternalAssignment(String gradebookUid,
                                 String externalId)
                          throws GradebookNotFoundException

Throws:

GradebookNotFoundException

getAssignmentByNameOrId

Assignment getAssignmentByNameOrId(String gradebookUid,
                                   String assignmentName)
                            throws AssessmentNotFoundException

Get an assignment based on its name or id. This is intended as a migration path from the deprecated getAssignment(String,String) to the new getAssignment(String,Long) This method will attempt to lookup the name as provided then fall back to the ID as a Long (If it is a Long) You should use getAssignment(String,Long) if you always can use the Long instead.

Parameters:

gradebookUid -

assignmentName -

Returns:

the associated Assignment with the given name

Throws:

AssessmentNotFoundException

getGradeDefinitionForStudentForItem

GradeDefinition getGradeDefinitionForStudentForItem(String gradebookUid,
                                                    Long assignmentId,
                                                    String studentUid)
                                             throws GradebookNotFoundException,
                                                    AssessmentNotFoundException

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

Returns a GradeDefinition for the student, respecting the grade entry type for the gradebook (ie in %, letter grade, or points format). Returns null if no grade

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreComment

CommentDefinition getAssignmentScoreComment(String gradebookUid,
                                            Long assignmentId,
                                            String studentUid)
                                     throws GradebookNotFoundException,
                                            AssessmentNotFoundException

Get the comment (if any) currently provided for the given combination of student and assignment.

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

null if no comment is avaailable

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getIsAssignmentExcused

boolean getIsAssignmentExcused(String gradebookUid,
                               Long assignmentId,
                               String studentUid)
                        throws GradebookNotFoundException,
                               AssessmentNotFoundException

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScoreComment

void setAssignmentScoreComment(String gradebookUid,
                               Long assignmentId,
                               String studentUid,
                               String comment)
                        throws GradebookNotFoundException,
                               AssessmentNotFoundException

Provide a student-viewable comment on the score (or lack of score) associated with the given assignment.

Parameters:

gradebookUid -

assignmentId -

studentUid -

comment - a plain text comment, or null to remove any currrent comment

Throws:

GradebookNotFoundException

AssessmentNotFoundException

isAssignmentDefined

boolean isAssignmentDefined(String gradebookUid,
                            String assignmentTitle)
                     throws GradebookNotFoundException

Check to see if an assignment with the given name already exists in the given gradebook. This will give clients a chance to avoid the ConflictingAssignmentNameException. This is not deprecated as we currently need the ability to check for duplciate assignment names in the given gradebook

Throws:

GradebookNotFoundException

transferGradebook

Map<String,String> transferGradebook(GradebookInformation gradebookInformation,
                                     List<Assignment> assignments,
                                     String toGradebookUid,
                                     String fromContext)

Transfer the gradebook information and assignments from one gradebook to another

Parameters:

gradebookInformation - GradebookInformation to copy

assignments - list of Assignments to copy

toGradebookUid - target gradebook uid

getGradebookInformation

GradebookInformation getGradebookInformation(String gradebookUid)

Parameters:

gradebookUid -

Returns:

a GradebookInformation object that contains information about this Gradebook that may be useful to consumers outside the Gradebook tool

removeAssignment

void removeAssignment(Long assignmentId)
               throws StaleObjectModificationException

Removes an assignment from a gradebook. The assignment should not be deleted, but the assignment and all grade records associated with the assignment should be ignored by the application. A removed assignment should not count toward the total number of points in the gradebook.

Parameters:

assignmentId - The assignment id

Throws:

StaleObjectModificationException

getCategories

@Deprecated
List getCategories(Long gradebookId)

Deprecated.

Get the categories for the given gradebook. This method cannot be used outside of the gradebook because it returns the org.sakaiproject.tool.gradebook.Category object. If you require info on the categories from a consumer outside the gradebook, use getCategoryDefinitions(String)

Parameters:

gradebookId -

Returns:

List of categories

Throws:

HibernateException

getCategoryDefinitions

List<CategoryDefinition> getCategoryDefinitions(String gradebookUid)

Get the categories for the given gradebook

Parameters:

gradebookUid -

Returns:

CategoryDefinitions for the categories defined for the given gradebook. Returns an empty list if the gradebook does not have categories.

Throws:

GradebookNotFoundException

removeCategory

void removeCategory(Long categoryId)
             throws StaleObjectModificationException

remove category from gradebook

Parameters:

categoryId -

Throws:

StaleObjectModificationException

addAssignment

Long addAssignment(String gradebookUid,
                   Assignment assignmentDefinition)

Create a new Gradebook-managed assignment.

Parameters:

assignmentDefinition -

Returns:

the id of the newly created assignment

updateAssignment

void updateAssignment(String gradebookUid,
                      Long assignmentId,
                      Assignment assignmentDefinition)

Modify the definition of an existing Gradebook item. Clients should be aware that it's allowed to change the points value of an assignment even if students have already been scored on it. Any existing scores will not be adjusted. This method can be used to manage both internal and external gradebook items, however the title, due date and total points will not be edited for external gradebook items.

Parameters:

assignmentId - the id of the assignment that needs to be changed

assignmentDefinition - the new properties of the assignment

getViewableAssignmentsForCurrentUser

List<Assignment> getViewableAssignmentsForCurrentUser(String gradebookUid)

Parameters:

gradebookUid -

Returns:

list of gb items that the current user is authorized to view. If user has gradeAll permission, returns all gb items. If user has gradeSection perm with no grader permissions, returns all gb items. If user has gradeSection with grader perms, returns only the items that the current user is authorized to view or grade. If user does not have grading privileges but does have viewOwnGrades perm, will return all released gb items.

getViewableAssignmentsForCurrentUser

List<Assignment> getViewableAssignmentsForCurrentUser(String gradebookUid,
                                                      SortType sortBy)

Parameters:

gradebookUid -

Returns:

list of gb items that the current user is authorized to view sorted by the provided SortType. If user has gradeAll permission, returns all gb items. If user has gradeSection perm with no grader permissions, returns all gb items. If user has gradeSection with grader perms, returns only the items that the current user is authorized to view or grade. If user does not have grading privileges but does have viewOwnGrades perm, will return all released gb items.

getViewableStudentsForItemForCurrentUser

Map<String,String> getViewableStudentsForItemForCurrentUser(String gradebookUid,
                                                            Long assignmentId)

Parameters:

gradebookUid -

assignmentId -

Returns:

a map of studentId to view/grade function for the given gradebook and gradebook item. students who are not viewable or gradable will not be returned. if the current user does not have grading privileges, an empty map is returned

getViewableStudentsForItemForUser

Map<String,String> getViewableStudentsForItemForUser(String userUid,
                                                     String gradebookUid,
                                                     Long assignmentId)

Parameters:

userUid -

gradebookUid -

assignmentId -

Returns:

a map of studentId to view/grade function for the given gradebook and gradebook item that the given userUid is allowed to view or grade. students who are not viewable or gradable will not be returned. if the given user does not have grading privileges, an empty map is returned

getGradebook

Object getGradebook(String uid)
             throws GradebookNotFoundException

Get the Gradebook. Note that this returns Object to avoid circular dependency with sakai-gradebook-tool Consumers will need to cast to org.sakaiproject.tool.gradebook.Gradebook

Throws:

GradebookNotFoundException

checkStudentsNotSubmitted

boolean checkStudentsNotSubmitted(String gradebookUid)

Check if there are students that have not submitted

Parameters:

gradebookUid -

Returns:

isGradableObjectDefined

boolean isGradableObjectDefined(Long gradableObjectId)

Check if a gradeable object with the given id exists

Parameters:

gradableObjectId -

Returns:

true if a gradable object with the given id exists and was not removed

getViewableSectionUuidToNameMap

Map<String,String> getViewableSectionUuidToNameMap(String gradebookUid)

Using the grader permissions, return map of section uuid to section name that includes all sections that the current user may view or grade

Parameters:

gradebookUid -

Returns:

currentUserHasGradeAllPerm

boolean currentUserHasGradeAllPerm(String gradebookUid)

Check if the current user has the gradebook.gradeAll permission

Parameters:

gradebookUid -

Returns:

true if current user has the gradebook.gradeAll permission

isUserAllowedToGradeAll

boolean isUserAllowedToGradeAll(String gradebookUid,
                                String userUid)

Check if the given user is allowed to grade all students in this gradebook

Parameters:

gradebookUid -

userUid -

Returns:

true if the given user is allowed to grade all students in this gradebook

currentUserHasGradingPerm

boolean currentUserHasGradingPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has some form of grading privileges in the gradebook (grade all, grade section, etc)

isUserAllowedToGrade

boolean isUserAllowedToGrade(String gradebookUid,
                             String userUid)

Parameters:

gradebookUid -

userUid -

Returns:

true if the given user has some form of grading privileges in the gradebook (grade all, grade section, etc)

currentUserHasEditPerm

boolean currentUserHasEditPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has the gradebook.editAssignments permission

currentUserHasViewOwnGradesPerm

boolean currentUserHasViewOwnGradesPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has the gradebook.viewOwnGrades permission

currentUserHasViewStudentNumbersPerm

boolean currentUserHasViewStudentNumbersPerm(String gradebookUid)

Parameters:

gradebookUid -

Returns:

true if the current user has the gradebook.viewStudentNumbers permission

getGradesForStudentsForItem

List<GradeDefinition> getGradesForStudentsForItem(String gradebookUid,
                                                  Long assignmentId,
                                                  List<String> studentIds)

Get the grade records for the given list of students and the given assignment. This can only be called by an instructor or TA that has access, not student. See getGradeDefinitionForStudentForItem(java.lang.String, java.lang.Long, java.lang.String) for the method call that can be made as a student.

Parameters:

gradebookUid -

assignmentId -

studentIds -

Returns:

a list of GradeDefinition with the grade information for the given students for the given gradableObjectId

Throws:

SecurityException - if the current user is not authorized to view or grade a student in the passed list

getGradesWithoutCommentsForStudentsForItems

Map<Long,List<GradeDefinition>> getGradesWithoutCommentsForStudentsForItems(String gradebookUid,
                                                                            List<Long> gradableOjbectIds,
                                                                            List<String> studentIds)

This method gets grades for multiple gradebook items with emphasis on performance. This is particularly useful for reporting tools

Parameters:

gradebookUid -

gradableObjectIds -

studentIds -

Returns:

a Map of GradableObjectIds to a List of GradeDefinitions containing the grade information for the given students for the given gradableObjectIds. Comments are excluded which can be useful for performance. If a student does not have a grade on a gradableObject, the GradeDefinition will be omitted

Throws:

SecurityException - if the current user is not authorized with gradeAll in this gradebook

IllegalArgumentException - if gradableObjectIds is null/empty, or if gradableObjectIds contains items that are not members of the gradebook with uid = gradebookUid

isGradeValid

boolean isGradeValid(String gradebookUuid,
                     String grade)
              throws GradebookNotFoundException

Parameters:

gradebookUuid -

grade -

Returns:

true if the given grade is a valid grade given the gradebook's grade entry type. ie, if gradebook is set to grade entry by points, will check for valid point value. if entry by letter, will check for valid letter, etc

Throws:

GradebookNotFoundException - if no gradebook exists with given gradebookUid

isValidNumericGrade

boolean isValidNumericGrade(String grade)

Determines if the given string contains a valid numeric grade.

Parameters:

grade - the grade as a string, expected to contain a numeric value

Returns:

true if the string contains a valid numeric grade

identifyStudentsWithInvalidGrades

List<String> identifyStudentsWithInvalidGrades(String gradebookUid,
                                               Map<String,String> studentIdToGradeMap)
                                        throws GradebookNotFoundException

Parameters:

gradebookUid -

studentIdToGradeMap - - the student's username mapped to their grade that you want to validate

Returns:

a list of the studentIds that were associated with invalid grades given the gradebook's grade entry type. useful if validating a list of student/grade pairs for a single gradebook (more efficient than calling gradeIsValid repeatedly). returns empty list if all grades are valid

Throws:

GradebookNotFoundException - if no gradebook exists with given gradebookUid

saveGradeAndCommentForStudent

void saveGradeAndCommentForStudent(String gradebookUid,
                                   Long assignmentId,
                                   String studentId,
                                   String grade,
                                   String comment)
                            throws InvalidGradeException,
                                   GradebookNotFoundException,
                                   AssessmentNotFoundException

Save a student score and comment for a gradebook item. The input score must be valid according to the given gradebook's grade entry type.

Parameters:

gradebookUid -

assignmentId -

studentId -

grade - - must be in format according to gradebook's grade entry type

comment -

Throws:

InvalidGradeException - - if grade is invalid. grade and comment will not be saved

GradebookNotFoundException

AssessmentNotFoundException

SecurityException - if current user is not authorized to grade student

saveGradesAndComments

void saveGradesAndComments(String gradebookUid,
                           Long assignmentId,
                           List<GradeDefinition> gradeDefList)
                    throws InvalidGradeException,
                           GradebookNotFoundException,
                           AssessmentNotFoundException

Given a list of GradeDefinitions for students for a given gradebook and gradable object, will save the associated scores and comments. Scores must be in a format according to the gradebook's grade entry type (ie points, %, letter).

Parameters:

gradebookUid -

assignmentId -

gradeDefList -

Throws:

InvalidGradeException - if any of the grades are not valid - none will be saved

SecurityException - if the user does not have access to a student in the list - no grades or comments will be saved for any student

GradebookNotFoundException

AssessmentNotFoundException

saveGradeAndExcuseForStudent

void saveGradeAndExcuseForStudent(String gradebookUid,
                                  Long assignmentId,
                                  String studentId,
                                  String grade,
                                  boolean excuse)
                           throws InvalidGradeException,
                                  GradebookNotFoundException,
                                  AssessmentNotFoundException

Throws:

InvalidGradeException

GradebookNotFoundException

AssessmentNotFoundException

getGradeEntryType

int getGradeEntryType(String gradebookUid)
               throws GradebookNotFoundException

Parameters:

gradebookUid -

Returns:

the constant representation of the grade entry type (ie points, %, letter grade)

Throws:

GradebookNotFoundException - if no gradebook exists w/ the given uid

getEnteredCourseGrade

Map<String,String> getEnteredCourseGrade(String gradebookUid)

Get a Map of overridden CourseGrade for students.

Parameters:

gradebookUid -

Returns:

Map of enrollment displayId as key, point as value string

getAssignmentScoreString

String getAssignmentScoreString(String gradebookUid,
                                Long assignmentId,
                                String studentUid)
                         throws GradebookNotFoundException,
                                AssessmentNotFoundException

Get student's assignment's score as string.

Parameters:

gradebookUid -

assignmentId -

studentUid -

Returns:

String of score

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreString

@Deprecated
String getAssignmentScoreString(String gradebookUid,
                                            String assignmentName,
                                            String studentUid)
                                     throws GradebookNotFoundException,
                                            AssessmentNotFoundException

Deprecated. See getAssignmentScoreString(String, Long, String)

Get student's assignment's score as string. This is provided for backward compatibility only.

Parameters:

gradebookUid -

assignmentName -

studentUid -

Returns:

String of score

Throws:

GradebookNotFoundException

AssessmentNotFoundException

getAssignmentScoreStringByNameOrId

String getAssignmentScoreStringByNameOrId(String gradebookUid,
                                          String assignmentName,
                                          String studentUid)
                                   throws GradebookNotFoundException,
                                          AssessmentNotFoundException

Get student's assignment's score as string. This is intended as a migration path from the deprecated #getAssignmentScoreString(String,String) to the new #getAssignmentScoreString(String,Long) This method will attempt to lookup the name as provided then fallback to the ID as a Long (If it is a Long) You should use #getAssignmentScoreString(String,Long) if you always can use the Long instead.

Parameters:

gradebookUid -

assignmentName -

studentUid -

Returns:

String of score

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScoreString

void setAssignmentScoreString(String gradebookUid,
                              Long assignmentId,
                              String studentUid,
                              String score,
                              String clientServiceDescription)
                       throws GradebookNotFoundException,
                              AssessmentNotFoundException

Set student's score for assignment.

Parameters:

gradebookUid -

assignmentId -

studentUid -

score -

clientServiceDescription -

Throws:

GradebookNotFoundException

AssessmentNotFoundException

setAssignmentScoreString

@Deprecated
void setAssignmentScoreString(String gradebookUid,
                                          String assignmentName,
                                          String studentUid,
                                          String score,
                                          String clientServiceDescription)
                                   throws GradebookNotFoundException,
                                          AssessmentNotFoundException

Deprecated. See setAssignmentScoreString(String, Long, String, String, String)

Set student's score for assignment. This is provided for backward compatibility only.

Parameters:

gradebookUid -

assignmentName -

studentUid -

score -

clientServiceDescription -

Throws:

GradebookNotFoundException

AssessmentNotFoundException

finalizeGrades

void finalizeGrades(String gradebookUid)
             throws GradebookNotFoundException

Finalize the gradebook's course grades by setting all still-unscored assignments to zero scores.

Parameters:

gradebookUid -

Throws:

GradebookNotFoundException

getLowestPossibleGradeForGbItem

String getLowestPossibleGradeForGbItem(String gradebookUid,
                                       Long assignmentId)

Parameters:

gradebookUid -

assignmentId -

Returns:

the lowest possible grade allowed for the given assignmentId. For example, in a points or %-based gradebook, the lowest possible grade for a gradebook item is 0. In a letter-grade gb, it may be 'F' depending on the letter grade mapping. Ungraded items have a lowest value of null.

Throws:

SecurityException - if user does not have permission to view assignments in the given gradebook

AssessmentNotFoundException - if there is no gradebook item with the given gradebookItemId

isPointsPossibleValid

GradebookService.PointsPossibleValidation isPointsPossibleValid(String gradebookUid,
                                                                Assignment assignment,
                                                                Double pointsPossible)

Parameters:

gradebookUid - (non-null)

assignment - (non-null) the Assignment object representing the gradebook item for which you are setting the points possible (aka relative weight). May be a new gradebook item without an id yet.

pointsPossible - the points possible/relative weight you would like to validate for the gradebookItem above.

Returns:

GradebookService.PointsPossibleValidation value indicating the validity of the given points possible/relative weight or a problem code defining why it is invalid

getAverageCourseGrade

String getAverageCourseGrade(String gradebookUid)

Computes the Average Course Grade as a letter.

Parameters:

gradebookUid -

Returns:

updateAssignmentOrder

void updateAssignmentOrder(String gradebookUid,
                           Long assignmentId,
                           Integer order)

Update the ordering of an assignment. This can be performed on internal and external assignments.

Parameters:

gradebookUid - uid of the gradebook

assignmentId - id of the assignment in the gradebook

order - the new order for this assignment. Note it is 0 based index ordering.

getGradingEvents

List getGradingEvents(String studentId,
                      long assignmentId)

Gets the grading events for the given student and the given assignment

Parameters:

studentId -

assignmentId -

Returns:

List of GradingEvent objects.

calculateCategoryScore

Optional<CategoryScoreData> calculateCategoryScore(Long gradebookId,
                                                   String studentUuid,
                                                   Long categoryId,
                                                   boolean includeNonReleasedItems,
                                                   int categoryType,
                                                   Boolean equalWeightAssignments)

Calculate the category score for the given gradebook, student and category, looking up the grades. Safe to call in context of a student.

Parameters:

gradebookId - Id of the gradebook

studentUuid - uuid of the student

categoryId - id of category

isInstructor - will determine whether category score includes non-released items

categoryType - category type of the gradebook

equalWeightAssignments - whether category is equal-weighting regardless of points

Returns:

percentage and dropped items, or empty if no calculations were made

calculateCategoryScore

Optional<CategoryScoreData> calculateCategoryScore(Object gradebook,
                                                   String studentUuid,
                                                   CategoryDefinition category,
                                                   List<Assignment> categoryAssignments,
                                                   Map<Long,String> gradeMap,
                                                   boolean includeNonReleasedItems)

Calculate the category score for the given gradebook, category, assignments in the category and grade map. This doesn't do any additional grade lookups. Safe to call in context of a student.

Parameters:

gradebook - the gradebook. As this method is called for every student at once, this is passed in to save additional lookups by id.

studentUuid - uuid of the student

category - the category

categoryAssignments - list of assignments the student can view, and are in the category

gradeMap - map of assignmentId to grade, to use for the calculations

includeNonReleasedItems - relevant for student view

Returns:

percentage and dropped items, or empty if no calculations were made

getCourseGradeForStudent

CourseGrade getCourseGradeForStudent(String gradebookUid,
                                     String userUuid)

Get the course grade for a student

Parameters:

gradebookUid -

userUuid - uuid of the user

Returns:

The CourseGrade for the student

getCourseGradeForStudents

Map<String,CourseGrade> getCourseGradeForStudents(String gradebookUid,
                                                  List<String> userUuids)

Get the course grade for a list of students

Parameters:

gradebookUid -

userUuids - uuids of the users

Returns:

a Map of CourseGrade for the students. Key is the student uuid.

getCourseGradeForStudents

Map<String,CourseGrade> getCourseGradeForStudents(String gradebookUid,
                                                  List<String> userUuids,
                                                  Map<String,Double> schema)

Get the course grade for a list of students using the given grading schema

Parameters:

gradebookUid -

userUuids - uuids of the users

schema - the grading schema (bottom percents) to use in the calculation

Returns:

a Map of CourseGrade for the students. Key is the student uuid.

getViewableSections

List getViewableSections(String gradebookUid)

Get a list of CourseSections that the current user has access to in the given gradebook. This is a combination of sections and groups and is permission filtered.

Parameters:

gradebookUid -

Returns:

list of CourseSection objects.

updateGradebookSettings

void updateGradebookSettings(String gradebookUid,
                             GradebookInformation gbInfo)

Update the settings for this gradebook

Parameters:

gradebookUid -

gbInfo - GradebookInformation object

getGradebookGradeMappings

Set getGradebookGradeMappings(Long gradebookId)

Return the GradeMappings for the given gradebook. The normal getGradebook(siteId) doesn't return the GradeMapping.

Parameters:

gradebookId -

Returns:

Set of GradeMappings for the gradebook

getGradebookGradeMappings

Set getGradebookGradeMappings(String gradebookUid)

Return the GradeMappings for the given gradebook.

Parameters:

gradebookUid -

Returns:

Set of GradeMappings for the gradebook

updateCourseGradeForStudent

void updateCourseGradeForStudent(String gradebookUid,
                                 String studentUuid,
                                 String grade)

Allows an instructor to set a course grade override for the given student

Parameters:

gradebookUid - uuid of the gradebook

studentUuid - uuid of the student

grade - the new course grade

updateAssignmentCategorizedOrder

void updateAssignmentCategorizedOrder(String gradebookUid,
                                      Long categoryId,
                                      Long assignmentId,
                                      Integer order)

Updates the categorized order of an assignment

Parameters:

gradebookUid - uuid of the gradebook

categoryId - id of the category

assignmentId - id of the assignment

order - new position of the assignment

getGradingEvents

List getGradingEvents(List<Long> assignmentIds,
                      Date since)

Return the grade changes made since a given time

Parameters:

assignmentIds - list of assignment ids to check

since - timestamp from which to check for changes

Returns:

set of changes made