d2l_sdk 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a6e8ed075f1d0e73100f4d1da16fd39626b49b3
-  data.tar.gz: 7fa70c1917e6c0a4aeb4f9cb853df0e68da0689e
+  metadata.gz: 88964b8ade0908b80eda0463f78cc82a18ca4c6a
+  data.tar.gz: 855c097579e67071038f779cee78e7b82daafddb
 SHA512:
-  metadata.gz: 81d1fe998f56240a5af90ab20402589278ddce187048b09c16ce87454550c262e4959b1dd4d5fcec9ce6ab73d0bce65b0aa5fc468e30065866368d65b2121027
-  data.tar.gz: 499ce6508d9320c0c3daeb4f641dee939e30dd41ebf4ff1cb811798227764357016364952e0b28930275b854d56d8e882f14a54bb5d4e4f23db9a05e26580d79
+  metadata.gz: f7c1ccbd845a45c2f51680e603309f5b9a72f0572b32213c6a2350012fa29331f9fed7708ea494b73df3bd356472489522b7275d06f26d863afd4006e5c0ef0d
+  data.tar.gz: d8476be7c9e325f11421bb91ff2cb11f1fe4622c11f026c93f5b94ece96020cf08694f30fc12f9ef2368c10ec6b3bf216a0ca8838f751d57fe9b9cebe1cc1ffd

data/lib/d2l_sdk.rb

@@ -1,16 +1,18 @@
-require_relative 'd2l_sdk/course_template'
-require_relative 'd2l_sdk/course'
-require_relative 'd2l_sdk/datahub'
-require_relative 'd2l_sdk/enroll'
-require_relative 'd2l_sdk/group'
-require_relative 'd2l_sdk/org_unit'
-require_relative 'd2l_sdk/section'
-require_relative 'd2l_sdk/semester'
-require_relative 'd2l_sdk/user'
-require_relative 'd2l_sdk/config_variables'
-require_relative 'd2l_sdk/demographics'
-require_relative 'd2l_sdk/logging'
-require_relative 'd2l_sdk/course_content'
-
+require_relative 'd2l_sdk/setup_versions' # Checked
+require_relative 'd2l_sdk/course_template' # Checked
+require_relative 'd2l_sdk/course' # Checked
+require_relative 'd2l_sdk/datahub' # Checked
+require_relative 'd2l_sdk/enroll' # Checked
+require_relative 'd2l_sdk/group' # Checked
+require_relative 'd2l_sdk/org_unit' # Checked
+require_relative 'd2l_sdk/section' # Checked
+require_relative 'd2l_sdk/semester' # Checked
+require_relative 'd2l_sdk/user' # Checked
+require_relative 'd2l_sdk/config_variables' # Checked
+require_relative 'd2l_sdk/demographics' # Checked
+require_relative 'd2l_sdk/logging' # Checked
+require_relative 'd2l_sdk/course_content' # Checked
+require_relative 'd2l_sdk/grades' # Checked -- added 3/21
+require_relative 'd2l_sdk/news' # Checked -- added 3/21
 
 puts "d2l_sdk loaded"

data/lib/d2l_sdk/auth.rb

@@ -2,7 +2,7 @@ require 'rubygems' # useful
 require 'awesome_print' # useful for debugging
 require 'base64' # NEEDED
 require 'json' # NEEDED
-require 'restclient' # NEEDED
+require 'rest-client' # NEEDED
 require 'openssl' # NEEDED
 require 'open-uri' # NEEDED
 require 'colorize' # useful

data/lib/d2l_sdk/config_variables.rb

@@ -1,26 +1,37 @@
 require_relative 'auth'
 
+
+@debug = false
+
 ########################
-# CONFIG VARIABLES:#####
+# DEFINITIONS:##########
 ########################
-@debug = false
+# NOTE: These provide access to the definition meta-data
+#       surrounding configuration variables.
 
