Score API

Score API for IMS Assignment and Grade Services

A Score object looks like:

{
  // The lti_user_id or the Canvas user_id
  "userId": "50 | 'abcasdf'",
  // The Current score received in the tool for this line item and user, scaled to
  // the scoreMaximum
  "scoreGiven": 50,
  // Maximum possible score for this result; it must be present if scoreGiven is
  // present.
  "scoreMaximum": 50,
  // Comment visible to the student about this score.
  "comment": null,
  // Date and time when the score was modified in the tool. Should use subsecond
  // precision.
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  // Indicate to Canvas the status of the user towards the activity's completion.
  // Must be one of Initialized, Started, InProgress, Submitted, Completed
  "activityProgress": "Completed",
  // Indicate to Canvas the status of the grading process. A value of
  // PendingManual will require intervention by a grader. Values of NotReady,
  // Failed, and Pending will cause the scoreGiven to be ignored. FullyGraded
  // values will require no action. Possible values are NotReady, Failed, Pending,
  // PendingManual, FullyGraded
  "gradingProgress": "FullyGraded",
  // Contains metadata about the submission attempt, like submittedAt: Date and
  // time that the submission was originally created - should use
  // ISO8601-formatted date with subsecond precision.
  "submission": {"submittedAt":"2017-04-14T18:54:36.736+00:00"}
}

Create a Score Lti::Ims::ScoresController#create

POST /api/lti/courses/:course_id/line_items/:line_item_id/scores

Scope: url:POST|/api/lti/courses/:course_id/line_items/:line_item_id/scores

Create a new Result from the score params. If this is for the first created line_item for a resourceLinkId, or it is a line item that is not attached to a resourceLinkId, then a submission record will be created for the associated assignment when gradingProgress is set to FullyGraded or PendingManual.

The submission score will also be updated when a score object is sent with either of those two values for gradingProgress. If a score object is sent with either of FullyGraded or PendingManual as the value for gradingProgress and scoreGiven is missing, the assignment will not be graded. This also supposes the line_item meets the condition to create a submission.

A submission comment with an unknown author will be created when the comment value is included. This also supposes the line_item meets the condition to create a submission.

It is also possible to submit a file along with this score, which will attach the file to the submission that is created. Files should be formatted as Content Items, with the correct syntax below.

Returns a url pointing to the Result. If any files were submitted, also returns the Content Items which were sent in the request, each with a url pointing to the Progress of the file upload.

Request Parameters:

Parameter Type Description
userId Required string

The lti_user_id or the Canvas user_id. Returns a 422 if user not found in Canvas or is not a student.
activityProgress Required string

Indicate to Canvas the status of the user towards the activity’s completion. Must be one of Initialized, Started, InProgress, Submitted, Completed.
gradingProgress Required string

Indicate to Canvas the status of the grading process. A value of PendingManual will require intervention by a grader. Values of NotReady, Failed, and Pending will cause the scoreGiven to be ignored. FullyGraded values will require no action. Possible values are NotReady, Failed, Pending, PendingManual, FullyGraded.
timestamp Required string

Date and time when the score was modified in the tool. Should use ISO8601-formatted date with subsecond precision. Returns a 400 if the timestamp is earlier than the updated_at time of the Result.
scoreGiven number

The Current score received in the tool for this line item and user, scaled to the scoreMaximum
scoreMaximum number

Maximum possible score for this result; it must be present if scoreGiven is present. Returns 422 if not present when scoreGiven is present.
comment string

Comment visible to the student about this score.
submission Object

Contains metadata about the submission attempt. Supported fields listed below.
submission[submittedAt] string

Date and time that the submission was originally created. Should use ISO8601-formatted date with subsecond precision.
https://canvas.instructure.com/lti/submission Object

(EXTENSION) Optional submission type and data. Fields listed below.
https://canvas.instructure.com/lti/submission[new_submission] boolean

(EXTENSION field) flag to indicate that this is a new submission. Defaults to true unless submission_type is none.
https://canvas.instructure.com/lti/submission[preserve_score] boolean

(EXTENSION field) flag to prevent a request from clearing an existing grade for a submission. Defaults to false.
https://canvas.instructure.com/lti/submission[prioritize_non_tool_grade] boolean

(EXTENSION field) flag to prevent a request from overwriting an existing grade for a submission. Defaults to false.
https://canvas.instructure.com/lti/submission[submission_type] string

(EXTENSION field) permissible values are: none, basic_lti_launch, online_text_entry, external_tool, online_upload, or online_url. Defaults to external_tool. Ignored if content_items are provided.
https://canvas.instructure.com/lti/submission[submission_data] string

(EXTENSION field) submission data (URL or body text). Only used for submission_types basic_lti_launch, online_text_entry, online_url. Ignored if content_items are provided.
https://canvas.instructure.com/lti/submission[submitted_at] string

(EXTENSION field) Date and time that the submission was originally created. Should use ISO8601-formatted date with subsecond precision. This should match the date and time that the original submission happened in Canvas. Use of submission.submittedAt is preferred.
https://canvas.instructure.com/lti/submission[content_items] Array

(EXTENSION field) Files that should be included with the submission. Each item should contain ‘type: file`, and a url pointing to the file. It can also contain a title, and an explicit MIME type if needed (otherwise, MIME type will be inferred from the title or url). If any items are present, submission_type will be online_upload.

Example Request:

{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "scoreGiven": 83,
  "scoreMaximum": 100,
  "comment": "This is exceptional work.",
  "submission": {
    "submittedAt": "2017-04-14T18:54:36.736+00:00"
  },
  "activityProgress": "Completed",
  "gradingProgress": "FullyGraded",
  "userId": "5323497",
  "https://canvas.instructure.com/lti/submission": {
    "new_submission": true,
    "preserve_score": false,
    "submission_type": "online_url",
    "submission_data": "https://instructure.com",
    "submitted_at": "2017-04-14T18:54:36.736+00:00",
    "content_items": [
      {
        "type": "file",
        "url": "https://instructure.com/test_file.txt",
        "title": "Submission File",
        "media_type": "text/plain"
      }
    ]
  }
}

Example Response:

{
  "resultUrl": "https://canvas.instructure.com/url/to/result",
  "https://canvas.instructure.com/lti/submission": {
    "content_items": [
      {
        "type": "file",
        "url": "https://instructure.com/test_file.txt",
        "title": "Submission File"
        "progress": "https://canvas.instructure.com/url/to/progress"
      }
}