RubyGems - lusi_api - Versions diffs - 0.1.11 - Mend

lusi_api 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

checksums.yaml +7 -0
data/.gitignore +58 -0
data/Gemfile +4 -0
data/LICENSE.txt +21 -0
data/README.md +235 -0
data/Rakefile +8 -0
data/bin/console +14 -0
data/bin/setup +8 -0
data/lib/lusi_api.rb +5 -0
data/lib/lusi_api/calendar.rb +234 -0
data/lib/lusi_api/core/api.rb +190 -0
data/lib/lusi_api/core/code.rb +101 -0
data/lib/lusi_api/core/exceptions.rb +47 -0
data/lib/lusi_api/core/lookup.rb +612 -0
data/lib/lusi_api/core/util.rb +102 -0
data/lib/lusi_api/core/xml.rb +168 -0
data/lib/lusi_api/country.rb +111 -0
data/lib/lusi_api/course.rb +1300 -0
data/lib/lusi_api/enrolment.rb +247 -0
data/lib/lusi_api/organisation.rb +291 -0
data/lib/lusi_api/person/staff.rb +115 -0
data/lib/lusi_api/person/student.rb +551 -0
data/lib/lusi_api/service_account.rb +121 -0
data/lib/lusi_api/service_method.rb +52 -0
data/lib/lusi_api/version.rb +5 -0
data/lib/lusi_api/vle.rb +329 -0
data/lusi_api.gemspec +36 -0
metadata +182 -0

data/lib/lusi_api/core/api.rb ADDED

