LTI Grade Return - MNV Gateway

In addition to the asynchronous bulk grade return provided by the Job Service, Gateway also provides a means in which a Tool Provider can push a single grade through LTI. This is useful to allow "real time" grade synchronization between the Tool Consumer and Tool Provider since the grade can be synched immediately after an assignment has been completed.

LTI Grade Return may need to be enabled on the Tool Consumer side. For instance in Blackboard this must be enabled on each LTI link. When enabled the Tool Consumer will pass additional information to the Gateway which will be stored for later use. During a launch the Gateway will look up this information and generate a GUID which will be passed to the Tool Provider for later use. This GUID does not expire and can be used multiple times to update the same grade in the Tool Consumer's Grade Book. The Gateway will pass this GUID, known as the "grade_return_token":

REQUEST:
    <form action="http://tool-provider.com/doLaunch?tpSpecificParameter=SomeVal" method="post" enctype="application/x-www-form-urlencoded" >
        <input type="hidden" name="access_token" value="335aea8b68e0da0e29259ee6631c3e2ce81a2a5a" />
        <input type="hidden" name="grade_return_token" value="3DA18D52-9498-CD68-77C2-51E4A52785C8">
        <input type="hidden" name="message_data" value="Some Data Needed By The Tool Provider"/>
        <input type="hidden" name="tp_user_id" value="5"/>
        <input type="hidden" name="tc_user_id" value="ea918c08a3874091a2644e72109ea898"/>
        <input type="hidden" name="tc_role" value="urn:lti:role:ims/lis/Learner"/>
        <input type="hidden" name="tc_first_name" value="Joe"/>
        <input type="hidden" name="tc_last_name" value="Smith"/>
        <input type="hidden" name="tc_email" value="joe.smith@university.edu"/>
    </form>

Once the Tool Provider is ready to update the grade, they can do so by calling the grade_return endpoint. It is important to note that the "grade" must be between 0 and 1 inclusive:

REQUEST:
 - POST /grade_return
 - HEADER:
         Content-Type: application/json
         Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

 - BODY:
    {
      "grade_return_token": "3DA18D52-9498-CD68-77C2-51E4A52785C8",
      "grade": 0.98751
    }

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": null,
        "message": "Successfully Pushed Grade for 3DA18D52-9498-CD68-77C2-51E4A52785C8",
        "status": 200,
        "time": null
    }

Error Handling

If there is an error the "error" value will be non-zero with the message stating what went wrong. Here are some examples:

Invalid token:

    {
        "error": 1,
        "data": {
            "error_messages": [
                "LTI Grade Push Token Not Found"
            ]
        },
        "message": "Invalid input data.  See Data object for description",
        "status": 200,
        "time": null
    }

Grade value out of range:

   {
       "error": 1,
       "data": {
           "error_messages": [
               "grade field must be between 0 and 1 inclusive"
           ]
       },
       "message": "Invalid input data.  See Data object for description",
       "status": 200,
       "time": null
   }

Empty grade return token and invalid grade:

    {
        "error": 1,
        "data": {
            "error_messages": [
                "grade return token field is required and cannot be empty",
                "grade field must be between 0 and 1 inclusive"
            ]
        },
        "message": "Invalid input data.  See Data object for description",
        "status": 200,
        "time": null
    }

Tool Consumer/Setup error:

    {
        "error": 1,
        "data": {
            "error_messages": [
                "Incorrect sourcedId:[bbgc8673gi3103-bad]"
            ]
        },
        "message": "Error while pushing grade via LTI.  See data for explination",
        "status": 200,
        "time": null
    }