lusi_api 0.1.11

data/lib/lusi_api/service_account.rb

@@ -0,0 +1,121 @@
+require 'lusi_api/core/xml'
+require 'lusi_api/organisation'
+require 'lusi_api/service_method'
+
+
+module LUSI
+  module API
+
+
+    # Represents a service account used to access the LUSI API
+    class ServiceAccount
+
+      # @!attribute [rw] contact_email
+      #   @return [String, nil] the email address of the service account owner
+      attr_accessor :contact_email
+
+      # @!attribute [rw] contact_name
+      #   @return [String, nil] the full name of the service account owner
+      attr_accessor :contact_name
+
+      # @!attribute [rw] description
+      #   @return [String, nil] the description of the service account
+      attr_accessor :description
+
+      # @!attribute [rw] expiry_date
+      #   @return [DateTime, nil] the expiry date of the service account password
+      attr_accessor :expiry_date
+
+      # @!attribute [rw] institutions
+      #   @return [Array<LUSI::API::Organisation::Unit>, nil] an array of institutions associated with this account
+      attr_accessor :institutions
+
+      # @!attribute [rw] service_methods
+      #   @return [Array<LUSI::API::ServiceMethod>, nil] an array of ServiceMethod instances callable from this account
+      attr_accessor :service_methods
+
+      # @!attribute [rw] username
+      #   @return [String, nil] the service account username
+      attr_accessor :username
+  
+      # The characters used to generate a random service account password
+      PASSWORD_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!-_=+,.'
+  
+      # Return a ServiceAccount instance for the API's service user
+      # @param api [LUSI::API::Core::API] the LUSI API instance
+      # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+      # @return [Array<LUSI::API::ServiceAccount>] a list containing the ServiceAccount for the API's service user
+      # @yield [obj] Passes the ServiceAccount instance to the block
+      # @yieldparam obj [LUSI::API::ServiceAccount] the ServiceAccount instance
+      # @raise [LUSI::API::Core::APIError] if the API call fails
+      def self.get_instance(api, lookup = nil)
+        xml = api.call('LUSIReference', 'General.asmx', 'GetServiceAccountDetails')
+        LUSI::API::Core::XML::xml(xml, 'xmlns:ServiceAccount') do |s|
+          obj = LUSI::API::ServiceAccount.new(s, lookup)
+          yield(obj) if block_given?
+          obj
+        end
+      end
+  
+      # Creates a new ServiceAccount instance
+      # Fields are extracted from the parsed XML response to the LUSI GetServiceAccountDetails API call.
+      # Default values for fields missing from the XML can be specified as keyword arguments.
+      # @param xml [Nokogiri::XML::Node, nil] the XML response from the LUSI GetServiceAccountDetails API call, or nil
+      # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+      # @param username [String, nil] the default username
+      # @param description [String, nil] the default description
+      # @param contact_name [String, nil] the default contact name
+      # @param contact_email [Stirng, nil] the default contact email
+      # @param expiry_date [DateTime, nil] the default expiry date
+      # @param institutions [Array<LUSI::API::Institution>] the default institution list
+      # @param service_methods [Array<LUSI::API::ServiceMethod>] the default service method list
+      # @return [void]
+      def initialize(xml = nil, lookup = nil, username: nil, description: nil, contact_name: nil, contact_email: nil,
+                    expiry_date: DateTime, institutions: nil, service_methods: nil)
+        @contact_email = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactEmail', contact_email)
+        @contact_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactName', contact_name)
+        @description = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Description', description)
+        @expiry_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:ExpiryDate', expiry_date)
+        @institutions = LUSI::API::Core::XML.xml(xml, 'xmlns:Institutions', institutions).map { |i| LUSI::API::Core::XML.lookup(i, lookup, :institution, 'xmlns:Institution') }
+        @service_methods = LUSI::API::Core::XML.xml(xml, 'xmlns:ServiceMethods/xmlns:ServiceMethod', service_methods).map { |m| LUSI::API::ServiceMethod.new(m, lookup) }
+        @username = LUSI::API::Core::XML.xml_content_at('xmlns:Username')
+      end
+  
+      # Returns a String representation of the ServiceAccount instance (the service username)
+      # @return [String] the string representation of the ServiceAccount instance
+      def to_s
+        @username
+      end
+  
+      # Generates a 16-character random password for the service account
+      # @return [String] the generated password
+      def self.generate_service_account_password
+        password = []
+        random = Random::new
+        (0..16).each { |i| password.push(PASSWORD_CHARS[random.rand(PASSWORD_CHARS.length)]) }
+        password.join('')
+      end
+  
+      # Sets a new password on the service account
+      # @param api [LUSI::API::Core::API] the LUSI API configured with the service account to be updated
+      # @param password [String, nil] the new password (if nil, a 16-digit random password will be generated)
+      # @return [String] the new password
+      # @raise [LUSI::API::Core::APIError] if the LUSI API call fails
+      def self.update_service_account_password(api, password = nil)
+  
+        # Generate a password if required
+        password ||= generate_service_account_password
+  
+        # Update the password
+        xml = api.call('LUSIReference', 'General.asmx', 'UpdateServiceAccountPassword', NewPassword: password)
+  
+        # Return the new password
+        password
+  
+      end
+  
+    end
+
+
+  end
+end

