d2l_sdk 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88964b8ade0908b80eda0463f78cc82a18ca4c6a
-  data.tar.gz: 855c097579e67071038f779cee78e7b82daafddb
+  metadata.gz: 4f7d151a275583e45a75dadc1282f5c9d2c8dc09
+  data.tar.gz: e74a5359b1aa0393f3c3d39a9078e6d5b1a52887
 SHA512:
-  metadata.gz: f7c1ccbd845a45c2f51680e603309f5b9a72f0572b32213c6a2350012fa29331f9fed7708ea494b73df3bd356472489522b7275d06f26d863afd4006e5c0ef0d
-  data.tar.gz: d8476be7c9e325f11421bb91ff2cb11f1fe4622c11f026c93f5b94ece96020cf08694f30fc12f9ef2368c10ec6b3bf216a0ca8838f751d57fe9b9cebe1cc1ffd
+  metadata.gz: 8ce26d16bfdb64942f20473b6cdf86a1769dbd69ada54f6f7db1f385becefa2921db44ed3c3b96eb05301977a5fe8ad8c645dbcfca5a938b486a0af5f8ba3bdf
+  data.tar.gz: a5be1c83743cbac6b44676e629323a327dced170235ec86926e3bceaedf84ef927bfdfb0ca985183698d09dfca5858da1e6425c51740f01d85411f7c076ebbf7

data/change_lastname.rb

@@ -0,0 +1,65 @@
+require 'd2l_sdk'
+
+# Setup vars for username and last name
+# retrieved via rundeck args passed to this script.
+@username = ARGV[0]
+@new_lastname = ARGV[1]
+@debug = false
+
+# Check that the user exists.
+# If the username doesn't exist, then raise.
+# Why: You can't change a user's profile that you can't reference.
+if !does_user_exist(@username)
+        raise ArgumentError, "ARGV[0], '#{@username}', is not a username that exists."
+end
+
+# Already asserted that the user exists. Retrieve Hash of the user's profile.
+user_profile = get_user_by_username(@username)
+
+# debug code
+puts "Old User Data: \n" if @debug
+ap user_profile if @debug
+
+# Change the previous d2l user data and create a new json-formatted
+# payload. The payload is merged! with a skeleton payload, but it as
+# each parameter is defined, this will not affect its usage.
+old_lastname = user_profile["LastName"]
+user_profile["LastName"] = @new_lastname # update the user's lastname
+user_profile["UserName"].sub! old_lastname, @new_lastname # update the user's username
+unless user_profile["ExternalEmail"].nil?
+  user_profile["ExternalEmail"].sub! old_lastname, @new_lastname # update the user's email
+end
+
+# Check if there already is a user created with the +new username+
+if does_user_exist(user_profile["UserName"])
+        raise RuntimeError, "A user already exists with the new username, '#{user_profile["UserName"]}'."
+end
+
+# Pull in data only necessary for user_data in +update+ form.
+new_user_data =
+{
+        'OrgDefinedId' => user_profile["OrgDefinedId"],
+        'FirstName' => user_profile["FirstName"],
+        'MiddleName' => user_profile["MiddleName"],
+        'LastName' => user_profile["LastName"], # Changed previously
+        'ExternalEmail' => user_profile["ExternalEmail"],
+        'UserName' => user_profile["UserName"],
+        'Activation' =>
+        {
+            'IsActive' => user_profile["Activation"]["IsActive"]
+        }
+}
+
+# Debug code
+puts "New User Data: \n" if @debug
+ap new_user_data if @debug
+
+# Finally update the user's UserData
+update_user_data(user_profile["UserId"], new_user_data)
+
+# Check if the user was properly created.
+if !does_user_exist(user_profile["UserName"])
+        raise "The user's last name was unsuccessfully updated."
+else
+        puts "The username was successfully updated to: '#{user_profile["UserName"]}'."
+end

data/lib/d2l_sdk/calendar.rb

