org.sakaiproject.service.gradebook.shared

Interface GradebookExternalAssessmentService

public interface GradebookExternalAssessmentService

This service is designed for use by external assessment engines. These use the Gradebook as a passive mirror of their own assignments and scores, letting Gradebook users see those assignments alongside Gradebook-managed assignments, and combine them when calculating a course grade. The Gradebook application itself will not modify externally-managed assignments and scores. WARNING: Because the Gradebook project team is not responsible for defining the external clients' requirements, the Gradebook service does not attempt to guess at their authorization needs. Our administrative and external-assessment methods simply follow orders and assume that the caller has taken the responsibility of "doing the right thing." DO NOT wrap these methods in an open web service!

Method Summary

Modifier and Type	Method and Description
void	addExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, double points, Date dueDate, String externalServiceDescription, String externalData) Deprecated. Replaced by addExternalAssessment(String, String, String, String, Double, Date, String, Boolean)
void	addExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, Double points, Date dueDate, String externalServiceDescription, String externalData, Boolean ungraded) Add an externally-managed assessment to a gradebook to be treated as a read-only assignment.
void	addExternalAssessment(String gradebookUid, String externalId, String externalUrl, String title, Double points, Date dueDate, String externalServiceDescription, String externalData, Boolean ungraded, Long categoryId) This method is identical to addExternalAssessment(String, String, String, String, Double, Date, String, String, Boolean) but allows you to also specify the associated Category for this assignment.
Long	getExternalAssessmentCategoryId(String gradebookUId, String externalId) Get the category of a gradebook with the externalId given
Map<String,String>	getExternalAssignmentsForCurrentUser(String gradebookUid) Retrieve all assignments for a gradebook that are marked as externally maintained and are visible to the current user.
OptionalLong	getInternalAssessmentID(String gradebookUUID, String externalID) Get the internal ID of an externally managed assessment (gradebook item) by it's external ID
Map<String,List<String>>	getVisibleExternalAssignments(String gradebookUid, Collection<String> studentIds) Retrieve a list of all visible, external assignments for a set of users.
boolean	isAssignmentDefined(String gradebookUid, String assignmentTitle) Check to see if an assignment with the given name already exists in the given gradebook.
boolean	isCategoriesEnabled(String gradebookUid) Checks to see whether a gradebook has the categories option enabled.
boolean	isExternalAssignmentDefined(String gradebookUid, String externalId) Check to see if an assignment with the given external id already exists in the given gradebook.
boolean	isExternalAssignmentGrouped(String gradebookUid, String externalId) Check with the appropriate external service if a specific assignment is available only to groups.
boolean	isExternalAssignmentVisible(String gradebookUid, String externalId, String userId) Check with the appropriate external service if a specific assignment is available to a specific user (i.e., the user is in an appropriate group).
boolean	isGradebookDefined(String gradebookUid) Checks to see whether a gradebook with the given uid exists.
void	registerExternalAssignmentProvider(ExternalAssignmentProvider provider) Register a new ExternalAssignmentProvider for handling the integration of external assessment sources with the sakai gradebook Registering more than once will overwrite the current with the new one
void	removeExternalAssessment(String gradebookUid, String externalId) Remove the assessment reference from the gradebook.
void	setExternalAssessmentToGradebookAssignment(String gradebookUid, String externalId) Break the connection between an external assessment engine and an assessment which it created, giving it up to the Gradebook application to control from now on.
void	unregisterExternalAssignmentProvider(String providerAppKey) Remove/unregister any ExternalAssignmentProvider which is currently registered, does nothing if they provider does not exist
void	updateExternalAssessment(String gradebookUid, String externalId, String externalUrl, String externalData, String title, double points, Date dueDate) Deprecated. Replaced by updateExternalAssessment(String, String, String, String, Double, Date, Boolean)
void	updateExternalAssessment(String gradebookUid, String externalId, String externalUrl, String externalData, String title, Double points, Date dueDate, Boolean ungraded) Update an external assessment
void	updateExternalAssessmentComment(String gradebookUid, String externalId, String studentUid, String comment) Updates an external comment for an external assignment in the gradebook.
void	updateExternalAssessmentComments(String gradebookUid, String externalId, Map<String,String> studentUidsToComments) Updates a set of external comments for an external assignment in the gradebook.
void	updateExternalAssessmentScore(String gradebookUid, String externalId, String studentUid, String points) Updates an external score for an external assignment in the gradebook.
void	updateExternalAssessmentScores(String gradebookUid, String externalId, Map<String,Double> studentUidsToScores) Deprecated. Replaced by updateExternalAssessmentScoresString(String, String, Map
void	updateExternalAssessmentScoresString(String gradebookUid, String externalId, Map<String,String> studentUidsToScores) Updates a set of external scores for an external assignment in the gradebook.

Method Detail

addExternalAssessment

void addExternalAssessment(String gradebookUid,
                           String externalId,
                           String externalUrl,
                           String title,
                           double points,
                           Date dueDate,
                           String externalServiceDescription,
                           String externalData)
                    throws GradebookNotFoundException,
                           ConflictingAssignmentNameException,
                           ConflictingExternalIdException,
                           AssignmentHasIllegalPointsException

Deprecated. Replaced by addExternalAssessment(String, String, String, String, Double, Date, String, Boolean)

Throws:

GradebookNotFoundException

ConflictingAssignmentNameException

ConflictingExternalIdException

AssignmentHasIllegalPointsException

addExternalAssessment

void addExternalAssessment(String gradebookUid,
                           String externalId,
                           String externalUrl,
                           String title,
                           Double points,
                           Date dueDate,
                           String externalServiceDescription,
                           String externalData,
                           Boolean ungraded)
                    throws GradebookNotFoundException,
                           ConflictingAssignmentNameException,
                           ConflictingExternalIdException,
                           AssignmentHasIllegalPointsException

Add an externally-managed assessment to a gradebook to be treated as a read-only assignment. The gradebook application will not modify the assessment properties or create any scores for the assessment. Since each assignment in a given gradebook must have a unique name, conflicts are possible.

Parameters:

gradebookUid -

externalId - some unique identifier which Samigo uses for the assessment. The externalId is globally namespaced within the gradebook, so if other apps decide to put assessments into the gradebook, they should prefix their externalIds with a well known (and unique within sakai) string.

externalUrl - a link to go to if the instructor or student wants to look at the assessment in Samigo; if null, no direct link will be provided in the gradebook, and the user will have to navigate to the assessment within the other application

title -

points - this is the total amount of points available and must be greater than zero. It could be null if it's an ungraded item.

dueDate -

externalServiceDescription -

externalData - if there is some data that the external service wishes to store.

ungraded -

Throws:

GradebookNotFoundException

ConflictingAssignmentNameException

ConflictingExternalIdException

AssignmentHasIllegalPointsException

addExternalAssessment

void addExternalAssessment(String gradebookUid,
                           String externalId,
                           String externalUrl,
                           String title,
                           Double points,
                           Date dueDate,
                           String externalServiceDescription,
                           String externalData,
                           Boolean ungraded,
                           Long categoryId)
                    throws GradebookNotFoundException,
                           ConflictingAssignmentNameException,
                           ConflictingExternalIdException,
                           AssignmentHasIllegalPointsException,
                           InvalidCategoryException

This method is identical to addExternalAssessment(String, String, String, String, Double, Date, String, String, Boolean) but allows you to also specify the associated Category for this assignment. If the gradebook is set up for categories and categoryId is null, assignment category will be unassigned

Parameters:

gradebookUid -

externalId -

externalUrl -

title -

points -

dueDate -

externalServiceDescription -

externalData - if there is some data that the external service wishes to store.

ungraded -

categoryId -

Throws:

GradebookNotFoundException

ConflictingAssignmentNameException

ConflictingExternalIdException

AssignmentHasIllegalPointsException

InvalidCategoryException

updateExternalAssessment

void updateExternalAssessment(String gradebookUid,
                              String externalId,
                              String externalUrl,
                              String externalData,
                              String title,
                              double points,
                              Date dueDate)
                       throws GradebookNotFoundException,
                              AssessmentNotFoundException,
                              ConflictingAssignmentNameException,
                              AssignmentHasIllegalPointsException

Deprecated. Replaced by updateExternalAssessment(String, String, String, String, Double, Date, Boolean)

Throws:

GradebookNotFoundException

AssessmentNotFoundException

ConflictingAssignmentNameException

AssignmentHasIllegalPointsException

updateExternalAssessment

void updateExternalAssessment(String gradebookUid,
                              String externalId,
                              String externalUrl,
                              String externalData,
                              String title,
                              Double points,
                              Date dueDate,
                              Boolean ungraded)
                       throws GradebookNotFoundException,
                              AssessmentNotFoundException,
                              ConflictingAssignmentNameException,
                              AssignmentHasIllegalPointsException

Update an external assessment

Parameters:

gradebookUid -

externalId -

externalUrl -

externalData -

title -

points -

dueDate -

ungraded -

Throws:

GradebookNotFoundException

AssessmentNotFoundException

ConflictingAssignmentNameException

AssignmentHasIllegalPointsException

removeExternalAssessment

void removeExternalAssessment(String gradebookUid,
                              String externalId)
                       throws GradebookNotFoundException,
                              AssessmentNotFoundException

Remove the assessment reference from the gradebook. Although Samigo doesn't currently delete assessments, an instructor can retract an assessment to keep it from students. Since such an assessment would presumably no longer be used to calculate final grades, Samigo should also remove that assessment from the gradebook.

Parameters:

externalId - the UID of the assessment

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentScore

void updateExternalAssessmentScore(String gradebookUid,
                                   String externalId,
                                   String studentUid,
                                   String points)
                            throws GradebookNotFoundException,
                                   AssessmentNotFoundException

Updates an external score for an external assignment in the gradebook.

Parameters:

gradebookUid - The Uid of the gradebook

externalId - The external ID of the assignment/assessment

studentUid - The unique id of the student

points - The number of points earned on this assessment, or null if a score should be removed

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentScores

void updateExternalAssessmentScores(String gradebookUid,
                                    String externalId,
                                    Map<String,Double> studentUidsToScores)
                             throws GradebookNotFoundException,
                                    AssessmentNotFoundException

Deprecated. Replaced by updateExternalAssessmentScoresString(String, String, Map

Parameters:

gradebookUid -

externalId -

studentUidsToScores -

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentScoresString

void updateExternalAssessmentScoresString(String gradebookUid,
                                          String externalId,
                                          Map<String,String> studentUidsToScores)
                                   throws GradebookNotFoundException,
                                          AssessmentNotFoundException

Updates a set of external scores for an external assignment in the gradebook.

Parameters:

gradebookUid - The Uid of the gradebook

externalId - The external ID of the assignment/assessment

studentUidsToScores - A map whose String keys are the unique ID strings of the students and whose String values are points earned on this assessment or null if the score should be removed.

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentComment

void updateExternalAssessmentComment(String gradebookUid,
                                     String externalId,
                                     String studentUid,
                                     String comment)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException

Updates an external comment for an external assignment in the gradebook.

Parameters:

gradebookUid - The Uid of the gradebook

externalId - The external ID of the assignment/assessment

studentUid - The unique id of the student

comment - The comment to be added to this grade, or null if a comment should be removed

Throws:

GradebookNotFoundException

AssessmentNotFoundException

updateExternalAssessmentComments

void updateExternalAssessmentComments(String gradebookUid,
                                      String externalId,
                                      Map<String,String> studentUidsToComments)
                               throws GradebookNotFoundException,
                                      AssessmentNotFoundException

Updates a set of external comments for an external assignment in the gradebook.

Parameters:

gradebookUid - The Uid of the gradebook

externalId - The external ID of the assignment/assessment

studentUidsToScores - A map whose String keys are the unique ID strings of the students and whose String values are comments or null if the comments should be removed.

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 external assessment systems a chance to avoid the ConflictingAssignmentNameException.

Throws:

GradebookNotFoundException

isExternalAssignmentDefined

boolean isExternalAssignmentDefined(String gradebookUid,
                                    String externalId)
                             throws GradebookNotFoundException

Check to see if an assignment with the given external id already exists in the given gradebook. This will give external assessment systems a chance to avoid the ConflictingExternalIdException.

Parameters:

gradebookUid - The gradebook's unique identifier

externalId - The external assessment's external identifier

Throws:

GradebookNotFoundException

isExternalAssignmentGrouped

boolean isExternalAssignmentGrouped(String gradebookUid,
                                    String externalId)
                             throws GradebookNotFoundException

Check with the appropriate external service if a specific assignment is available only to groups.

Parameters:

gradebookUid - The gradebook's unique identifier

externalId - The external assessment's external identifier

Throws:

GradebookNotFoundException

isExternalAssignmentVisible

boolean isExternalAssignmentVisible(String gradebookUid,
                                    String externalId,
                                    String userId)
                             throws GradebookNotFoundException

Check with the appropriate external service if a specific assignment is available to a specific user (i.e., the user is in an appropriate group). Note that this method will return true if the assignment exists in the gradebook and is marked as externally maintained while no provider recognizes it; this is to maintain a safer default (no change from the 2.8 release) for tools that have not implemented a provider.

Parameters:

gradebookUid - The gradebook's unique identifier

externalId - The external assessment's external identifier

userId - The user ID to check

Throws:

GradebookNotFoundException

getExternalAssignmentsForCurrentUser

Map<String,String> getExternalAssignmentsForCurrentUser(String gradebookUid)
                                                 throws GradebookNotFoundException

Retrieve all assignments for a gradebook that are marked as externally maintained and are visible to the current user. Assignments may be included with a null providerAppKey, indicating that the gradebook references the assignment, but no provider claims responsibility for it.

Parameters:

gradebookUid - The gradebook's unique identifier

Returns:

A map from the externalId of each activity to the providerAppKey

Throws:

GradebookNotFoundException

getVisibleExternalAssignments

Map<String,List<String>> getVisibleExternalAssignments(String gradebookUid,
                                                       Collection<String> studentIds)
                                                throws GradebookNotFoundException

Retrieve a list of all visible, external assignments for a set of users.

Parameters:

gradebookUid - The gradebook's unique identifier

studentIds - The collection of student IDs for which to retrieve assignments

Returns:

A map from the student ID to all visible, external activity IDs

Throws:

GradebookNotFoundException

registerExternalAssignmentProvider

void registerExternalAssignmentProvider(ExternalAssignmentProvider provider)

Register a new ExternalAssignmentProvider for handling the integration of external assessment sources with the sakai gradebook Registering more than once will overwrite the current with the new one

Parameters:

provider - the provider implementation object

unregisterExternalAssignmentProvider

void unregisterExternalAssignmentProvider(String providerAppKey)

Remove/unregister any ExternalAssignmentProvider which is currently registered, does nothing if they provider does not exist

Parameters:

providerAppKey - the unique app key for a provider

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

setExternalAssessmentToGradebookAssignment

void setExternalAssessmentToGradebookAssignment(String gradebookUid,
                                                String externalId)

Break the connection between an external assessment engine and an assessment which it created, giving it up to the Gradebook application to control from now on.

Parameters:

gradebookUid -

externalId -

getExternalAssessmentCategoryId

Long getExternalAssessmentCategoryId(String gradebookUId,
                                     String externalId)

Get the category of a gradebook with the externalId given

Parameters:

gradebookUId -

externalId -

Returns:

isCategoriesEnabled

boolean isCategoriesEnabled(String gradebookUid)

Checks to see whether a gradebook has the categories option enabled.

Parameters:

gradebookUid - The gradebook UID to check

Returns:

Whether the gradebook has categories enabled

getInternalAssessmentID

OptionalLong getInternalAssessmentID(String gradebookUUID,
                                     String externalID)
                              throws GradebookNotFoundException,
                                     AssessmentNotFoundException

Get the internal ID of an externally managed assessment (gradebook item) by it's external ID

Parameters:

gradebookUUID - the UUID of the gradebook to check

externalID - the external ID of the assessment (gradebook item) in question

Returns:

Long value of the internal ID of the assessment (gradebook item) in question

Throws:

GradebookNotFoundException

AssessmentNotFoundException