-#Retrieve the definitions for all the configuration variables the user has access to view.
+# Retrieve the definitions for all the configuration variables the
+# user has access to view.
 def get_all_config_var_definitions(search='', bookmark='')
   path = "/d2l/api/lp/#{$lp_ver}/configVariables/definitions/"
   path += "?search=#{search}" if search != ''
   path += "?bookmark=#{bookmark}" if bookmark != ''
   _get(path)
-  #returns paged result set of Definition JSON data blocks
+  # returns paged result set of Definition JSON data blocks
 end
 
-#Retrieve the definitions for a configuration variable.
+# Retrieve the definitions for a configuration variable.
 def get_config_var_definitions(variable_id)
   path = "/d2l/api/lp/#{$lp_ver}/configVariables/(#{variable_id}/definition"
   _get(path)
   # returns Definition JSON data block
 end
 
+########################
+# VALUES:###############
+########################
+# NOTE: These provide access to the values assigned to configuration
+#       variables in the running back-end service.
+
 #Retrieve the value summary for a configuration variable.
 def get_config_var_values(variable_id)
   path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/values"
@@ -50,6 +61,7 @@ def get_config_var_org_unit_override_value(variable_id, org_unit_id)
   # returns OrgUnitValue JSON block
 end
 
+# NOTE: UNSTABLE!!!
 # Retrieve the effective value for a configuration variable within an org unit.
 def get_config_var_org_unit_effective_value(variable_id, org_unit_id)
   path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/effectiveValues/orgUnits/#{org_unit_id}"
@@ -75,7 +87,71 @@ def get_config_var_system_value(variable_id)
   _get(path)
 end
 
+# REVIEW: Set a new org value for a configuration variable.
+def set_config_var_org_value(variable_id, org_value)
+  path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/values/org"
+  if org_value.is_a? String || org_value.nil?
+    payload = {"OrgValue" => org_value}
+    _put(path, payload)
+  else
+    raise ArgumentError, "Argument 'org_value' is not a String or nil"
+  end
+end
+
+# REVIEW: Set a new org unit override value for a configuration variable.
+def set_config_var_override_value(variable_id, org_unit_id, org_unit_value)
+  path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/values/orgUnits/#{org_unit_id}"
+  if org_unit_value.is_a? String || org_unit_value.nil?
+    payload = {"OrgUnitValue" => org_unit_value}
+    _put(path, payload)
+  else
+    raise ArgumentError, "Argument 'org_unit_value' is not a String or nil"
+  end
+end
+
+# REVIEW: Set a new role override value for a configuration variable.
+def set_config_var_role_value(variable_id, role_id, role_value)
+  path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/values/roles/#{role_id}"
+  if role_value.is_a? String || role_value.nil?
+    payload = {"RoleValue" => role_value}
+    _put(path, payload)
+  else
+    raise ArgumentError, "Argument 'role_value' is not a String or nil"
+  end
+end
+
+# REVIEW: Set a new system value for a configuration variable.
+def set_config_var_system_value(variable_id, system_value)
+  path = "/d2l/api/lp/#{$lp_ver}/configVariables/#{variable_id}/values/system"
+  if system_value.is_a?(String) || system_value.nil?
+    payload = {"SystemValue" => system_value}
+    _put(path, payload)
+  else
+    raise ArgumentError, "Argument 'system_value' is not a String or nil"
+  end
+end
+
+########################
+# RESOLVER:#############
+########################
+# NOTE: These provide a way to manage a configuration variable’s
+#       resolution strategy.
+
+# NOTE: UNSTABLE!!!
+# TODO: UNSTABLE!!! --Restore the default resolution strategy for an org unit configuration variable.
+def restore_default_org_unit_config_var_resolution(variable_id)
+  # DELETE /d2l/api/lp/(version)/configVariables/(variableId)/resolver
+end
+
+# NOTE: UNSTABLE!!!
+# REVIEW: Retrieve the resolution strategy for an org unit configuration variable.
 def get_config_var_resolver(variable_id)
   path = "/d2l/api/lp/#{lp_ver}/configVariables/#{variable_id}/resolver"
   _get(path)
 end