@@ -0,0 +1,190 @@
+require 'nokogiri'
+require 'rest-client'
+require 'lusi_api/core/exceptions'
+require 'lusi_api/service_account'
+module LUSI
+  module API
+    module Core
+      # Provides a wrapper for the LUSI web service API
+      class API
+        # Initializes a new API instance
+        # @param api_user [String] the service account username
+        # @param api_password [String] the service account password
+        # @param logger [Logger, nil] a Logger instance for optional logging
+        # @param timeout [Integer] the timeout in seconds for LUSI API calls
+        def initialize(api_user: nil, api_password: nil, api_root: nil, logger: nil, timeout: nil)
+          @api_password = api_password
+          @api_root = api_root || 'https://lusiservice.lancs.ac.uk'
+          @api_user = api_user
+          @logger = logger
+          @timeout = timeout.to_i
+        end
+        # Calls a LUSI API method and return the parsed XML response
+        # Any undocumented keyword parameters are passed as parameters to the LUSI API call. The LUSI 'Username' and
+        # 'Password' parameters are automatically added.
+        # @param path [String] the path of the API call (e.g. 'LUSIReference')
+        # @param endpoint [String] the endpoint of the API call (e.g. 'General.asmx')
+        # @param method [String] the method name of the API call (e.g. 'GetServiceAccountDetails')
+        # @param headers [Hash<String, String>] optional HTTP headers for the API call
+        # @param options [Hash<String, Object>] options for the REST client
+        # @return [Nokogiri::XML::Node] the parsed XML <body> content from the API response
+        # @raise [LUSIAPI::Core::APITimeoutError] if the LUSI API call times out
+        # @raise [LUSIAPI::Core::APICallError] if the LUSI API call fails for any other reason (e.g. network unavailable)
+        # @raise [LUSIAPI::Core::APIContentError] if the LUSI API call returns an XML document with an error response
+        def call(path, endpoint, method, headers: nil, options: nil, **params)
+          # Add the username and password to the params
+          params[:Username] ||= @api_user
+          params[:Password] ||= @api_password
+          # Set the REST client headers
+          rest_headers = {}.merge(headers || {})
+          # Set the REST client options
+          rest_options = {
+              method: :post,
+              headers: rest_headers,
+              payload: params,
+              url: url(path, endpoint, method),
+          }
+          rest_options[:timeout] = @timeout if @timeout > 0
+          rest_options.merge(options) if options
+          RestClient.log = @log if @log
+          # Make the API call
+          begin
+            response = RestClient::Request.execute(**rest_options)
+          rescue RestClient::Exceptions::Timeout => e
+            raise APITimeoutError.new(url: rest_options[:url])
+          rescue RestClient::Exception => e
+            raise APICallError.new(url: rest_options[:url])
+          rescue => e
+            raise APIError.new(url: rest_options[:url])
+          end
+          # Extract and return the XML content
+          xml(response)
+        end
+        # Return a ServiceAccount instance representing the API's service user
+        # @return [LUSI::API::ServiceAccount] the ServiceAccount instance representing the API's service user
+        def get_service_account_details
+          # There should only be one instance but get_instance returns an array for consistnecy with other classes
+          result = LUSI::API::ServiceAccount.get_instance(self)
+          result.length == 0 ? nil : result[0]
+        end
+        # Make a POST API call
+        # @see #call
+        alias post call
+        # Update the service user's password via the LUSI API
+        # @param password [String, nil] the new password (a random 16-character password is generated if this is omitted)
+        # @return [String] the new password
+        def update_service_account_password(password = nil)
+          @api_password = LUSI::API::ServiceAccount.update_service_account_password(self, password)
+        end
+        # Construct a full API method URL from its constituents
+        # @param path [String] the path of the API call (e.g. 'LUSIReference')
+        # @param endpoint [String] the endpoint of the API call (e.g. 'General.asmx')
+        # @param method [String] the method name of the API call (e.g. 'GetServiceAccountDetails')
+        # @return [String] the fully-qualified URL of the API method
+        def url(path = nil, endpoint = nil, method = nil)
+          "#{@api_root}/#{path}/#{endpoint}/#{method}"
+        end
+        protected
+        # Validate the XML response from an API call
+        # @param xml [Nokogiri::XML::Node] the parsed XML response
+        # @return [Nokogiri::XML::Node] the parsed <body> element of the XML response
+        # @raise [LUSI::API::Core::APIContentError] if the XML response indicates an error
+        def validate(xml)
+          header = LUSI::API::Core::XML.xml_at(xml, '//xmlns:Header')
+          status = LUSI::API::Core::XML.xml_content_at(header, 'xmlns:Status')
+          if status == 'Success'
+            # No errors, return the body content
+            LUSI::API::Core::XML.xml_at(xml, '//xmlns:Body')
+          else
+            # Errors present, raise APIContentError with the details
+            error = {
+              error_code: LUSI::API::Core::XML.xml_content_at(header, 'xmlns:ErrorCode'),
+              fault: LUSI::API::Core::XML.xml_content_at(header, 'xmlns:Fault'),
+              status: status
+            }
+            error_message = LUSI::API::Core::XML.xml_content_at(header, 'xmlns:ErrorMessage')
+            case error[:error_code]
+              when 'CLIENT004'
+                raise APIPermissionError.new(error_message, **error)
+              else
+                raise APIContentError.new(error_message, **error)
+            end
+          end
+        end
+        # Parse and validate the XML content from a LUSI API call
+        # @param response [String] the string-serialized XML response from the API
+        # @return [Nokogiri::XML::Document] the parsed <body> element of the XML response
+        # @raise [LUSIAPI::Core::APIContentError] if the XML parsing fails or the response indicates an error
+        def xml(response)
+          # Parse the HTTP response as XML
+          begin
+            xml = Nokogiri::XML(response.to_s)
+          rescue Nokogiri::SyntaxError => e
+            raise APIContentError('XML syntax error')
+          end
+          # Validate the XML and return the <body> element if successful
+          validate(xml)
+        end
+      end
+      # Mixin defining properties for a LUSI API endpoint URL, "extend LUSI::API::Core::Endpoint" to include as class
+      # methods
+      module Endpoint
+        # Returns the LUSI API endpoint
+        # @return [String] the LUSI API endpoint
+        def lusi_ws_endpoint
+          raise NotImplementedError
+        end
+        # Returns the LUSI API method
+        # @return [String] the LUSI API method
+        def lusi_ws_method
+          raise NotImplementedError
+        end
+        # Returns the LUSI API URL path
+        # @return [String] the LUSI API URL path
+        def lusi_ws_path
+          raise NotImplementedError
+        end
+        # Returns the root element name of the LUSI API XML response
+        # @return [String] the root XML element name
+        def lusi_ws_xml_root
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/lusi_api/core/code.rb ADDED

