lusi_api 0.1.11

data/lib/lusi_api/person/staff.rb

@@ -0,0 +1,115 @@
+require 'lusi_api/core/code'
+require 'lusi_api/core/xml'
+
+
+module LUSI
+  module API
+    module Person
+
+
+      # Represents a staff course role in the LUSI API
+      class StaffCourseRole < LUSI::API::Core::Code
+
+        # @!attribute [rw] vle_role_description
+        #   @return [String, nil] the VLE role description
+        attr_accessor :vle_role_description
+
+        # Returns an instance of StaffCourseRole matching the specified parameters
+        # @param api [LUSI::API::Core::API, nil] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param (see LUSI::API::Core::Code#get_instance)
+        # @return [Array<LUSI::API::Person::StaffCourseRole>, nil]
+        def self.get_instance(api = nil, lookup = nil, **kwargs)
+          super(api, lookup, 'LUSIReference', 'Lookup.asmx', 'GetStaffCourseRoles', 'xmlns:StaffCourseRole',
+                result_class: StaffCourseRole, **kwargs)
+        end
+
+        # Initialises a new StaffCourseRole 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
+
+
+      # Represents a staff member in the LUSI API
+      class StaffMember
+
+        # @!attribute [rw] identity
+        #   @return [String, nil] the identity code of the staff member
+        attr_accessor :identity
+
+        # @!attribute [rw] title
+        #   @return [String, nil] the title (honourific) of the staff member
+        attr_accessor :title
+
+        # @!attribute [rw] surname
+        #   @return [String, nil] the surname of the staff member
+        attr_accessor :surname
+
+        # @!attribute [rw] forename
+        #   @return [String, nil] the forename of the staff member
+        attr_accessor :forename
+
+        # @!attribute [rw] preferred_name
+        #   @return [String, nil] the preferred name of the staff member
+        attr_accessor :preferred_name
+
+        # @!attribute [rw] department
+        #   @return [LUSI::API::Organisation::Unit, nil] the staff member's associated department
+        attr_accessor :department
+
+        # @!attribute [rw] faculty
+        #   @return [LUSI::API::Organisation::Unit, nil] the staff member's associated faculty
+        attr_accessor :faculty
+
+        # @!attribute [rw] institution
+        #   @return [LUSI::API::Organisation::Unit, nil] the staff member's associated institution
+        attr_accessor :institution
+
+        # Initialises a new StaffMember instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the staff member
+        # @param lookup [LUSI::API::Core::LookupTable, nil] the lookup service for organisation unit resolution
+        # @param department [LUSI::API::Organisation::Unit, nil] the default department
+        # @param faculty [LUSI::API::Organisation::Unit, nil] the default faculty
+        # @param forename [String, nil] the default forename
+        # @param identity [String, nil] the default identity code
+        # @param institution [LUSI::API::Organisation::Unit, nil] the default institution
+        # @param preferred_name [String, nil] the default preferred name
+        # @param surname [String, nil] the default surname
+        # @param title [String, nil] the default title (honourific)
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, department: nil, faculty: nil, forename: nil, identity: nil,
+                       institution: nil, preferred_name: nil, surname: nil, title: nil)
+          @department = LUSI::API::Core::XML.lookup(xml, lookup, :department, 'xmlns:Department/xmlns:Identity',
+                                                    department)
+          @faculty = LUSI::API::Core::XML.lookup(xml, lookup, :faculty, 'xmlns:Faculty/xmlns:Identity', faculty)
+          @forename = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Forename', forename)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @institution = LUSI::API::Core::XML.lookup(xml, lookup, :institution, 'xmlns:Institution/xmlns:Identity',
+                                                     institution)
+          @preferred_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PreferredName', preferred_name)
+          @surname = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Surname', surname)
+          @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
+        end
+
+        # Returns a string representation of the staff member (full name)
+        # @return [String] the string representation of the staff member (full name)
+        def to_s
+          str = "#{@title} #{@forename} #{@surname}"
+          str.strip!
+          str.squeeze!(' ')
+          str
+        end
+
+      end
+
+
+    end
+  end
+end

