Module: Get

Included in:
Openapply::Client
Defined in:
lib/openapply/get_student.rb,
lib/openapply/get_students.rb

Overview

MULTIPLE STUDENTS API GET CALLS

Instance Method Summary collapse

Instance Method Details

#check_details_keys_validity(flatten_keys, reject_keys) ⇒ Object

Check the validity of keys to process student_details

Attributes

  • flatten_keys - is an array of symbols

  • reject_keys - is an array of symbols



208
209
210
211
212
213
214
215
216
217
 
# File 'lib/openapply/get_student.rb', line 208

def check_details_keys_validity(flatten_keys, reject_keys)
  # # be sure flatten_keys are in an array
  return {error: "invalid flatten_keys - need array"}  unless flatten_keys.is_a? Array
  # # be sure reject_keys are in an array
  return {error: "invalid reject_keys - need array"}   unless reject_keys.is_a? Array
  # # test if any values are non-symbols (remain after removing symbols)
  return {error: "invalid flatten_keys - use symbols"} if flatten_keys.reject{|k| k.is_a? Symbol}.count > 0
  # # test if any values are non-symbols (remain after removing symbols)
  return {error: "invalid reject_keys - use symbols"}  if reject_keys.reject{|k| k.is_a? Symbol}.count > 0
end

#clean_data(value) ⇒ Object

return value & remove linebreaks & trim spaces (if a string)



129
130
131
132
 
# File 'lib/openapply/get_student.rb', line 129

def clean_data( value )
  return value.gsub("\n",' ').strip   if value.is_a? String
  return value
end

#flatten_array_vals(key, val, flatten_keys, reject_keys) ⇒ Object 



178
179
180
181
182
 
# File 'lib/openapply/get_student.rb', line 178

def flatten_array_vals(key, val, flatten_keys, reject_keys)
  return {} if val.empty?

  return {}
end

#flatten_hash_vals(key, val, flatten_keys, reject_keys) ⇒ Object 



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/openapply/get_student.rb', line 186

def flatten_hash_vals(key, val, flatten_keys, reject_keys)
  return {} if val.empty?

  answer = {}
  # un-nest a hash a to top level keys
  val.each do |k,v|
    # remove any nested values if they match a reject_key
    next if reject_keys.include? k

    # (prepend flatten_key_to_current_key to prevent conflicts)
    new_key = "#{key.to_s}_#{k.to_s}".to_sym
    # clean the data and add back to to top level with a new key
    answer[new_key] = clean_data(v)
  end                                if val.is_a? Hash
  return answer
end

#flatten_key_vals(key, val, flatten_keys, reject_keys) ⇒ Object 



163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/openapply/get_student.rb', line 163

def flatten_key_vals(key, val, flatten_keys, reject_keys)
  if val.is_a? Array
    return flatten_array_vals(key, val, flatten_keys, reject_keys)

  elsif val.is_a? Hash
    return flatten_hash_vals(key, val, flatten_keys, reject_keys)

  else
    return {}
  end

end

#flatten_record(hash, flatten_keys = [:flatten_no_keys], reject_keys = [:reject_no_keys]) ⇒ Object

This method preprocesses records - brings keys to the top level and removes fields and removes n from strings

Attributes

  • hash – **ONE students** student_details

  • flatten_keys – keys to bring to the top level (with top key prepended)

  • reject_keys – remove data matching these keys

TODO: add recursion?



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/openapply/get_student.rb', line 142

def flatten_record(hash, flatten_keys=[:flatten_no_keys],reject_keys=[:reject_no_keys])
  answer = {}

  # loop through each key value of the student record
  hash.each do |key,val|
    # skip loop if this key matches a value to remove
    next                               if reject_keys.include? key

    if flatten_keys.include? key
      answer.merge!( flatten_key_vals(key, val, flatten_keys, reject_keys) )
    else
      # put data back into hash if not to be flattened
      answer[key] = clean_data(val)  unless flatten_keys.include? key
    end
  end

  return answer
end

#payments_by_id(student_id, options = {}) ⇒ Object Also known as: payments

Payment details for ONE student

Attributes

  • student_id - openapply student_id

  • options - see httparty options

Example code

@demo = Openapply.new
@demo.payments_by_id(96)



37
38
39
40
 
# File 'lib/openapply/get_student.rb', line 37

def payments_by_id(student_id, options={})
  url = "#{api_path}#{student_id}/payments?auth_token=#{api_key}"
  return oa_answer( url, options )
end

#student_by_id(student_id, options = {}) ⇒ Object Also known as: student

Summary record for ONE student - this API return has the parent info 2x!

Attributes

# @student_id - openapply student_id

  • @options - see httparty options

Example code

@demo = Openapply.new
@demo.student_by_id(96)



18
19
20
21
 
# File 'lib/openapply/get_student.rb', line 18

def student_by_id(student_id, options ={})
  url = "#{api_path}#{student_id}?auth_token=#{api_key}"
  return oa_answer( url, options )
end

