lusi_api 0.1.11

data/lib/lusi_api/enrolment.rb

@@ -0,0 +1,247 @@
+require 'lusi_api/core/api'
+require 'lusi_api/core/code'
+require 'lusi_api/core/xml'
+
+
+module LUSI
+  module API
+    module Enrolment
+
+      # Represents an enrolment role in the LUSI API
+      class EnrolmentRole < LUSI::API::Core::Code
+
+        # @!attribute [rw] vle_role_description
+        #   @return [String, nil] the VLE role description a member has against this enrolment
+        attr_accessor :vle_role_description
+
+        # Initialises a new EnrolmentRole instance
+        # @param (see LUSI::API::Core::Code#initialize)
+        # @param vle_role_description [String, nil] the default VLE role description
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, vle_role_description: nil, **kwargs)
+          super(xml, lookup, **kwargs)
+          @vle_role_description = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:VLERoleDescription',
+                                                                      vle_role_description)
+        end
+
+      end
+
+
+      # The abstract base class for enrolment classes
+      # @abstract Subclasses must define the lusi_ws_* endpoint methods and additional attributes
+      class EnrolmentBase
+
+        extend LUSI::API::Core::Endpoint
+
+        # @!attribute [rw] enrolment_role
+        #   @return [LUSI::API::Enrolment::EnrolmentRole, nil] the role that members have against this enrolment
+        attr_accessor :enrolment_role
+
+        # @!attribute [rw] identity
+        #   @return [LUSI::API::Enrolment::EnrolmentIdentity] the identity of the subject (person) of the enrolment
+        attr_accessor :identity
+
+        # @!attribute [rw] is_current_enrolment
+        #   @return [Boolean, nil] true if the enrolment is current, false otherwise
+        attr_accessor :is_current_enrolment
+
+        # @!attribute [rw] is_current_identity
+        #   @return [Boolean, nil] true if the member's identity is current, false otherwise
+        attr_accessor :is_current_identity
+
+        # @!attribute [rw] username
+        #   @return [String, nil] the username of the subject (person) of the enrolment
+        attr_accessor :username
+
+        # Initalises a new Enrolment instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the enrolment
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param enrolment_role [LUSI::API::Enrolment::EnrolmentRole, nil] the default enrolment role
+        # @param identity [String, nil] the default user identity code
+        # @param is_current_enrolment [Boolean, nil] the default current enrolment flag
+        # @param is_current_identity [Boolean, nil] the default current identity flag
+        # @param username [String, nil] the default username
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, enrolment_role: nil, identity: nil, is_current_enrolment: nil,
+                       is_current_identity: nil, username: nil)
+          is_current_enrolment = is_current_enrolment.nil? || is_current_enrolment ? true : false
+          is_current_identity = is_current_identity.nil? || is_current_identity ? true : false
+          @enrolment_role = EnrolmentRole.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:EnrolmentRole', enrolment_role),
+                                              lookup)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @is_current_enrolment = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:IsCurrentEnrolment',
+                                                                      is_current_enrolment)
+          @is_current_identity = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:IsCurrentIdentity',
+                                                                     is_current_identity)
+          @username = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Username', username)
+        end
+
+        # Returns an array of instances matching the specified search criteria
+        # @param api [LUSI::API::Core::API] the LUSI API instance to use for searching
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param (see #get_instance_params)
+        # @yield [obj] Passes the instance to the block
+        def self.get_instance(api, lookup = nil, current_only: nil, **kwargs)
+          current_only = current_only.nil? || current_only ? true : false
+          if current_only
+            # Filter nodes which have current enrolments and user identities
+            filter = Proc.new do |node|
+              LUSI::API::Core::XML.xml_boolean_at(node, 'xmlns:IsCurrentEnrolment', false) &&
+                  LUSI::API::Core::XML.xml_boolean_at(node, 'xmlns:IsCurrentIdentity', false)
+            end
+          else
+            filter = nil
+          end
+          params = self.get_instance_params(**kwargs)
+          xml = api.call(self.lusi_ws_path, self.lusi_ws_endpoint, self.lusi_ws_method, **params)
+          result = LUSI::API::Core::XML.xml(xml, "xmlns:#{self.lusi_ws_xml_root}", filter: filter) do |m|
+            obj = self.new(m, lookup)
+            yield(obj) if block_given?
+            obj
+          end
+          # Return the array of instances
+          result
+        end
+
+        # Returns the lookup indices supported by this enrolment type
+        # @return [Array<Symbol>] the supported lookup indices
+        def lookup_indices
+          [:identity, :role, :username]
+        end
+
+        # Returns the value to be used as a key for the specified lookup index
+        # @return [Object] the key value
+        def lookup_key(index = nil)
+          case index
+            when :identity
+              self.identity
+            when :role
+              self.enrolment_role ? self.enrolment_role.identity : nil
+            when :username
+              self.username
+            else
+              nil
+          end
+        end
+
+        # @see (LUSI::API::Core::Endpoint#lusi_ws_path)
+        def self.lusi_ws_path
+          'UserDetails'
+        end
+
+        protected
+
+        # Returns a hash of parameters for the LUSI API call. Subclasses may extend or override this method.
+        # @param active_vle_space_only [Boolean, nil] if true, restrict results to active VLE spaces only
+        # @param asp_identity [String, nil] return instances matching the academically significant period (ASP) identity
+        # @param cohort_identity [String, nil] return instances matching the cohort identity
+        # @param course_identity [String, nil] return instances matching the course identity
+        # @param current_student_only [Boolean, nil] if true, restrict results to current students only
+        # @param department_identity [String, nil] return instances matching the department identity
+        # @param require_username [Boolean, nil] if true, include the student username, ignore students with no username
+        # @param year_identity (String, nil) return instances matching the year identity
+        # @return [Hash<String, String>] the parameters for the LUSI API call
+        def self.get_instance_params(**kwargs)
+          result = {
+            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, ''),
+            DepartmentIdentity: kwargs.fetch(:department_identity, ''),
+            RequireUsername: kwargs.fetch(:require_username, true) ? 'true' : 'false',
+            YearIdentity: kwargs.fetch(:year_identity, '')
+          }
+          if self.lusi_ws_endpoint == 'Student.asmx'
+            result[:CurrentStudentOnly] = kwargs.fetch(:current_student_only, true) ? 'true' : 'false'
+          end
+          result
+        end
+
+      end
+
+
+      class EnrolmentLookup
+
+        # Initialises a new EnrolmentLookup instance
+        def initialize(enrolments = nil, *indices, &block)
+          @default_proc = block
+          @indices = {}
+          enrolments.each { |e| add(e, *indices) }
+        end
+
+        # @see (LUSI::API::Enrolment::EnrolmentLookup#fetch)
+        def [](key, *indices)
+          fetch(key, *indices)
+        end
+
+        # Adds an enrolment to specified indices (default is all indices if unspecified)
+        # @param enrolment [LUSI::API::Enrolment::EnrolmentBase] the enrolment to add
+        # Reminaing positional parameters specify the indices to update
+        # @return [void]
+        def add(enrolment = nil, *indices)
+          indices = enrolment.lookup_indices if indices.nil? || indices.empty?
+          indices.each { |index| add_enrolment(enrolment, index) }
+          nil
+        end
+
+        # Searches the specified indices for the lookup key and returns the first match
+        # @param key [Object] the lookup key. If the key defines method #enrolment_lookup_keys, this method determines
+        #   which keys are searched for.
+        # Remaining positional parameters specify the indices to search. If no indices are specified, but the key
+        # instance defines method #enrolment_lookup_indices, this method determines which indices are searched.
+        # @return [Array<LUSI::API::Enrolment::EnrolmentBase>, nil] the enrolments corresponding to key, or nil
+        #   if match was found
+        def fetch(key = nil, *indices)
+
+          # If no index is specified, infer it from the key type if possible
+          if indices.nil? || indices.empty?
+            indices = key.respond_to?(:enrolment_lookup_indices) ? key.enrolment_lookup_indices : nil
+          end
+          return nil if indices.nil? || indices.empty?
+
+          # Use the lookup keys specified by the key instance if possible, otherwise use the literal key value
+          keys = key.respond_to?(:enrolment_lookup_keys) ? key.enrolment_lookup_keys : [key]
+
+          # Search the specified indices until a match is found, then return matches for all key values from this index
+          unless keys.nil? || keys.empty?
+            result = []
+            indices.each do |index|
+              i = @indices[index]
+              if i
+                keys.each { |key| result += i[key] || [] }
+              end
+              return result unless result.empty?
+            end
+          end
+
+          # If we get here, the search failed in all indices - call the default_proc if available, otherwise return nil
+          @default_proc ? @default_proc.call(key) : nil
+
+        end
+
+        protected
+
+        # Adds an enrolment to the specified index
+        # @param enrolment [LUSI::API::Enrolment::EnrolmentBase] the enrolment
+        # @param index [Symbol] the index to be updated
+        def add_enrolment(enrolment, index)
+          # Get the specified index hash
+          @indices[index] = {} unless @indices.include?(index)
+          hash = @indices[index]
+          # Add the enrolment to the list
+          key = enrolment.lookup_key(index)
+          if hash.include?(key)
+            hash[key].push(enrolment)
+          else
+            hash[key] = [enrolment]
+          end
+          # Return the list containing the enrolment
+          hash[key]
+        end
+
+      end
+
+
+    end
+  end
+end