data/lib/lusi_api/service_method.rb

@@ -0,0 +1,52 @@
+require 'lusi_api/core/xml'
+
+module LUSI
+  module API
+
+
+    # Represents a LUSI API service method
+    class ServiceMethod
+
+      # @!attribute [rw] endpoint
+      #   @return [String] the endpoint component of the web service address (e.g. 'General.asmx')
+      attr_accessor :endpoint
+
+      # @!attribute [rw] method_name
+      #   @return [String] the method name of the web service (e.g. 'GetServiceAccountDetails')
+      attr_accessor :method_name
+
+      # @!attribute [rw] url
+      #   @return [String] the web service URL root, excluding the endpoint and method name
+      attr_accessor :url
+
+      # @!attribute [rw] web_service
+      #   @return [String] the web service name
+      attr_accessor :web_service
+  
+      # Initialize a new ServiceMethod instance
+      # Fields are extracted from the parsed XML from the LUSI API response. A single <ServiceMethod> element is expected.
+      # Default values for fields missing from the XML can be specified as keyword arguments.
+      # @param xml [Nokogiri::XML::Node, Nokogiri:nil] the XML response from the LUSI GetServiceAccountDetails API call, or nil
+      # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+      # @param web_service [String, nil] the default web service name
+      # @param url [Stirng, nil] the default URL
+      # @param endpoint [String, nil] the default endpoint name
+      # @param method_name [String, nil] the default method name
+      def initialize(xml = nil, lookup = nil, web_service: nil, url: nil, endpoint: nil, method_name: nil)
+        @web_service = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:WebService', web_service)
+        @url = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Url', url)
+        @endpoint = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:EndPoint', endpoint)
+        @method_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:MethodName', method_name)
+      end
+  
+      # Return a string representation of the ServiceMethod instance (the full URL path)
+      # @return [String] the string representation of the ServiceMethod instance
+      def to_s
+        "#{@url}/#{@endpoint}/#{@method_name}"
+      end
+  
+    end
+
+
+  end
+end

data/lib/lusi_api/version.rb

@@ -0,0 +1,5 @@
+module LUSI
+  module API
+    VERSION = '0.1.11'.freeze
+  end
+end

data/lib/lusi_api/vle.rb

