MNV Gateway

Bulk LTI Grades Push

In addition to the Single LTI Grade Return, Gateway also provides the ability to push bulk grades via LTI. This can be preferable to the other bulk grade push method as this version will work with any LTI 1.1 compliant LMS.

Similar to the Single LTI Grade Return, the Tool Provider must send a grade_return_token and grade for each item that they would like to sync. The difference is that this endpoint will process the grades asynchronously via a job.

To push grades into the Gateway via either LTI method you must first capture the grade_return_token during the SSO Launch.

Bulk LTI Grades Push Example

REQUEST:
 - POST /job/lti_grade
 - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=
 - BODY:
    {
        "grades":[
            {
                "grade_return_token": "D4C36065-1F9B-C724-7E1D-B9561A9AB49B",
                "grade": 0.55555
            },
            {
                "grade_return_token": "876FAECE-1AED-58CE-A8C2-AF52BD1BFAD8",
                "grade": 0.12345
            }
        ]
    }

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": {
            "async": true,
            "job_id": "d5f5d8796c770720cc32ac6dfb3cac2d"
        },
        "message": null,
        "status": 200,
        "time": null
    }

You may periodicly check the status of the results by querying the job status endpoint.

REQUEST:
 - GET /job/d5f5d8796c770720cc32ac6dfb3cac2d
 - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

RESPONSE:
 - BODY:
     {
         "job_status_message": "Job is still queued",
         "job_status_code": 1,
         "data": null,
         "error": 0,
         "message": null,
         "status": 200,
         "time": null
     }

Eventually the job will be complete and when the job status is pulled the data will come back with the job.

REQUEST:
  - GET /job/d5f5d8796c770720cc32ac6dfb3cac2d
  - HEADER:
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=

RESPONSE:
 - BODY:
    {
        "error": 0,
        "data": [
            {
                "grade_return_token": "D4C36065-1F9B-C724-7E1D-B9561A9AB49B",
                "status": "success",
                "message": null
            },
            {
                "grade_return_token": "876FAECE-1AED-58CE-A8C2-AF52BD1BFAD8",
                "status": "success",
                "message": null
            }
        ],
        "message": null,
        "status": 200,
        "time": 6.36,
        "job_status_message": "Job is complete",
        "job_status_code": 4
    }

Handling Errors

Each grade entry (the grade_return_token and grade pair) will be attempted provided all tokens can be found in the gateway. Thus a single failure will not abort the grade push process. Therefor the Tool Provider should expect to parse the data object for successful and failed attempts. In the case of a failure the grade push should be reattempted as an LTI Grade Push is idempotent.

Below are some example responses for failed Bulk LTI Grade Pushes.

  1. Grade value out of range. The grade must be between 0 and 1 inclusive. The grade must also be numeric:
    {
        "error": 1,
        "data": [
            {
                "grade_return_token": "D4C36065-1F9B-C724-7E1D-B9561A9AB49B",
                "status": "success",
                "message": null
            },
            {
                "grade_return_token": "876FAECE-1AED-58CE-A8C2-AF52BD1BFAD8",
                "status": "failure",
                "message": "grade must be between 0 and 1 inclusive"
            }
        ],
        "message": "Not all grades synced correctly",
        "status": 200,
        "time": 5.96,
        "job_status_message": "Job is complete",
        "job_status_code": 4
    }
  1. Token not found:
    {
        "error": 1,
        "data": null,
        "message": "LTI Grade Push Token Not Found",
        "status": 200,
        "time": null
    }
  1. Tool Provider not authorized will result in a 401.