@@ -0,0 +1,264 @@
+require_relative 'requests'
+require 'json-schema'
+
+##################
+## Calendar ######
+##################
+# REVIEW: Remove a calendar event from a particular org unit.
+# Returns: ?
+def delete_org_unit_calendar_event(org_unit_id, event_id)
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/#{event_id}"
+  _delete(path)
+end
+
+# REVIEW: Retrieve a calendar event from a particular org unit.
+# Returns: a EventDataInfo JSON data block
+def get_org_unit_calendar_event(org_unit_id, event_id)
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/#{event_id}"
+  _get(path)
+end
+
+# REVIEW: Retrieve all the calendar events for the calling user,
+#       within the provided org unit context.
+# RETURNS: This action returns a JSON array of EventDataInfo data blocks.
+def get_current_user_calendar_events_by_org_unit(org_unit_id, associated_events_only = nil)
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/events/"
+  path += "?associatedEventsOnly=#{associated_events_only}" unless associated_events_only.nil?
+  _get(path)
+end
+
+# REVIEW: Retrieve the calling user’s calendar events, within a
+#       number of org units (see query parameter)
+# RETURNS: An ObjectListPage JSON block containing a list of EventDataInfo JSON data blocks.
+def get_current_user_calendar_events_by_org_units(association = nil, event_type = nil,
+                                                  org_unit_ids_csv, start_date_time,
+                                                  end_date_time)
+  path = "/d2l/api/le/#{$le_ver}/calendar/events/myEvents/"
+  path += "?orgUnitIdsCSV=#{org_unit_ids_csv}"
+  path += "&startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&association=#{association}" unless association.nil?
+  path += "&eventType=#{event_type}" unless event_type.nil?
+  _get(path)
+end
+
+# REVIEW: Retrieve the calling user’s events for a particular org unit.
+# RETURNS: An ObjectListPage JSON block containing a list of EventDataInfo JSON data blocks.
+def get_current_user_events_by_org_unit(association = nil, event_type = nil,
+                                        start_date_time, end_date_time)
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/events/myEvents/"
+  path += "&startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&association=#{association}" unless association.nil?
+  path += "&eventType=#{event_type}" unless event_type.nil?
+  _get(path)
+end
+
+# REVIEW: Retrieve a count of calling user’s calendar events, within a number of org units
+# RETURNS: An ObjectListPage JSON block containing a list of EventCountInfo JSON data blocks.
+def get_calendar_event_count(association = nil, event_type = nil, org_unit_ids_csv,
+                             start_date_time, end_date_time)
+  path = "/d2l/api/le/#{$le_ver}/calendar/events/myEvents/itemCounts/"
+  path += "?orgUnitIdsCSV=#{org_unit_ids_csv}"
+  path += "&startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&association=#{association}" unless association.nil?
+  path += "&eventType=#{event_type}" unless event_type.nil?
+  _get(path)
+end
+
+# REVIEW: Retrieve a count of calling user’s calendar events, within the
+#       provided org unit context.
+# RETURNS: An EventCountInfo JSON data block.
+def get_org_unit_calendar_event_count(association = nil, event_type = nil,
+                                      start_date_time, end_date_time)
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/events/myEvents/itemCounts/"
+  path += "?startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&association=#{association}" unless association.nil?
+  path += "&eventType=#{event_type}" unless event_type.nil?
+  _get(path)
+end
+
+# REVIEW: Retrieve all the calendar events for the calling user, within a number of org units.
+# RETURNS: a paged result set containing the resulting EventDataInfo JSON data blocks
+def get_paged_calendar_events_by_org_units(org_unit_ids_csv, start_date_time,
+                                           end_date_time, bookmark = '')
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/events/orgunits/"
+  path += "?orgUnitIdsCSV=#{org_unit_ids_csv}"
+  path += "&startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&bookmark=#{bookmark}" unless bookmark == ''
+  _get(path)
+end
+
+# REVIEW: Retrieve all the calendar events for a specified user’s explicit
+#       enrollments within the organization containing the specified org unit.
+# RETURNS: a paged result set containing the resulting EventDataInfo JSON data blocks
+def get_user_calendar_events(org_unit_id, user_id, start_date_time, end_date_time,
+                             bookmark = '')
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/events/user/"
+  path += "?userId=#{user_id}"
+  path += "&startDateTime=#{start_date_time}"
+  path += "&endDateTime=#{end_date_time}"
+  path += "&bookmark=#{bookmark}" unless bookmark == ''
+  _get(path)
+  # RETURNS: a paged result set containing the resulting EventDataInfo JSON data blocks
+end
+
+# Check the validity of the Calendar.EventData that is passed as a payload
+def check_calendar_event_data_validity(event_data)
+  schema =
+    {
+        'type' => 'object',
+        'required' => %w(Title Description StartDateTime EndDateTime StartDay
+                         EndDay GroupId RecurrenceInfo HasVisibilityRestrictions
+                         VisibilityRestrictions CalendarEventViewUrl),
+        'properties' =>
+        {
+            'Title' => { 'type' => 'integer' },
+            "Description" => { 'type' => 'integer' },
+            "StartDateTime" => { 'type' => %w(string nil) }, # UTCDateTime || nil
+            "EndDateTime" => { 'type' => %w(string nil) }, # UTCDateTime || nil
+            "StartDay" => { 'type' => %w(string nil) }, # LocalDateTime || nil
+            "EndDay" => { 'type' => %w(string nil) }, # LocalDateTime || nil
+            "GroupId" => { 'type' => %w(integer nil) }, # D2LID || nil
+            "RecurrenceInfo" =>
+            {
+              'type' => 'object',
+              'required' => %w(RepeatType RepeatEvery RepeatOnInfo RepeatUntilDate),
+              'properties' =>
+              {
+                "RepeatType" => { 'type' => 'integer' }, # number -- repeat type
+                "RepeatEvery" => { 'type' => 'integer' }, # number
+                "RepeatOnInfo" => # Calendar.RepeatOnInfo
+                {
+                  'type' => 'object',
+                  'required' => %w(Monday Tuesday Wednesday Thursday Friday
+                                   Saturday Sunday),
+                  'properties' =>
+                  {
+                    "Monday" => { 'type' => 'boolean' }, # boolean
+                    "Tuesday" => { 'type' => 'boolean' }, # boolean
+                    "Wednesday" => { 'type' => 'boolean' }, # boolean
+                    "Thursday" => { 'type' => 'boolean' }, # boolean
+                    "Friday" => { 'type' => 'boolean' }, # boolean
+                    "Saturday" => { 'type' => 'boolean' }, # boolean
+                    "Sunday" => { 'type' => 'boolean' }, # boolean
+                  }
+                },
+                "RepeatUntilDate" => { 'type' => 'string' } # UTCDATETIME
+              }
+            }, # Calendar.RecurrenceInfo
+            "HasVisibilityRestrictions" => { 'type' => 'boolean' },
+            "VisibilityRestrictions" =>
+            {
+              'type' => 'object',
+              'required' => %w(Type Range HiddenRangeUnitType StartDate EndDate),
+              'properties' =>
+              {
+                "Type" => { 'type' => 'integer' }, # <number:VISIBILITY_T>,
+                "Range" => { 'type' => %w(integer nil) }, # <number>|null,
+                "HiddenRangeUnitType" => { 'type' => %w(integer nil) }, # <number:HIDDENUNIT_T>|null,
+                "StartDate" => { 'type' => %w(string nil) }, # <string:UTCDateTime>|null,
+                "EndDate" => { 'type' => %w(string nil) } # <string:UTCDateTime>|null,
+              }
+            }, # Calendar.VisibilityInfo
+            "CalendarEventViewUrl" => { 'type' => 'string' } # url
+        }
+    }
+  JSON::Validator.validate!(schema, event_data, validate_schema: true)
+end
+
+# REVIEW: Create Schema checker; Check that this payload conforms to it.
+# Create a new event.
+# INPUT: Calendar.EventData
+# RETURNS:a EventDataInfo data block for the newly created event.
+def create_event(org_unit_id, event_data)
+  # POST /d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/"
+  payload = { #Calendar.EventDataInfo
+    "Title" => "",
+    "Description" => "",
+    "StartDateTime" => nil, # UTCDateTime || nil
+    "EndDateTime" => nil, # UTCDateTime || nil
+    "StartDay" => nil, # LocalDateTime || nil
+    "EndDay" => nil, # LocalDateTime || nil
+    "GroupId" => nil, # D2LID || nil
+    "RecurrenceInfo" => # Calendar.RecurrenceInfo
+    {
+      "RepeatType" => 0, # number -- repeat type
+      "RepeatEvery" => 0, # number
+      "RepeatOnInfo" => # Calendar.RepeatOnInfo
+      {
+        "Monday" => false, # boolean
+        "Tuesday" => false, # boolean
+        "Wednesday" => false, # boolean
+        "Thursday" => false, # boolean
+        "Friday" => false, # boolean
+        "Saturday" => false, # boolean
+        "Sunday" => false, # boolean
+      },
+      "RepeatUntilDate" => "" # UTCDATETIME
+    },
+    "HasVisibilityRestrictions" => false,
+    "VisibilityRestrictions" => # Calendar.VisibilityInfo
+    {
+      "Type" => 0, # <number:VISIBILITY_T>,
+      "Range" => nil, # <number>|null,
+      "HiddenRangeUnitType" => nil, # <number:HIDDENUNIT_T>|null,
+      "StartDate" => nil, # <string:UTCDateTime>|null,
+      "EndDate" => nil # <string:UTCDateTime>|null,
+    },
+    "CalendarEventViewUrl" => "" # String:URL
+  }.merge!(event_data)
+  check_calendar_event_data_validity(payload) # NOTE: Test later
+  _post(path, payload)
+
+end
+
+# REVIEW: Create Schema checker; Check that this payload conforms to it.
+# Update the properties for a calendar event from a particular org unit.
+# INPUT: Calendar.EventData
+# RETURNS:a EventDataInfo data block for the newly updated event.
+def update_event(org_unit_id, event_id, event_data)
+  # PUT /d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/#{event_id}
+  path = "/d2l/api/le/#{$le_ver}/#{org_unit_id}/calendar/event/#{event_id}"
+  payload = { #Calendar.EventDataInfo
+    "Title" => "",
+    "Description" => "",
+    "StartDateTime" => nil, # UTCDateTime || nil
+    "EndDateTime" => nil, # UTCDateTime || nil
+    "StartDay" => nil, # LocalDateTime || nil
+    "EndDay" => nil, # LocalDateTime || nil
+    "GroupId" => nil, # D2LID || nil
+    "RecurrenceInfo" => # Calendar.RecurrenceInfo
+    {
+      "RepeatType" => 0, # number -- repeat type
+      "RepeatEvery" => 0, # number
+      "RepeatOnInfo" => # Calendar.RepeatOnInfo
+      {
+        "Monday" => false, # boolean
+        "Tuesday" => false, # boolean
+        "Wednesday" => false, # boolean
+        "Thursday" => false, # boolean
+        "Friday" => false, # boolean
+        "Saturday" => false, # boolean
+        "Sunday" => false, # boolean
+      },
+      "RepeatUntilDate" => "" # UTCDATETIME
+    },
+    "HasVisibilityRestrictions" => false,
+    "VisibilityRestrictions" => # Calendar.VisibilityInfo
+    {
+      "Type" => 0, # <number:VISIBILITY_T>,
+      "Range" => nil, # <number>|null,
+      "HiddenRangeUnitType" => nil, # <number:HIDDENUNIT_T>|null,
+      "StartDate" => nil, # <string:UTCDateTime>|null,
+      "EndDate" => nil # <string:UTCDateTime>|null,
+    },
+    "CalendarEventViewUrl" => "" # String:URL
+  }.merge!(event_data)
+  check_calendar_event_data_validity(payload) # NOTE: Test later
+  _put(path, payload)
+end

