R/AssignmentFunctions.R

In sterfa02/SchoologyAPI: Creates R Functions for Schoology API Functions

#' List Assignments for a Course
#' 
#' This function returns a list of published assignments.
#' 
#' An assignment is specific user assigned to the realm object. 
#' @param section_id The section id of the course.
#' @param limit Limit returned values.
#' @concept Assignments
#' @return A dataframe of assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
# This function returns a data frame of assignments.
listAssignments <- function(section_id, limit = NULL){
  
  params <- list()
  
  endpoint <- paste0('sections/', section_id, '/assignments')
  
  toReturn <- data.frame()
  total <- min(1000000, limit)
  while(nrow(toReturn) < total - 1){
    params$start <- nrow(toReturn) + 0
    params$limit <- 200
    resource <- makeRequest(endpoint, params, verb = 'GET')
    total <- as.integer(resource$total)
    newData <- jsonlite::fromJSON(toJSON(resource$assignment), flatten = TRUE)
    if(length(newData) == 0) break()
    toReturn <- bind_rows(toReturn, characterizeDataFrame(newData))
    if(length(total) == 0) break()
  }
  
  return(toReturn)
}


#' List Folder Items for a Course
#' 
#' This function returns a list of grade items for a course section.
#' 
#' An assignment is specific user assigned to the realm object. 
#' @param course_id The course id of the course.
#' @param folder_id The folder id of the course.
#' @concept Assignments
#' @return A dataframe of assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
listFolderItems <- function(course_id, folder_id){
  
  endpoint <- paste0('courses/', course_id, '/folder/', folder_id)
  
  resource <- makeRequest(endpoint, verb = 'GET')
  
  toReturn <- data.frame()
  total <- 1000000
  while(nrow(toReturn) < total - 1){
    params$start <- nrow(toReturn) + 0
    params$limit <- 200
    resource <- makeRequest(endpoint, params, verb = 'GET')
    total <- as.integer(resource$total)
    newData <- jsonlite::fromJSON(toJSON(resource$assignment), flatten = TRUE)
    if(length(newData) == 0) break()
    toReturn <- bind_rows(toReturn, characterizeDataFrame(newData))
    if(length(total) == 0) break()
  }
  
  return(toReturn)
}





#' List Grade Items for a Course
#' 
#' This function returns a list of grade items for a course section.
#' 
#' An assignment is specific user assigned to the realm object. 
#' @param section_id The section id of the course.
#' @param with_tags Return tags
#' @param with_attachments Return attachments
#' @concept Assignments
#' @return A dataframe of assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
# This function returns a data frame of assignments.
listGradeItems <- function(section_id, with_tags = T, with_attachments = T){
  
  params <- list(with_tags = as.integer(with_tags), with_attachments = as.integer(with_attachments))
  
  endpoint <- paste0('sections/', section_id, '/grade_items')
  
  toReturn <- data.frame()
  total <- 1000000
  while(nrow(toReturn) < total - 1){
    params$start <- nrow(toReturn) + 0
    params$limit <- 200
    resource <- makeRequest(endpoint, params, verb = 'GET')
    
  #  return(resource)
    
    total <- as.integer(resource$total)
    newData <- jsonlite::fromJSON(toJSON(resource$assignment), flatten = TRUE)
    if(length(newData) == 0) break()
    toReturn <- bind_rows(toReturn, characterizeDataFrame(newData))
    if(length(total) == 0) break()
  }
  
  return(toReturn)
}


#' Get Assignment Details
#' 
#' This function returns details about a Schoology assignment.
#' 
#' @param section_id The id of the section containing the assignment.
#' @param assignment_id The id of the assignment.
#' @concept Assignments
#' @return A dataframe of assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
viewAssignment = function(section_id, assignment_id, with_attachments = 1, with_tags = 1){
  
  params <- list(with_attachments = with_attachments, 
                 with_tags = with_tags)
  
  endpoint = paste0('sections/', section_id, '/assignments/', assignment_id)
  
  resource = makeRequest(endpoint, params, verb = 'GET')
  
  # ... Return resource.
  resource = fromJSON(toJSON(resource), flatten = TRUE)
  resource = characterizeDataFrame(resource)
  
  return(resource)
}