+
+# NOTE: UNSTABLE!!!
+# TODO: Update the resolution strategy for an org unit configuration variable.
+def update_org_unit_config_var_resolution(resolver_value)
+  # PUT /d2l/api/lp/(version)/configVariables/(variableId)/resolver
+end

data/lib/d2l_sdk/course.rb

@@ -1,9 +1,48 @@
 require_relative 'requests'
 require 'json-schema'
+
 ########################
-# COURSES:##############
+# ACTIONS:##############
 ########################
 
+# Deletes a course based, referencing it via its org_unit_id
+# This reference is created through a formatted path appended with the id.
+# Then, a delete http method is executed using this path, deleting the course.
+def delete_course_by_id(org_unit_id)
+    path = "/d2l/api/lp/#{$lp_ver}/courses/#{org_unit_id}" # setup user path
+    #ap path
+    _delete(path)
+    puts '[+] Course data deleted successfully'.green
+end
+
+# retrieve the list of parent org unit type constraints for course offerings
+def get_parent_outypes_courses_schema_constraints
+  path = "/d2l/api/lp/#{$lp_ver}/courses/schema"
+  _get(path)
+  # returns a JSON array of SchemaElement blocks
+end
+
+# Performs a get request to retrieve a particular course using the org_unit_id
+# of this particular course. If the course does not exist, as specified by the
+# org_unit_id, the response is typically a 404 error.
+#
+# returns: JSON object of the course
+def get_course_by_id(org_unit_id)
+    path = "/d2l/api/lp/#{$lp_ver}/courses/#{org_unit_id}"
+    _get(path)
+    # returns: JSON object of the course
+end
+
+
+def get_course_image(org_unit_id, width = 0, height = 0)
+  path = "/d2l/api/lp/#{lp_ver}/courses/#{org_unit_id}/image"
+  if width > 0 && height > 0
+    path += "?width=#{width}"
+    path += "&height=#{height}"
+  end
+  _get(path)
+end
+
 # Checks whether the created course data conforms to the valence api for the
 # course data JSON object. If it does conform, then nothing happens and it
 # simply returns true. If it does not conform, then the JSON validator raises
@@ -59,93 +98,7 @@ def create_course_data(course_data)
     # requires: CreateCourseOffering JSON block
     path = "/d2l/api/lp/#{$lp_ver}/courses/"
     _post(path, payload)