data/lib/lusi_api/person/student.rb

@@ -0,0 +1,551 @@
+require 'date'
+
+require 'lusi_api/core/api'
+require 'lusi_api/core/xml'
+require 'lusi_api/country'
+require 'lusi_api/course'
+require 'lusi_api/organisation'
+
+
+module LUSI
+  module API
+    module Person
+
+
+      # Represents a student's leaving details in the LUSI API
+      class LeaveDetails
+
+        # @!attribute [rw] last_attend_date
+        #   @return [DateTime, nil] the date of last attendance
+        attr_accessor :last_attend_date
+
+        # @!attribute [rw] leave_date
+        #   @return [DateTime, nil] the date of leaving
+        attr_accessor :leave_date
+
+        # @!attribute [rw] leave_reason
+        #   @return [LUSI::API::Core::Code, nil] the reason for leaving
+        attr_accessor :leave_reason
+
+        # Initialises a new LeaveDetails instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the leave details
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param last_attend_date [DateTime, nil] the default date of last attendance
+        # @param leave_date [DateTime, nil] the default leave date
+        # @param leave_reason [LUSI::API::Core::Code, nil] the reason for leaving
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, last_attend_date: nil, leave_date: nil, leave_reason: nil)
+          @leave_reason = LUSI::API::Core::Code.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:LeaveReason'), lookup)
+          @leave_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:LeaveDate')
+          @last_attend_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:LastAttendDate')
+        end
+
+        # Returns a string representation of the LeaveDetails instance
+        # @return [String] the string representation of the LeaveDetails instance
+        def to_s
+          @leave_reason.to_s
+        end
+
+      end
+
+
+      # Represents a person's postal address
+      class PersonAddress
+
+        # @!attribute [rw] address_type
+        #   @return [String, nil] the address type (e.g. 'Termtime Address')
+        attr_accessor :address_type
+
+        # @!attribute [rw] address_line_1
+        #   @return [String, nil] the first address line
+        attr_accessor :address_line_1
+
+        # @!attribute [rw] address_line_2
+        #   @return [String, nil] the second address line
+        attr_accessor :address_line_2
+
+        # @!attribute [rw] address_line_3
+        #   @return [String, nil] the third address line
+        attr_accessor :address_line_3
+
+        # @!attribute [rw] address_line_4
+        #   @return [String, nil] the fourth address line
+        attr_accessor :address_line_4
+
+        # @!attribute [rw] address_line_5
+        #   @return [String, nil] the fifth address line
+        attr_accessor :address_line_5
+
+        # @!attribute [rw] post_code
+        #   @return [String, nil] the postal or zip code
+        attr_accessor :post_code
+
+        # @!attribute [rw] country
+        #   @return [LUSI::API::Person::AddressCountry, nil] the country
+        attr_accessor :country
+
+        # Initialises a PersonAddress instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the address
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param address_type [String, nil] the default address type
+        # @param address_line_1 [String, nil] the default first address line
+        # @param address_line_2 [String, nil] the default second address line
+        # @param address_line_3 [String, nil] the default third address line
+        # @param address_line_4 [String, nil] the default fourth address line
+        # @param address_line_5 [String, nil] the default fifth address line
+        # @param post_code [String, nil] the default postal or zip code
+        # @param country [LUSI::API::Country::AddressCountry, nil] the default country
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, address_type: nil, address_line_1: nil, address_line_2: nil,
+                       address_line_3: nil, address_line_4: nil, address_line_5: nil, post_code: nil, country: nil)
+          @address_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressType', address_type)
+          @address_line_1 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine1', address_line_1)
+          @address_line_2 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine2', address_line_2)
+          @address_line_3 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine3', address_line_3)
+          @address_line_4 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine4', address_line_4)
+          @address_line_5 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine5', address_line_5)
+          @post_code = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PostCode', post_code)
+          @country = LUSI::API::Core::XML.lookup(xml, lookup, :address_country, 'xmlns:Country/xmlns:Identity', country)
+        end
+
+        # Returns a string representation of the PersonAddress instance
+        # @return [String] the string representation of the PersonAddress instance
+        def to_s(sep = nil)
+          sep ||= ', '
+          fields = []
+          [@address_type, @address_line_1, @address_line_2, @address_line_3, @address_line_4, @address_line_5,
+           @post_code, @country].each do |field|
+            field_s = field.to_s
+            fields.push(field_s) unless field_s.nil? || field_s.empty?
+          end
+          fields.join(sep)
+        end
+
+      end
+
+
+      # Holds a person's combined contact details (postal addresses, email addresses, phone numbers)
+      class ContactDetail
+
+        # @!attribute [rw] addresses
+        #   @return [Array<PersonAddress>, nil] postal addresses as an array of PersonAddress instances
+        attr_accessor :addresses
+
+        # @!attribute [rw] personal_email_address
+        #   @return [Array<String>, nil] an array of personal email addresses
+        attr_accessor :personal_email_address
+
+        # @!attribute [rw] lancaster_email_address
+        #   @return [Array<String>, nil] and array of institutional email addresses
+        attr_accessor :institutional_email_address
+
+        # !@attribute [rw] mobile_phone_number
+        #   @return [String, nil] mobile phone number
+        attr_accessor :mobile_phone_number
+
+        # @see institutional_email_address an alias for institutional_email_address for consistency with the LUSI API
+        alias lancaster_email_address institutional_email_address
+
+        # Initialises a new ContactDetails instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the contact details record
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param addresses [Array<PersonAddress>, nil] the default array of postal addresses
+        # @param institutional_email_address [String, nil] the default semi-colon-separated institutional email addresses
+        # @param mobile_phone_number [String, nil] the default mobile phone number
+        # @param personal_email_address [String, nil] the default semi-colon-separated personal email addresses
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, addresses: nil, institutional_email_address: nil, mobile_phone_number: nil,
+                       personal_email_address: nil)
+          @addresses = LUSI::API::Core::XML.xml(xml, 'xmlns:Addresses/xmlns:PersonAddress') { |a| PersonAddress.new(a, lookup) }
+          @institutional_email_address = email_list(xml, 'xmlns:LancasterEmailAddress', institutional_email_address)
+          @mobile_phone_number = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:MobilePhoneNumber', mobile_phone_number)
+          @personal_email_address = email_list(xml, 'xmlns:PersonalEmailAddress', personal_email_address)
+        end
+
+        protected
+
+        # Extracts a semi-colon-separated email address from XML and splits into an array of single email addresses.
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the email address
+        # @param path [String] the XPath of the required email address
+        # @param default [String, nil] the default email address string
+        # @return [Array<String>] the array of single email addresses
+        def email_list(xml, path, default = nil)
+          # Extract the email address string from XML
+          emails = LUSI::API::Core::XML.xml_content_at(xml, path, default).to_s
+          # Split the string on semi-colons and remove empty entries
+          emails.strip.split(/\s*;\s*/).reject { |email| email.nil? || email.empty? }
+        end
+
+      end
+
+
+      class UserContact
+
+        # @!attribute [rw] identity
+        #   @return [String, nil] the identity code of the contact
+        attr_accessor :identity
+
+        # @!attribute [rw] contact_type
+        #   @return [String, nil] the type of contact ('Staff' | 'Student')
+        attr_accessor :contact_type
+
+        # @!attribute [rw] contact_name
+        #   @return [String, nil] the name of the contact
+        attr_accessor :contact_name
+
+        # @!attribute [rw] email_address
+        #   @return [String, nil] the email address of the contact
+        attr_accessor :email_address
+
+        # Initialises a new UserContact instance
+        # @param identity [String, nil] the default identity code of the contact
+        # @param contact_type [String, nil] the default contact type ('Staff' | 'Student')
+        # @param contact_name [String, nil] the default contact name
+        # @param email_address [String, nil] the default email address
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, identity: nil, contact_type: nil, contact_name: nil, email_address: nil)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @contact_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactType', contact_type)
+          @contact_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactName', contact_name)
+          @email_address = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:EmailAddress', email_address)
+        end
+
+        # Returns a string representation of the instance
+        # @return [String] the string representation of the contact
+        def to_s
+          email = @email_address ? " <#{@email_address}>" : ''
+          "#{@contact_name}#{@email}"
+        end
+
+      end
+
+
+      # Represents a student's relationship with a member of staff
+      class Relationship
+
+        # @!attribute [rw] staff_relationship
+        #   @return [LUSI::API::Core::Code, nil] the staff relationship type
+        attr_accessor :staff_relationship
+
+        # @!attribute [rw] user_contact
+        #   @return [LUSI::API::Person::UserContact, nil] the related person's contact details
+        attr_accessor :user_contact
+
+        # Initialises a new Relationship instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the relationship
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param staff_relationship [LUSI::API::Core::Code, nil] the default staff relationship code
+        # @param user_contact [LUSI::API::Person::UserContact, nil] the default related person's contact details
+        def initialize(xml = nil, lookup = nil, staff_relationship: nil, user_contact: nil)
+          @staff_relationship = LUSI::API::Core::Code.new(
+              LUSI::API::Core::XML.xml_at(xml, 'xmlns:StaffRelationship', staff_relationship), lookup)
+          @user_contact = UserContact.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:UserContact', user_contact), lookup)
+        end
+
+        # Returns a string representation of the relationship
+        def to_s
+          contact = @user_contact ? @user_contact.contact_name : ''
+          description = @staff_relationship ? "#{@staff_relationship.description}: " : ''
+          "#{description}#{contact}"
+        end
+
+      end
+
+
+      # Represents a student record in the LUSI API
+      class StudentRecord
+
+        # @!attribute [rw] identity
+        #   @return [String, nil] the institutional identity code for the student registration
+        attr_accessor :identity
+
+        # @!attribute [rw] external_institution_identity
+        #   @return [String, nil] the external institutional identity code for the student registration
+        attr_accessor :external_institution_identity
+
+        # @!attribute [rw] category
+        #   @return [String, nil] the category (type) of registration
+        attr_accessor :category
+
+
+        # @!attribute [rw] college
+        #   @return [String, nil] the associated college name
+        attr_accessor :college
+
+        # @!attribute [rw] department
+        #   @return [LUSI::API::Organisation::Unit, nil] the organisation Unit representing the associated department
+        attr_accessor :department
+
+        # @!attribute [rw] attendance_status
+        #   @return [String, nil] the current status of the registration
+        attr_accessor :attendance_status
+
+        # @!attribute [rw] research_student
+        #   @return [Boolean, nil] true if the registration is for a research course, otherwise false
+        attr_accessor :research_student
+
+        # @!attribute [rw] scheme_of_study
+        #   @return [LUSI::API::Course::SchemeOfStudy, nil] the student's scheme (or programme) of study
+        attr_accessor :scheme_of_study
+
+        # @!attribute [rw] programme_of_study
+        #   @see (#scheme_of_study)
+        alias programme_of_study scheme_of_study
+
+        # @!attribute [rw] entry_date
+        #   @return [DateTime, nil] the start date of the scheme of study
+        attr_accessor :entry_date
+
+        # @!attribute [rw] expected_completion_date
+        #   @return [DateTime, nil] the expected date of completion
+        attr_accessor :expected_completion_date
+
+        # @!attribute [rw] year_of_study
+        #   @return [Integer, nil] the current year of study (1 = first year, 2 = second year etc.)
+        attr_accessor :year_of_study
+
+        # @!attribute [rw] year_of_scheme_of_study
+        #   @return [Integer, nil] the nominal year of the student's scheme of study
+        attr_accessor :year_of_scheme_of_study
+
+        # @!attribute [rw] modules
+        #   @return [Array<LUSI::API::Course::ModuleEnrolment>, nil] an array of associated module enrolments
+        attr_accessor :modules
+
+        # @!attribute [rw] relationships
+        #   @return [Array<LUSI::API::Person::Relationship>, nil] an array of relationships for the student
+        attr_accessor :relationships
+
+        # @!attribute [rw] full_name_on_certificate
+        #   @return [String, nil] the full name to be used on the certificate
+        attr_accessor :full_name_on_certificate
+
+        # @!attribute [rw] leave_details
+        #   @return [LUSI::API::Person::LeaveDetails, nil] the student's leaving details, nil if still a current student
+        attr_accessor :leave_details
+
+        # @!attribute [rw] user_account
+        #   @return [Array<LUSI::API::Person::UserAccount>, nil] an array of the student's network accounts
+        attr_accessor :user_account
+
+        # Initialises a new StudentRecord instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the student record
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param identity [String, nil] the default institutional registration identity code
+        # @param external_institution_identity [String, nil] the default external institution registration identity code
+        # @param category [String, nil] the default registration category (type)
+        # @param college [String, nil] the default associated college name
+        # @param department [LUSI::API::Organisation::Unit, nil] the default associated department
+        # @param attendance_status [String, nil] the default registration status
+        # @param research_student [Boolean, nil] the default value of the research student indicator flag
+        # @param scheme_of_study [LUSI::API::Course::SchemeOfStudyEnrolment, nil] the default scheme of study enrolment
+        # @param programme_of_study [LUSI::API::Course::SchemeOfStudyEnrolment, nil] synonym for scheme_of_study
+        # @param entry_date [DateTime, nil] the default start date of the scheme of study
+        # @param expected_completion_date [DateTime, nil] the default expected completion date
+        # @param year_of_study [Integer, nil] the default year of study
+        # @param year_of_scheme_of_study [Integer, nil] the default year of the scheme of study
+        # @param modules [Array<LUSI::API::Course::ModuleEnrolment>, nil] the default list of associated modules
+        # @param relationships [Array<LUSI::API::Person::Relationship>, nil] the default list of staff relationships
+        # @param full_name_on_certificate [String, nil] the default full certificate name
+        # @param leave_details [LUSI::API::Person::LeaveDetails] the default leaving details
+        # @param user_account [Array<LUSI::API::Person::UserAccount>, nil] the default list of user accounts
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, identity: nil, external_institution_identity: nil, category: nil,
+                       college: nil, department: nil, attendance_status: nil, research_student: nil,
+                       programme_of_study: nil, scheme_of_study: nil, entry_date: nil, expected_completion_date: nil,
+                       year_of_study: nil, year_of_scheme_of_study: nil, modules: nil, relationships: nil,
+                       full_name_on_certificate: nil, leave_details: nil, user_account: nil)
+          scheme_of_study ||= programme_of_study
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+          @external_institution_identity = LUSI::API::Core::XML.xml_content_at(xml,
+                                                                                'xmlns:ExternalInstitutionIdentity',
+                                                                                external_institution_identity)
+          @category = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Category', category)
+          @college = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:College', college)
+          @department = LUSI::API::Core::XML.lookup(xml, lookup, :department, 'xmlns:Department', department)
+          @attendance_status = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AttendanceStatus', attendance_status)
+          @research_student = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:ResearchStudent', research_student)
+          @scheme_of_study = LUSI::API::Course::SchemeOfStudyEnrolment.new(
+              LUSI::API::Core::XML.xml_at(xml, 'xmlns:ProgrammeOfStudy', scheme_of_study), lookup)
+          @entry_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:EntryDate', entry_date)
+          @expected_completion_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:ExpectedCompletionDate',
+                                                                           expected_completion_date)
+          @year_of_study = LUSI::API::Core::XML.xml_int_at(xml, 'xmlns:YearOfStudy', year_of_study)
+          @year_of_scheme_of_study = LUSI::API::Core::XML.xml_int_at(xml, 'xmlns:YearOfSchemeOfStudy',
+                                                                     year_of_scheme_of_study)
+          @modules = LUSI::API::Core::XML.xml(xml, 'xmlns:Modules/xmlns:Module') { |m| LUSI::API::Course::ModuleEnrolment.new(m, lookup) }
+          @relationships = LUSI::API::Core::XML.xml(xml, 'xmlns:Relationships/xmlns:Relationship',
+                                                    relationships) { |r| Relationship.new(r, lookup) }
+          @full_name_on_certificate = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FullNameOnCertificate',
+                                                                          full_name_on_certificate)
+          @leave_details = LeaveDetails.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:LeaveDetails', leave_details),
+                                            lookup)
+          @user_account = LUSI::API::Core::XML.xml(xml, 'xmlns:UserAccounts/xmlns:UserAccount',
+                                                   user_account) { |a| UserAccount.new(a, lookup) }
+        end
+
+        # Returns a string representation of the StudentRecord instance
+        # @return [String] the string representation of the instance
+        def to_s
+          @identity
+        end
+
+      end
+
+
+      # Represents a user's network account in the LUSI API
+      class UserAccount
+
+        # @!attribute [rw] account_name
+        #   @return [String, nil] the account username
+        attr_accessor :account_name
+
+        # @!attribute [rw] identity
+        #   @return [String, nil] the student identity associated with the username
+        attr_accessor :identity
+
+        # Initialises a new UserAccount instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed root of the user account
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param account_name [String, nil] the default account name
+        # @param identity [String, nil] the default student identity
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, account_name: nil, identity: nil)
+          @account_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AccountName', account_name)
+          @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
+        end
+
+        # Returns a string representation of the UserAccount instance
+        # @return [String] the string representation of the UserAccount instance
+        def to_s
+          @account_name
+        end
+
+      end
+
+
+      # Represents a person (student) in the LUSI API
+      class Student
+
+        # @!attribute [rw] title
+        #   @return [String, nil] the person's title (honourific)
+        attr_accessor :title
+
+        # !@attribute [rw] surname
+        #   @return [String, nil] the person's surname
+        attr_accessor :surname
+
+        # !@attribute [rw] forenames
+        #   @return [String, nil] the person's full forenames (space-separated string)
+        attr_accessor :forenames
+
+        # @!attribute [rw] preferred_name
+        #   @return [String, nil] the person's preferred name
+        attr_accessor :preferred_name
+
+        # @!attribute [rw] date_of_birth
+        #   @return [DateTime, nil] the person's date of birth
+        attr_accessor :date_of_birth
+
+        # @!attribute [rw] gender
+        #   @return [String, nil] the person's gender
+        attr_accessor :gender
+
+        # @!attribute [rw] fee_status
+        #   @return [String, nil] the person's fee status
+        attr_accessor :fee_status
+
+        # @!attribute [rw] nationality
+        #   @return [LUSI::API::Country::Nationality] the person's nationality
+        attr_accessor :nationality
+
+        # @!attribute [rw] contact_detail
+        #   @return [LUSI::API::Person::ContactDetail, nil] the person's contact details
+        attr_accessor :contact_detail
+
+        # @!attribute [rw] student_records
+        #   @return [Array<LUSI::API::Person::StudentRecord>, nil] the person's student record list
+        attr_accessor :student_records
+
+        # Returns an array of Student instances matching the search parameters
+        # @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 lancaster_student_id [String, nil] the Lancaster University student ID to search for
+        # @param external_student_id [String, nil] the external student ID to search for
+        # @param user_login [String, nil] the user login name to search for
+        # @param relationship_is_current_only [Boolean, nil] if true, search only current students;
+        #   otherwise search current and historic students
+        # @param relationship_identity [String, nil] the relationship identity to search for
+        # @return [Array<Student>, nil] the list of matching Student instances
+        # @yield [obj] Pass the Student instance to the block
+        # @yieldparam obj [LUSI::API::Person::Student] the Student instance
+        def self.get_instance(api, lookup = nil, lancaster_student_id: nil, external_student_id: nil, user_login: nil,
+                              relationship_is_current_only: nil, relationship_identity: nil)
+          params = get_instance_params(lancaster_student_id: lancaster_student_id,
+                                       external_student_id: external_student_id, user_login: user_login,
+                                       relationship_is_current_only: relationship_is_current_only,
+                                       relationship_identity: relationship_identity)
+          xml = api.call('UserDetails', 'StudentManager.asmx', 'GetFullDetails', **params)
+          LUSI::API::Core::XML.xml(xml, 'xmlns:Person') do |p|
+            obj = Student.new(p, lookup)
+            yield(obj) if block_given?
+            obj
+          end
+        end
+
+        # Initialises a new Person instance
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the person
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param title [String, nil] the default title (honourific)
+        # @param surname [String, nil] the default surname
+        # @param forenames [String, nil] the default forenames (space-separated string)
+        # @param preferred_name [String, nil] the default preferred name
+        # @param date_of_birth [DateTime, nil] the default date of birth
+        # @param gender [String, nil] the default gender
+        # @param fee_status [String, nil] the default fee status
+        # @param nationality [LUSI::API::Country::Nationality, nil] the default nationality
+        # @param contact_detail [LUSI::API::Person::ContactDetail, nil] the default contact detail record
+        # @param student_records [Array<LUSI::API::Person::StudentRecord>, nil] the default student record list
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, title: nil, surname: nil, forenames: nil, preferred_name: nil,
+                       date_of_birth: nil, gender: nil, fee_status: nil, nationality: nil, contact_detail: nil,
+                       student_records: nil)
+          @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
+          @surname = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Surname', surname)
+          @forenames = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Forenames', forenames)
+          @preferred_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PreferredName', preferred_name)
+          @date_of_birth = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:DateOfBirth', date_of_birth)
+          @gender = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Gender', gender)
+          @fee_status = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FeeStatus', fee_status)
+          @nationality = LUSI::API::Core::XML.lookup(xml, lookup, :nationality, 'xmlns:Nationality', nationality)
+          @contact_detail = ContactDetail.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:ContactDetail', contact_detail),
+                                              lookup)
+          @student_records = LUSI::API::Core::XML.xml(xml, 'xmlns:StudentRecords/xmlns:StudentRecord',
+                                                       student_records) { |r| StudentRecord.new(r, lookup) }
+        end
+
+        # Returns a string representation of the person (full title and names)
+        # @return [String] the string representation of the person
+        def to_s
+          "#{@title} #{@sforenames} #{@surname}".squeeze!(' ').strip!
+        end
+
+        protected
+
+        def self.get_instance_params(**kwargs)
+          current_relationship_only = kwargs[:relationship_is_current_only]
+          current_relationship_only = current_relationship_only.nil? || current_relationship_only ? 'true' : 'false'
+          {
+            ExternalStudentId: kwargs[:external_student_id] || '',
+            LancasterStudentId: kwargs[:lancaster_student_id ]|| '',
+            RelationshipIsCurrentOnly: current_relationship_only,
+            RelationshipIdentity: kwargs[:relationship_identity] || '',
+            UserLogin: kwargs[:user_login] || ''
+          }
+        end
+      end
+
+
+    end
+  end
+end