Grades Push
The Grades Push job allows a Tool Provider to send grades to an LMS. To do this the Gateway needs the Grades Push Object which is described in detail below.
All elements of the Grades Push Object are required and the URL to push grades is protected by HTTP Basic Authentication over SSL.
Below is a complete definition of the GradesPush object which is described above.
{
"title": "GradesPush",
"description": "Object used to push grades to an LMS",
"type": "object",
"properties": {
"tool_consumer_url": {
"description": "Url of the LMS to push grades into, should only be base URL, ie blackboard.school.edu",
"type": "string"
},
"tool_consumer_username": {
"description": "Username of instructor who has rights to push grades into the specified course",
"type": "string"
},
"tool_consumer_sso_key": {
"description": "Key used to authenticate the instructor.",
"type": "string"
},
"course_grades": {
"description": "Array of multiple sets of grades per course",
"type": "array",
"items":{
"title": "CourseGrade",
"type": "object",
"properties": {
"course_id": {
"description": "LMS ID of the course to push grades into. Can be found during a Course Pull job.",
"type": "string"
},
"assignments": {
"description": "Array of Assignment objects",
"type": "array",
"items": {
"title": "Assignment",
"type": "object",
"properties": {
"category": {
"description": "Category for assignment grade. This will show up in the Grade Book of the LMS",
"type": "string"
},
"name": {
"description": "Friendly name for assignment. This will show up in the Grade Book of the LMS",
"type": "string"
},
"total_points": {
"description": "Number of points to be assigned for the assignment",
"type": "number"
},
"grades": {
"description": "Array of Grades objects to push into the course",
"type": "array",
"items": {
"title": "Grade",
"type": "object",
"properties": {
"user_id": {
"description": "Tool Provider user ID for the student",
"type": "string"
},
"points_earned": {
"description": "Points the student earned for the assignment",
"type": "number"
}
},
"required": [
"user_id",
"points_earned"
]
}
}
},
"required": [
"category",
"name",
"total_points",
"grades"
]
}
}
},
"required": [
"course_id",
"assignments"
]
}
}
},
"required": [
"tool_consumer_url",
"tool_consumer_username",
"tool_consumer_sso_key",
"course_grades"
]
}
A populated version of the GradesPush Object can be seen below with a full Request/Response cycle:
REQUEST:
- POST /job/grades
- HEADER:
Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=
- BODY
{
"tool_consumer_url": "iclicker.blackboard.com",
"tool_consumer_username": "msmith",
"tool_consumer_sso_key": "AfaOSSUPe1Wt",
"course_grades": [
{
"course_id": "c547e2e418274c03a54f74726d53708c",
"assignments": [
{
"category": "Homework",
"name": "Chapter 3 Homework",
"total_points": 10,
"grades": [
{
"user_id": "182",
"points_earned": 8
}
]
}
]
},
{
"course_id": "e2d78a3111ec4d7f88f2d0001dcc863a",
"assignments": [
{
"category": "Tests",
"name": "Test 2",
"total_points": 100,
"grades": [
{
"user_id": "569",
"points_earned": 84
}
]
}
]
}
]
}
RESPONSE
- BODY
{
"error": 0,
"data": {
"async": true,
"job_id": "d5f5d8796c770720cc32ac6dfb3cac2d"
},
"message": null,
"status": 200,
"time": null
}
Like other jobs the status of the Grades Push job can be queried sending a request to the Job end point. An example of this is below:
REQUEST:
- GET /job/d5f5d8796c770720cc32ac6dfb3cac2d
- HEADER:
Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=
RESPONSE:
- BODY:
{
"error": 0,
"data": null
"message": null,
"status": 200,
"time": null,
"job_status_message": "Job is still queued",
"job_status_code": 4
}
Response Objects
When the job is complete the service will return with some status. The "error" property should be checked to verify that there are no errors. Otherwise the data element will contain information explaining what the errors are. Job status objects are more fully described in the Retrieving Results page.
Success
Below is an example of a successful Grades Push Job:
{
"error": 0,
"data": {
"status": [
{
"courseId": "c547e2e418274c03a54f74726d53708c",
"successfulGrades": 2,
"totalGrades": 2,
"errors": [],
"success": true
}
],
"unknown_tool_provider_users": null
},
"message": null,
"status": 200,
"time": 6.64,
"job_status_message": "Job is complete",
"job_status_code": 4
}
Failures
The job can fail in a multitude of ways. Since Grades Push is idempotent the Gateway will attempt to push all grades that it does not find errors with.
Missing Fields/Validation Errors
As all elements in the Grades Push Object are required an error message will be generated if these fields are missing. This will also result in the job not being queued and the error will return immediately.
Invalid Credentials
These errors are covered in the Retrieving Results - Errors section.
Missing Association
Indicated below is a case in which the multiple users were pushed and one user 'user123' was not associated with the Gateway. However the other user was associated and had their grades successfully pushed:
{
"error": 1,
"data": {
"status": [
{
"courseId": "c547e2e418274c03a54f74726d53708c",
"successfulGrades": 1,
"totalGrades": 1,
"errors": [],
"success": true
}
],
"unknown_tool_provider_users": [
"user123"
]
},
"message": "Errors found during Grades Push.",
"status": 200,
"time": 6.56,
"job_status_message": "Job is complete",
"job_status_code": 4
}
Invalid Course
If the Gateway cannot find the course that grades are being pushed for the following error will be produced:
{
"error": 1,
"data": {
"status": [
{
"courseId": "c547e2e418274c03a54f74726d53708c",
"successfulGrades": 0,
"totalGrades": 2,
"errors": [
"Unrecognized Course Id",
"Not all grades were successfully pushed."
],
"success": false
}
],
"unknown_tool_provider_users": null
},
"message": "Errors found during Grades Push.",
"status": 200,
"time": 6.48,
"job_status_message": "Job is complete",
"job_status_code": 4
}
User not enrolled
In the event that the user is known to Gateway and the LMS, it is still possible that the user is not enrolled in the course. In which case the following result may be returned:
{
"error": 1,
"data": {
"status": [
{
"courseId": "c547e2e418274c03a54f74726d53708c",
"successfulGrades": 1,
"totalGrades": 1,
"errors": [
"User not enrolled: phil"
],
"success": false
}
],
"unknown_tool_provider_users": null
},
"message": "Errors found during Grades Push.",
"status": 200,
"time": 6.81,
"job_status_message": "Job is complete",
"job_status_code": 4
}