-    puts '[+] Course creation completed successfully'.green
-end
-
-# In order to retrieve an entire department's class list, this method uses a
-# predefined org_unit identifier. This identifier is then appended to a path
-# and all classes withiin the department are returned as JSON objects in an arr.
-#
-# returns: JSON array of classes.
-def get_org_department_classes(org_unit_id)
-    path = "/d2l/api/lp/#{$lp_ver}/orgstructure/#{org_unit_id}"
-    _get(path)
-    # returns: JSON array of classes.
-end
-
-# Performs a get request to retrieve a particular course using the org_unit_id
-# of this particular course. If the course does not exist, as specified by the
-# org_unit_id, the response is typically a 404 error.
-#
-# returns: JSON object of the course
-def get_course_by_id(org_unit_id)
-    path = "/d2l/api/lp/#{$lp_ver}/courses/#{org_unit_id}"
-    _get(path)
-    # returns: JSON object of the course
-end
-
-def get_all_courses
-    path = "/d2l/api/lp/#{$lp_ver}/orgstructure/6606/descendants/?ouTypeId=3"
-    _get(path)
-end
-
-# much slower means of getting courses if less than 100 courses
-def get_courses_by_code(org_unit_code)
-  all_courses = get_all_courses
-  courses = []
-  all_courses.each do |course|
-    courses.push(course) if course["Code"].downcase.include? "#{org_unit_code}".downcase
-  end
-  courses
-end
-# Retrieves all courses that have a particular string (org_unit_name) within
-# their names. This is done by first defining that none are found yet and then
-# searching through all course  for ones that do have a particular string within
-# their name, the matches are pushed into the previously empty array of matches.
-# This array is subsequently returned; if none were found, a message is returned
-#
-# returns: JSON array of matching course  data objects
-def get_courses_by_name(org_unit_name)
-    get_courses_by_property_by_string('Name', org_unit_name)
-end
-
-# Retrieves all matching courses that are found using a property and a search
-# string. First, it is considered that the class is not found. Then, all courses
-# are retrieved and stored as a JSON array in the varaible +results+. After this
-# each of the +results+ is iterated, downcased, and checked for their matching
-# of the particular search string. If there is a match, they are pushed to
-# an array called +courses_results+. This is returned at the end of this op.
-#
-# returns: array of JSON course objects (that match the search string/property)
-def get_courses_by_property_by_string(property, search_string)
-    puts "[+] Searching for courses using search string: #{search_string}".yellow +
-         + " -- And property: #{property}"
-    courses_results = []
-    results = get_all_courses
-    results.each do |x|
-        if x[property].downcase.include? search_string.downcase
-            courses_results.push(x)
-        end
-    end
-    courses_results
-    # returns array of all matching courses in JSON format.
-end
-
-# Retrieves all courses that have the specified prop match a regular expression.
-# This is done by iterating through all courses and returning an array of all
-# that match a regular expression.
-#
-# returns: array of JSON course objects (with property that matches regex)
-def get_courses_by_property_by_regex(property, regex)
-    puts "[+] Searching for courses using regex: #{regex}".yellow +
-         + " -- And property: #{property}"
-    courses_results = []
-    results = get_all_courses
-    results.each do |x|
-        courses_results.push(x) if (x[property] =~ regex) != nil
-    end
-    courses_results
-    # returns array of all matching courses in JSON format.
+    #puts '[+] Course creation completed successfully'.green
 end
 
 # Checks whether the updated course data conforms to the valence api for the
@@ -192,16 +145,30 @@ def update_course_data(course_id, new_data)
     # Provide feedback that the update was successful
 end
 
-def is_course_component(key)
-  valid_components = %w(AttendanceRegisters Glossary News Checklists
-                        Grades QuestionLibrary Competencies GradesSettings
-                        Quizzes Content Groups ReleaseConditions CourseFiles
-                        Homepages Rubrics Discussions IntelligentAgents
-                        Schedule DisplaySettings Links SelfAssessments
-                        Dropbox LtiLink Surveys Faq LtiTP ToolNames Forms
-                        Navbars Widgets)
-  valid_components.include?(key)
-  # returns whether the key is actually a course component
+# TODO: Update the course image for a course offering.
+def update_course_image(org_unit_id, image_file)
+  # PUT /d2l/api/lp/(version)/courses/(orgUnitId)/image
+end
+
+########################
+# COURSE TEMPLATES:#####
+########################
+# NOTE: Course template related functions are now in 'course_template.rb'
+
+########################
+# COPYING COURSES:######
+########################
+
+def get_copy_job_request_status(org_unit_id, job_token)
+    path = "/d2l/api/le/#{le_ver}/import/#{org_unit_id}/copy/#{job_token}"
+    _get(path)
+    # returns GetCopyJobResponse JSON block
+    # GetImportJobResponse:
+    # {"JobToken" => <string:COPYJOBSTATUS_T>,
+    #  "TargetOrgUnitID" => <number:D2LID>,
+    #  "Status" => <string:IMPORTJOBTSTATUS_T>}
+    # States of getImport: UPLOADING, PROCESSING, PROCESSED, IMPORTING,
+    #                      IMPORTFAILED, COMPLETED
 end
 
 def check_create_copy_job_request_validity(create_copy_job_request)
