d2l_api 0.1.2

data/lib/d2l_api/course_template.rb

@@ -0,0 +1,135 @@
+require_relative 'requests'
+########################
+# COURSE TEMPLATES:#####
+########################
+
+# This method creates a course template using a merged payload between a
+# pre-formatted payload and the argument "course_template_data". Upon this merge
+# the path is defined for the POST http method that is then executed to create
+# the course_template object.
+# Required: "Name", "Code"
+# /d2l/api/lp/(version)/coursetemplates/ [POST]
+def create_course_template(course_template_data)
+    # ForceLocale- course override the user’s locale preference
+    # Path- root path to use for this course offering’s course content
+    #       if your back-end service has path enforcement set on for
+    #       new org units, leave this property as an empty string
+    # Define a valid, empty payload and merge! with the user_data. Print it.
+    payload = { 'Name' => '', # String
+                'Code' => 'off_SEMESTERCODE_STARNUM', # String
+                'Path' => '', # String
+                'ParentOrgUnitIds' => [99_989], # number: D2L_ID
+              }.merge!(course_template_data)
+    puts "Creating Course Template:"
+    ap payload
+    # Define a path referencing the courses path
+    path = "/d2l/api/lp/#{$version}/coursetemplates/"
+    _post(path, payload)
+    puts '[+] Course template creation completed successfully'.green
+end
+
+# Retrieves a course template based upon an explicitly defined course template
+# org_unit_id or Identifier. This is done by using the identifier as a component
+# of the path, and then performing a GET http method that is then returned.
+#
+# returns: JSON course template data
+# /d2l/api/lp/(version)/coursetemplates/(orgUnitId) [GET]
+def get_course_template(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/coursetemplates/" + org_unit_id.to_s
+    _get(path)
+end
+
+# Instead of explicitly retrieving a single course template, this method uses
+# the routing table to retrieve all of the organizations descendants with the
+# outTypeId of 2. What this means is that it is literally retrieving any and all
+# course templates that have an ancestor of the organization...which should be
+# all of them.
+#
+# returns: JSON array of course template data objects
+def get_all_course_templates
+  path = "/d2l/api/lp/#{$version}/orgstructure/6606/descendants/?ouTypeId=2"
+  _get(path)
+end
+
+# This method retrieves all course templates that have a specific string, as
+# specified by org_unit_name, within their names. This is done by first defining
+# that none are found yet and initializing an empty array. Then, by searching
+# through all course templates 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 template data objects
+def get_course_template_by_name(org_unit_name)
+  course_template_not_found = true
+  course_template_results = []
+  puts "[+] Searching for templates using search string: \'#{org_unit_name}\'".yellow
+  results = get_all_course_templates
+  results.each do |x|
+      if x['Name'].downcase.include? org_unit_name.downcase
+          course_template_not_found = false
+          course_template_results.push(x)
+      end
+  end
+  if course_template_not_found
+      puts '[-] No templates could be found based upon the search string.'.yellow
+  end
+  course_template_results
+end
+
+# Moreso a helper method, but this really just returns the schema of the
+# course templates. This is predefined in the routing table, and retrieved via
+# a GET http method.
+#
+# returns: JSON of course templates schema
+# /d2l/api/lp/(version)/coursetemplates/schema [GET]
+def get_course_templates_schema
+    path = "/d2l/api/lp/#{$version}/coursetemplates/schema"
+    _get(path)
+end
+
+# This is the primary method utilized to update course templates. As only the
+# Name and the Code can be changed in an update, they are pre-defined to
+# conform to the required update data. The update is then performed via a
+# PUT http method that is executed using a path referencing the course template.
+# /d2l/api/lp/(version)/coursetemplates/(orgUnitId) [PUT]
+def update_course_template(org_unit_id, new_data)
+    # Define a valid, empty payload and merge! with the new data.
+    payload = { 'Name' => '', # String
+                'Code' => 'off_SEMESTERCODE_STARNUM', # String
+              }.merge!(new_data)
+    puts "Updating course template #{org_unit_id}"
+    #ap payload
+    # Define a path referencing the courses path
+    path = "/d2l/api/lp/#{$version}/coursetemplates/" + org_unit_id.to_s
+    _put(path, payload)
+    puts '[+] Course template update completed successfully'.green
+end
+
+
+# Simply, a course template can be deleted by refencing it using its Identifier
+# as an argument for this method. The argument is then used to refernce the obj
+# by a path and then the path is passed in for a delete http method.
+# /d2l/api/lp/(version)/coursetemplates/(orgUnitId) [DELETE]
+def delete_course_template(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/coursetemplates/" + org_unit_id.to_s
+    _delete(path)
+    puts '[+] Course template data deleted successfully'.green
+end
+
+# As a more streamlined approach to deleting many course templates conforming to
+# a particular naming style, this function performs deletions based on a string.
+# Using the name argument, +get_course_template_by_name+ is called in order to
+# retrieve all matching templates. They are then deleted by referencing each
+# of their Identifiers as arguments for +delete_course_template+.
+def delete_all_course_templates_with_name(name)
+  puts "[!] Deleting all course templates with the name: #{name}"
+  get_course_template_by_name(name).each do |course_template|
+    puts "[!] Deleting the following course:".red
+    ap course_template
+    delete_course_template(course_template["Identifier"])
+  end
+end
+#TO DO:
+def delete_course_templates_by_regex(regex)
+  
+end

data/lib/d2l_api/org_unit.rb

@@ -0,0 +1,185 @@
+require_relative 'requests'
+########################
+# Org Units:############
+########################
+
+# gets all descendents of a particular org unit, as referenced by the
+# "org_unit_id" argument. A get request is then performed by a preformatted
+# path.
+def get_org_unit_descendants(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/descendants/"
+    _get(path)
+    # return json of org_unit descendants
+end
+
+def get_paged_org_unit_descendants(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/descendants/paged/"
+    _get(path)
+    # return json of org_unit descendants
+end
+
+# gets all parents of a particular org unit, as referenced by the
+# "org_unit_id" argument. A get request is then performed by a preformatted
+# path.
+def get_org_unit_parents(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/parents/"
+    _get(path)
+    # return json of org_unit parents
+end
+
+def add_parent_to_org_unit(parent_ou_id, child_ou_id)
+    # Must follow structure of data
+    # (course <-- semester <== org -->custom dept--> dept -->templates--> courses)
+    # Refer to valence documentation for further structural understanding..
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{child_ou_id}/parents/"
+    _post(path, parent_ou_id)
+    # return json of org_unit parents
+end
+
+def get_org_unit_ancestors(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/ancestors/"
+    _get(path)
+    # return json of org_unit parents
+end
+
+# gets all children of a particular org unit, as referenced by the
+# "org_unit_id" argument. A get request is then performed by a preformatted
+# path.
+def get_org_unit_children(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/children/"
+    _get(path)
+    # return json of org_unit children
+end
+
+def get_paged_org_unit_children(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/children/paged/"
+    _get(path)
+    # return json of org_unit children
+end
+
+# gets all properties of a particular org unit, as referenced by the
+# "org_unit_id" argument. A get request is then performed by a preformatted
+# path.
+def get_org_unit_properties(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}"
+    _get(path)
+    # return json of org_unit properties
+end
+
+def delete_relationship_of_child_with_parent(parent_ou_id, child_ou_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{parent_ou_id}/children/#{child_ou_id}"
+    _delete(path)
+end
+
+def delete_relationship_of_parent_with_child(parent_ou_id, child_ou_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{child_ou_id}/parents/#{parent_ou_id}"
+    _delete(path)
+end
+
+def get_all_childless_org_units
+    path = "/d2l/api/lp/#{$version}/orgstructure/childless/"
+    _get(path)
+    # ONLY RETRIEVES FIRST 100
+end
+
+def get_all_orphans
+    path = "/d2l/api/lp/#{$version}/orgstructure/orphans/"
+    _get(path)
+end
+
+# Adds a child to the org unit by using org_unit_id to reference the soon-to-be
+# parent of the child_org_unit and referencing the soon-to-be child through the
+# child_org_unit_id argument. Then, a path is created to reference the children
+# of the soon-to-be parent and executing a post http method that adds the child.
+#
+# TL;DR, this adds a child org_unit to the children of an org_unit.
+def add_child_org_unit(org_unit_id, child_org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}/children/"
+    _post(path, child_org_unit_id)
+end
+
+def get_recycled_org_units
+    path = "/d2l/api/lp/#{$version}/orgstructure/recyclebin/"
+    _get(path)
+    # GETS ONLY FIRST 100
+end
+
+# An org unit is recycled by executing a POST http method and recycling it. The
+# path for the recycling is created using the org_unit_id argument and then the
+# post method is executed afterwards.
+def recycle_org_unit(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/recyclebin/#{org_unit_id}/recycle"
+    _post(path, {})
+end
+
+def delete_recycled_org_unit(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/recyclebin/#{org_unit_id}"
+    _delete(path)
+end
+
+def restore_recycled_org_unit(org_unit_id)
+    path = "/d2l/api/lp/#{$version}/orgstructure/recyclebin/#{org_unit_id}/restore"
+    _post(path, {})
+end
+
+# Functions considered for basic added functionality to api, not sure if needed.
+def create_custom_org_unit(org_unit_data)
+    # Requires the type to have the correct parent. This will work fine in this
+    # sample, as the department (101) can have the parent Organiation (6606)
+    payload = { 'Type' => 101, # Number:D2LID
+                'Name' => 'custom_ou_name', # String
+                'Code' => 'custom_ou_code', # String
+                'Parents' => [6606], # Number:D2LID
+              }.merge!(org_unit_data)
+    path = "/d2l/api/lp/#{$version}/orgstructure/"
+    _post(path, payload)
+end
+
+def update_org_unit(org_unit_id, org_unit_data)
+    previous_data = get_org_unit_properties(org_unit_id)
+    payload = { # Can only update NAME, CODE, and PATH variables
+        'Identifier' => org_unit_id.to_s, # String: D2LID // DO NOT CHANGE
+        'Name' => previous_data['Name'], # String
+        # String #YearNUM where NUM{sp:01,su:06,fl:08}  | nil
+        'Code' => previous_data['Code'],
+        # String: /content/enforced/IDENTIFIER-CODE/
+        'Path' => "/content/enforced/#{org_unit_id}-#{previous_data['Code']}/",
+        'Type' => previous_data['Type']
+        # example:
+        # { # DO NOT CHANGE THESE
+        #    'Id' => 5, # <number:D2LID>
+        #    'Code' => 'Semester', # <string>
+        #    'Name' => 'Semester', # <string>
+        # }
+    }.merge!(org_unit_data)
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}"
+    puts '[-] Attempting put request (updating orgunit)...'
+    _put(path, payload)
+    puts '[+] Semester update completed successfully'.green
+end
+
+# Retrieves the organization info. Only gets a small amount of information,
+# but may be useful in some instances.
+def get_organization_info
+    path = "/d2l/api/lp/#{$version}/organization/info"
+    _get(path)
+end
+
+def get_all_org_units_by_type_id(outype_id)
+  path = "/d2l/api/lp/#{$version}/orgstructure/6606/children/?ouTypeId=#{outype_id}"
+  _get(path)
+end
+
+# This retrieves information about a partituclar org unit type, referenced via
+# the outype_id argument. This is then returned as a JSON object.
+def get_outype(outype_id)
+    path = "/d2l/api/lp/#{$version}/outypes/#{outype_id}"
+    _get(path)
+end
+
+# retrieves all outypes that are known and visible. This is returned as a JSON
+# array of orgunittype data blocks.
+def get_all_outypes
+    path = "/d2l/api/lp/#{$version}/outypes/"
+    _get(path)
+end

data/lib/d2l_api/requests.rb

@@ -0,0 +1,92 @@
+require_relative 'auth'
+
+########################
+# QUERIES/RESPONSE:#####
+########################
+
+# performs a get request on a particular path of the host.
+# To do this, a uniform resource identifier string is created using the path and
+# specifying that this is a get request. Then, the RestClient get method is
+# used to retrieve the data and parse it as a JSON. Then, the parsed response is
+# returned. Otherwise, nothing is returned and the response code is printed
+#
+# returns: JSON parsed response.
+def _get(path)
+    uri_string = create_authenticated_uri(path, 'GET')
+    RestClient.get(uri_string) do |response, _request, _result|
+        case response.code
+        when 200
+            # ap JSON.parse(response) # Here is the JSON fmt'd response printed
+            JSON.parse(response)
+        else
+            display_response_code(response.code)
+        end
+    end
+end
+
+# performs a post request using the path and the payload arguments. First, an
+# authenticated uri is created to reference a particular resource. Then, the
+# post method is executed using the payload and specifying that it is formatted
+# as JSON.
+def _post(path, payload)
+    auth_uri = create_authenticated_uri(path, 'POST')
+    RestClient.post(auth_uri, payload.to_json, content_type: :json)
+end
+
+# performs a put request using the path and the payload arguments. After first
+# creating an authenticated uri, the put request is performed using the
+# authenticated uri, the payload argument, and specifying that the payload is
+# formatted in JSON.
+def _put(path, payload)
+    auth_uri = create_authenticated_uri(path, 'PUT')
+    # Perform the put action, updating the data; Provide feedback to client.
+    RestClient.put(auth_uri, payload.to_json, content_type: :json)
+end
+
+# Performs a delete request by creating an authenticated uri and using the
+# RestClient delete method and specifying the content_type as being JSON.
+def _delete(path)
+    auth_uri = create_authenticated_uri(path, 'DELETE')
+    RestClient.delete(auth_uri, content_type: :json)
+end
+
+# based upon the specific code that is returned from the http method, this
+# displays the response, in the case that it is an error within the request
+# or the server. This is simply informative and assists in describing the
+# lacking response information from the valence api. In the case of a Bad
+# Request, it is likely that it cannot be further specified without looking
+# back at the d2l_api documentation or looking at the documentation on
+# the docs.valence.desire2learn.com website.
+def display_response_code(code)
+    case code
+    when 400
+        puts '[!] 400: Bad Request'
+    when 401
+        puts '[!] 401: Unauthorized'
+
+    when 403
+        print '[!] Error Code Forbidden 403: accessing the page or resource '\
+              'you were trying to reach is absolutely forbidden for some reason.'
+    when 404
+        puts '[!] 404: Not Found'
+    when 405
+        puts '[!] 405: Method Not Allowed'
+    when 406
+        puts 'Unacceptable Type'\
+    	    'Unable to provide content type matching the client\'s Accept header.'
+    when 412
+        puts '[!] 412: Precondition failed\n'\
+          'Unsupported or invalid parameters, or missing required parameters.'
+    when 415
+        puts '[!] 415: Unsupported Media Type'\
+          'A PUT or POST payload cannot be accepted.'
+    when 423
+        puts '[!] 423'
+    when 500
+        puts '[!] 500: General Service Error\n'\
+          'Empty response body. The service has encountered an unexpected'\
+            'state and cannot continue to handle your action request.'
+    when 504
+        puts '[!] 504: Service Error'
+    end
+end

data/lib/d2l_api/semester.rb

@@ -0,0 +1,120 @@
+require_relative "requests"
+########################
+# SEMESTER:#############
+########################
+
+# Creates a semester based upon a merged result from merging a preformatted
+# payload and the inputed semester data. This is then created server-side
+# via executing a POST http method using a predefined path and the new payload.
+def create_semester_data(semester_data)
+    # Define a valid, empty payload and merge! with the semester_data. Print it.
+    payload = { 'Type' => 5, # Number:D2LID
+                'Name' => 'Winter 2013 Semester', # String
+                'Code' => '201701', # String #YearNUM where NUM{sp:01,su:06,fl:08}
+                'Parents' => [6606], # ARR of Number:D2LID
+              }.merge!(semester_data)
+    #ap payload
+    path = "/d2l/api/lp/#{$version}/orgstructure/"
+    _post(path, payload)
+    puts '[+] Semester creation completed successfully'.green
+end
+
+# This retrieves all semesters via getting all children from the main
+# organization and filtering them by the default data type of semesters.
+#
+# Returns: Array of all semester JSON formatted data
+def get_all_semesters
+  path = "/d2l/api/lp/#{$version}/orgstructure/6606/children/?ouTypeId=5"
+  _get(path)
+end
+
+def get_semester_by_id(org_unit_id)
+  path = "/d2l/api/lp/#{$version}/orgstructure/" + org_unit_id.to_s
+  _get(path)
+  # return json of org_unit properties
+end
+# Rather than retrieving all semesters, this retrieves all semesters by a
+# particular string. First, a boolean is created where it is assumed the
+# semester is not found. Then an array is created with all the 'found' semesters
+# assuming none are found, but providing the structure to still return uniform
+# data that can be iterated. Then, by iterating through all semesters and only
+# storing ones that conform to the search string, all matched semesters are then
+# returned.
+#
+# Returns: Array of all semester JSON formatted data (with search string in name)
+def get_semester_by_name(search_string)
+  semester_not_found = true
+  semester_results = []
+  puts "[+] Searching for semesters using search string: \'#{search_string}\'".yellow
+  results = get_all_semesters
+  results.each do |x|
+      if x['Name'].downcase.include? search_string.downcase
+          semester_not_found = false
+          semester_results.push(x)
+      end
+  end
+  if semester_not_found
+      puts '[-] No semesters could be found based upon the search string.'.yellow
+  end
+  semester_results
+end
+
+# This is simply a helper function that can assist in preformatting a path
+# that conforms to the required 'Path' for updating semester data.
+#
+# returns: preformatted semester 'Path' string
+def create_semester_formatted_path(org_id, code)
+    "/content/enforced/#{org_id}-#{code}/"
+end
+
+# Updates a semester's data via merging a preformatted payload with the new
+# semester data. The 'path' is then initialized using a defined org_unit_id
+# and the semester is then updated via the newly defined payload and the path.
+def update_semester_data(org_unit_id, semester_data)
+    # Define a valid, empty payload and merge! with the semester_data. Print it.
+    payload = { # Can only update NAME, CODE, and PATH variables
+        'Identifier' => org_unit_id.to_s, # String: D2LID // DO NOT CHANGE
+        'Name' => 'NAME', # String
+        # String #YearNUM where NUM{sp:01,su:06,fl:08}  | nil
+        'Code' => 'REQUIRED',
+        # String: /content/enforced/IDENTIFIER-CODE/
+        'Path' => create_semester_formatted_path(org_unit_id.to_s, 'YEAR01'),
+        'Type' => { # DO NOT CHANGE THESE
+            'Id' => 5, # <number:D2LID>
+            'Code' => 'Semester', # <string>
+            'Name' => 'Semester', # <string>
+        }
+    }.merge!(semester_data)
+    # print out the projected new data
+    #puts '[-] New Semester Data:'.yellow
+    #ap payload
+    # Define a path referencing the course data using the course_id
+    path = "/d2l/api/lp/#{$version}/orgstructure/#{org_unit_id}"
+    puts '[-] Attempting put request (updating orgunit)...'
+    _put(path, payload)
+    puts '[+] Semester update completed successfully'.green
+end
+
+# This function provides the means to put the semester data into the recycling
+# bin. A path is then created using the org_unit_id argument. Once this is done
+# the post http method is then completed in order to officially recycle the data
+def recycle_semester_data(org_unit_id)
+    # Define a path referencing the user data using the user_id
+    puts '[!] Attempting to recycle Semester data referenced by id: ' + org_unit_id.to_s
+    path = "/d2l/api/lp/#{$version}/orgstructure/recyclebin/" + org_unit_id.to_s + '/recycle' # setup user path
+    _post(path, {})
+    puts '[+] Semester data recycled successfully'.green
+end
+
+# Rather than recycling a semester by a specific id, this function can recycle
+# all semesters that match a particular name. The names must be exactly the same
+# as the "name" argument. Each name that is the exact same as this argument is
+# then recycled, iteratively.
+def recycle_semester_by_name(name)
+  results = get_semester_by_name(name)
+  results.each do |semester_match|
+    if semester_match["Name"] == name
+      recycle_semester_data(semester_match["Identifier"])
+    end
+  end
+end