This page discusses implementation details for creating an attachment and working with student submissions. Note that you may need to supply attachment-related parameters when making making these requests.
Create an attachment
Create an attachment by issuing a
CREATE request to the appropriate
courses.*.addOnAttachments.create endpoint. Your request must include an
AddOnAttachment in the request body.
The following fields are required when creating an attachment:
title: the string name of the attachment.
teacherViewUri: the URI for the Teacher View of the attachment.
studentViewUri: the URI for the Student View of the attachment.
studentWorkReviewUri: the URI for the teacher to see the student's work on the attachment. This field is only required for activity-type attachments.
You may want to include some of the following optional fields:
dueTimeif specifying when the attachment is due.
maxPoints: the maximum grade for the attachment. Must be a non-zero value if you want to support grade passback. Applies to activity-type attachments only.
AddOnAttachment resource reference for more details on these fields.
Student submission details
A typical submission workflow follows these steps:
- A student launches the
studentViewUrito complete an activity.
- The add-on retrieves a
getAddOnContextmethod using student credentials.
attachmentIdare stored by the add-on developer as the unique identifier of the student's work. In the event that a teacher copies an assignment in Classroom, you can use the composite key of these two parameters to display a new attachment in the copied assignment. See our page on copied content for more details.
- A teacher interested in reviewing student work launches the
studentWorkReviewUri. The request includes the following query parameters:
- The add-on developer uses these four IDs to retrieve the student work. Use
courses.courseWork.addOnAttachments.studentSubmissionsendpoint to retrieve or modify information about a student submission.
Detect submission state
GET request to the
courses.courseWork.addOnAttachments.studentSubmissions endpoint to get
details about a specific
submissionId. You receive an
AddOnAttachmentStudentSubmission object, which contains the submission's grade
pointsEarned) and current state (
postSubmissionState). The submission state
can be one of the following values:
NEW, if the student has never accessed the submission.
CREATED, if the student has created a submission but not yet submitted it.
TURNED_IN, if the student has submitted their work to the teacher.
RETURNED, if the teacher has returned the submission to the student.
RECLAIMED_BY_STUDENT, if the student has "unsubmitted" their work.
Use this endpoint to detect the state of the student's work in your add-on. You might then adjust the views or options provided to the student depending on the state returned. This might include features such as:
- Displaying the turn-in status of assignments within your add-on. This may help students avoid potential confusion and ensure they don't mistakenly fail to turn in an assignment.
- Restricting submission edit privileges. If the assignment has status
RECLAIMED_BY_STUDENT, the student might be allowed to edit their submission. If the assignment has status
RETURNED, the student might not be allowed to edit their submission.
Grades and multiple attachments
Only one add-on attachment can be used to set the grade for a single
assignment. If a teacher creates more than one activity-type attachment that
maxPoints value, only the first such attachment can set the
assignment grade. Either leave the
maxPoints value unset or set it to zero to
disable grade passback for an attachment.
Set a submission's grade
You can modify a student submission by sending a
PATCH request to the
courses.courseWork.addOnAttachments.studentSubmissions endpoint. The request
body must include an instance of
AddOnAttachmentStudentSubmission with the
modified values. Set the
pointsEarned field to modify a submission's grade.
The value passed in
pointsEarned becomes a draft grade visible to the
teacher in the Classroom UI. Teachers can modify the draft grade
before returning the assignment to students. See Overview of grading in the
Classroom UI for details on how grades are
presented to teachers.
Note that you can set the grade with
pointsEarned only if the following are
- The attachment must have a positive
- The add-on must have been the original creator of the attachment.
Note also that you can modify an already-created
value by issuing a
PATCH request to the
When to set a grade
You have some choice over when a grade is passed back to Google Classroom. The critical distinction is whether you choose to store teacher's credentials, as only the teacher can modify a grade.
There are two add-on moments at which you might pass a grade to Google Classroom: when the student completes their work or when the teacher opens the student's work in the Student Work Review iframe.
If you want to set grades when the student completes the work, you must store a teacher's offline credentials, then retrieve and use them to modify the grade when the student completes the work. This method provides some potential benefits:
- Provide seamless grade updates. Teachers don't need to take any special action to cause grades to populate in the Classroom UI.
- Provide real-time insight into a class's progression through an assignment. By setting grades as students complete attachments, teachers can get a sense of their students' understanding without opening every submission.
Note that this approach also allows for an asynchronous approach to grade
sync. You might periodically poll the
endpoint to detect when a student has submitted their work. When it has been
submitted, set the submission's grade using the stored credentials.
If you don't want to load the teacher's credentials during a student session, you can use the active teacher's credentials when they load the student's submission in the Student Work Review iframe. However, this may not provide an especially smooth user experience as grades in the Classroom UI don't update in real time and teachers would be required to open every submission's Student Work Review iframe.
Detect changes in assignment grades
it's possible for teachers to edit the grade settings in Classroom after an assignment has been created. Such edits might include:
- Changing the assigned points value.
- Changing an assignment's
- Changing whether the assignment should be graded at all.
To see the current grading settings of an assignment, we recommend that you send
GET request to the
courses.courseWork endpoint. The response includes
maxPoints value. An ungraded assignment has a null or zero
If you have passed a grade back to Classroom, use the
courses.courseWork.addOnAttachments.studentSubmissions endpoint to fetch or
alter the grade for an add-on attachment. The grade value is set using the
pointsEarned field. Consider checking and, if necessary, updating this value
if your product allows teachers to edit a student's score for a particular