data/lib/d2l_sdk/config_variables.rb

@@ -151,7 +151,123 @@ def get_config_var_resolver(variable_id)
 end
 
 # NOTE: UNSTABLE!!!
-# TODO: Update the resolution strategy for an org unit configuration variable.
+# TODO: UNSTABLE!!! --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
+
+################################################################################
+###############################     TOOLS    ###################################
+################################################################################
+# NOTE: This section has been appended to config variables due to its similar
+#       placement in the GUI and the fact that tools functions are rather small
+#       in number.
+
+########################
+# ORGANIZATION:#########
+########################
+
+# REVIEW: Retrieve the current organization-level information for all tools.
+# => GET /d2l/api/lp/(version)/tools/org/
+# RETURNS: paged result set containing the resulting OrgInformation data blocks
+def get_org_tools_info(include_restricted_tools = nil, bookmark = '')
+  path = "/d2l/api/lp/#{$lp_ver}/tools/org/?"
+  path += "includeRestrictedTools=#{includeRestrictedTools}&" unless include_restricted_tools.nil?
+  path += "bookmark=#{bookmark}" unless bookmark == ''
+  _get(path)
+  # RETURNS: paged result set containing the resulting OrgInformation data blocks
+end
+
+# REVIEW: Retrieve the current organization-level information for a tool.
+# => GET /d2l/api/lp/(version)/tools/org/(toolId)
+# RETURNS: an OrgInformation JSON block
+def get_org_tool_info(tool_id)
+  path = "GET /d2l/api/lp/#{$lp_ver}/tools/org/#{tool_id}"
+  _get(path)
+  # RETURNS: an OrgInformation JSON block
+end
+
+# NOTE: Not inherent d2l_api function. This is to check that the update_status
+#       is actually a boolean and return a formatted UpdateStatus JSON block.
+def check_and_create_update_status_payload(update_status)
+  if update_status != true && update_status != false
+    raise ArgumentError, 'update_status is not a boolean'
+  end
+  payload = {"Status" => update_status} # Tools.UpdateStatus JSON data block
+  payload
+end
+
+# REVIEW: Update the organization-level status for a tool.
+# => PUT /d2l/api/lp/(version)/tools/org/(toolId)
+def update_org_tool_status(tool_id, update_status)
+  path = "/d2l/api/lp/#{$lp_ver}/tools/org/#{tool_id}"
+  payload = check_and_create_update_status_payload(update_status)
+  _put(path, payload)
+end
+
+# REVIEW: Update a tool’s default status for new org units.
+# => PUT /d2l/api/lp/(version)/tools/org/(toolId)/OUDefault
+def update_tool_default_status(tool_id, update_status)
+  path = "/d2l/api/lp/#{$lp_ver}/tools/org/#{tool_id}/OUDefault"
+  payload = check_and_create_update_status_payload(update_status)
+  _put(path, payload)
+end
+
+# REVIEW: Update a tool’s current status for all org units.
+# => PUT /d2l/api/lp/(version)/tools/org/(toolId)/OUDefault/override
+def update_all_org_unit_tool_status(tool_id, update_status)
+  path = "/d2l/api/lp/#{$lp_ver}/tools/org/#{tool_id}/OUDefault/override"
+  payload = check_and_create_update_status_payload(update_status)
+  _put(path, payload)
+end
+
+########################
+# ORG UNITS:############
+########################
+
+# REVIEW: Retrieve the current information for all tools enabled for the provided org unit.
+# => GET /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)
+def get_org_enabled_tools_info(org_unit_id, bookmark = '')
+  path = "/d2l/api/lp/#{$lp_ver}/tools/orgUnits/#{org_unit_id}?"
+  path += "bookmark=#{bookmark}" unless bookmark == ''
+  _get(path)
+end
+
+# REVIEW: Retrieve the current information for a tool enabled for the provided org unit.
+# => GET /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)/(toolId)
+def get_org_enabled_tool_info(org_unit_id, tool_id)
+  path = "/d2l/api/lp/#{$lp_ver}/tools/orgUnits/#{org_unit_id}/#{tool_id}"
+  _get(path)
+end
+
+def check_org_unit_information_validity(data_block)
+    schema = {
+        'type' => 'object',
+        'required' => %w(ToolId DisplayName OrgUnitId Status CustomNavbarName),
+        'properties' => {
+            'ToolId' => { 'type' => 'string' },
+            'DisplayName' => { 'type' => 'string' },
+            'CallbackUrl' => { 'type' => 'integer' },
+            'Status' => { 'type' => 'boolean' },
+            'CustomNavbarName' => { 'type' => 'string' }
+        }
+    }
+    JSON::Validator.validate!(schema, data_block, validate_schema: true)
+end
+
+# REVIEW: Update the org unit-level information for a tool.
+# INPUT: OrgUnitInformation JSON block
+# => PUT /d2l/api/lp/(version)/tools/orgUnits/(orgUnitId)/(toolId)
+def update_org_unit_level_tool_info(org_unit_id, tool_id, org_unit_information)
+  path = "/d2l/api/lp/#{$lp_ver}/tools/orgUnits/#{org_unit_id}/#{tool_id}"
+  payload =
+  {
+    "ToolId" => "", # <string:D2LID>
+    "DisplayName" => "",   # <string> ## added with LP v1.6 API
+    "OrgUnitId" => 0, # D2LID:number
+    "Status" => false, # boolean
+    "CustomNavbarName" => "" # <string>
+  }.merge!(org_unit_information)
+  check_org_unit_information_validity(payload) # NOTE: Check this later.
+  _put(path, payload)
+end