LMS API guidelines for OneNote class notebook add-in integration
Applies to: Enterprise notebooks on Office 365
This document provides the API calls needed for OneNote to enumerate classes and assignments, set assignments, download grades and update grades in any LMS.
All requests should be authenticated. All requests should be made over HTTPS.
Note
We recommended that each LMS implement authorization code grant flow for oauth2 implementation. This prevents the user the hassle of entering credentials every time an access token expires.
Retrieve a list of classes
Make a GET request to <Specify URL for retrieving list of classes>.
LMS should return a JSON array of classes for the currently authenticated user.
Each class should have the following properties:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the class, unique on the LMS installation |
| name | string | Human readable name of the class |
Retrieve a list of students in a class
Make a GET request to <Specify URL for retrieving list of students in a class>.
LMS should return a JSON array of students in the class.
Each student should have the following properties:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the student, unique on the LMS installation |
| name | string | Human readable name of the student |
| string | Email address of the student |
Retrieve a list of assignments for a class
Make a GET request to <Specify URL for retrieving list of assignments for a class>.
LMS should return a JSON array of assignments for the class.
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the assignment, unique on the LMS installation |
| title | string | Title of the assignment |
| description | string | Description of the assignment |
| gradetypeid | string | Identifier for the grade type, unique on the LMS installation |
| dueDate | date as string(format: 2016-12-25T00:00:00) | Due date of the assignment. LMS will not store or use the time portion. |
| url | string | URL of the assignment. Available only in the supported versions of LMS. |
| Optional Property Name | Type | Description |
|---|---|---|
| gradetypeid | string | Identifier for the grade type, unique on the LMS installation |
| min | integer | Minimum score that can be assigned to a student |
| max | integer | Maximum score that can be assigned to a student |
| validgradevalues | list | Valid values for grades for this assignment |
Set an assignment to a class
Make a POST request to <Specify URL for setting an assignment to a class>.
The following form POST variables are required:
| Property Name | Type | Description |
|---|---|---|
| title | string (max length: 280) | Title of the assignment |
| dueDate | date as string(format: 2016-12-25T00:00:00) | Due date of the assignment |
| description | string | Description of the assignment |
| Optional Property Name | Type | Description |
|---|---|---|
| gradetypeid | string | Identifier for the grade type, unique on the LMS installation |
| min | integer | Minimum score that can be assigned to a student |
| max | integer | Maximum score that can be assigned to a student |
| validgradevalues | list | Valid values for grades for this assignment |
LMS will return a JSON object with a single id property. The value of this property will be the identifier of the newly set assignment.
Retrieve a list of grades for an assignment
Make a GET request to <Specify URL for retrieving grades for a given assignment>.
LMS should return a JSON array of students who received the assignment and their grades/score.
Each student JSON segment should have the following properties:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the student, unique on the LMS installation |
| string | Email address of the student | |
| graded | boolean | Indicates whether a mark has been supplied by the teacher |
| obtainedMark | integer | Optional mark achieved by the student (e.g. 85) |
| maxMark | integer | Optional highest mark possible (e.g. 100) |
| feedback | string | Optional feedback given to the student (e.g. "Great work") |
| grade | string | Optional grade given to the student (e.g. "A") |
Note that LMS may support grading out of numbers other than 100. In that case (maxMark is not equal to 100), OneNote may need to convert the obtainedMark if this cannot be displayed in the OneNote UI.
Set a grade for a student
Make a POST request to <Specify URL for setting grade for a given student>.
The following form POST variables can be included:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the student, a guid |
| source | string | Always set the value to "onenote" |
| obtainedMark | integer | Mark achieved by the student |
| maxMark | integer | Maximum possible mark achievable |
| obtainedGrade | string | Grade or level achieved by the student (e.g.: "A") |
| comments | string | Free text feedback for the student |
Get grade types
Make a GET request to <Specify URL for getting grade types>.
LMS should return a JSON array of grade types. Each grade type should have the following properties:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the grade type, unique on the LMS installation |
| gradeTypeCategory | GradeTypeCategory | Category for the grade type, unique on the LMS installation |
| max | integer | Maximum score possible |
| description | string | Display string for the grade type |
Get specific grade type
Make a GET request to <Specify URL for getting grade type by id>.
LMS should return a JSON of single grade type, which has the following properties:
| Property Name | Type | Description |
|---|---|---|
| id | string | Identifier for the grade type, unique on the LMS installation |
| gradeTypeCategory | GradeTypeCategory | Category for the grade type, unique on the LMS installation |
| max | integer | Maximum score possible |
| description | string | Display string for the grade type |
Create/delete classes and delete assignments
These are optional but highly recommended to have for integration testing. The Microsoft Class Notebook team exercises these endpoints for cleanup purposes.
enum GradeTypeCategory
{
/// <summary>
/// no grade type category.
/// </summary>
None,
/// <summary>
/// Numeric grade type category.
/// </summary>
Numeric,
/// <summary>
/// Percent grade type category.
/// </summary>
Percentage,
/// <summary>
/// Letter grade type category.
/// </summary>
Letters,
}
Test environment prerequisites
Your test environment is composed of two systems:
Office 365 test tenant
This can be any Office 365 tenant that you have access to, and there are several teacher and student accounts with valid office licenses.
The Demo Office 365 Tenant is available to partners. When you set up this demo tenant, you can choose a custom K–12 EDU instance that comes pre-populated with teachers and students and education SKUs.
LMS test environment and accounts
You need to provide the Class Notebook team with the following information:
- Base Url of your LMS/SIS that hosts the API endpoints.
- App ID (if you don't support oauth2): A unique app ID assigned to the class notebook add-in that allows you to detect it as a valid application.
- App key (if you don't support oauth2): The app secret for the given app ID.
Marketing information prerequisites
Logo image. It doesn’t have to be super high resolution. Our current logos are in fact less than 100 K in size and up to 300x300 pixels max.
Description. The description should be short, ~75 words (better if around 50) of messaging about your offering.
Link to your website. Meant to learn more about your offering.
Button logo. Should be a 64x64 pixels logo.