Pearson
Always Learning

Overview

This use case outlines the recommended flow for retrieving and posting grades associated to the content item the user of your integrated application is launching from within the associated LearningStudio course.

Recommended Sequence

The below steps should be done in sequence. This use case assumes you have a valid set of API keys and a the proper LTI provider profile has been created and activated for integrating campus. If you have not yet requested a LTI provider profile created and activated you can do so here.

  • Note: This use case assumes your application is being launched from the External Tool content item within a LearningStudio course. This is required in order to pass the applicable content item ID value within the "resource_link_id" parameter of the LTI launch.

1. LTI Launch

User accesses the external tool link in a LearningStudio course which generates the following tool launch request:

context_id=31388494
context_label=Demo
context_title=Integrated Item Demo
context_type=CourseSection
example_deeplinking_param=sample123
launch_presentation_locale=en-US
launch_presentation_return_url=http://blti.next.ecollege.com/launch/error
lis_person_contact_email_primary=zachmorris@email.com
lis_person_name_family=Morris
lis_person_name_full=Zach Morris
lis_person_name_given=Zach
lti_message_type=basic-lti-launch-request
lti_version=LTI-1p0
oauth_callback=about:blank
oauth_consumer_key=12345
oauth_nonce=7985210
oauth_signature=b9S1mrX/3phA22lzHZq+Beigc+Q=
oauth_signature_method=HMAC-SHA1
oauth_timestamp=1437511433
oauth_version=1.0
resource_link_id=100561235546
resource_link_title=LTI Tool
roles=Student
tool_consumer_instance_description=SIS Integration Sandbox (Integration Partner)
tool_consumer_instance_guid=gbtestc.two.
tool_consumer_instance_name=gbtestc
user_id=28456671


2. Get Gradable Item ID From Content Item ID

In order to begin posting grades to a given content item reference point for which the LTI tool launch was initiated from, you will need to obtain the gradable item ID for is associated to that content item. In order to make the request you will leverage the course ID value (passed under the title "context_id") as well as the content item ID of the content item the user is launching out from (which is passed under the "resource_link_id" parameter of the launch). Using the LTI launch above the two values would be "31388494" and "100561235546" respectively. With these two values, you will make the following GET call:

Request

GET /courses/31388494/items/100561235546/gradebookItem

Response

{
  "gradebookItem": {
    "links":[{
      "href":"https://api.learningstudio.com/courses/123456/gradebookItems/b24e5de6-ABEE-1334-XTZF-123456789000",
      "rel":"self"
    }]
  }
}


3. Review Current Grade

Once you have the gradable item ID of the associated content item, you will need to determine if a grade has been assigned for the given item so that the subsequent POST or PUT calls can be initiated. An example of the request to retrieve the grade data for a given student/assignment combination is as follows:

Request

GET /users/28456671/courses/31388494/gradebookItems/b24e5de6-ABEE-1334-XTZF-123456789000/grade

Response

{
  "grade": {
    "id": 1051754261,
    "points": 100,
    "letterGrade": "A",
    "comments": "",
    "shareWithStudent": true,
    "updatedDate": "2015-07-21T16:27:47Z",
    "gradedStudent": {
      "id": 28456671,
      "links": [
        {
          "href": "https://api.learningstudio.com/users/28456671",
          "rel": "self"
        }
      ]
    }
  }
}

There are three potential outputs from the request to obtain the current grade assigned to a given student/assignment combination which define what the subsequent API call would be:

  • GET request returns a 404 error "Grade not found." This response indicates that no grade has been assigned for the specified student/assignment combination for which a POST request can then be made as illustrated in step 4.
  • GET request returns a 200 success message with a grade ID but a blank letter grade, numerical grade and comments elements. This response indicates that a grade was previously assigned but could have been deleted by the course instructor. The API call would then be a PUT request using the grade ID value retrieved from the GET request.
  • GET request returns a 200 success message with the associated letter grade, numerical grade and comments assigned to the student and assignment combination. This would be essentially the example above in which case a PUT request can be made at step 4 to update the currently assigned grade data for the student/assignment combination.


4. Post Or Update Grade Result

Now that you have the context of the student, course, gradebook item as well as if a grade has been assigned you can now step through the API call to specify the grade for the given student assignment using one of the following methods.

If no grade currently exists for the associated gradable item for the student, you will make a POST call as outlined below:

Request

POST /users/28456671/courses/31388494/gradebookItems/b24e5de6-ABEE-1334-XTZF-123456789000/grade

Request Body

{
  "grade":{
    "points":100.00,
    "letterGrade":"A",
    "comments":"Example grade comment.",
  }
}

If a grade had been previously assigned (as indicated by getting a 200 message back in step 3), you can now make a PUT call to update the specified grade for the given student assignment as outlined below:

Request

PUT /users/28456671/courses/31388494/gradebookItems/b24e5de6-ABEE-1334-XTZF-123456789000/grade

Request Body

{
  "grade":{
    "id":1051754261
    "points":100,
    "letterGrade":"A",
    "comments":"Example grade comment."
  }
}
1 reads
Always Learning
Pearson