Manage Coursework

You can manage coursework distributed to students using the CourseWork resource, and completed assignments using the StudentSubmission resource. The following sections describe these in more detail.

Manage assignments and questions

A Coursework resource describes an assignment or question that has been assigned to the students in a course, including any additional materials, and can optionally specify a due date and a max score.

Create assignments

You can create an assignment for a teacher in one of their courses, as shown in the following example:

Python

courseWork = {  
  'title': 'Ant colonies',  
  'description': 'Read the article about ant colonies and complete the quiz.',  
  'materials': [  
     {'link': { 'url': 'http://example.com/ant-colonies' }},  
     {'link': { 'url': 'http://example.com/ant-quiz' }}  
],  
  'workType': 'ASSIGNMENT',  
  'state': 'PUBLISHED',  
}  
courseWork = service.courses().courseWork().create(  
    courseId='<course ID or alias>', body=courseWork).execute()  
print('Assignment created with ID {0}'.format(courseWork.get('id')))

The result includes a server-assigned identifier that can be used to reference the assignment.

To include linked materials in an assignment created via the Classroom API, use a Link resource, specifying the target URL. Classroom automatically fetches the title and thumbnail image. The Classroom API also natively supports Drive and YouTube materials, which can included with a DriveFile resource or YouTubeVideo resource in a similar way.

To specify a due date, set the dueDate and dueTime fields to the corresponding UTC time. The due date must be in the future.

Retrieve assignments and questions

You can retrieve assignments and questions for students and teachers of the corresponding course or by a domain administrator. To retrieve a specific assignment or question, use courses.courseWork.get. To retrieve all assignments or questions (optionally matching some criteria), use courses.courseWork.list.

The required scope depends on the role that the requesting user has in the course. If the user is a student, use one of the following scopes:

  • https://www.googleapis.com/auth/classroom.coursework.students.readonly
  • https://www.googleapis.com/auth/classroom.coursework.students

If the user is a teacher or a domain administrator, use one of the following scopes:

  • https://www.googleapis.com/auth/classroom.coursework.me.readonly
  • https://www.googleapis.com/auth/classroom.coursework.me

Having permission to retrieve an assignment or question does not imply permissions to access materials or material metadata. In practice, this means that an administrator may not see the title of an attached Drive file if they're not a member of the course. If you want to allow administrators access to user files, see the domain-wide delegation guide.

Manage student responses

A StudentSubmission resource represents the work done and grade of a student for an assignment or question. A StudentSubmission resource is implicitly created for each student when a new question or assignment is created.

The following sections explain common actions that manage student responses.

Retrieve student responses

Students can retrieve their own submissions, teachers can retrieve submissions for all students in their courses, and domain administrators can retrieve all submissions for all students in their domain. Each student submission is assigned an identifier; if you know the identifier, use courses.courseWork.studentSubmissions.get to retrieve it.

Use courses.courseWork.studentSubmissions.list to get StudentSubmission that match some criteria, as shown in the following sample:

Python

studentSubmissions = service.courses().courseWork().studentSubmissions().list(  
    courseId=<course ID or alias>, courseWorkId=<assignment ID>).execute()

Retrieve student submissions that belong to a particular student by specifying the userId parameter, as shown in the following sample:

Python

service.courses().courseWork().studentSubmissions().list(  
    courseId=<course ID or alias>,  
    courseWorkId=<assignment ID>,  
    userId=<user ID>).execute()

Students are identified by the unique ID or email address of the user, as returned by the Google Admin SDK. The current user may also refer to their own ID using the "me" shorthand.

It's also possible to get student submissions for all assignments within a course. To do so, use the literal "-" as the courseWorkId, as shown in the following sample:

Python

service.courses().courseWork().studentSubmissions().list(  
    courseId=<course ID or alias>,  
    courseWorkId='-',  
    userId=<user ID>).execute()

The required scope depends on the role that the requesting user has in the course. Use the following scope if the user is a teacher or a domain administrator:

  • https://www.googleapis.com/auth/classroom.coursework.students.readonly
  • https://www.googleapis.com/auth/classroom.coursework.students

Use the following scope if the user is a student:

  • https://www.googleapis.com/auth/classroom.coursework.me.readonly
  • https://www.googleapis.com/auth/classroom.coursework.me

Having permission to retrieve a student submission does not imply permissions to access attachments or attachment metadata. In practice, this means that an administrator may not see the title of an attached Drive file if they're not a member of the course. If you want to allow administrators access to user files, see the domain-wide delegation guide.

Adding attachments to a student response

You can attach links to a student submission by attaching a Link, DriveFile, or YouTubeVideo resource. This is done with courses.courseWork.studentSubmissions.modifyAttachments, as shown in the following sample:

Python

request = {
  'addAttachments': [
    {'link': { 'url': 'http://example.com/quiz-results' }},
    {'link': { 'url': 'http://example.com/quiz-reading' }}
  ]
}
service.courses().courseWork().studentSubmissions().modifyAttachments(  
    courseId=<course ID or alias>,  
    courseWorkId=<assignment ID>,  
    id=<studentSubmission ID>,  
    body=request).execute()

A Link attachment is defined by the target URL; Classroom will automatically fetch the title and thumbnail image. You can learn about the other materials at their respective reference pages.

Materials can be created by a course teacher or by the student that owns the corresponding student submission, but only for student submissions with a courseWorkType of "ASSIGNMENT".

The required scope depends on the role that the requesting user has in the course. Use the following scope if the user is a teacher:

  • https://www.googleapis.com/auth/classroom.coursework.students

Use the following scope if the user is a student:

  • https://www.googleapis.com/auth/classroom.coursework.me

Grade student responses

The StudentSubmission resource has two fields to store grades: assignedGrade, which is the grade reported to students, and draftGrade, which is a tentative grade visible only to teachers. These fields are updated using courses.courseWork.studentSubmissions.patch with a field mask containing the appropriate fields, as shown in the following sample.

Python

studentSubmission = {  
  'assignedGrade': 99,  
  'draftGrade': 80  
}  
service.courses().courseWork().studentSubmissions().patch(  
    courseId=<course ID or alias>,  
    courseWorkId=<courseWork ID>,  
    id=<studentSubmission ID>,  
    updateMask='assignedGrade,draftGrade',  
    body=studentSubmission).execute()

Students don't see the draftGrade value, but only the final assignedGrade. Setting assignedGrade is the most direct way to grade student work. However, it's better to use draftGrade when teachers are going to manually review and return student work from within Classroom; the draftGrade value will be copied to assignedGrade when the teacher manually returns the student submission.

Manage student response state

A student response may be unsubmitted, turned in, or returned. The state field in StudentSubmission indicates the current state. To change the state, call one of the following methods:

All of these methods take an empty body. Example:

Python

service.courses().courseWork().studentSubmission().turnIn(
    courseId=<course ID or alias>,
    courseWorkId=<courseWork ID>,
    id=<studentSubmission ID>,
    body={}).execute()

The student that owns a StudentSubmission may turn it in or reclaim it. Only a turned in submission may be reclaimed. Course teachers can return a StudentSubmission that is in the turned in state.

Send feedback about...

Classroom API
Classroom API