cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Grade Passback Integration Considerations

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.

Grading Categories

Depending upon your SIS gradebook configuration, you can customize the getCategories query to correctly sync assignments from Canvas to your SIS gradebook.

Grading Periods

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.

LineItem Payload

You can configure your lineitem requests. Learn more about the OneRoster lineitem category data structure.  

Results Payload

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 = graded
Should always have a score associated.
not submitted submission.missing = true
Mostly will only pass if there is a score associated, but it is possible to have ascore=null
exempt submission.excused = true
Score will be null by default or 0






If you find a typo or outdated info, or have a suggestion to improve this guide, please share your feedback