@@ -223,6 +190,19 @@ def check_create_copy_job_request_validity(create_copy_job_request)
     JSON::Validator.validate!(schema, create_copy_job_request, validate_schema: true)
 end
 
+# simple schema check to assure the course component is an actual course component
+# returns: boolean
+def is_course_component(key)
+  valid_components = %w(AttendanceRegisters Glossary News Checklists
+                        Grades QuestionLibrary Competencies GradesSettings
+                        Quizzes Content Groups ReleaseConditions CourseFiles
+                        Homepages Rubrics Discussions IntelligentAgents
+                        Schedule DisplaySettings Links SelfAssessments
+                        Dropbox LtiLink Surveys Faq LtiTP ToolNames Forms
+                        Navbars Widgets)
+  valid_components.include?(key)
+  # returns whether the key is actually a course component
+end
 
 def create_new_copy_job_request(org_unit_id, create_copy_job_request)
   payload =
@@ -247,27 +227,26 @@ def create_new_copy_job_request(org_unit_id, create_copy_job_request)
   # Returns CreateCopyJobResponse JSON block
 end
 
-def get_copy_job_request_status(org_unit_id, job_token)
-    path = "/d2l/api/le/#{le_ver}/import/#{org_unit_id}/copy/#{job_token}"
-    _get(path)
-    # returns GetCopyJobResponse JSON block
-    # GetImportJobResponse:
-    # {"JobToken" => <string:COPYJOBSTATUS_T>,
-    #  "TargetOrgUnitID" => <number:D2LID>,
-    #  "Status" => <string:IMPORTJOBTSTATUS_T>}
-    # States of getImport: UPLOADING, PROCESSING, PROCESSED, IMPORTING,
-    #                      IMPORTFAILED, COMPLETED
+# NOTE: UNSTABLE!!!!
+# TODO: --UNSTABLE-- Retrieve the list of logs for course copy jobs.
+# Query Params:
+# --OPTIONAL--
+# -bookmark : string
+# -page_size : number
+# -source_org_unit_id : number
+# -destination_org_unit_id : number
+# -start_date : UTCDateTime
+# -end_date : UTCDateTime
+# RETURNS: An object list page containing the resulting CopyCourseLogMessage data blocks
+def get_copy_jobs_logs(bookmark = '', page_size = 0, source_org_unit_id = 0,
+                       destination_org_unit_id = 0, start_date = '', end_date = '')
+  # GET /d2l/api/le/(version)/ccb/logs
 end
-#########
-=begin
-def create_course_import_request(org_unit_id, callback_url = '')
-    path = "/d2l/le/#{le_ver}/import/#{org_unit_id}/imports/"
-    path += "?callbackUrl=#{callback_url}" if callback_url != ''
-    #_post(path, payload)
-    #_upload(path, json, file, 'POST', 'file', filename)
 
-end
-=end
+########################
+# IMPORTING COURSES:####
+########################
+
 def get_course_import_job_request_status(org_unit_id, job_token)
   path = "/d2l/api/le/#{le_ver}/import/#{org_unit_id}/imports/#{job_token}"
   _get(path)
@@ -284,28 +263,97 @@ def get_course_import_job_request_logs(org_unit_id, job_token, bookmark = '')
   # returns PAGED RESULT of ImportCourseLog JSON blocks following bookmark param
 end
 
-# Deletes a course based, referencing it via its org_unit_id
-# This reference is created through a formatted path appended with the id.
-# Then, a delete http method is executed using this path, deleting the course.
-def delete_course_by_id(org_unit_id)
-    path = "/d2l/api/lp/#{$lp_ver}/courses/#{org_unit_id}" # setup user path
-    #ap path
-    _delete(path)
-    puts '[+] Course data deleted successfully'.green
+# TODO: Create a new course import job request.
+# INPUT: simple file upload process
+def create_course_import_request(org_unit_id, callback_url = '')
+    #path = "/d2l/le/#{le_ver}/import/#{org_unit_id}/imports/"
+    #path += "?callbackUrl=#{callback_url}" if callback_url != ''
+    #_post(path, payload)
+    #_upload(path, json, file, 'POST', 'file', filename)
 end
 
