d2l_sdk 0.1.8 → 0.1.9

data/lib/d2l_sdk/requests.rb

@@ -108,10 +108,11 @@ 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, isD2l = true)
+def _delete(path, isD2l = true, headers = {})
+    headers[:content_type] = :json
     auth_uri = path
     auth_uri = create_authenticated_uri(path, 'DELETE') if isD2l == true
-    RestClient.delete(auth_uri, content_type: :json)
+    RestClient.delete(auth_uri, headers)
 end
 
 # based upon the specific code that is returned from the http method, this
@@ -182,18 +183,6 @@ def get_latest_product_version(product_code)
   end
 end
 
-# init products to newest versions.
-$le_ver = get_latest_product_version('le')
-$lp_ver = get_latest_product_version('lp')
-$ep_ver = get_latest_product_version('ep')
-#lti, rp, LR, ext,
-puts "versions set to:"
-versions = {
-  "le_ver" => $le_ver,
-  "lp_ver" => $lp_ver,
-  "ep_ver" => $ep_ver
-}
-ap versions
 # retrieve all supported versions for all product components
 def get_versions
   path = "/d2l/api/versions/"

data/lib/d2l_sdk/section.rb

@@ -11,58 +11,6 @@ def delete_section(org_unit_id, section_id)
   _delete(path)
 end
 
-##########
-# WesternOnline Specific GET Section ID by Code
-##########
-def create_semester_code(star_num, course_date)
-    "sec_#{course_date}_#{star_num}"
-end
-
-def get_section_by_section_code(code)
-  _get("/d2l/api/lp/1.4/orgstructure/?orgUnitCode=#{code}")["Items"][0]
-end
-
-def get_section_id_by_section_code(code)
-  get_section_by_section_code(code)["Identifier"]
-end
-
-def get_section_data_by_code(code)
-    sect_id = get_section_by_section_code(code)["Identifier"]
-    parent_id = get_org_unit_parents(sect_id)[0]["Identifier"]
-    get_section_data(parent_id, sect_id)
-end
-=begin
-def get_section_by_offering_code(code)
-  section_data = 0
-  parent_course = nil
-  courses = get_courses_by_code(code)
-  if courses.size > 1 # If the course code matches two codes..should be CL then
-    courses.each do |course| # iterate through each course...should be < 3
-      if course["Code"].include? "cl_off"
-        parent_course = course
-      end
-    end
-    # ELSE IF no course with "cl_off" found: Not properly cross listed
-    if parent_course == nil
-      puts "More than two courses with same code index; No proper crosslisting"
-    end
-  end
-  # get all sections of the course offering
-  sections = get_org_unit_sections(parent_course["Identifier"])
-  sections.each do |sect|
-    if sect["Code"].include? code[-5..-1]
-      section_data = sect
-    end
-  end
-  return section_data
-end
-
-def get_section_id_by_section_code(code)
-  get_section_data_by_code(code)["SectionId"]
-end
-=end
-############
-############
 # Retrieve all the sections for a provided org unit.
 def get_org_unit_sections(org_unit_id)
   path = "/d2l/api/lp/#{$lp_ver}/#{org_unit_id}/sections/"
@@ -193,6 +141,7 @@ def update_org_unit_section_properties(org_unit_id, section_property_data)
     # for the org unit’s updated section properties.
 end
 