#student_details_by_id(id, flatten_keys = [], reject_keys = [], get_payments = true) ⇒ Object Also known as: student_details

Combines the student_by_id & payments_by_id into one call with all the data

Attributes

  • student_id - openapply student_id

  • flatten_keys - an array of keys to bring to the top level

(with this key prepened) – default (blank does nothing)

  • reject_keys - an array of keys to remove from the data – default (blank does nothing)

  • get_payments - default is true (but needs double lookup) - faster when false!

Usage

students_details_by_id(95)
students_details_by_id(95, [], [], false)
students_details_by_id(95, [:custom_fields], [:parent_guardian])
students_details_by_id(95, [:custom_fields], [:parent_guardian], false)

Returned Data

returns the data structured as:

{ student:
  { id: xxx,
    record: {xxx}      # complete student record
    guardians: [ {} ]  # all guardian information
    payments: [ {} ]   # all payments made via openapply
  }
}



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/openapply/get_student.rb', line 71

def student_details_by_id(id, flatten_keys=[], reject_keys=[], get_payments=true)

  check = check_details_keys_validity(flatten_keys, reject_keys)
  return check     unless check.nil? # or check[:error].nil?

  # get full student record and guardian information
  student_info = student_by_id( "#{id}" )
  # get student payment records
  payment_info = payments_by_id( "#{id}" )     if get_payments.eql? true

  # be sure there is student data to process -- if not return an empty record
  return {student: {id: id, empty: []}}        if student_info.nil? or
                                                  student_info[:student].nil?
                                                  student_info[:student].empty?
  student = []
  guardians = []
  # extract guardian information
  guardians = student_info[:linked][:parents].dup unless
                                                  student_info[:linked].nil? or
                                                  student_info[:linked].empty? or
                                                  student_info[:linked][:parents].nil?
  payments = []
  # extract payment information
  payments = payment_info[:payments].dup   unless payment_info.nil? or
                                                  payment_info[:payments].nil?
  # if flatten and reject are not set - set them so they do nothing
  flatten_keys = [:flatten_no_keys] if flatten_keys.nil? or flatten_keys.empty?
  reject_keys  = [:reject_no_keys]  if reject_keys.nil?  or reject_keys.empty?

  # extract the student info into the desired format (and removes \n in strings)
  # student = student_info[:student] - this is the effective result wo
  # flatten/reject keys
  student = flatten_record(student_info[:student], flatten_keys, reject_keys)

  # process guardian records - the same way student records
  # (loop on guardian arrary since there can be multiple parents)
  g_flat = []
  guardians = guardians.each do |guard|
    next                 if guard.empty?
    g_flat << flatten_record( guard, flatten_keys, reject_keys )
  end                unless guardians.empty?
  guardians = g_flat unless g_flat.empty?

  # organize the student details
  return { student:
            { id: id,
              record: student,
              payments: payments,
              guardians: guardians,
            }
          }
end

#student_ids_by_status(status) ⇒ Object Also known as: all_student_ids_by_status, student_ids_by_statuses

returns a list of student ids that match a give status (this is recursive - so returns the entire list - even if that list is longer than the api_return_count)

Attributes

status - a string matching one of the OA allowed statuses OR status can be an array of statuses (matching OA statuses)

Usage

student_ids_by_status('applied')
student_ids_by_statuses(['applied','enrolled'])

Return

{student_ids: [1, 3, 40]}

TODO: test with a mix of good and bad keys

only use good keys be sure count >= 1



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/openapply/get_students.rb', line 94

def student_ids_by_status(status)
  ids = []
  # when a single status is sent
  states = [status] if status.is_a? String
  states = status   if status.is_a? Array
  states.each do |state|
    answer = students_by_status(state)

    ids   += answer[:students].map{ |l| l[:id] } unless answer.nil? or
                                                    answer[:students].nil? or
                                                    answer[:students].empty?
  end
  return { student_ids: [] }       if ids.nil? or ids.empty?
  return { student_ids: ids }
end

#students_by_status(status) ⇒ Object Also known as: students

Returns a list of student summaries (in OpenApply’s format) that match a give status (this is recursive - so returns the entire list - even if that list is longer than the api_return_count)

Attributes

status - **MUST BE A STRING** returns the data as is from OpenApply

Usage

students_by_status('applied')



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/openapply/get_students.rb', line 124

def students_by_status(status)
  url = students_custom_url(status)
  answer = oa_answer( url )
  return { error: "nil" }             if answer[:students].nil?
  return { students: [] }             if answer[:students].empty?

  page_number = answer[:meta][:pages]
  return answer                       if page_number == 1

  # inspect meta data -- loop until page = 1 (all students found)
  all_students = answer[:students]
  while page_number > 1
    last_student = answer[:students].last
    since_id     = last_student[:id]
    url = students_custom_url(status,since_id)
    answer       = oa_answer( url )
    page_number  = answer[:meta][:pages]
    all_students += answer[:students]
  end
  return { students: all_students }
end

#students_details_by_status(status, flatten_keys = [], reject_keys = [], get_payments = true) ⇒ Object Also known as: students_details, students_details_by_statuses