-# retrieve the list of parent org unit type constraints for course offerings
-def get_parent_outypes_courses_schema_constraints
-  path = "/d2l/api/lp/#{$lp_ver}/courses/schema"
-  _get(path)
-  # returns a JSON array of SchemaElement blocks
+################################################################################
+################################################################################
+
+
+###########################
+# ADDITIONAL FUNCTIONS:####
+###########################
+
+
+# In order to retrieve an entire department's class list, this method uses a
+# predefined org_unit identifier. This identifier is then appended to a path
+# and all classes withiin the department are returned as JSON objects in an arr.
+#
+# returns: JSON array of classes.
+def get_org_department_classes(org_unit_id)
+    path = "/d2l/api/lp/#{$lp_ver}/orgstructure/#{org_unit_id}"
+    _get(path)
+    # returns: JSON array of classes.
 end
 
-def get_course_image(org_unit_id, width = 0, height = 0)
-  path = "/d2l/api/lp/#{lp_ver}/courses/#{org_unit_id}/image"
-  if width > 0 && height > 0
-    path += "?width=#{width}"
-    path += "&height=#{height}"
+
+
+def get_all_courses
+    path = "/d2l/api/lp/#{$lp_ver}/orgstructure/6606/descendants/?ouTypeId=3"
+    _get(path)
+end
+
+# much slower means of getting courses if less than 100 courses
+def get_courses_by_code(org_unit_code)
+  all_courses = get_all_courses
+  courses = []
+  all_courses.each do |course|
+    courses.push(course) if course["Code"].downcase.include? "#{org_unit_code}".downcase
   end
-  _get(path)
+  courses
+end
+# Retrieves all courses that have a particular string (org_unit_name) within
+# their names. This is done by first defining that none are found yet and then
+# searching through all course  for ones that do have a particular string within
+# their name, the matches are pushed into the previously empty array of matches.
+# This array is subsequently returned; if none were found, a message is returned
+#
+# returns: JSON array of matching course  data objects
+def get_courses_by_name(org_unit_name)
+    get_courses_by_property_by_string('Name', org_unit_name)
+end
+
+# Retrieves all matching courses that are found using a property and a search
+# string. First, it is considered that the class is not found. Then, all courses
+# are retrieved and stored as a JSON array in the varaible +results+. After this
+# each of the +results+ is iterated, downcased, and checked for their matching
+# of the particular search string. If there is a match, they are pushed to
+# an array called +courses_results+. This is returned at the end of this op.
+#
+# returns: array of JSON course objects (that match the search string/property)
+def get_courses_by_property_by_string(property, search_string)
+    puts "[+] Searching for courses using search string: #{search_string}".yellow +
+         + " -- And property: #{property}"
+    courses_results = []
+    results = get_all_courses
+    results.each do |x|
+        if x[property].downcase.include? search_string.downcase
+            courses_results.push(x)
+        end
+    end
+    courses_results
+    # returns array of all matching courses in JSON format.
+end
+
+# Retrieves all courses that have the specified prop match a regular expression.
+# This is done by iterating through all courses and returning an array of all
+# that match a regular expression.
+#
+# returns: array of JSON course objects (with property that matches regex)
+def get_courses_by_property_by_regex(property, regex)
+    puts "[+] Searching for courses using regex: #{regex}".yellow +
+         + " -- And property: #{property}"
+    courses_results = []
+    results = get_all_courses
+    results.each do |x|
+        courses_results.push(x) if (x[property] =~ regex) != nil
+    end
+    courses_results
+    # returns array of all matching courses in JSON format.
 end