#' Create Assignment
#'
#' This function creates a section assignment.
#'
#' @param section_id The id of the assignment section
#' @param assignment_id The id of the assignment to update.
#' @param title The assignment title
#' @param description The assignment description
#' @param due When the assignment is due
#' @param grading_scale The ID of the grading scale for this assignment. For no grading scale, use "0". Course grading scales can be found on the course Grade Setup page.
#' @param grading_period The grading period ID to which this assignment belongs. For "Other", use "0".
#' @param grading_category The grading category ID to which this assignment belongs
#' @param max_points The maximum number of points for this assignment (excl. extra credit)
#' @param factor The relative weight of this assignment
#' @param is_final Mark this assignment as a midterm or final
#' @param show_comments Show grade comments to students
#' @param grade_stats 0 - Hide statistics, 1 - Show statistics without bell curve
#' @param allow_dropbox Allow students to post assignment submissions to a dropbox.
#' @param allow_discussion Enable the assignment profile discussion board
#' @param published Whether or not the assignment is published
#' @param type Distinguishes different types of grade items (grade items being a broad term for anything that can have a grade).
#' @param grade_item_id If this is of type assignment, this ID will point to the assignment object id attribute. If this is of type discussion, this ID will point to the discussion object ID.
#' @param dropbox_submissions This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a snapshot of the number of submissions in this assignments dropbox
#' @param last_dropbox_submission This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a timestamp representing when the last dropbox revision was submitted.
#' @param show_rubric This field is true when the assignment is using a rubric and the teacher has enabled the option for students to see the rubric.
#' @param assignees This field shows which enrollees are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all assignees will be removed from the assignment
#' @param grading_group_ids This field shows what grading groups are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all grading groups will be removed from the assignment
#' @concept Assignments
#' @return A dataframe of updated assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
createAssignment = function(section_id, title = NULL, description = NULL, due = NULL, grading_scale = NULL, grading_period = NULL, grading_category = NULL, max_points = NULL, factor = NULL, is_final = NULL, show_comments = NULL, grade_stats = NULL, allow_dropbox = NULL, allow_discussion = NULL, published = NULL, type = NULL, grade_item_id = NULL, dropbox_submissions = NULL, last_dropbox_submission = NULL, show_rubric = NULL, assignees = NULL, grade_group_ids = NULL){

  params = as.list(environment())[-(1)]

  endpoint = paste0(realm, '/', realm_id, '/assignments')

  response <- makeRequest(endpoint, verb = 'POST', payload = fromJSON(toJSON(params, pretty = TRUE)))

  return(response)
}

#' Update Assignment Details
#' 
#' This function modifies one or more attributes of an assignment.
#' 
#' @param section_id The id of the assignment section
#' @param assignment_id The id of the assignment to update.
#' @param title The assignment title
#' @param description The assignment description
#' @param due When the assignment is due
#' @param grading_scale The ID of the grading scale for this assignment. For no grading scale, use "0". Course grading scales can be found on the course Grade Setup page.
#' @param grading_category The grading category ID to which this assignment belongs
#' @param max_points The maximum number of points for this assignment (excl. extra credit)
#' @param factor The relative weight of this assignment
#' @param is_final Mark this assignment as a midterm or final
#' @param show_comments Show grade comments to students
#' @param grade_stats 0 - Hide statistics, 1 - Show statistics without bell curve
#' @param allow_dropbox Allow students to post assignment submissions to a dropbox.
#' @param allow_discussion Enable the assignment profile discussion board
#' @param published Whether or not the assignment is published
#' @param type Distinguishes different types of grade items (grade items being a broad term for anything that can have a grade).
#' @param grade_item_id If this is of type assignment, this ID will point to the assignment object id attribute. If this is of type discussion, this ID will point to the discussion object ID.
#' @param dropbox_submissions This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a snapshot of the number of submissions in this assignments dropbox
#' @param last_dropbox_submission This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a timestamp representing when the last dropbox revision was submitted.
#' @param show_rubric This field is true when the assignment is using a rubric and the teacher has enabled the option for students to see the rubric.
#' @param assignees This field shows which enrollees are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all assignees will be removed from the assignment
#' @param grading_group_ids This field shows what grading groups are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all grading groups will be removed from the assignment
#' @concept Assignments
#' @return A dataframe of updated assignment details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/assignment}{API Documentation}
#' @export
updateAssignment = function(section_id, assignment_id, title = NULL, description = NULL, due = NULL, grading_scale = NULL, grading_category = NULL, max_points = NULL, factor = NULL, is_final = NULL, show_comments = NULL, grade_stats = NULL, allow_dropbox = NULL, allow_discussion = NULL, published = NULL, type = NULL, grade_item_id = NULL, dropbox_submissions = NULL, last_dropbox_submission = NULL, show_rubric = NULL, grading_period = NULL, assignees = NULL, grade_group_ids = NULL){
  
  readline('Warning: updateAssignment has caused assignment attachment loss in the past. Are you sure you want to proceed?')
  
  params = as.list(environment())[-(1:2)]
  
  params <- purrr::compact(params)
  
  if(length(params) == 0){
    stop('ERROR: No changes requested.')
  }
  
  print(jsonlite::fromJSON(jsonlite::toJSON(params, pretty = TRUE)))
  
  endpoint = glue::glue('sections/{section_id}/assignments/{assignment_id}')
  
  response <- makeRequest(endpoint, verb = 'PUT', payload = fromJSON(toJSON(params, pretty = TRUE)))
  
  return(response)
}


