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"
}

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.

NOTE: Upcoming Feature It will soon be 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 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 412 if not present when scoreGiven is present.
comment string

Comment visible to the student about this score.
https://canvas.instructure.com/lti/submission Object

(EXTENSION) Optional submission type and data. new_submission [Boolean] flag to indicate that this is a new submission. Defaults to true unless submission_type is none. submission_type [String] 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. submission_data [String] submission data (URL or body text) submitted_at [String] Date and time that the submission was originally created. Should use subsecond precision. This should match the data and time that the original submission happened in Canvas. content_items [Array] Files that should be included with the submission. Each item should contain `type: file`, a url pointing to the file, a title, and a progress url that Canvas can report to. If 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.",
  "activityProgress": "Completed",
  "gradingProgress": "FullyGraded",
  "userId": "5323497",
  "https://canvas.instructure.com/lti/submission": {
    "new_submission": true,
    "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"
      }
    ]
  }
}

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"
      }
}