@@ -0,0 +1,329 @@
+require 'lusi_api/core/code'
+require 'lusi_api/core/xml'
+require 'lusi_api/course'
+require 'lusi_api/enrolment'
+
+module LUSI
+  module API
+    module VLE
+      class Department
+        # @!attribute [rw] identity
+        #   @return [String] the department identity
+        attr_accessor :identity
+
+        # @!attribute [rw] org_unit
+        #   @return [LUSI::API::Organisation::Unit] the organisation unit
+        #     representing the department
+        attr_accessor :org_unit
+
+        # @!attribute [rw] title
+        #   @return [String] the department name
+        attr_accessor :title
+
+        # Initialises a new Department instance
+        # @param identity [String] the department's identity
+        # @param org_unit [LUSI::API::Organisation::Unit] the organisation unit
+        #   for the department
+        # @param title [String] the department's title
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, identity: nil, org_unit: nil,
+                       title: nil)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @org_unit = LUSI::API::Core::XML.lookup(xml, lookup, :department, 'xmlns:Identity', org_unit)
+          @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
+        end
+
+        # Returns a string representation of the Department instance
+        # @return [String] the string representation of the Department instance
+        def to_s
+          title
+        end
+      end
+
+      class VLESpaceCourse
+        # @!attribute [rw] identity
+        #   @return [LUSI::API::Course::EnrolmentIdentity] the VLE space course
+        #     identity
+        attr_accessor :identity
+
+        # @!attribute [rw] display_long_title
+        #   @return [String, nil] the long course title
+        attr_accessor :display_long_title
+
+        # @!attribute [rw] display_short_title
+        #   @return [String, nil] the short course title
+        attr_accessor :display_short_title
+
+        # @!attribute [rw] department
+        #   @return [LUSI::API::VLE::Department] the department
+        attr_accessor :department
+
+        # @!attribute [rw] talis_code
+        #   @return [String, nil] the Talis Aspire course code
+        attr_accessor :talis_code
+
+        # Initialises a new VLESpaceCourse instance
+        # @return [void]
+        def initialize(xml = nil, lookup = nil,
+                       department: nil, display_long_title: nil,
+                       display_short_title: nil, identity: nil, talis_code: nil)
+          @department = LUSI::API::VLE::Department.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Department', department), lookup)
+          @display_long_title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:DisplayLongTitle', display_long_title)
+          @display_short_title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:DisplayShortTitle', display_short_title)
+          @identity = LUSI::API::Course::EnrolmentIdentity.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Identity', identity), lookup)
+          @talis_code = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:TalisCode', talis_code)
+        end
+
+        # Returns a string representation of the VLESpaceCourse instance
+        # @return [String] the string representation of the VLESpaceCourse instance
+        def to_s
+          display_long_title || display_short_title
+        end
+      end
+
+      class VLESpace
+        # @!attribute [rw] copy_course_materials_from_prev_session
+        #   @return [Boolean, nil] the space copy flag
+        attr_accessor :copy_course_materials_from_prev_session
+
+        # @!attribute [rw] course_departments
+        #   @return [Array<LUSI::API::Course::CourseDepartment>, nil] the list
+        #     of associated course departments
+        attr_accessor :course_departments
+
+        # @!attribute [rw] course_type
+        #   @return [String, nil] the course type (CMOD|SOS)
+        attr_accessor :course_type
+
+        # @!attribute [rw] create_space_date
+        #   @return [DateTime, nil] the VLE space creation date
+        attr_accessor :create_space_date
+
+        # @!attribute [rw] create_space_date_utc
+        #   @return [DateTime, nil] the UTC VLE space creation date
+        attr_accessor :create_space_date_utc
+
+        # @!attribute [rw] display_long_title
+        #   @return [String, nil] the long course title
+        attr_accessor :display_long_title
+
+        # @!attribute [rw] display_short_title
+        #   @return [String, nil] the short course title
+        attr_accessor :display_short_title
+
+        # @!attribute [rw] end_date
+        #   @return [DateTime, nil] the VLE space end date
+        attr_accessor :end_date
+
+        # @!attribute [rw] end_date_utc
+        #   @return [DateTime, nil] the UTC VLE space end date
+        attr_accessor :end_date_utc
+
+        # @!attribute [rw] hide_content_on_rollover
+        #   @return [Boolean, nil] the hide content on rollover flag
+        attr_accessor :hide_content_on_rollover
+
+        # @!attribute [rw] is_conversion_space
+        #   @return [Boolean, nil] the space conversion flag
+        attr_accessor :is_conversion_space
+
+        # @!attribute [rw] lusi_year_id
+        #   @return [String] the year identity code
+        attr_accessor :lusi_year_id
+
+        # @!attribute [rw] lusi_vle_space_id
+        #   @return [String] the VLE space ID
+        attr_accessor :lusi_vle_space_id
+
+        # @!attribute [rw] space_type
+        #   @return [String, nil] the space type (SINGLE|SHARED)
+        attr_accessor :space_type
+
+        # @!attribute [rw] start_date
+        #   @return [DateTime, nil] the VLE space start date
+        attr_accessor :start_date
+
+        # @!attribute [rw] start_date_utc
+        #   @return [DateTime, nil] the UTC VLE space start date
+        attr_accessor :start_date_utc
+
+        # @!attribute [rw] student_access_date
+        #   @return [DateTime, nil] the VLE space student access date
+        attr_accessor :student_access_date
+
+        # @!attribute [rw] student_access_date_utc
+        #   @return [DateTime, nil] the UTC VLE space student access date
+        attr_accessor :student_access_date_utc
+
+        # @!attribute [rw] url
+        #   @return [String, nil] the VLE space URL
+        attr_accessor :url
+
+        # @!attribute [rw] vle_provider
+        #   @return [LUSI::API::Core::Code, nil] the VLE provider
+        attr_accessor :vle_provider
+
+        # @!attribute [rw] vle_space_courses
+        #   @return [Array<LUSI::API::VLESpace::VLESpaceCourse>, nil] the list
+        #     of associated courses
+        attr_accessor :vle_space_courses
+
+        # @!attribute [rw] vle_template
+        #   @return [LUSI::API::Core::Code, nil] the VLE template
+        attr_accessor :vle_template
+
+        # Returns an array of instances matching the specified search criteria
+        # @param api [LUSI::API::Core::API] the LUSI API instance for searching
+        # @param (see #get_instance_params)
+        # @return [<Array<LUSI::API::VLE::VLESpace>] the matching instances
+        # @yield [obj] Passes the instance to the block
+        # @yieldparam obj [LUSI::API::VLE::VLESpace] the instance
+        def self.get_instance(api, lookup = nil, **kwargs)
+          params = get_instance_params(**kwargs)
+          xml = api.call('LUSIReference', 'General.asmx', 'GetVLESpaces',
+                         **params)
+          LUSI::API::Core::XML.xml(xml, 'xmlns:VLESpace') do |m|
+            obj = self.new(m, lookup)
+            yield(obj) if block_given?
+            obj
+          end
+        end
+
+        # Returns a hash of parameters for the LUSI API call.
+        # @param asp_identity [String, nil] return instances matching this
+        #   academic significant period (ASP)
+        # @param cohort_identity (String, nil) return instances matching this
+        #   cohort identity
+        # @param course_identity [String, nil] return instances matching this
+        #   course identity
+        # @param course_type [String, nil] return instances matching this course
+        #   type (CMOD|SOS)
+        # @param department_identity (String, nil) return instances matching
+        #   this department identity
+        # @param space_type [String, nil] return instances matching this space
+        #   type (SHARED|SINGLE)
+        # @param vle_space_identity [String, nil] return instances matching this
+        #   VLE space identity
+        # @param vle_provider_identity [String, nil] return instances matching
+        #   this VLE provider identity
+        # @param year_identity (String, nil) return instances matching this year
+        #   identity
+        # @param active_vle_space_only [Boolean, nil] if true, return only
+        #   active VLE spaces, otherwise return all spaces
+        # @return [Array<VLESpace>, nil] the matching VLESpace instances
+        # @yield [obj] Passes the VLESpace instance to the block
+        # @yieldparam obj [LUSI::API::VLE::VLESpace] the VLESpace instance
+        def self.get_instance_params(**kwargs)
+          {
+            ActiveVLESpaceOnly: kwargs.fetch(:active_vle_space_only, true) ? 'true' : 'false',
+            ASPIdentity: kwargs.fetch(:asp_identity, ''),
+            CohortIdentity: kwargs.fetch(:cohort_identity, ''),
+            CourseIdentity: kwargs.fetch(:course_identity, ''),
+            CourseType: kwargs.fetch(:course_type, ''),
+            DepartmentIdentity: kwargs.fetch(:department_identity, ''),
+            SpaceType: kwargs.fetch(:space_type, ''),
+            VLEProviderIdentity: kwargs.fetch(:vle_provider_identity, ''),
+            VLESpaceIdentity: kwargs.fetch(:vle_space_identity, ''),
+            YearIdentity: kwargs.fetch(:year_identity, '')
+          }
+        end
+
+        # Initialises a new VLESpace instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the VLE space
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param copy_course_materials_from_prev_session [Boolean, nil] the
+        #   default space copy flag
+        # @param course_departments [Array<LUSI::API::Course::CourseDepartment>, nil] the default course departments
+        # @param course_type [String, nil] the default course type
+        # @param create_space_date [DateTime] the default VLE space creation date
+        # @param create_space_date_utc [DateTime] the default UTC VLE space creation date
+        # @param display_long_title [String, nil] the default long title
+        # @param display_short_title [String, nil] the default short title
+        # @param end_date [DateTime] the default VLE space end date
+        # @param end_date_utc [DateTime] the default UTC VLE space end date
+        # @param hide_content_on_rollover [Boolean, nil] the default hide
+        #   content on rollover flag
+        # @param is_conversion_space [Boolean, nil] the default conversion space
+        #   flag
+        # @param lusi_vle_space_id [String, nil] the default VLE space ID
+        # @param lusi_year_id [String, nil] the default year identity code
+        # @param space_type [String, nil] the default space type
+        # @param start_date [DateTime] the default VLE space start date
+        # @param start_date_utc [DateTime] the default UTC VLE space start date
+        # @param student_access_date [DateTime] the default student enrolment date
+        # @param student_access_date_utc [DateTime] the default UTC student enrolment date
+        # @param url [String, nil] the URL for the VLE space
+        # @param vle_provider [LUSI::API::Core::Code] the VLE provider
+        # @param vle_space_courses [Array<LUSI::API::VLESpace::VLESpaceCourse>]
+        #   the list of associated courses
+        # @param vle_template [LUSI::API::Core::Code] the VLE template
+        # @return [void]
+        def initialize(xml = nil, lookup = nil,
+                       copy_course_materials_from_prev_session: nil,
+                       course_departments: nil,
+                       course_type: nil,
+                       create_space_date: nil,
+                       create_space_date_utc: nil,
+                       display_long_title: nil,
+                       display_short_title: nil,
+                       end_date: nil,
+                       end_date_utc: nil,
+                       hide_content_on_rollover: nil,
+                       is_conversion_space: nil,
+                       lusi_vle_space_id: nil,
+                       lusi_year_id: nil,
+                       space_type: nil,
+                       start_date: nil,
+                       start_date_utc: nil,
+                       student_access_date: nil,
+                       student_access_date_utc: nil,
+                       url: nil,
+                       vle_provider: nil,
+                       vle_space_courses: nil,
+                       vle_template: nil)
+          @copy_course_materials_from_prev_session = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:CopyCourseMaterialsFromPrevSession', copy_course_materials_from_prev_session)
+          @course_departments = LUSI::API::Core::XML.xml(xml, 'xmlns:Departments/xmlns:CourseDepartment',
+                                                         course_departments) { |d| LUSI::API::Course::CourseDepartment.new(d, lookup) }
+          @course_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:CourseType', course_type)
+          @create_space_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:CreateSpaceDate', create_space_date)
+          @create_space_date_utc = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:CreateSpaceDateUTC', create_space_date_utc)
+          @display_long_title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:DisplayLongTitle', display_long_title)
+          @display_short_title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:DisplayShortTitle',
+                                                                     display_short_title)
+          @end_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:EndDate', end_date)
+          @end_date_utc = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:EndDateUTC', end_date_utc)
+          @hide_content_on_rollover = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:HideContentOnRollover', hide_content_on_rollover)
+          @is_conversion_space = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:IsConversionSpace', is_conversion_space)
+          @lusi_vle_space_id = LUSI::API::Core::XML.xml_content_at(xml, '@LUSIVLESpaceId', lusi_vle_space_id)
+          @lusi_year_id = LUSI::API::Core::XML.xml_content_at(xml, '@LUSIYearId', lusi_year_id)
+          @space_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:SpaceType', space_type)
+          @start_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:StartDate', start_date)
+          @start_date_utc = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:StartDateUTC', start_date_utc)
+          @student_access_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:StudentAccessDate', student_access_date)
+          @student_access_date_utc = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:StudentAccessDateUTC', student_access_date_utc)
+          @url = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:URL', url)
+
+          @vle_provider = LUSI::API::Core::Code.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:VLEProvider',
+                                                                                vle_provider), lookup)
+          @vle_space_courses = LUSI::API::Core::XML.xml(xml, 'xmlns:VLESpaceCourses/xmlns:VLESpaceCourse',
+                                                        vle_space_courses) { |c| VLESpaceCourse.new(c, lookup) }
+          @vle_template = LUSI::API::Core::Code.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:VLETemplate',
+                                                                                vle_template), lookup)
+        end
+
+        # Returns a string representation of the VLESpace instance
+        # @return [String] the string representation of the VLESpace instance
+        def to_s
+          display_long_title || display_short_title
+        end
+      end
+
+      class ModuleVLEEnrolment < LUSI::API::Course::StaffModuleEnrolment
+        # @see (LUSI::API::Core::Endpoint#lusi_ws_method)
+        def self.lusi_ws_method
+          'BulkGetModuleVLEEnrolments'
+        end
+      end
+    end
+  end
+end