Grade Passback Integration Considerations
When you configure your Instructure OneRoster integration, review grade passback integration considerations. The Instructure OneRoster grade passback (GPB) integration includes variations of the OneRoster specifications, as required by various SIS providers.
Depending upon your SIS gradebook configuration, you can customize the getCategories query to correctly sync assignments from Canvas to your SIS gradebook.
Because most SIS providers automatically calculate grading periods based on an assignment's due date, you may not need to include this endpoint in your grade passback configuration.
You can configure your lineitem requests. Learn more about the OneRoster lineitem category data structure.
You can configure your lineitem requests. Learn more about the OneRoster results.
Note: Instructure is a OneRoster Consumer. For OneRoster Consumer and Provider definitions, view the Introduction to OneRoster.
Grading Categories
When the Instructure OneRoster integration runs a grade sync, the getAllCategories request returns all SIS gradebook grading categories.
Any grading category that does not include the metadata.classId field is considered a global category that can be applied and used in all classes.
Global Categories
If your SIS gradebook only supports global grading categories, then the integration should function properly without the metadata fields.
Category Object Extension: metadata.classId
To allow the OneRoster API v1.1 to more correctly associate categories and other objects in the grade passback specification, a category field is required.
The below extension allows the integration to correctly identify the SIS grading categories needed for grade passback. Any categories that do not have this metadata.classId field are assumed to be global, and the first category name that matches a Canvas assignment group name is used for GPB.
If you choose to support metadata.classId, you should also include a filter query for the getCategories endpoint. This allows the integration to pull categories for a single section.
| Category Object Extension |
|---|
| { "categories": [ { "status": "active”, "title": "Assessments”, “sourcedId": "guid”, "href": "URI to resource in SIS”, "metadata": { "classId": "{class_id}” }, "dateLastModified": null }… ] } |
Endpoint Option: getCategoriesForClass
In anticipation of the OneRoster API 1.2 specification, you can add support for a new getCategoriesForClass endpoint. This allows the integration to identify available SIS grading categories for a section during a grade passback sync.
Note: If you implement this approach, you do not need to configure support for the metadata.classId field.
No Matching Categories
Your Instructure OneRoster integration may be configured to sync Canvas assignments into SIS grading categories. During a grade sync, if no matching categories are found, an error message displays indicating that none of the SIS grading category names match the Canvas assignment group names.
Default Category
Your SIS may include a default sourcedId grading category that is supported in all of the SIS gradebooks. During a grade sync from Canvas, if an assignment cannot be matched to a SIS grading category, it syncs to the default grading category.
If a common category sourcedId is not available, this value can also be sent as null.
Not Sending Categories
If your institution's SIS supports gradebooks without grading categories, your Instructure OneRoster integration can be configured to send the assignment's lineItem JSON without the category field or with “category”: null. The integration can choose to always send null, or only send null if no matching category is found.
Alternatively, your existing integration may automatically sync uncategorized assignment lineItems to the SIS gradebook’s uncategorized grading category. If this is the case for your integration, instructors can move the assignment into the appropriate SIS grading category. To prevent the assignment from re-syncing to the uncategorized field, your integration should be configured to recognize the manually assigned category as a sticky field.
Overriding Category
Your institution's SIS gradebook may be configured with an always-used preselected default grading category. To accomodate this configuration, your Instructure OneRoster integration can include a hardcoded category sourcedId. All instructor gradebooks in your SIS must include this category. Alternatively, the integration can be configured with an overriding null category value.
Grading Periods
During a grade sync from Canvas, most SIS automatically calculate and associate an assignment's correct grading period using the dueDate lineitem. This automatic calculation means that the gradingPeriod lineitem can be omitted or sent as null.
If required by your integration, a gradingPeriod lineitem can be configured. However, if it is incorrectly configured, grade sync errors will occur more frequently.
Learn more about OneRoster academic sessions.
LIneItem Payload Considerations
You can configure lineitem requests to include in your GPB sync payload.
The below chart displays configurable lineitem requests. As part of the individual client configuration process, you can customize most of the default values. You can also omit any of these values from the payload. Alternatively, if the correlating data is available in the Canvas data extract, you can also configure additional metadata fields.
Learn more about the OneRoster lineitem category data structure.
| OneRoster LIneItem Field Name | Default Value |
|---|---|
sourcedId |
UUIDv4 |
title |
{assignment.name} |
status |
"active" |
description |
Imported from Canvas: https://school.instructure.com/courses/{course_id}/assignments/{assignment_id} |
resultValueMax |
{assignment.points_possible} |
resultValueMin |
0 |
assignDate |
{assignment.unlock_at} OR {assignment.due_at} |
dueDate |
{assignment.due_at} |
class |
{OneRoster class reference object} |
category |
{OneRoster category reference object} OR null* |
gradingPeriod |
null OR {OneRoster academicSession reference object}** |
*see grade passback implementation notes for categories
**see grade passback implementation notes for gradingPeriods
Example Payload Configurations
| Payload Example with SourceID |
|---|
| { "lineItem": { "sourcedId": "799e2caf-728d-4ef6-8ff9-5325e64cecd5” "status": "active”, "title": "Canvas Test Assignment 1”, "description": "Imported from Canvas: https://school.instructure.com/courses/5582/assignments/135”, "resultValueMax": 10, "resultValueMin": 0, "assignDate": "2021-03-10T23:59:59”, "dueDate": "2021-03-10T23:59:59”, "metadata": { "vendorId": “" }, "class": { "href": "~/ims/oneroster/v1p1/classes/100453379”, "sourcedId": "100453379”, "type": “class" }, "category": { "href": "~/ims/oneroster/v1p1/categories/C5C3AC8C-8D0F-48EB-96F4-31437B640D16”, "sourcedId": "C5C3AC8C-8D0F-48EB-96F4-31437B640D16”, "type": “category" }, "gradingPeriod": null } } |
| Payload Example Without SourceID |
|---|
| { "lineItem": { "status": "active”, "title": "Canvas Test Assignment 1”, "description": "Imported from Canvas: https://school.instructure.com/courses/5582/assignments/135”, "resultValueMax": 10, "resultValueMin": 0, "assignDate": "2021-03-10T23:59:59”, "dueDate": "2021-03-10T23:59:59”, "metadata": { "vendorId": “" }, "class": { "href": "~/ims/oneroster/v1p1/classes/100453379”, "sourcedId": "100453379”, "type": “class" }, "category": { "href": "~/ims/oneroster/v1p1/categories/C5C3AC8C-8D0F-48EB-96F4-31437B640D16”, "sourcedId": "C5C3AC8C-8D0F-48EB-96F4-31437B640D16”, "type": “category" }, "gradingPeriod": null } } |
Result Payload Considerations
You can configure result payloads included in your GPB sync.
The below chart displays configurable lineitem requests. As part of the individual client configuration process, you can customize most of the default values. You can also omit any of these values from the payload. Alternatively, if the correlating data is available in the Canvas data extract, you can also configure additional metadata fields.
Learn more about the OneRoster results.
| OneRoster Field Name | Default Value |
|---|---|
| sourcedId | {sourcedId} |
| lineItem | {OneRoster lineItem reference object} |
| student | {OneRoster user reference object} |
| scoreStatus | "fully graded" or “not submitted” or “exempt” |
| score | {submission.score} |
| comment | omitted by default* |
| scoreDate | omitted by default** |
*see grade passback implementation notes for comments
**see grade passback implementation notes for scoreDate
| Payload Example |
|---|
| { "result": { "sourcedId": "0031e9ee-5bd0-4d80-a5f7-5c14fe75acc0”, "lineItem": { "href": "~/ims/oneroster/v1p1/lineItems/0ea49ae5-4a6b-45d5-a0c2-b01facbfbc5f”, "sourcedId": "0ea49ae5-4a6b-45d5-a0c2-b01facbfbc5f”, "type": “lineItem" }, "student": { "href": "~/ims/oneroster/v1p1/students/S100051158”, "sourcedId": "S100051158”, "type": “student" }, "scoreStatus": "fully graded”, "score": 10 } } |
Scores
In Canvas an instructor can assign negative score values as well as exceed the maximum score value. Consider how your integration will handle these potential situations.
In certain cases, like an exempt scoreStatus, your integration should be configured to pass a null score value, otherwise a 0 score value is passed to the SIS.
| scoreStatus Value from Canvas | Notes |
|---|---|
| fully graded |
submission.workflow_state = gradedShould always have a score associated. |
| not submitted |
submission.missing = trueMostly will only pass if there is a score associated, but it is possible to have a score=null
|
| exempt |
submission.excused = trueScore will be null by default or 0
|
