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.
@@ -0,0 +1,115 @@
1
+ require 'lusi_api/core/code'
2
+ require 'lusi_api/core/xml'
3
+
4
+
5
+ module LUSI
6
+ module API
7
+ module Person
8
+
9
+
10
+ # Represents a staff course role in the LUSI API
11
+ class StaffCourseRole < LUSI::API::Core::Code
12
+
13
+ # @!attribute [rw] vle_role_description
14
+ # @return [String, nil] the VLE role description
15
+ attr_accessor :vle_role_description
16
+
17
+ # Returns an instance of StaffCourseRole matching the specified parameters
18
+ # @param api [LUSI::API::Core::API, nil] the LUSI API instance
19
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
20
+ # @param (see LUSI::API::Core::Code#get_instance)
21
+ # @return [Array<LUSI::API::Person::StaffCourseRole>, nil]
22
+ def self.get_instance(api = nil, lookup = nil, **kwargs)
23
+ super(api, lookup, 'LUSIReference', 'Lookup.asmx', 'GetStaffCourseRoles', 'xmlns:StaffCourseRole',
24
+ result_class: StaffCourseRole, **kwargs)
25
+ end
26
+
27
+ # Initialises a new StaffCourseRole instance
28
+ # @param (see LUSI::API::Core::Code#initialize)
29
+ # @param vle_role_description [String, nil] the default VLE role description
30
+ # @return [void]
31
+ def initialize(xml = nil, lookup = nil, vle_role_description: nil, **kwargs)
32
+ super(xml, lookup, **kwargs)
33
+ @vle_role_description = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:VLERoleDescription',
34
+ vle_role_description)
35
+ end
36
+
37
+ end
38
+
39
+
40
+ # Represents a staff member in the LUSI API
41
+ class StaffMember
42
+
43
+ # @!attribute [rw] identity
44
+ # @return [String, nil] the identity code of the staff member
45
+ attr_accessor :identity
46
+
47
+ # @!attribute [rw] title
48
+ # @return [String, nil] the title (honourific) of the staff member
49
+ attr_accessor :title
50
+
51
+ # @!attribute [rw] surname
52
+ # @return [String, nil] the surname of the staff member
53
+ attr_accessor :surname
54
+
55
+ # @!attribute [rw] forename
56
+ # @return [String, nil] the forename of the staff member
57
+ attr_accessor :forename
58
+
59
+ # @!attribute [rw] preferred_name
60
+ # @return [String, nil] the preferred name of the staff member
61
+ attr_accessor :preferred_name
62
+
63
+ # @!attribute [rw] department
64
+ # @return [LUSI::API::Organisation::Unit, nil] the staff member's associated department
65
+ attr_accessor :department
66
+
67
+ # @!attribute [rw] faculty
68
+ # @return [LUSI::API::Organisation::Unit, nil] the staff member's associated faculty
69
+ attr_accessor :faculty
70
+
71
+ # @!attribute [rw] institution
72
+ # @return [LUSI::API::Organisation::Unit, nil] the staff member's associated institution
73
+ attr_accessor :institution
74
+
75
+ # Initialises a new StaffMember instance
76
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the staff member
77
+ # @param lookup [LUSI::API::Core::LookupTable, nil] the lookup service for organisation unit resolution
78
+ # @param department [LUSI::API::Organisation::Unit, nil] the default department
79
+ # @param faculty [LUSI::API::Organisation::Unit, nil] the default faculty
80
+ # @param forename [String, nil] the default forename
81
+ # @param identity [String, nil] the default identity code
82
+ # @param institution [LUSI::API::Organisation::Unit, nil] the default institution
83
+ # @param preferred_name [String, nil] the default preferred name
84
+ # @param surname [String, nil] the default surname
85
+ # @param title [String, nil] the default title (honourific)
86
+ # @return [void]
87
+ def initialize(xml = nil, lookup = nil, department: nil, faculty: nil, forename: nil, identity: nil,
88
+ institution: nil, preferred_name: nil, surname: nil, title: nil)
89
+ @department = LUSI::API::Core::XML.lookup(xml, lookup, :department, 'xmlns:Department/xmlns:Identity',
90
+ department)
91
+ @faculty = LUSI::API::Core::XML.lookup(xml, lookup, :faculty, 'xmlns:Faculty/xmlns:Identity', faculty)
92
+ @forename = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Forename', forename)
93
+ @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
94
+ @institution = LUSI::API::Core::XML.lookup(xml, lookup, :institution, 'xmlns:Institution/xmlns:Identity',
95
+ institution)
96
+ @preferred_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PreferredName', preferred_name)
97
+ @surname = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Surname', surname)
98
+ @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
99
+ end
100
+
101
+ # Returns a string representation of the staff member (full name)
102
+ # @return [String] the string representation of the staff member (full name)
103
+ def to_s
104
+ str = "#{@title} #{@forename} #{@surname}"
105
+ str.strip!
106
+ str.squeeze!(' ')
107
+ str
108
+ end
109
+
110
+ end
111
+
112
+
113
+ end
114
+ end
115
+ end
@@ -0,0 +1,551 @@
1
+ require 'date'
2
+
3
+ require 'lusi_api/core/api'
4
+ require 'lusi_api/core/xml'
5
+ require 'lusi_api/country'
6
+ require 'lusi_api/course'
7
+ require 'lusi_api/organisation'
8
+
9
+
10
+ module LUSI
11
+ module API
12
+ module Person
13
+
14
+
15
+ # Represents a student's leaving details in the LUSI API
16
+ class LeaveDetails
17
+
18
+ # @!attribute [rw] last_attend_date
19
+ # @return [DateTime, nil] the date of last attendance
20
+ attr_accessor :last_attend_date
21
+
22
+ # @!attribute [rw] leave_date
23
+ # @return [DateTime, nil] the date of leaving
24
+ attr_accessor :leave_date
25
+
26
+ # @!attribute [rw] leave_reason
27
+ # @return [LUSI::API::Core::Code, nil] the reason for leaving
28
+ attr_accessor :leave_reason
29
+
30
+ # Initialises a new LeaveDetails instance
31
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the leave details
32
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
33
+ # @param last_attend_date [DateTime, nil] the default date of last attendance
34
+ # @param leave_date [DateTime, nil] the default leave date
35
+ # @param leave_reason [LUSI::API::Core::Code, nil] the reason for leaving
36
+ # @return [void]
37
+ def initialize(xml = nil, lookup = nil, last_attend_date: nil, leave_date: nil, leave_reason: nil)
38
+ @leave_reason = LUSI::API::Core::Code.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:LeaveReason'), lookup)
39
+ @leave_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:LeaveDate')
40
+ @last_attend_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:LastAttendDate')
41
+ end
42
+
43
+ # Returns a string representation of the LeaveDetails instance
44
+ # @return [String] the string representation of the LeaveDetails instance
45
+ def to_s
46
+ @leave_reason.to_s
47
+ end
48
+
49
+ end
50
+
51
+
52
+ # Represents a person's postal address
53
+ class PersonAddress
54
+
55
+ # @!attribute [rw] address_type
56
+ # @return [String, nil] the address type (e.g. 'Termtime Address')
57
+ attr_accessor :address_type
58
+
59
+ # @!attribute [rw] address_line_1
60
+ # @return [String, nil] the first address line
61
+ attr_accessor :address_line_1
62
+
63
+ # @!attribute [rw] address_line_2
64
+ # @return [String, nil] the second address line
65
+ attr_accessor :address_line_2
66
+
67
+ # @!attribute [rw] address_line_3
68
+ # @return [String, nil] the third address line
69
+ attr_accessor :address_line_3
70
+
71
+ # @!attribute [rw] address_line_4
72
+ # @return [String, nil] the fourth address line
73
+ attr_accessor :address_line_4
74
+
75
+ # @!attribute [rw] address_line_5
76
+ # @return [String, nil] the fifth address line
77
+ attr_accessor :address_line_5
78
+
79
+ # @!attribute [rw] post_code
80
+ # @return [String, nil] the postal or zip code
81
+ attr_accessor :post_code
82
+
83
+ # @!attribute [rw] country
84
+ # @return [LUSI::API::Person::AddressCountry, nil] the country
85
+ attr_accessor :country
86
+
87
+ # Initialises a PersonAddress instance
88
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the address
89
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
90
+ # @param address_type [String, nil] the default address type
91
+ # @param address_line_1 [String, nil] the default first address line
92
+ # @param address_line_2 [String, nil] the default second address line
93
+ # @param address_line_3 [String, nil] the default third address line
94
+ # @param address_line_4 [String, nil] the default fourth address line
95
+ # @param address_line_5 [String, nil] the default fifth address line
96
+ # @param post_code [String, nil] the default postal or zip code
97
+ # @param country [LUSI::API::Country::AddressCountry, nil] the default country
98
+ # @return [void]
99
+ def initialize(xml = nil, lookup = nil, address_type: nil, address_line_1: nil, address_line_2: nil,
100
+ address_line_3: nil, address_line_4: nil, address_line_5: nil, post_code: nil, country: nil)
101
+ @address_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressType', address_type)
102
+ @address_line_1 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine1', address_line_1)
103
+ @address_line_2 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine2', address_line_2)
104
+ @address_line_3 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine3', address_line_3)
105
+ @address_line_4 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine4', address_line_4)
106
+ @address_line_5 = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AddressLine5', address_line_5)
107
+ @post_code = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PostCode', post_code)
108
+ @country = LUSI::API::Core::XML.lookup(xml, lookup, :address_country, 'xmlns:Country/xmlns:Identity', country)
109
+ end
110
+
111
+ # Returns a string representation of the PersonAddress instance
112
+ # @return [String] the string representation of the PersonAddress instance
113
+ def to_s(sep = nil)
114
+ sep ||= ', '
115
+ fields = []
116
+ [@address_type, @address_line_1, @address_line_2, @address_line_3, @address_line_4, @address_line_5,
117
+ @post_code, @country].each do |field|
118
+ field_s = field.to_s
119
+ fields.push(field_s) unless field_s.nil? || field_s.empty?
120
+ end
121
+ fields.join(sep)
122
+ end
123
+
124
+ end
125
+
126
+
127
+ # Holds a person's combined contact details (postal addresses, email addresses, phone numbers)
128
+ class ContactDetail
129
+
130
+ # @!attribute [rw] addresses
131
+ # @return [Array<PersonAddress>, nil] postal addresses as an array of PersonAddress instances
132
+ attr_accessor :addresses
133
+
134
+ # @!attribute [rw] personal_email_address
135
+ # @return [Array<String>, nil] an array of personal email addresses
136
+ attr_accessor :personal_email_address
137
+
138
+ # @!attribute [rw] lancaster_email_address
139
+ # @return [Array<String>, nil] and array of institutional email addresses
140
+ attr_accessor :institutional_email_address
141
+
142
+ # !@attribute [rw] mobile_phone_number
143
+ # @return [String, nil] mobile phone number
144
+ attr_accessor :mobile_phone_number
145
+
146
+ # @see institutional_email_address an alias for institutional_email_address for consistency with the LUSI API
147
+ alias lancaster_email_address institutional_email_address
148
+
149
+ # Initialises a new ContactDetails instance
150
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the contact details record
151
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
152
+ # @param addresses [Array<PersonAddress>, nil] the default array of postal addresses
153
+ # @param institutional_email_address [String, nil] the default semi-colon-separated institutional email addresses
154
+ # @param mobile_phone_number [String, nil] the default mobile phone number
155
+ # @param personal_email_address [String, nil] the default semi-colon-separated personal email addresses
156
+ # @return [void]
157
+ def initialize(xml = nil, lookup = nil, addresses: nil, institutional_email_address: nil, mobile_phone_number: nil,
158
+ personal_email_address: nil)
159
+ @addresses = LUSI::API::Core::XML.xml(xml, 'xmlns:Addresses/xmlns:PersonAddress') { |a| PersonAddress.new(a, lookup) }
160
+ @institutional_email_address = email_list(xml, 'xmlns:LancasterEmailAddress', institutional_email_address)
161
+ @mobile_phone_number = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:MobilePhoneNumber', mobile_phone_number)
162
+ @personal_email_address = email_list(xml, 'xmlns:PersonalEmailAddress', personal_email_address)
163
+ end
164
+
165
+ protected
166
+
167
+ # Extracts a semi-colon-separated email address from XML and splits into an array of single email addresses.
168
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the email address
169
+ # @param path [String] the XPath of the required email address
170
+ # @param default [String, nil] the default email address string
171
+ # @return [Array<String>] the array of single email addresses
172
+ def email_list(xml, path, default = nil)
173
+ # Extract the email address string from XML
174
+ emails = LUSI::API::Core::XML.xml_content_at(xml, path, default).to_s
175
+ # Split the string on semi-colons and remove empty entries
176
+ emails.strip.split(/\s*;\s*/).reject { |email| email.nil? || email.empty? }
177
+ end
178
+
179
+ end
180
+
181
+
182
+ class UserContact
183
+
184
+ # @!attribute [rw] identity
185
+ # @return [String, nil] the identity code of the contact
186
+ attr_accessor :identity
187
+
188
+ # @!attribute [rw] contact_type
189
+ # @return [String, nil] the type of contact ('Staff' | 'Student')
190
+ attr_accessor :contact_type
191
+
192
+ # @!attribute [rw] contact_name
193
+ # @return [String, nil] the name of the contact
194
+ attr_accessor :contact_name
195
+
196
+ # @!attribute [rw] email_address
197
+ # @return [String, nil] the email address of the contact
198
+ attr_accessor :email_address
199
+
200
+ # Initialises a new UserContact instance
201
+ # @param identity [String, nil] the default identity code of the contact
202
+ # @param contact_type [String, nil] the default contact type ('Staff' | 'Student')
203
+ # @param contact_name [String, nil] the default contact name
204
+ # @param email_address [String, nil] the default email address
205
+ # @return [void]
206
+ def initialize(xml = nil, lookup = nil, identity: nil, contact_type: nil, contact_name: nil, email_address: nil)
207
+ @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
208
+ @contact_type = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactType', contact_type)
209
+ @contact_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:ContactName', contact_name)
210
+ @email_address = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:EmailAddress', email_address)
211
+ end
212
+
213
+ # Returns a string representation of the instance
214
+ # @return [String] the string representation of the contact
215
+ def to_s
216
+ email = @email_address ? " <#{@email_address}>" : ''
217
+ "#{@contact_name}#{@email}"
218
+ end
219
+
220
+ end
221
+
222
+
223
+ # Represents a student's relationship with a member of staff
224
+ class Relationship
225
+
226
+ # @!attribute [rw] staff_relationship
227
+ # @return [LUSI::API::Core::Code, nil] the staff relationship type
228
+ attr_accessor :staff_relationship
229
+
230
+ # @!attribute [rw] user_contact
231
+ # @return [LUSI::API::Person::UserContact, nil] the related person's contact details
232
+ attr_accessor :user_contact
233
+
234
+ # Initialises a new Relationship instance
235
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the relationship
236
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
237
+ # @param staff_relationship [LUSI::API::Core::Code, nil] the default staff relationship code
238
+ # @param user_contact [LUSI::API::Person::UserContact, nil] the default related person's contact details
239
+ def initialize(xml = nil, lookup = nil, staff_relationship: nil, user_contact: nil)
240
+ @staff_relationship = LUSI::API::Core::Code.new(
241
+ LUSI::API::Core::XML.xml_at(xml, 'xmlns:StaffRelationship', staff_relationship), lookup)
242
+ @user_contact = UserContact.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:UserContact', user_contact), lookup)
243
+ end
244
+
245
+ # Returns a string representation of the relationship
246
+ def to_s
247
+ contact = @user_contact ? @user_contact.contact_name : ''
248
+ description = @staff_relationship ? "#{@staff_relationship.description}: " : ''
249
+ "#{description}#{contact}"
250
+ end
251
+
252
+ end
253
+
254
+
255
+ # Represents a student record in the LUSI API
256
+ class StudentRecord
257
+
258
+ # @!attribute [rw] identity
259
+ # @return [String, nil] the institutional identity code for the student registration
260
+ attr_accessor :identity
261
+
262
+ # @!attribute [rw] external_institution_identity
263
+ # @return [String, nil] the external institutional identity code for the student registration
264
+ attr_accessor :external_institution_identity
265
+
266
+ # @!attribute [rw] category
267
+ # @return [String, nil] the category (type) of registration
268
+ attr_accessor :category
269
+
270
+
271
+ # @!attribute [rw] college
272
+ # @return [String, nil] the associated college name
273
+ attr_accessor :college
274
+
275
+ # @!attribute [rw] department
276
+ # @return [LUSI::API::Organisation::Unit, nil] the organisation Unit representing the associated department
277
+ attr_accessor :department
278
+
279
+ # @!attribute [rw] attendance_status
280
+ # @return [String, nil] the current status of the registration
281
+ attr_accessor :attendance_status
282
+
283
+ # @!attribute [rw] research_student
284
+ # @return [Boolean, nil] true if the registration is for a research course, otherwise false
285
+ attr_accessor :research_student
286
+
287
+ # @!attribute [rw] scheme_of_study
288
+ # @return [LUSI::API::Course::SchemeOfStudy, nil] the student's scheme (or programme) of study
289
+ attr_accessor :scheme_of_study
290
+
291
+ # @!attribute [rw] programme_of_study
292
+ # @see (#scheme_of_study)
293
+ alias programme_of_study scheme_of_study
294
+
295
+ # @!attribute [rw] entry_date
296
+ # @return [DateTime, nil] the start date of the scheme of study
297
+ attr_accessor :entry_date
298
+
299
+ # @!attribute [rw] expected_completion_date
300
+ # @return [DateTime, nil] the expected date of completion
301
+ attr_accessor :expected_completion_date
302
+
303
+ # @!attribute [rw] year_of_study
304
+ # @return [Integer, nil] the current year of study (1 = first year, 2 = second year etc.)
305
+ attr_accessor :year_of_study
306
+
307
+ # @!attribute [rw] year_of_scheme_of_study
308
+ # @return [Integer, nil] the nominal year of the student's scheme of study
309
+ attr_accessor :year_of_scheme_of_study
310
+
311
+ # @!attribute [rw] modules
312
+ # @return [Array<LUSI::API::Course::ModuleEnrolment>, nil] an array of associated module enrolments
313
+ attr_accessor :modules
314
+
315
+ # @!attribute [rw] relationships
316
+ # @return [Array<LUSI::API::Person::Relationship>, nil] an array of relationships for the student
317
+ attr_accessor :relationships
318
+
319
+ # @!attribute [rw] full_name_on_certificate
320
+ # @return [String, nil] the full name to be used on the certificate
321
+ attr_accessor :full_name_on_certificate
322
+
323
+ # @!attribute [rw] leave_details
324
+ # @return [LUSI::API::Person::LeaveDetails, nil] the student's leaving details, nil if still a current student
325
+ attr_accessor :leave_details
326
+
327
+ # @!attribute [rw] user_account
328
+ # @return [Array<LUSI::API::Person::UserAccount>, nil] an array of the student's network accounts
329
+ attr_accessor :user_account
330
+
331
+ # Initialises a new StudentRecord instance
332
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the student record
333
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
334
+ # @param identity [String, nil] the default institutional registration identity code
335
+ # @param external_institution_identity [String, nil] the default external institution registration identity code
336
+ # @param category [String, nil] the default registration category (type)
337
+ # @param college [String, nil] the default associated college name
338
+ # @param department [LUSI::API::Organisation::Unit, nil] the default associated department
339
+ # @param attendance_status [String, nil] the default registration status
340
+ # @param research_student [Boolean, nil] the default value of the research student indicator flag
341
+ # @param scheme_of_study [LUSI::API::Course::SchemeOfStudyEnrolment, nil] the default scheme of study enrolment
342
+ # @param programme_of_study [LUSI::API::Course::SchemeOfStudyEnrolment, nil] synonym for scheme_of_study
343
+ # @param entry_date [DateTime, nil] the default start date of the scheme of study
344
+ # @param expected_completion_date [DateTime, nil] the default expected completion date
345
+ # @param year_of_study [Integer, nil] the default year of study
346
+ # @param year_of_scheme_of_study [Integer, nil] the default year of the scheme of study
347
+ # @param modules [Array<LUSI::API::Course::ModuleEnrolment>, nil] the default list of associated modules
348
+ # @param relationships [Array<LUSI::API::Person::Relationship>, nil] the default list of staff relationships
349
+ # @param full_name_on_certificate [String, nil] the default full certificate name
350
+ # @param leave_details [LUSI::API::Person::LeaveDetails] the default leaving details
351
+ # @param user_account [Array<LUSI::API::Person::UserAccount>, nil] the default list of user accounts
352
+ # @return [void]
353
+ def initialize(xml = nil, lookup = nil, identity: nil, external_institution_identity: nil, category: nil,
354
+ college: nil, department: nil, attendance_status: nil, research_student: nil,
355
+ programme_of_study: nil, scheme_of_study: nil, entry_date: nil, expected_completion_date: nil,
356
+ year_of_study: nil, year_of_scheme_of_study: nil, modules: nil, relationships: nil,
357
+ full_name_on_certificate: nil, leave_details: nil, user_account: nil)
358
+ scheme_of_study ||= programme_of_study
359
+ @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
360
+ @external_institution_identity = LUSI::API::Core::XML.xml_content_at(xml,
361
+ 'xmlns:ExternalInstitutionIdentity',
362
+ external_institution_identity)
363
+ @category = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Category', category)
364
+ @college = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:College', college)
365
+ @department = LUSI::API::Core::XML.lookup(xml, lookup, :department, 'xmlns:Department', department)
366
+ @attendance_status = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AttendanceStatus', attendance_status)
367
+ @research_student = LUSI::API::Core::XML.xml_boolean_at(xml, 'xmlns:ResearchStudent', research_student)
368
+ @scheme_of_study = LUSI::API::Course::SchemeOfStudyEnrolment.new(
369
+ LUSI::API::Core::XML.xml_at(xml, 'xmlns:ProgrammeOfStudy', scheme_of_study), lookup)
370
+ @entry_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:EntryDate', entry_date)
371
+ @expected_completion_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:ExpectedCompletionDate',
372
+ expected_completion_date)
373
+ @year_of_study = LUSI::API::Core::XML.xml_int_at(xml, 'xmlns:YearOfStudy', year_of_study)
374
+ @year_of_scheme_of_study = LUSI::API::Core::XML.xml_int_at(xml, 'xmlns:YearOfSchemeOfStudy',
375
+ year_of_scheme_of_study)
376
+ @modules = LUSI::API::Core::XML.xml(xml, 'xmlns:Modules/xmlns:Module') { |m| LUSI::API::Course::ModuleEnrolment.new(m, lookup) }
377
+ @relationships = LUSI::API::Core::XML.xml(xml, 'xmlns:Relationships/xmlns:Relationship',
378
+ relationships) { |r| Relationship.new(r, lookup) }
379
+ @full_name_on_certificate = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FullNameOnCertificate',
380
+ full_name_on_certificate)
381
+ @leave_details = LeaveDetails.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:LeaveDetails', leave_details),
382
+ lookup)
383
+ @user_account = LUSI::API::Core::XML.xml(xml, 'xmlns:UserAccounts/xmlns:UserAccount',
384
+ user_account) { |a| UserAccount.new(a, lookup) }
385
+ end
386
+
387
+ # Returns a string representation of the StudentRecord instance
388
+ # @return [String] the string representation of the instance
389
+ def to_s
390
+ @identity
391
+ end
392
+
393
+ end
394
+
395
+
396
+ # Represents a user's network account in the LUSI API
397
+ class UserAccount
398
+
399
+ # @!attribute [rw] account_name
400
+ # @return [String, nil] the account username
401
+ attr_accessor :account_name
402
+
403
+ # @!attribute [rw] identity
404
+ # @return [String, nil] the student identity associated with the username
405
+ attr_accessor :identity
406
+
407
+ # Initialises a new UserAccount instance
408
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed root of the user account
409
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
410
+ # @param account_name [String, nil] the default account name
411
+ # @param identity [String, nil] the default student identity
412
+ # @return [void]
413
+ def initialize(xml = nil, lookup = nil, account_name: nil, identity: nil)
414
+ @account_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:AccountName', account_name)
415
+ @identity = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Identity', identity)
416
+ end
417
+
418
+ # Returns a string representation of the UserAccount instance
419
+ # @return [String] the string representation of the UserAccount instance
420
+ def to_s
421
+ @account_name
422
+ end
423
+
424
+ end
425
+
426
+
427
+ # Represents a person (student) in the LUSI API
428
+ class Student
429
+
430
+ # @!attribute [rw] title
431
+ # @return [String, nil] the person's title (honourific)
432
+ attr_accessor :title
433
+
434
+ # !@attribute [rw] surname
435
+ # @return [String, nil] the person's surname
436
+ attr_accessor :surname
437
+
438
+ # !@attribute [rw] forenames
439
+ # @return [String, nil] the person's full forenames (space-separated string)
440
+ attr_accessor :forenames
441
+
442
+ # @!attribute [rw] preferred_name
443
+ # @return [String, nil] the person's preferred name
444
+ attr_accessor :preferred_name
445
+
446
+ # @!attribute [rw] date_of_birth
447
+ # @return [DateTime, nil] the person's date of birth
448
+ attr_accessor :date_of_birth
449
+
450
+ # @!attribute [rw] gender
451
+ # @return [String, nil] the person's gender
452
+ attr_accessor :gender
453
+
454
+ # @!attribute [rw] fee_status
455
+ # @return [String, nil] the person's fee status
456
+ attr_accessor :fee_status
457
+
458
+ # @!attribute [rw] nationality
459
+ # @return [LUSI::API::Country::Nationality] the person's nationality
460
+ attr_accessor :nationality
461
+
462
+ # @!attribute [rw] contact_detail
463
+ # @return [LUSI::API::Person::ContactDetail, nil] the person's contact details
464
+ attr_accessor :contact_detail
465
+
466
+ # @!attribute [rw] student_records
467
+ # @return [Array<LUSI::API::Person::StudentRecord>, nil] the person's student record list
468
+ attr_accessor :student_records
469
+
470
+ # Returns an array of Student instances matching the search parameters
471
+ # @param api [LUSI::API::Core::API] the LUSI API instance to use for searching
472
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
473
+ # @param lancaster_student_id [String, nil] the Lancaster University student ID to search for
474
+ # @param external_student_id [String, nil] the external student ID to search for
475
+ # @param user_login [String, nil] the user login name to search for
476
+ # @param relationship_is_current_only [Boolean, nil] if true, search only current students;
477
+ # otherwise search current and historic students
478
+ # @param relationship_identity [String, nil] the relationship identity to search for
479
+ # @return [Array<Student>, nil] the list of matching Student instances
480
+ # @yield [obj] Pass the Student instance to the block
481
+ # @yieldparam obj [LUSI::API::Person::Student] the Student instance
482
+ def self.get_instance(api, lookup = nil, lancaster_student_id: nil, external_student_id: nil, user_login: nil,
483
+ relationship_is_current_only: nil, relationship_identity: nil)
484
+ params = get_instance_params(lancaster_student_id: lancaster_student_id,
485
+ external_student_id: external_student_id, user_login: user_login,
486
+ relationship_is_current_only: relationship_is_current_only,
487
+ relationship_identity: relationship_identity)
488
+ xml = api.call('UserDetails', 'StudentManager.asmx', 'GetFullDetails', **params)
489
+ LUSI::API::Core::XML.xml(xml, 'xmlns:Person') do |p|
490
+ obj = Student.new(p, lookup)
491
+ yield(obj) if block_given?
492
+ obj
493
+ end
494
+ end
495
+
496
+ # Initialises a new Person instance
497
+ # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node] the parsed XML root of the person
498
+ # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
499
+ # @param title [String, nil] the default title (honourific)
500
+ # @param surname [String, nil] the default surname
501
+ # @param forenames [String, nil] the default forenames (space-separated string)
502
+ # @param preferred_name [String, nil] the default preferred name
503
+ # @param date_of_birth [DateTime, nil] the default date of birth
504
+ # @param gender [String, nil] the default gender
505
+ # @param fee_status [String, nil] the default fee status
506
+ # @param nationality [LUSI::API::Country::Nationality, nil] the default nationality
507
+ # @param contact_detail [LUSI::API::Person::ContactDetail, nil] the default contact detail record
508
+ # @param student_records [Array<LUSI::API::Person::StudentRecord>, nil] the default student record list
509
+ # @return [void]
510
+ def initialize(xml = nil, lookup = nil, title: nil, surname: nil, forenames: nil, preferred_name: nil,
511
+ date_of_birth: nil, gender: nil, fee_status: nil, nationality: nil, contact_detail: nil,
512
+ student_records: nil)
513
+ @title = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Title', title)
514
+ @surname = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Surname', surname)
515
+ @forenames = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Forenames', forenames)
516
+ @preferred_name = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:PreferredName', preferred_name)
517
+ @date_of_birth = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:DateOfBirth', date_of_birth)
518
+ @gender = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Gender', gender)
519
+ @fee_status = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FeeStatus', fee_status)
520
+ @nationality = LUSI::API::Core::XML.lookup(xml, lookup, :nationality, 'xmlns:Nationality', nationality)
521
+ @contact_detail = ContactDetail.new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:ContactDetail', contact_detail),
522
+ lookup)
523
+ @student_records = LUSI::API::Core::XML.xml(xml, 'xmlns:StudentRecords/xmlns:StudentRecord',
524
+ student_records) { |r| StudentRecord.new(r, lookup) }
525
+ end
526
+
527
+ # Returns a string representation of the person (full title and names)
528
+ # @return [String] the string representation of the person
529
+ def to_s
530
+ "#{@title} #{@sforenames} #{@surname}".squeeze!(' ').strip!
531
+ end
532
+
533
+ protected
534
+
535
+ def self.get_instance_params(**kwargs)
536
+ current_relationship_only = kwargs[:relationship_is_current_only]
537
+ current_relationship_only = current_relationship_only.nil? || current_relationship_only ? 'true' : 'false'
538
+ {
539
+ ExternalStudentId: kwargs[:external_student_id] || '',
540
+ LancasterStudentId: kwargs[:lancaster_student_id ]|| '',
541
+ RelationshipIsCurrentOnly: current_relationship_only,
542
+ RelationshipIdentity: kwargs[:relationship_identity] || '',
543
+ UserLogin: kwargs[:user_login] || ''
544
+ }
545
+ end
546
+ end
547
+
548
+
549
+ end
550
+ end
551
+ end