+# Update information for a section in a particular org unit.
 def update_org_unit_section_info(org_unit_id, section_id, section_data)
     payload = { 'Name' => '', # String
                 'Code' => '', # String
@@ -205,3 +154,79 @@ def update_org_unit_section_info(org_unit_id, section_id, section_data)
     _put(path, payload)
     # returns the SectionData JSON block, in its Fetch form
 end
+
+#########################################################
+# WesternOnline Specific GET Section ID by Code##########
+#########################################################
+# NOTE: These are additional functions that were primarily made to work with
+# the Western Illinois University brightspace instance. Most will work
+# universally, but others may be of no use outside our specific instance.
+
+# creates a properly formatted section code, based on WIU's standard
+# section code.
+# RETURNS: formatted section code
+def create_section_code(star_num, course_date)
+    "sec_#{course_date}_#{star_num}"
+end
+
+# retrieves all sections with the same code.
+# NOTE: As the code SHOULD be unique, this function assumes that the returned
+# item is the requested item.
+def get_section_by_section_code(code)
+  path = "/d2l/api/lp/#{$lp_ver}/orgstructure/?orgUnitCode=#{code}"
+  _get(path)["Items"][0]
+  # RETURNS: SectionData block
+end
+
+# Simple bridge function that allows for the retrieval of a section's ID
+# based on its section code.
+# NOTE: Again, As the code SHOULD be unique, this function assumes that the
+# returned item is the requested item.
+def get_section_id_by_section_code(code)
+  get_section_by_section_code(code)["Identifier"]
+  # RETURNS: D2LID of the section identified by its section code
+end
+
+# Simple bridge function allowing for retrieval of section data by using
+# the section's code. As D2L does not allow for accessing the SectionData block
+# without using a parent's id, this retrieves the parents id and allows for
+# such functionality.
+def get_section_data_by_code(code)
+    sect_id = get_section_by_section_code(code)["Identifier"]
+    parent_id = get_org_unit_parents(sect_id)[0]["Identifier"]
+    get_section_data(parent_id, sect_id)
+end
+
+=begin
+ # IDEA::
+def get_section_by_offering_code(code)
+  section_data = 0
+  parent_course = nil
+  courses = get_courses_by_code(code)
+  if courses.size > 1 # If the course code matches two codes..should be CL then
+    courses.each do |course| # iterate through each course...should be < 3
+      if course["Code"].include? "cl_off"
+        parent_course = course
+      end
+    end
+    # ELSE IF no course with "cl_off" found: Not properly cross listed
+    if parent_course == nil
+      puts "More than two courses with same code index; No proper crosslisting"
+    end
+  end
+  # get all sections of the course offering
+  sections = get_org_unit_sections(parent_course["Identifier"])
+  sections.each do |sect|
+    if sect["Code"].include? code[-5..-1]
+      section_data = sect
+    end
+  end
+  return section_data
+end
+
+def get_section_id_by_section_code(code)
+  get_section_data_by_code(code)["SectionId"]
+end
+=end
+############
+############

data/lib/d2l_sdk/semester.rb

@@ -4,6 +4,9 @@ require 'json-schema'
 ########################
 # SEMESTER:#############
 ########################
+# NOTE: These functions are supplementary to the basic +org unit+ functions
+# provided by the valence API. These simply provide a little more tailored
+# functionality to this particular org unit type.
 
 # Checks if the created semester data conforms to the valence api for the
 # semester JSON object. If it does conform, then nothing happens and it

data/lib/d2l_sdk/setup_versions.rb

@@ -0,0 +1,14 @@
+require_relative "requests"
+
+# init products to newest versions.
+$le_ver = get_latest_product_version('le')
+$lp_ver = get_latest_product_version('lp')
+$ep_ver = get_latest_product_version('ep')
+#lti, rp, LR, ext,
+puts "versions set to:"
+versions = {
+  "le_ver" => $le_ver,
+  "lp_ver" => $lp_ver,
+  "ep_ver" => $ep_ver
+}
+ap versions

data/lib/d2l_sdk/user.rb

@@ -59,11 +59,11 @@ def create_user_data(user_data)
 end
 
 # Retrieves the whoami of the user authenticated through the config file.
-# returns: JSON whoami response
+# RETURNS: JSON whoami response
 def get_whoami
     path = "/d2l/api/lp/#{$lp_ver}/users/whoami"
     _get(path)
-    # returns a WhoAmIUser JSON block for the current user context
+    # RETURNS: a WhoAmIUser JSON block for the current user context
 end
 
 # Simple get users function that assists in retrieving users by particular
@@ -193,12 +193,12 @@ end
 # known as the Identifier of this user object. Upon retrieving the user, it
 # is then returned.
 #
-# returns: JSON user object.
+# RETURNS: JSON user object.
 def get_user_by_user_id(user_id)
     # Retrieve data for a particular user
     path = "/d2l/api/lp/#{$lp_ver}/users/#{user_id}"
     _get(path)
-    # returns a UserData JSON block
+    # RETURNS: a UserData JSON block
 end
 
 # Checks whether the updated user data conforms to the valence api for the
@@ -268,21 +268,108 @@ def delete_user_data(user_id)
     puts '[+] User data deleted successfully'.green
 end
 
-# Retrieve a list of all the enrolled user roles the calling user can view
-# in an org unit
-def get_enrolled_roles_in_org_unit(org_unit_id)
-  # this only lists ones viewable by the CALLING user
-  # also, only includes roles that are enrolled in the org unit
-  path = "/d2l/api/#{$lp_ver}/#{org_unit_id}/roles/"
+########################
+# ACTIVATION:###########
+########################
+# REVIEW: Retrieve a particular user’s activation settings.
+# RETURNS: a UserActivationData JSON block with the user’s current activation status.
+def get_user_activation_settings(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/users/#{user_id}/activation"
   _get(path)
-  # returns JSON array of Role data blocks
+  # RETURNS: a UserActivationData JSON block with the user’s current activation status.
+end
+
+# TODO: Update a particular user’s activation settings.
+# RETURNS: ?
+def update_user_activation_settings(user_id, user_activation_data)
+  # PUT /d2l/api/lp/(version)/users/(userId)/activation
+  # RETURNS: ?
+end
+
+########################
+# INTEGRATIONS:#########
+########################
+
+# NOTE: UNSTABLE!
+# TODO: Link a user to a Google Apps user account.
+# RETURNS: ?
+def link_user_google_apps_account(google_apps_linking_item)
+  # POST /d2l/api/gae/(version)/linkuser
+end
+
+
+########################
+# NOTIFICATIONS:########
+########################
+
+# REVIEW: Delete the subscription for messages of a particular type,
+#       delivered by a particular carrier.
+def delete_subscription(carrier_id, message_type_id)
+  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/#{carrier_id}/subscriptions/#{message_type_id}"
+  _delete(path)
+end
+
+# Retrieve all the carrier channels for delivering notification messages.
+# RETURNS: a JSON array of CarrierOutput data blocks.
+def get_all_notification_carrier_channels
+  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/"
+  _get(path)
+end
+
+# Retrieve all the current subscriptions for notification messages.
+# RETURNS: a JSON array of SubscriptionOutput data blocks.
+def get_all_subscriptions_by_carrier(carrier_id)
+  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/#{carrier_id}/subscriptions/"
+  _get(path)
+end
+
+# Subscribe to notification messages of a particular type, delivered by a particular carrier.
+def subscribe_to_carrier_notification(carrier_id, message_type_id)
+  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/#{carrier_id}/subscriptions/#{message_type_id}"
+  _put(path, {})
 end
 
+########################
+# PASSWORDS:############
+########################
+
+# REVIEW: Clear a particular user’s password.
+def delete_user_password(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/users/#{user_id}/password"
+  _delete(path)
+end
+
+# REVIEW: Reset a particular user’s password.
+# INPUT: nil (no payload necessary)
+# NOTE: Prompts the service to send a password-reset email to the provided user.
+def reset_user_password(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/users/#{user_id}/password"
+  _post(path, {})
+end
+
+# REVIEW: Update a particular user’s password.
+# NOTE: 400 errors are implicitly invalid password
+def update_user_password(user_id, user_password_data)
+  if user_password_data.is_a? String
+    path = "/d2l/api/lp/#{$lp_ver}/users/#{user_id}/password"
+    payload = {"Password" => user_password_data}
+    _put(path, payload)
+  else
+    raise ArgumentError, "Argument 'user_password_data' is not a String"
+  end
+end
+
+
+
+########################
+# ROLES:################
+########################
+
 # retrieve list of all known user roles
 def get_all_user_roles
   path = "/d2l/api/lp/#{$lp_ver}/roles/"
   _get(path)
-  # returns a JSON array of Role data blocks
+  # RETURNS: a JSON array of Role data blocks
 end
 
 # Retrieve a particular user role
@@ -292,19 +379,66 @@ def get_user_role(role_id)
   # returns a Role JSON data block
 end
 
+# Retrieve a list of all the enrolled user roles the calling user can view
+# in an org unit
+def get_enrolled_roles_in_org_unit(org_unit_id)
+  # this only lists ones viewable by the CALLING user
+  # also, only includes roles that are enrolled in the org unit
+  path = "/d2l/api/#{$lp_ver}/#{org_unit_id}/roles/"
+  _get(path)
+  # returns JSON array of Role data blocks
+end
+
+# TODO: --UNSTABLE -- Create a new role copied from an existing role.
+# INPUT: deep_copy_role_id = d2lID; role_copy_data = User.role_copy_data
+# RETURN: a Role JSON data block representing the newly-created copy of the role.
+def create_new_role_from_existing_role(deep_copy_role_id, role_copy_data)
+  # POST /d2l/api/lp/(version)/roles/
+end
+
+
+########################
+# PROFILES:#############
+########################
+
+# REVIEW: Remove the current user’s profile image.
+def remove_current_user_profile_image
+  path = "/d2l/api/lp/#{$lp_ver}/profile/myProfile/image"
+  _delete(path)
+end
+
+# REVIEW: Remove the profile image from a particular personal profile, by Profile ID.
+def remove_profile_image_by_profile_id(profile_id)
+  path = "/d2l/api/lp/#{$lp_ver}/profile/#{profile_id}/image"
+  _delete(path)
+end
+
+# REVIEW: Remove the profile image from a particular personal profile, by User ID.
+def remove_profile_image_by_user_id(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/profile/user/#{user_id}/image"
+  _delete(path)
+end
 
 # retrieve personal profile info for the current user context
+# Returns: UserProfile JSON data block
 def get_current_user_profile
   path = "/d2l/api/lp/#{$lp_ver}/profile/myProfile"
   _get(path)
-  # Returns UserProfile JSON data block
+  # Returns: UserProfile JSON data block
 end
 
-# retrieve personal profile info of the specified user
-def get_user_profile_by_user_id(user_id)
-  path = "/d2l/api/lp/#{$lp_ver}/profile/user/#{user_id}"
+# Retrieve the current user’s profile image.
+# INPUT: size (integer) determines the thumbnail size
+# RETURNS: This action returns a file stream containing the current user’s
+#          profile image. Note that the back-end service may return a
+#          profile image larger than your provided size.
+def get_current_user_profile_image(size = 0)
+  path = "/d2l/api/lp/#{$lp_ver}/profile/myProfile/image"
+  path += "?size=#{size}" if size != 0
   _get(path)
-  # Returns UserProfile JSON data block
+  # RETURNS: This action returns a file stream containing the current user’s
+  #          profile image. Note that the back-end service may return a
+  #          profile image larger than your provided size.
 end
 
 # retrieve a particular personal profile, by Profile ID
@@ -314,107 +448,239 @@ def get_user_profile_by_profile_id(profile_id)
   # Returns UserProfile JSON data block
 end
 
+# Retrieve a particular profile image, by Profile ID.
+# RETURNS: This action returns a file stream containing the current user’s
+#          profile image. Note that the back-end service may return a
+#          profile image larger than your provided size.
 def get_profile_image(profile_id, size = 0)
   path = "/d2l/api/lp/#{$lp_ver}/profile/#{profile_id}/image"
   path += "?size=#{size}" if size != 0
   _get(path)
+  # RETURNS: This action returns a file stream containing the current user’s
+  #          profile image. Note that the back-end service may return a
+  #          profile image larger than your provided size.
 end
 
-def get_current_user_profile_image(size = 0)
-  path = "/d2l/api/lp/#{$lp_ver}/profile/myProfile/image"
-  path += "?size=#{size}" if size != 0
+# Retrieve a particular personal profile, by User ID.
+def get_user_profile_by_user_id(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/profile/user/#{user_id}"
   _get(path)
+  # Returns UserProfile JSON data block
 end
 
+
+# Retrieve a particular profile image, by User ID.
+# RETURNS: This action returns a file stream containing the current user’s
+#          profile image. Note that the back-end service may return a
+#          profile image larger than your provided size.
 def get_user_profile_image(user_id)
   path = "/d2l/api/lp/#{$lp_ver}/profile/user/#{user_id}"
   path += "?size=#{size}" if size != 0
   _get(path)
-end
-#####Notifications
-def get_all_notification_carrier_channels
-  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/"
+  # RETURNS: This action returns a file stream containing the current user’s
+  #          profile image. Note that the back-end service may return a
+  #          profile image larger than your provided size.
+end
+
+# TODO: Update the personal profile image for the current user context.
+# INPUT: Provide an uploaded image file using the simple file upload process;
+#        the content-disposition part header for the file part should have the
+#        name profileImage
+#        http://docs.valence.desire2learn.com/basic/fileupload.html#simple-uploads
+# RETURNS: ?
+def update_current_user_profile_image()
+  # POST /d2l/api/lp/(version)/profile/myProfile/image
+  # RETURNS: ?
+end
+
+# TODO: Update the profile image for the identified personal profile, by Profile ID.
+# INPUT: Provide an uploaded image file using the simple file upload process;
+#        the content-disposition part header for the file part should have the
+#        name profileImage
+#        http://docs.valence.desire2learn.com/basic/fileupload.html#simple-uploads
+# RETURNS: ?
+def update_profile_image_by_profile_id
+  # POST /d2l/api/lp/(version)/profile/(profileId)/image
+  # RETURNS: ?
+end
+
+# TODO: Update the profile image for the identified personal profile, by User ID.
+# INPUT: Provide an uploaded image file using the simple file upload process;
+#        the content-disposition part header for the file part should have the
+#        name profileImage
+#        http://docs.valence.desire2learn.com/basic/fileupload.html#simple-uploads
+# RETURNS: ?
+def update_profile_image_by_user_id
+  # POST /d2l/api/lp/(version)/profile/user/(userId)/image
+  # RETURNS: ?
+end
+
+# TODO: Update the personal profile data for the current user context.
+# NOTE: block's data will replace all user profile data
+# RETURNS: a UserProfile JSON data block for the updated current user profile.
+def update_current_user_profile_data(user_profile_data)
+  # PUT /d2l/api/lp/(version)/profile/myProfile
+end
+
+# TODO: Update a particular personal profile, by Profile ID.
+# NOTE: block's data will replace all user profile data
+# RETURNS: a UserProfile JSON data block for the updated personal profile.
+def update_profile_by_profile_id(profile_id, user_profile_data)
+  # PUT /d2l/api/lp/(version)/profile/(profileId)
+    # NOTE: Example of User.UserProfile JSON Data Block
+    #    {  "Nickname": <string>,
+    #       "Birthday": {
+    #           "Month": <number>,
+    #           "Day": <number>
+    #       },
+    #       "HomeTown": <string>,
+    #       "Email": <string>,
+    #       "HomePage": <string>,
+    #       "HomePhone": <string>,
+    #       "BusinessPhone": <string>,
+    #       "MobilePhone": <string>,
+    #       "FaxNumber": <string>,
+    #       "Address1": <string>,
+    #       "Address2": <string>,
+    #       "City": <string>,
+    #       "Province": <string>,
+    #       "PostalCode": <string>,
+    #       "Country": <string>,
+    #       "Company": <string>,
+    #       "JobTitle": <string>,
+    #       "HighSchool": <string>,
+    #       "University": <string>,
+    #       "Hobbies": <string>,
+    #       "FavMusic": <string>,
+    #       "FavTVShows": <string>,
+    #       "FavMovies": <string>,
+    #       "FavBooks": <string>,
+    #       "FavQuotations": <string>,
+    #       "FavWebSites": <string>,
+    #       "FutureGoals": <string>,
+    #       "FavMemory": <string>,
+    #       "SocialMediaUrls": [ // Array of SocialMediaUrl blocks
+    #           {
+    #                 "Name": <string>,
+    #                 "Url": <string:URL>
+    #           },
+    #           { <composite:SocialMediaUrl> }, ...
+    #       ]
+    #    }
+    # NOTE: The back-end service also expects a file names "profileImage"
+  # RETURNS: a UserProfile JSON data block for the updated personal profile.
+end
+
+#####################################
+# IMS/LIS role configuration:########
+#####################################
+
+# NOTE: UNSTABLE
+# REVIEW: retrieve list of known LIS roles
+def get_lis_roles(lis_urn = "")
+  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/roles/"
+  path += "#{lis_urn}" if lis_urn != ""
   _get(path)
+  # returns array of LIS role data blocks
 end
 
-def get_all_subscriptions_by_carrier(carrier_id)
-  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/#{carrier_id}/subscriptions/"
+# NOTE: UNSTABLE
+# REVIEW: retrieve mappings between user roles and LIS roles
+def get_user_role_lis_mappings(lis_urn = "", d2lid = 0)
+  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/map/roles/"
+  path += "#{lis_urn}" if lis_urn != ""
+  path += "#{d2lid}" if d2lid != 0
   _get(path)
+  # returns JSON array of LIS role mapping data blocks
 end
 
-def subscribe_to_carrier_notification(carrier_id, message_type_id)
-  path = "/d2l/api/lp/#{$lp_ver}/notifications/instant/carriers/#{carrier_id}/subscriptions/#{message_type_id}"
-  _put(path,{})
+# NOTE: UNSTABLE
+# REVIEW: retrieve mapping between a user role and a LIS role
+def get_user_role_lis_mappings(role_id, d2lid = 0)
+  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/map/roles/#{role_id}"
+  path += "#{d2lid}" if d2lid != 0
+  _get(path)
+  # returns JSON array of LIS role mapping data blocks
 end
 
-#####LOCALES
-=begin
-# retrieve the locale account settings for a particular user.
-def get_locale_account_settings(user_id)
-  path = "/d2l/api/lp/#{$lp_ver}/accountSettings/#{user_id}/locale/"
-  _get(path)
-  # returns Locale JSON block
+# NOTE: UNSTABLE
+# TODO: --UNSTABLE-- Map a user role to a set of LIS Roles.
+# input: Mappings = String array
+def map_user_role_to_lis_roles(role_id, mappings)
+  # PUT /d2l/api/lp/(version)/imsconfig/map/roles/(roleId)
 end
 
-# optional parameter 'bookmark' for querying with a paging offset
-# Retrieve the collection of all known locales.
-def get_all_locales(bookmark = '')
-  path = "/d2l/api/lp/#{$lp_ver}/locales/"
+
+########################
+# SETTINGS:#############
+########################
+# NOTE: As the settings page only has 4 functions, these functions are simply
+# appended to this, the most relevant file.
+
+# REVIEW: Retrieve the current user’s locale account settings.
+def get_current_user_locale_settings
+  path = "/d2l/api/lp/#{$lp_ver}/accountSettings/mySettings/locale/"
   _get(path)
-  # returns paged result set containing Locale data blocks
+  # RETURNS: a Locale JSON block
 end
 
-# Retrieve the properties for a particular locale.
-def get_locale_properties(locale_id)
-  path = "/d2l/api/lp/#{$lp_ver}/locales/#{locale_id}"
+# REVIEW: retrieve the locale account settings for a particular user.
+def get_locale_account_settings(user_id)
+  path = "/d2l/api/lp/#{$lp_ver}/accountSettings/#{user_id}/locale/"
   _get(path)
   # returns Locale JSON block
 end
 
-def is_valid_locale_id(locale_id)
 
 
+# TODO: Add schema check for update_locale conforming to the D2L update_locale
+# JSON data block of form: { "LocaleId" : <D2LID>}.
+def is_valid_locale_id(locale_id)
+
 end
 
-# Update the current user's locale account settings
+# REVIEW: Update the current user’s locale account settings.
+# TODO: Add schema check for update_locale
+# update_locale = { "LocaleId" : <D2LID>}
 def update_current_user_locale_account_settings(update_locale)
   payload = {"LocaleId" => 0}.merge!(update_locale)
   path = "/d2l/api/lp/#{$lp_ver}/accountSettings/mysettings/locale/"
   # requires UpdateSettings JSON data block
+  # update_locale = { "LocaleId" : <D2LID>}
   _put(path, payload)
 end
 
-def update_user_locale_account_settings(user_id)
+# REVIEW: Update the locale account settings for a particular user.
+# TODO: Add schema check for update_locale
+# update_locale = { "LocaleId" : <D2LID>}
+def update_user_locale_account_settings(user_id, update_locale)
   payload = {"LocaleId" => 0}.merge!(update_locale)
   path = "/d2l/api/lp/#{$lp_ver}/accountSettings/#{user_id}/locale/"
   # requires UpdateSettings JSON data block
+  # update_locale = { "LocaleId" : <D2LID>}
   _put(path, payload)
 end
 
+########################
+# LOCALE:###############
+########################
+# NOTE: As the locale page only has only 2 functions, these functions are simply
+# appended to this, the most relevant file.
 
-######IMS/LIS role configuration
-# retrieve list of known LIS roles
-def get_lis_roles(lis_urn = "")
-  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/roles/"
-  path += "#{lis_urn}" if lis_urn != ""
-  _get(path)
-  # returns array of LIS role data blocks
-end
-
-# retrieve mappings between user roles and LIS roles
-def get_user_role_lis_mappings(lis_urn = "", d2lid = 0)
-  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/map/roles/"
-  path += "#{lis_urn}" if lis_urn != ""
-  path += "#{d2lid}" if d2lid != 0
+# NOTE: UNSTABLE
+# optional parameter 'bookmark' for querying with a paging offset
+# Retrieve the collection of all known locales.
+def get_all_locales(bookmark = '')
+  path = "/d2l/api/lp/#{$lp_ver}/locales/"
+  path += "?bookmark=#{bookmark}" if bookmark != ''
   _get(path)
-  # returns JSON array of LIS role mapping data blocks
+  # returns paged result set containing Locale data blocks
 end
 
-# retrieve mapping between a user role and a LIS role
-def get_user_role_lis_mappings(role_id, d2lid = 0)
-  path = "/d2l/api/lp/#{$lp_ver}/imsconfig/map/roles/#{role_id}"
-  path += "#{d2lid}" if d2lid != 0
+# NOTE: UNSTABLE
+# Retrieve the properties for a particular locale.
+def get_locale_properties(locale_id)
+  path = "/d2l/api/lp/#{$lp_ver}/locales/#{locale_id}"
   _get(path)
-  # returns JSON array of LIS role mapping data blocks
+  # returns Locale JSON block
 end
-=end