@@ -0,0 +1,101 @@
+require 'lusi_api/core/xml'
+module LUSI
+  module API
+    module Core
+      # Represents a LUSI code definition (identity code and text description)
+      class BasicCode
+        # @!attribute [rw] description
+        #   @return [any, nil] the text description
+        attr_accessor :description
+        # @!attribute [rw] identity
+        #   @return [any, nil] the identity code
+        attr_accessor :identity
+        # Initialises a new Code instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the XML root of the code from the LUSI API
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param identity [any, nil] the default identity code
+        # @param description [String, nil] the default text description
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, identity: nil, description: nil)
+          @description = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Description', description)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+        end
+        # Returns a string representation of the code
+        # @return [String, nil] the string representation (text description)
+        def to_s
+          @description
+        end
+        # Default get_instance implementation
+        # - Instances cannot be retrieved through the LUSI API
+        def self.get_instance(*args, **kwargs)
+          raise NotImplementedError
+        end
+        # Default get_instance_params implementation
+        # - Instances cannot be retrieved through the LUSI API
+        protected
+        def self.get_instance_params(*args, **kwargs)
+          {}
+        end
+      end
+      # Represents a LUSI code definition which can be retrieved through the LUSI API
+      class Code < BasicCode
+        # Returns a Code instance for the specifiec LUSI API call
+        # @param api [LUSI:API::Core::API] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param path [String] the LUSI API URL path
+        # @param endpoint [String] the LUSI API URL endpoint
+        # @param method [String] the LUSI API method
+        # @param xml_root [String] the XPath of the root element in the LUSI API response
+        # @param identity [any] the identity to search for
+        # @param description [String, nil] the description to search for
+        # @return [Array<LUSI::API::Core::Code>] the matching Code instances
+        # @yield [obj] Passes the Code instance to the block
+        # @yieldparam obj [LUSI::API::Core::Code] the Code instance
+        def self.get_instance(api = nil, lookup = nil, path = nil, endpoint = nil, method = nil, xml_root = nil, **kwargs)
+          params = get_instance_params(**kwargs)
+          xml = api.call(path, endpoint, method, **params)
+          LUSI::API::Core::XML.xml(xml, xml_root) do |c|
+            obj = new(c, lookup)
+            begin
+              yield(obj) if block_given?
+            rescue StandardError => e
+              puts e
+            end
+            obj
+          end
+        end
+        protected
+        # Returns a hash of parameters for the LUSI API call
+        # @param identity [any, nil] the identity code
+        # @param description [String. nil] the description
+        # @return [Hash<String, any>] the parameter hash for the LUSI API call
+        def self.get_instance_params(**kwargs)
+          {
+            Identity: kwargs[:identity] || '',
+            Description: kwargs[:description] || ''
+          }
+        end
+      end
+    end
+  end
+end

data/lib/lusi_api/core/exceptions.rb ADDED

@@ -0,0 +1,47 @@
+module LUSI
+  module API
+    module Core
+      # The root of the LUSI API exception hierarchy
+      class APIError < StandardError
+        def initialize(message = nil, url: nil)
+          super(message || 'LUSI API error')
+          @url = url
+        end
+      end
+      # Indicates an error with the LUSI API call (e.g. network error)
+      class APICallError < APIError; end
+      # Indicates a LUSI API timeout error
+      class APITimeoutError < APICallError; end
+      # Indicates a successful LUSI API call which returned invalid XML or a document containing an error header
+      class APIResponseError < APIError
+        def initialize(message = nil, status: nil, fault: nil, error_code: nil, **kwargs)
+          super(message, **kwargs)
+          @error_code = error_code
+          @fault = fault
+          @status = status
+        end
+      end
+      # Indicates an invalid response from the LUSI API
+      class APIContentError < APIResponseError; end
+      # Indicates a LUSI API permission-denied error
+      class APIPermissionError < APIResponseError; end
+    end
+  end
+end

data/lib/lusi_api/core/lookup.rb ADDED