Returns all student details (combines student, guardian and payments records)

Attributes

flatten_keys - brings these keys to the top level - prepending the group name to the key name – we usually use:

flatten_keys = [:custom_fields]

reject keys – removes the data matching these keys – we usually use:

reject_keys = [:parent_guardian] (since this is duplicated)

  • get_payments - default is true (but needs double lookup) - faster when false!

Usage

students_details_by_status('applied')
students_details_by_status('applied', [], [],false)
students_details_by_status('applied', [:custom_fields], [:parent_guardian])
students_details_by_status('applied', [:custom_fields], [:parent_guardian], false)
students_details_by_statuses(['applied','enrolled'])
students_details_by_statuses(['applied','enrolled'], [:custom_fields], [:parent_guardian])
students_details_by_statuses(['applied','enrolled'], [:custom_fields], [:parent_guardian], false)

Returned Data

returns the data structured as:

{ students:
  [
    { id: xxx,                     # openapply student id
      record: {xxx}                # complete student record
      guardians: [ {xxx}, {xxx} ]  # all guardian information
      payments: [ {xxx}, {xxx} ]   # all payments made via openapply
    },
    {
      id: xxx,                     # openapply student id
      record: {xxx}                # complete student record
      guardians: [ {xxx}, {xxx} ]  # all guardian information
      payments: [ {xxx}, {xxx} ]   # all payments made via openapply
    }
  ]
}



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/openapply/get_students.rb', line 45

def students_details_by_status( status, flatten_keys=[], reject_keys=[], get_payments=true )

  check = check_details_keys_validity(flatten_keys, reject_keys)
  return check     unless check.nil? # or check[:error].nil?

  ids = student_ids_by_status(status)
  return { error: 'answer nil' }  if ids.nil?
  return { error: 'ids nil' }     if ids[:student_ids].nil?
  return { students: [] }         if ids[:student_ids].empty?

  # loop through each student
  error_ids       = []
  student_records = []
  ids[:student_ids].each do |id|
    student = student_details_by_id( "#{id}", flatten_keys, reject_keys, get_payments )

    error_ids << id                          if student.nil? or
                                                student[:student].nil? or
                                                student[:student].empty?
    student_records << student[:student] unless student.nil? or
                                                student[:student].nil? or
                                                student[:student].empty?
  end
  return { students: student_records }
end

#students_query(status = nil, since_id = nil, since_date = nil, count = api_records) ⇒ Object Also known as: students_custom_query

Executes a custom query **(non-recursive)** to get a list of students summaries matching the allowed attribute’s criteria – used to build recursive or custom queries (within what is allowed by OpenApply API)

Attributes

  • status - match status (be sure it is in the list of OpenApply status)

  • since_id - get all ids matching the criteria LARGER than the given number

  • since_date - get all records updated after the given date (YYYY-MM-DD) or

Date and Time (YYYY-MM-DD HH:MM:SS) - 24 hour clock (not sure about timeszone)

  • count - return a custom number of records (no more than 1000)

Usage

students_query(nil, since_id=95, since_date=2017-01-01, count=2)

returned

{ students:
  [
    { student summary data from openapply api },
    { student summary data from openapply api },
  ]
}



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/openapply/get_students.rb', line 173

def students_query(status=nil, since_id=nil, since_date=nil, count=api_records)
  return { error: "invalid count" } unless count.to_i >= 1

  url    = students_custom_url(status, since_id, since_date, count)
  answer = oa_answer( url )
  return { error: "nil answer" }        if answer.nil?
  return { error: "nil students" }      if answer[:students].nil?
  return { students: [] }               if answer[:students].empty?
  return answer
end

#students_query_url(status = nil, since_id = nil, since_date = nil, count = api_records) ⇒ Object Also known as: students_custom_url

Builds a custom url (with domain) to get a list of students summaries matching the attribute’s criteria (but not do a Query) - returns a URL

Attributes

  • status - match status (be sure it is in the list of OpenApply status)

  • since_id - get all ids matching the criteria LARGER than the given number

  • since_date - get all records updated after the given date (YYYY-MM-DD) or

Date and Time (YYYY-MM-DD HH:MM:SS) - 24 hour clock (not sure about timeszone)

  • count - return a custom number of records (no more than 1000)

Return Format

“/api/v1/students/?status=applied&since_id=96&since_date=2017-01-25&count=2&auth_token=319d9axxxxxxx”



197
198
199
200
201
202
203
204
205
206
 
# File 'lib/openapply/get_students.rb', line 197

def students_query_url(status=nil, since_id=nil, since_date=nil, count=api_records)
  url_options = []
  url_options << "status=#{status}"         unless status.to_s.eql? ""
  url_options << "since_id=#{since_id}"     unless since_id.to_s.eql? ""
  url_options << "since_date=#{since_date}" unless since_date.to_s.eql? ""
  url_options << "count=#{count}"
  url_options << "auth_token=#{api_key}"

  return "#{api_path}?#{url_options.join('&')}"
end