Breaking change: Education API updates in Microsoft Graph beta

Microsoft Graph team

We are announcing several changes to the education API in Microsoft Graph beta, including a breaking change related to submissions. This change will affect existing applications that get and update submissions. This change is a step toward exposing rubrics in Microsoft Graph in the future.

Breaking change to submissions

We will be deploying a breaking change to the Get submission, List submissions, and Update submission APIs in the Microsoft Graph beta endpoint. We expect the breaking change to be fully deployed by the end of April 2019. These changes are part of steps to expose rubrics in Microsoft Graph and will affect existing applications that are getting and updating submissions.

The following are the updates:

  • Get submission, List submissions: A submission will no longer return with the following properties: feedback, publishedFeedback, grade, publishedGrade. Instead, a submission will return with a single outcomes property. The outcomes property is a list that contains any number of outcome objects. An outcome is the result of a submission, and one of each type of outcome can be contained within the outcomes list. We support any combination of supported outcome types, and you do not need to have all of them. Currently, we support the following types of outcomes: feedback and points (formerly grade).
    • A submission can be expanded ($expand = outcomes) to fetch the outcomes field. If outcomes is not expanded, a submission will not have the outcomes property (and due to this change, will also not have feedback or grade properties).
  • Update submission: This method will no longer update the feedback or grade properties. You can update these values via Update outcomes (as described later in this post).

Eventually, when rubrics are exposed in Microsoft Graph, you will be able to get an update a rubric outcome via the outcomes list on the submission.

Get submission – current behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission/{id}

Response

Submission with the following properties: feedback, publishedFeedback, grade, publishedGrade

Get submission – new behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission/{id}/?$expand=outcomes

Response

Submission WITHOUT the following properties: feedback, publishedFeedback, grade, publishedGrade. Submission WITH the following property: outcomes

List submissions – current behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission/

Response

Submission with the following properties: feedback, publishedFeedback, grade, publishedGrade

List submission – new behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission/?$expand=outcomes

Response

Submissions, where each submission lacks the following properties: feedback, publishedFeedback, grade, publishedGrade. Submissions, where each submission has the following property: outcomes.

Update submission – current behavior

Request

PATCH https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission
{
	"feedback": {
		"text": {
			"contentType":"text",
			"content": "Needs work"
		}
	}
}

Response

Ability to patch submission on the following properties: feedback, publishedFeedback, grade, publishedGrade

Update submission – new behavior

Request

PATCH https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}/submission/{id}/outcomes/{id}
{
	"@odata.type": "#microsoft.education.assignments.api.educationFeedbackOutcome",
	"feedback": {
		"text": {
			"contentType":"text",
			"content": "Needs work"
		}
	}
}

Response

Ability to patch one outcome at a time per unique submission. For example, if you want to update both feedback and points, you will need to make two separate calls – one to update the feedback outcome, and one to update the points outcome. You will be able to find the outcomeId you want to update by getting the submission.

Assignment categories

We are exposing assignment categories in the Microsoft Graph beta endpoint. We now support the following Microsoft Graph calls:

Forms resource

We are exposing Microsoft Forms as a resource through the Microsoft Graph API. A Microsoft Forms resource is currently served as a hyperlink (URL). The formResource resource in Microsoft Graph beta exposes its own custom properties.

Get assignment – current behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}

Response

Assignment with forms resource has the following property:

fileUrl

Get assignment – new behavior

Request

GET https://graph.microsoft.com/beta/Education/classes/{id}/assignments/{id}

Response

Assignment with forms resource will have the following resource properties:

"resource":{
	"@odata.type":"#microsoft.education.assignments.api.educationFormResource",
	"displayName":"",
	"createdDateTime":"2019-04-01T22:01:38.2604366Z",
	"lastModifiedDateTime":"2019-04-01T22:01:38.2614376Z",
	"originalFormId":"",
	"formId":"",
	"isGroupForm":true,
	"viewUrl":"",
	"editUrl":"",
	"createdBy":{
		"application":"",
		"device":"",
		"user":{
			"id":"",
			"displayName":""
		}
	},
	"lastModifiedBy":{
		"application":"",
		"device":"",
		"user":{
			"id":""
			"displayName":""
		}
	}
}

Notes:

  • viewUrl is the URL for students and editUrl is the URL for teacher(s).
  • originalFormId refers to the form that this form was cloned from for this assignment.
  • formId refers to the cloned form.

Feedback usabilla icon