Class CanvasService

java.lang.Object
edu.ucsb.cs156.frontiers.services.CanvasService

@Service @Validated public class CanvasService extends Object
Service for interacting with the Canvas API.

Note that the Canvas API uses a GraphQL endpoint, which allows for more flexible queries compared to traditional REST APIs.

For more information on the Canvas API, visit the official documentation at ....

You can typically interact with Canvas API GraphQL endpoints interactively by appending /graphiql to the URL of the Canvas instance.

For example, for UCSB Canvas, use: ...

Every Canvas GraphQL connection is paginated: without a first argument Canvas returns only the first page (20 items by default), and it never returns more than PAGE_SIZE per request. Every connection read here therefore asks for PAGE_SIZE items and follows pageInfo.endCursor until hasNextPage is false.

  • Constructor Details

    • CanvasService

      public CanvasService(com.fasterxml.jackson.databind.ObjectMapper mapper, org.springframework.web.client.RestClient.Builder builder, CanvasApiTokenSecurityService canvasApiTokenSecurityService)
  • Method Details

    • getCanvasGroupSets

      public List<CanvasGroupSet> getCanvasGroupSets(@HasLinkedCanvasCourse Course course)
    • getCanvasRoster

      public List<RosterStudent> getCanvasRoster(@HasLinkedCanvasCourse Course course)
      Fetches the roster of students from Canvas for the given course, following pagination so that every enrolled student is returned.
      Parameters:
      course - the Course entity containing canvasApiToken and canvasCourseId
      Returns:
      list of RosterStudent objects from Canvas
    • getCanvasGroups

      public List<CanvasGroup> getCanvasGroups(@HasLinkedCanvasCourse Course course, String groupSetId)
      Fetches the groups in a Canvas group set with their members' emails, as used by the pull-teams job. This is a view of getCanvasGroupSetDetail(Course, String).
      Parameters:
      course - the course, which must be linked to Canvas
      groupSetId - the group set's GraphQL relay id or numeric Canvas id
      Returns:
      the groups, each with its members' canonical emails
    • getCanvasGroupSetDetail

      public CanvasGroupSetDetail getCanvasGroupSetDetail(@HasLinkedCanvasCourse Course course, String groupSetId)
      Fetches a Canvas group set with everything the push-to-Canvas job needs: the numeric ids of the group set and its groups, and each group's members as canonical email to numeric Canvas user id. Group membership is paginated, so groups with more than PAGE_SIZE members are completed with follow-up queries.
      Parameters:
      course - the course, which must be linked to Canvas
      groupSetId - the group set's GraphQL relay id (as returned by getCanvasGroupSets) or its numeric Canvas id (as shown in Canvas URLs)
      Returns:
      the group set detail
    • getCanvasUserIdsByEmail

      public Map<String,Integer> getCanvasUserIdsByEmail(@HasLinkedCanvasCourse Course course)
      Fetches the numeric Canvas user id of every student enrolled in the Canvas course, keyed by canonical email, following pagination so that every enrolled student is included.
      Parameters:
      course - the course, which must be linked to Canvas
      Returns:
      map from canonical email to Canvas user id
    • createCanvasGroup

      public Integer createCanvasGroup(@HasLinkedCanvasCourse Course course, Integer groupSetId, String name)
      Creates a group in a Canvas group set.
      Parameters:
      course - the course, which must be linked to Canvas
      groupSetId - the numeric Canvas id of the group set
      name - the name of the new group
      Returns:
      the numeric Canvas id of the new group
      Throws:
      RuntimeException - if Canvas reports a validation error
    • deleteCanvasGroup

      public void deleteCanvasGroup(@HasLinkedCanvasCourse Course course, Integer groupId)
      Deletes a Canvas group.
      Parameters:
      course - the course, which must be linked to Canvas
      groupId - the numeric Canvas id of the group
    • addCanvasGroupMember

      public void addCanvasGroupMember(@HasLinkedCanvasCourse Course course, Integer groupId, Integer userId)
      Adds a user to a Canvas group.
      Parameters:
      course - the course, which must be linked to Canvas
      groupId - the numeric Canvas id of the group
      userId - the numeric Canvas id of the user
    • removeCanvasGroupMember

      public void removeCanvasGroupMember(@HasLinkedCanvasCourse Course course, Integer groupId, Integer userId)
      Removes a user from a Canvas group.
      Parameters:
      course - the course, which must be linked to Canvas
      groupId - the numeric Canvas id of the group
      userId - the numeric Canvas id of the user