#' List Grading Rubrics for a Course
#' 
#' This function returns a list of grading_rubrics.
#' 
#' An grading_rubric is specific user assigned to the realm object. 
#' @param section_id The section id of the course.
#' @param limit Limit returned values.
#' @concept Grading Rubrics
#' @return A dataframe of grading_rubric details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-grading_rubric}{API Documentation}
#' @export
# This function returns a data frame of grading_rubrics.
listGradingRubrics <- function(section_id){
  
  params <- list()
  
  endpoint <- paste0('sections/', section_id, '/grading_rubrics')
  
  toReturn <- data.frame()
  total <- 1000000
  while(nrow(toReturn) < total - 1){
    params$start <- nrow(toReturn) + 0
    params$limit <- 200
    resource <- makeRequest(endpoint, params, verb = 'GET')
    total <- as.integer(resource$total)
    newData <- jsonlite::fromJSON(toJSON(resource$grading_rubric), flatten = TRUE)
    if(length(newData) == 0) break()
    toReturn <- bind_rows(toReturn, characterizeDataFrame(newData))
    if(length(total) == 0) break()
  }
  
  return(toReturn)
}

#' List Documents for a Course
#' 
#' This function returns a list of published documents
#' 
#' @param section_id The section id of the course.
#' @param limit Limit returned values.
#' @concept Assignments
#' @return A dataframe of document details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
# This function returns a data frame of assignments.
listDocumentsForSection <- function(section_id){
  
  params <- list()
  
  endpoint <- paste0('sections/', section_id, '/documents')
  
  toReturn <- data.frame()
  total <- 1000000
  while(nrow(toReturn) < total - 1){
    params$start <- nrow(toReturn) + 0
    params$limit <- 200
    resource <- makeRequest(endpoint, params, verb = 'GET')
    total <- as.integer(resource$total)
    newData <- jsonlite::fromJSON(toJSON(resource$document), flatten = TRUE)
    if(length(newData) == 0) break()
    toReturn <- bind_rows(toReturn, characterizeDataFrame(newData))
    if(length(total) == 0) break()
  }
  
  return(toReturn)
}


#' Get Document Details
#' 
#' This function returns details about a Schoology document
#' 
#' @param section_id The id of the section containing the document
#' @param document_id The id of the document
#' @concept Assignments
#' @return A dataframe of document details.
#' @section References:
#' \href{https://developers.schoology.com/api-documentation/rest-api-v1/course-assignment}{API Documentation}
#' @export
viewDocument = function(section_id, document_id){
  
  endpoint = paste0('sections/', section_id, '/documents/', document_id)
  
  resource = makeRequest(endpoint, verb = 'GET')
  
  # ... Return resource.
  resource = fromJSON(toJSON(resource), flatten = TRUE)
  resource = characterizeDataFrame(resource)
  
  return(resource)
}