data/lib/lusi_api/organisation.rb

@@ -0,0 +1,291 @@
+require 'lusi_api/core/xml'
+
+
+module LUSI
+  module API
+
+    # Classes representation organisation structure
+    module Organisation
+  
+      # Represents an organisation as a hierarchy of Units.
+      #
+      # The position in the hierarchy is defined by the Unit.type attribute.
+      #
+      # For each hierarchy level (Unit type) the Organisation maintains three indices, identified as follows:
+      #   :identity   allows retrieval by the Unit.identity attribute
+      #   :mnemonic   allows retrieval by the Unit.mnemonic attribute
+      #   :title      allows retrieval by the Unit.title attribute
+      #
+      # Once an instance is created, it should be populated by calling the #load method
+      # @example Populating an Organisation instance
+      #   api = LUSI::API::Core::API.new(...)
+      #   org = LUSI::API::Organisation::Organisation.new
+      #   begin
+      #     org.load(api, in_use_only: false)
+      #   rescue LUSI::API::Core::APIError => e
+      #     # API error handling
+      #   end
+      class Organisation
+  
+        # Defines the organisation hierarchy as a mapping from unit type to its child unit type and corresponding XPath.
+        # A leaf unit with no children maps to nil. The reserved unit type "_root" defines the root of the hierarchy.
+        HIERARCHY = {
+            _root: { type: :institution, path: '//xmlns:Institution' },
+            institution: { type: :faculty, path: 'xmlns:Faculties/xmlns:Faculty' },
+            faculty: { type: :department, path: 'xmlns:Departments/xmlns:Department' },
+            department: nil
+        }
+  
+        # Initialises a new Organisation instance
+        # @param api [LUSI::API::Core::API, nil] an optional LUSI API instance used to retrieve data
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @return [void]
+        def initialize(api = nil, lookup = nil)
+          @api = api
+          clear
+        end
+
+        # Searches the organisation top-down for the specified identity code and returns the first matching Unit
+        # @param identity [any] the identity code
+        # @return [Unit, nil] the matching Unit instance, or nil if no match is found
+        def [](identity = nil)
+          key = self.class.key(identity)
+          type = HIERARCHY[:_root][:type]
+          until type.nil? do
+            if @indices[type]
+              unit = @indices[type][:identity][key]
+              return unit if unit
+            end
+            type = HIERARCHY[type] ? HIERARCHY[type][:type] : nil
+          end
+          nil
+        end
+
+        # Adds a new Unit to the Organisation
+        # Child units are recursively added
+        # @param unit [LUSI::API::Organisation::Unit] the Unit instance
+        # @return void
+        def add(unit)
+  
+          # Require a Unit instance
+          return unless unit.is_a?(Unit)
+  
+          # Initialise the indices for this Unit type if required
+          @indices[unit.type] = { identity: {}, mnemonic: {}, title: {} } unless @indices.include?(unit.type)
+  
+          # Index the unit
+          hash = @indices[unit.type]
+          hash[:identity][self.class.key(unit.identity)] = unit
+          hash[:mnemonic][self.class.key(unit.mnemonic)] = unit
+          hash[:title][self.class.key(unit.title)] = unit
+  
+          # Index the unit's child units
+          unit.children.each { |child| add(child) } if unit.children
+  
+        end
+  
+        # Clears the organisation structure
+        # @return [void]
+        def clear
+          @indices = {}
+        end
+  
+        # Iterates over selected parts of the organisation hierarchy
+        # @param type [Symbol, nil] the Unit type to iterate over
+        # @param index [Symbol, nil] the Unit type's index to iterate over (:identity | :mnemonic | :title)
+        # @return [void]
+        # @yield Passes a Unit instance to the block
+        # @yieldparam unit [LUSI::API::Organisation::Unit] the current unit of the iterator
+        def each(type = nil, index = nil, &block)
+          if type
+            # Iterate over the selected type; ignore invalid types
+            hash = @indices[type]
+            if hash
+              hash_index = hash.include?(index) ? index : :identity
+              hash[hash_index].each_value(&block) if hash[hash_index]
+            end
+          else
+            # Iterate over all types
+            @indices.each_value do |type|
+              hash_index = type.include?(index) ? index : :identity
+              type[hash_index].each_value(&block) if type[hash_index]
+            end
+          end
+        end
+
+        # Iterates over each unit type in the organisation hierarchy starting from the root
+        # @return [void]
+        # @yield [unit_type] Passes the unit type to the block
+        # @yieldparam unit_type [Symbol] the current unit type of the iterator
+        def each_unit_type
+          unit_type = HIERARCHY[:_root][:type]
+          while unit_type
+            yield(unit_type)
+            unit_type = HIERARCHY[unit_type] ? HIERARCHY[unit_type][:type] : nil
+          end
+        end
+
+        # Indicates whether the organisation is empty (contains units) or not
+        # @return [Boolean] true if the organisation contains no units, otherwise false
+        def empty?
+          # If @indices is not empty, use the #length method to determine emptiness
+          @indices.nil? || @indices.empty? || length == 0
+        end
+
+        # Returns the Unit instance matching the given parameters
+        # Key values are case-insensitive and normalised by removing leading, trailing and redundant whitespace.
+        # Title matching is based on the exact title after key normalisation.
+        # @param key [any] the Unit attribute value to search for
+        # @param type [Symbol, nil] the Unit type to search for (defaults to the root type of the organisation hierarchy)
+        # @param index [Symbol, nil] the Unit index to search (:identity, :mnemonic, :title)
+        # @return [Unit, nil] the matching Unit instance, or nil if no matches are found
+        def get(key, type = nil, index: nil)
+          hash = @indices[type] || @indices[HIERARCHY[:_root][:type]]
+          if hash
+            index = :identity unless hash.include?(index)
+            hash[index][self.class.key(key)]
+          else
+            nil
+          end
+        end
+
+        # Returns the number of Units matching the given parameters
+        # @param type [Symbol, nil] the Unit type to count (defaults to all units)
+        # @param index [Symbol, nil] the Unit index to count (:identity, :mnemonic, :title)
+        # @return [Integer, nil] the number of Unit instances for the given parameters, or nil
+        def length(type = nil, index: nil)
+          count = 0
+          types = type.nil? ? @indices.keys : [type]
+          types.each do |unit_type|
+            hash = @indices[unit_type]
+            if hash
+              hash_index = hash.include?(index) ? hash[index] : hash[:identity]
+              count += hash_index.length if hash_index
+            end
+          end
+          count
+        end
+
+        # Populates the Organisation instance from the LUSI API
+        # @param api [LUSI::API::Core::API, nil] the LUSI API instance to use (defaults to the Organisation's @api)
+        # @param in_use_only [Boolean] if true, include only current Units; if false, additionally include historic Units
+        # @return [Nokogiri::XML::Node] the parsed XML <body/> content from the LUSI API call
+        def load(api = nil, in_use_only: true)
+
+          # Call the LUSI API
+          api ||= @api
+          xml = api.call('LUSIReference', 'General.asmx', 'GetOrganisationStructure', InUseOnly: in_use_only)
+
+          # Clear the existing organisation structure
+          clear
+
+          # Add each organisation unit to the structure
+          root = HIERARCHY[:_root]
+          LUSI::API::Core::XML.xml(xml, root[:path]) do |u|
+            add(Unit.new(u, type: root[:type], hierarchy: HIERARCHY))
+          end
+
+          # Return the parsed XML body content from the LUSI API call
+          xml
+
+        end
+  
+        protected
+  
+        # Returns a normalised index key
+        # Normalisation removes redundant whitespace and converts to uppercase for case-insensitivity
+        # @param key [any] the key value
+        # @return [String, nil] the normalised key value
+        def self.key(key)
+          return nil if key.nil?
+          key = key.to_s.strip
+          key.squeeze!(' ')
+          key.upcase!
+          key
+        end
+
+      end
+  
+  
+      # Represents a single unit (component) of an Organisation
+      class Unit
+  
+        # @!attribute [rw] children
+        #  @return [Array<Unit>, nil] an array of child Unit instances
+        attr_accessor :children
+        # @!attribute [rw] identity
+        #  @return [any, nil] the identity code of the unit
+        attr_accessor :identity
+        # @!attribute [rw] in_use
+        #   @return [Boolean, nil] true if the unit is currently in use, or false if historic
+        attr_accessor :in_use
+        # @!attribute [rw] is_academic
+        #   @return [Boolean, nil] true if the unit is an academic unit, or false if not (e.g. administrative)
+        attr_accessor :is_academic
+        # @!attribute [rw] mnemonic
+        #   @return [String, nil] a short mnemonic code for the unit
+        attr_accessor :mnemonic
+        # @!attribute [rw] parent
+        #   @return [Unit, nil] the parent of this unit in the organisation hierarchy, or nil if this is a top-level unit
+        attr_accessor :parent
+        # @!attribute [rw] talis_code
+        #   @return [String, nil] the code for this unit used by Talis Aspire reading lists
+        attr_accessor :talis_code
+        # @!attribute [rw] title
+        #   @return [String, nil] the title (name) of the unit
+        attr_accessor :title
+        # @!attribute [rw] type
+        #   @return [Symbol, nil] the type of the unit (e.g. :institution, :faculty, :department)
+        attr_accessor :type
+  
+        # Initialises a new Unit instance
+        # If the hierarchy definition for the unit type specifies child units, the child unit instances are recursively
+        # created and added to the @children attribute.
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the XML root of the unit from the LUSI API call
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param type [Symbol] the unit type
+        # @param hierarchy [Hash] the organisation's hierarchy definition
+        #   @see LUSI::API::Organisation::Organisation::HIERARCHY
+        # @param parent [Unit, nil] the parent Unit of this unit, or nil for a top-level unit
+        # @param identity [any, nil] the default identity code
+        # @param in_use [Boolean, nil] the default in-use flag value
+        # @param is_academic [Boolean, nil] the default is-academic flag value
+        # @param mnemonic [any, nil] the default mnemonic code
+        # @param talis_code [any, nil] the default Talis code
+        # @param title [any, nil] the default unit title (name)
+        def initialize(xml = nil, lookup = nil, type: nil, hierarchy: nil, parent: nil, identity: nil, in_use: nil,
+                       is_academic: nil, mnemonic: nil, talis_code: nil, title: nil)
+  
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @in_use = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:InUse', in_use)
+          @is_academic = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:IsAcademic', is_academic)
+          @mnemonic = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Mnemonic', mnemonic)
+          @parent = parent
+          @talis_code = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:TalisCode', talis_code)
+          @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
+          @type = type
+  
+          # Get the child units of this unit
+          # If a block is given, yield each child to the block
+          child = hierarchy ? hierarchy[type] : nil
+          if child
+            @children = LUSI::API::Core::XML.xml(xml, child[:path]) do |u|
+              Unit.new(u, lookup, type: child[:type], parent: self, hierarchy: hierarchy)
+            end
+          else
+            @children = nil
+          end
+  
+        end
+  
+        # Returns a string representation of the unit
+        def to_s
+          "#{@type}: #{@title}"
+        end
+  
+      end
+  
+    end
+  
+  end
+end