@@ -0,0 +1,612 @@
+require 'lusi_api/core/code'
+require 'lusi_api/core/exceptions'
+require 'lusi_api/calendar'
+require 'lusi_api/country'
+require 'lusi_api/organisation'
+require 'lusi_api/person/staff'
+module LUSI
+  module API
+    module Core
+      module Lookup
+        # The root of the lookup exception hierarchy
+        class LookupError < ::LUSI::API::Core::APIError
+          # @!attribute [rw] key
+          #   @return [any] the key which triggered the lookup error
+          attr_accessor :key
+          # Initialises a new LookupError instance
+          # @param key [any] the key which triggered the lookup error
+          # @return [void]
+          def initialize(*args, key: nil)
+            super(*args)
+            @key = key
+          end
+        end
+        # Implements a caching lookup table
+        class LookupTable < Hash
+          # Initialises a new LookupTable instance
+          # @param (see Hash)
+          # @return [void]
+          def initialize(*args, &block)
+            # Initialise the superclass
+            super(*args)
+            # Define a default proc to look up and cache missing keys
+            # Note that if a hash has a default value set, this is lost (reset to nil) when a default_proc is set,
+            # so we preserve the default value here to use in the proc.
+            default_value = default
+            self.default_proc = Proc.new do |hash, key|
+              begin
+                # If the lookup succeeds, add the value to the hash and return the value.
+                self[key] = get_value(key)
+              rescue LookupError => e
+                # Lookup failed
+                if block
+                  # Call the block passed by the caller
+                  block.call(hash, key)
+                else
+                  # Return the default value for the hash
+                  default_value
+                end
+              end
+            end
+          end
+          # Retrieves the value for a key from some data source
+          # @param key [any] the key to search for
+          # @return [any] the corresponding value
+          # @raise [LookupError] if the data source lookup fails
+          def get_value(key)
+            raise LookupError.new(key)
+          end
+        end
+        # A caching lookup table which retrieves values from the LUSI API
+        class LUSILookupTable < LookupTable
+          # @!attribute [rw] api
+          #   @return [LUSI::API::Core::API, nil] the LUSI API instance to use for lookups
+          attr_accessor :api
+          # Initialises a new LUSILookupTable instance
+          # @param api [LUSI::API::Core::API] the LUSI API instance to use
+          # @param result_class [Class] the class to instantiate from the LUSI API XML response
+          # @param key_attribute [Proc, String, Symbol, nil] an extractor to return the key attribute from the instance
+          #   If a Proc is supplied, it will be called with the instance as the sole parameter.
+          #   If a String or Symbol are supplied, the named attribute will be returned from the instance
+          #   If nil or no extractor is supplied, the attribute 'identity' will be returned if it exists.
+          #   @raise [NameError] if the specified attribute cannot be found
+          # @param loadable [Boolean, nil] if true, the lookup table is populated from a single API call; otherwise
+          #   the lookup table is populated by individual API calls each time a key lookup fails
+          # @param param [String, nil] the LUSI API parameter to use for the key lookup
+          # @param load_params [Hash<String, any>, nil] default LUSI API parameters passed to the load call
+          # Other positional and keyword parameters are passed to the result class' #get_instance method
+          # @return [void]
+          def initialize(api = nil, result_class = nil, *args, key_attribute: nil, loadable: nil, param: nil,
+                         load_params: nil, **kwargs, &block)
+            super(block)
+            key_attribute = :identity if key_attribute.nil?
+            if key_attribute.is_a? Proc
+              @key_attribute = key_attribute
+            else
+              @key_attribute = Proc.new { |obj| obj.nil? ? nil : obj.instance_variable_get("@#{key_attribute}") }
+            end
+            @api = api
+            @args = args || []
+            @kwargs = kwargs || {}
+            @load_params = load_params
+            @loadable = loadable ? true : false
+            @param = param
+            @result_class = result_class
+          end
+          # Retrieves the object corresponding to the key from the LUSI API and instantiates a result from the XML
+          # @param key [any] the key to search
+          # @return [any] an instance of the result_class for the matching object
+          def get_value(key)
+            # A loadable lookup table is populated with a single API call, so do regular key lookup
+            raise LookupError.new('lookup table is loadable') if @loadable
+            # For non-loadable lookup tables, call the LUSI API to get the key value and create a corresponding instance
+            xml = @api.call(@path, @endpoint, @method, { @param => key })
+            result_class.new(xml, xml_root)
+          end
+          # Retrieves all objects from the LUSI API and adds them to the lookup table
+          # @param clear [Boolean, nil] if true, clear the lookup table before loading
+          # @param lookup [LUSI::API::Core::Lookup::LookupService] the lookup service for object resolution
+          # @return [Boolean] true if the lookup table was loaded, false if it is not loadable
+          def load(clear = false, lookup = nil, **params)
+            # Bail out if this lookup table isn't loadable
+            return false unless @loadable
+            # Set up the LUSI API call parameters
+            params ||= @load_params || {}
+            # Clear the lookup table before loading if required
+            self.clear if clear
+            # Call the LUSI API
+            # - do not use the lookup service to resolve result_class instances
+            #xml = @api.call(@path, @endpoint, @method, **params)
+            #xml.xpath(@xml_root) do |x|
+            params.merge(@kwargs)
+            @result_class.get_instance(@api, lookup, *@args, use_lookup: false, **params) do |obj|
+              # Get the lookup key from the instance and add the instance to the hash
+              begin
+                key = @key_attribute.call(obj)
+                self[key] = obj
+              rescue NameError => e
+                # ?
+              end
+            end
+            # Return true to indicate successful loading
+            true
+          end
+        end
+        class LUSILookupTable < LookupTable
+          # @!attribute [rw] api
+          #   @return [LUSI::API::Core::API, nil] the LUSI API instance to use for lookups
+          attr_accessor :api
+          # Initialises a new LUSILookupTable instance
+          # @param api [LUSI::API::Core::API] the LUSI API instance to use
+          # @param result_class [Class] the class to instantiate from the LUSI API XML response
+          # @param key_attribute [Proc, String, Symbol, nil] an extractor to return the key attribute from the instance
+          #   If a Proc is supplied, it will be called with the instance as the sole parameter.
+          #   If a String or Symbol are supplied, the named attribute will be returned from the instance
+          #   If nil or no extractor is supplied, the attribute 'identity' will be returned if it exists.
+          #   @raise [NameError] if the specified attribute cannot be found
+          # @param loadable [Boolean, nil] if true, the lookup table is populated from a single API call; otherwise
+          #   the lookup table is populated by individual API calls each time a key lookup fails
+          # @param param [String, nil] the LUSI API parameter to use for the key lookup
+          # @param load_params [Hash<String, any>, nil] default LUSI API parameters passed to the load call
+          # Other positional and keyword parameters are passed to the result class' #get_instance method
+          # @return [void]
+          def initialize(api = nil, result_class = nil, *args, key_attribute: nil, loadable: nil, param: nil,
+                         load_params: nil, **kwargs, &block)
+            super(block)
+            key_attribute = :identity if key_attribute.nil?
+            if key_attribute.is_a? Proc
+              @key_attribute = key_attribute
+            else
+              @key_attribute = Proc.new { |obj| obj.nil? ? nil : obj.instance_variable_get("@#{key_attribute}") }
+            end
+            @api = api
+            @args = args || []
+            @kwargs = kwargs || {}
+            @load_params = load_params
+            @loadable = loadable ? true : false
+            @param = param
+            @result_class = result_class
+          end
+          # Retrieves the object corresponding to the key from the LUSI API and instantiates a result from the XML
+          # @param key [any] the key to search
+          # @return [any] an instance of the result_class for the matching object
+          def get_value(key)
+            # A loadable lookup table is populated with a single API call, so do regular key lookup
+            raise LookupError.new('lookup table is loadable') if @loadable
+            # For non-loadable lookup tables, call the LUSI API to get the key value and create a corresponding instance
+            xml = @api.call(@path, @endpoint, @method, { @param => key })
+            result_class.new(xml, xml_root)
+          end
+          # Retrieves all objects from the LUSI API and adds them to the lookup table
+          # @param clear [Boolean, nil] if true, clear the lookup table before loading
+          # @param lookup [LUSI::API::Core::Lookup::LookupService] the lookup service for object resolution
+          # @return [Boolean] true if the lookup table was loaded, false if it is not loadable
+          def load(clear = false, lookup = nil, **params)
+            # Bail out if this lookup table isn't loadable
+            return false unless @loadable
+            # Set up the LUSI API call parameters
+            params ||= @load_params || {}
+            # Clear the lookup table before loading if required
+            self.clear if clear
+            # Call the LUSI API
+            # - do not use the lookup service to resolve result_class instances
+            #xml = @api.call(@path, @endpoint, @method, **params)
+            #xml.xpath(@xml_root) do |x|
+            params.merge(@kwargs)
+            @result_class.get_instance(@api, lookup, *@args, use_lookup: false, **params) do |obj|
+              # Get the lookup key from the instance and add the instance to the hash
+              begin
+                key = @key_attribute.call(obj)
+                self[key] = obj
+              rescue NameError => e
+                # ?
+              end
+            end
+            # Return true to indicate successful loading
+            true
+          end
+        end
+        # Collects a number of lookup tables into a single service
+        class LookupService
+          # Configuration for lookup services
+          # The structure is:
+          # {
+          #   service: {
+          #       available: include this service in the list of available services if true
+          #       class: the LUSI API class returned by the lookup table (default: LUSI::API::Core::Code)
+          #       create: create method name
+          #       creates: the list of services created by this service
+          #       depends: the list of services this service depends on
+          #       load: load method name
+          #       params: the LUSI API class #get_instance parameters
+          #   }
+          # }
+          #
+          # The available option, if specifies, dictates whether the service is included in the list of available
+          # services. The default is true.
+          #
+          # The class option, if specified, is the Class instance of the object class stored in the lookup table.
+          # If no class is specified, the default is LUSI::API::Core::Code
+          #
+          # The create option, if specified, is a symbol (method name on the LookupService instance) or callable.
+          # The create method should accept an arbitrary parameter list (method(*params)) and return a configured
+          # lookup table instance or functional equivalent.
+          # If no create method is specified, the default is to create a LookupTable instance as follows:
+          #   LUSILookupTable.new(@api, *params, loadable: true)
+          # where params is the list from the params option (see below)
+          #
+          # The creates option, if specified, is a list of services created by this service. This allows a single
+          # service definition to create multiple related lookup services which can be iterated in the list of
+          # available services.
+          #
+          # The depends option, if specified, specifies a list of lookup services on which the current lookup service
+          # depends. These services are automatically loaded before the current lookup service.
+          #
+          # The load option, if specified, is a symbol (method name on the LookupService instance) or callable.
+          # The load method should accepts two parameters:
+          # If no load method is specified, the default is to call the lookup table's load method.
+          #
+          # The params option specifies the parameters to the create method or LookupTable constructor as a list:
+          #   [ lusi-api-url-path, lusi-api-endpoint, lusi-api-method, xml-root, result-class ]
+          #
+          #
+          SERVICES = {
+              absence_reason: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetAbsenceReasons', 'xmlns:AbsenceReason']
+              },
+              address_country: {
+                  class: LUSI::API::Country::AddressCountry,
+              },
+              event_contact_type: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetEventContactTypes', 'xmlns:EventContactType']
+              },
+              leave_reason: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetLeaveReasons', 'xmlns:LeaveReason']
+              },
+              location_of_tuition: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetLocationsOfTuition', 'xmlns:LocationOfTuition']
+              },
+              nationality: {
+                  class: LUSI::API::Country::Nationality
+              },
+              organisation: {
+                  available: false,
+                  create: :create_organisation,
+                  creates: [:department, :faculty, :institution]
+              },
+              staff_course_role: {
+                  class: LUSI::API::Person::StaffCourseRole
+              },
+              staff_relationship: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetStaffRelationships', 'xmlns:StaffRelationship']
+              },
+              student_category: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetStudentCategories', 'xmlns:StudentCategory']
+              },
+              subject_area: {
+                  params: ['LUSIReference', 'Lookup.asmx', 'GetSubjectAreas', 'xmlns:SubjectArea']
+              },
+              week: {
+                  class: LUSI::API::Calendar::Week,
+                  depends: [:year],
+                  load: :load_weeks
+              },
+              year: {
+                  class: LUSI::API::Calendar::Year
+              }
+          }
+          # The list of available services - built lazily
+          @@services = nil
+          # Initialises a new LookupService instance
+          # @param api [LUSI::API::Core::API] the LUSI API instance
+          # @param (see #load)
+          # @return [void]
+          def initialize(api = nil, **services)
+            @api = api
+            clear
+            load(**services) unless services.nil? || services.empty?
+          end
+          # Clears all lookup tables from the LookupService instance
+          def clear
+            @lookups = {}
+            @organisation = nil
+          end
+          # Iterates over each lookup table
+          # @yield [service, lookup_table] passes the service name and corresponding lookup table to the block
+          # @yieldparam service [Symbol] the service name
+          # @yieldparam lookup [LUSI::API::Core::Lookup::LookupTable] the lookup table for the service
+          # @yieldreturn [void]
+          def each
+            @lookups.each { |service, lookup| yield(service, lookup) }
+          end
+          # Returns true if all specified services are defined
+          # Parameters are the service names to be checked
+          # @return [Boolean] true if all services are definied, false if any service is undefined
+          def has?(*services)
+            services.each { |service| return false unless @lookups.include?(service) }
+            true
+          end
+          # Returns the number of configured lookup tables
+          # @param service [Symbol, nil] the service to check
+          #   if present, return the number of entries in the specified lookup table, otherwise return the number of
+          #   lookup tables
+          # @return [Integer] the number of configured lookup tables (if service is unspecified) or the number of
+          #   entries in the specified lookup table. If an invalid service is specified, 0 is returned.
+          def length(service = nil)
+            if service
+              lookup = @lookups[service]
+              lookup ? lookup.length : 0
+            else
+              @lookups.length
+            end
+          end
+          # Loads specified lookup services, or all services if none are specified.
+          # Each named parameter specifies a configuration for the lookup service: service: config
+          # False parameter values cause that service to be ignored.
+          # @return [void]
+          def load(**services)
+            # If no services are specified, load all services with default configuration
+            if services.nil? || services.empty?
+              services = {}
+              SERVICES.each_key { |key| services[key] = true }
+            end
+            # Create the services
+            services.each do |service, config|
+              # Ignore invalid and unconfigured services
+              create_lookup_service(service, config, services) if config && SERVICES.has_key?(service)
+            end
+          end
+          # Fetches a key from the specified lookup table
+          # @param service [Symbol] the lookup table to use
+          # @param key [any] the key to search for
+          # @param default [any] the default value if the lookup fails
+          # @return [Object] the value corresponding to the key
+          def lookup(service, key, default = nil)
+            lookup_method = get_callable(service, :lookup)
+            if lookup_method
+              lookup_method.call(service, key, default)
+            else
+              lookup = @lookups[service]
+              if lookup.is_a?(Hash)
+                lookup[key]
+              elsif lookup.is_a?(Method) || lookup.is_a?(Proc)
+                lookup.call(service, key, default)
+              else
+                default
+              end
+            end
+          end
+          # Returns the specified lookup table
+          # @param service [Symbol] the lookup table to return
+          # @return [LUSI::API::Core::Lookup::LookupTable] the lookup table
+          def service(service)
+            @lookups[service]
+          end
+          # Returns a list of configured services
+          # @param all [Boolean] if true, returns all available services; if false, returns only configured services
+          # @yield [service] Passes the service name to the block
+          # @yieldparam service [Symbol] the service name
+          def services(all = false)
+            if all
+              # Return all services defined in SERVICES
+              return @@services if @@services
+              @@services = []
+              SERVICES.each do |service, config|
+                if config.fetch(:available, true)
+                  @@services.push(service)
+                  yield(service) if block_given?
+                end
+                config.fetch(:creates, []).each do |created|
+                  @@services.push(created)
+                  yield(created) if block_given?
+                end
+              end
+              @@services
+            else
+              # Return all services configured in @lookups
+              result = @lookups.keys
+              result.each { |service| yield(service) } if block_given?
+              result
+            end
+          end
+          protected
+          # Creates a lookup service
+          # - the create method is responsible for loading the table
+          # @param service [Symbol] the lookup service being created
+          # @param config [any] the lookup service configuration
+          # @param services [Hash<Symbol, any>] the configuration hash for all lookup services
+          # @return [void]
+          def create_lookup_service(service, config, services)
+            create_method = get_callable(service, :create)
+            params = SERVICES[service][:params] || []
+            if create_method
+              lookup = create_method.call(service, config, services, *params)
+            else
+              lookup = create_lookup(service, config, services, *params)
+            end
+          end
+          # Creates a lookup table
+          # @param service [Symbol] the lookup service being created
+          # @param config [any] the lookup service configuration
+          # @param services [Hash<Symbol, any>] the configuration hash for all lookup services
+          # params is the list of parameters from the service definition in SERVICES
+          # @return [void]
+          def create_lookup(service, config, services, *params)
+            # Create the lookup table
+            result_class = SERVICES[service].fetch(:class, LUSI::API::Core::Code)
+            lookup = LUSILookupTable.new(@api, result_class, *params, loadable: true)
+            # Load the lookup table
+            begin
+              # Load dependencies
+              load_dependencies(service, services) if SERVICES[service][:depends]
+              # Load the table
+              load_lookup(service, config, lookup)
+              # Add the lookup table to the service if successful
+              @lookups[service] = lookup
+            rescue APIPermissionError => e
+              puts("Permission denied for #{service}")
+            end
+          end
+          # Creates organisation lookups
+          #
+          # @param service [Symbol] the lookup service being created
+          # @param config [any] the lookup service configuration
+          # @param services [Hash<Symbol, any>] the configuration hash for all lookup services
+          # params is the list of parameters from the service definition in SERVICES
+          # @return [void]
+          def create_organisation(service, config, services, *params)
+            # Create and load the organisation structure
+            @organisation = LUSI::API::Organisation::Organisation.new
+            @organisation.load(@api)
+            # Create lookups for each level of the organisation
+            @organisation.each_unit_type do |unit_type|
+              @lookups[unit_type] = Proc.new do |service, key, default|
+                @organisation.get(key, unit_type)
+              end
+            end
+          end
+          # Gets a method or proc of the LookupService instance
+          # @param service [Symbol] the lookup service
+          # @param type [Symbol] the type of method (:create | :load | :lookup)
+          # @return [Method, Proc] the corresponding method or proc, or nil if no method is found or an invalid
+          #   parameter is passed
+          def get_callable(service, type)
+            callable = SERVICES[service] ? SERVICES[service][type] : nil
+            case
+              when callable.nil?
+                nil
+              when callable.is_a?(Symbol) || callable.is_a?(String)
+                # callable refers to a method on this LookupService instance
+                method(callable.to_sym)
+              when callable.is_a?(Method) || callable.is_a?(Proc)
+                # callable is already a callable object
+                callable
+              else
+                nil
+            end
+          end
+          # Loads service dependencies
+          # @param service [Symbol] the lookup service being configured
+          # @param services [Hash<Symbol, any>] the configuration hash for all lookup services
+          # @return [void]
+          def load_dependencies(service, services)
+            depends = SERVICES[service][:depends]
+            depends.each do |depend|
+              # Skip if the dependency already exists
+              continue if @lookups[depend]
+              # Get the config for the dependency, or use the default configuration if unspecified
+              config = services[depend] || true
+              # Create the lookup service if it doesn't already exist
+              create_lookup_service(depend, config, services)
+            end
+          end
+          # Loads a lookup table
+          # @param service [Symbol] the lookup service being configured
+          # @param config [any] the lookup service configuration
+          # @param lookup [LUSILookupTable] the lookup table to be loaded
+          # @return [LUSILookupTable] the lookup table
+          def load_lookup(service, config, lookup)
+            load_method = get_callable(service, :load)
+            if load_method
+              # Call the specified load method
+              load_method.call(service, config, lookup)
+            else
+              # Call the lookup table's load method
+              # - pass this LookupService as the lookup service for object resolution
+              lookup.load(false, self)
+            end
+            lookup
+          end
+          # Loads the academic weeks lookup table
+          # @param service [Symbol] the lookup service
+          # @param config [Array<String>] the list of year identity codes to load weeks for (default is all available weeks)
+          # @param lookup [LUSILookupTable] the lookup table being loaded
+          # @return [LUSILookupTable] the lookup table
+          def load_weeks(service, config, lookup)
+            if config.is_a?(Array) && !config.empty?
+              # Load weeks for each specified year (note: clear = false to accumulate results)
+              config.each { |year_identity| lookup.load(false, self, year_identity: year_identity) }
+            elsif config
+              # Load all weeks
+              lookup.load(false, self)
+            end
+            lookup
+          end
+        end
+      end
+    end
+  end
+end