openapply 0.2.0 → 0.2.1

data/lib/openapply/get_student.rb

@@ -1,125 +1,21 @@
 module Get
 
-  # Record details for ONE student - this API return has the parent info 2x!
+  # SINGLE STUDENT CODE
+  #####################
+
+
+  # STUDENT FULL RECORD
+  #####################
+
+  # Summary record for ONE student - this API return has the parent info 2x!
   #
-  # @param
   # ==== Attributes
-  # * +student_id+ - openapply student_id
-  # * +options+ - see httparty options
+  # # @student_id - openapply student_id
+  # * @options - see httparty options
   #
   # ==== Example code
   #  @demo = Openapply.new
   #  @demo.student_by_id(96)
-  #
-  # ==== Result
-  # {:student=>
-  #   {:id=>96,
-  #    :serial_number=>86,
-  #    :custom_id=>"86",
-  #    :applicant_id=>"00000086",
-  #    :email=>"Jerry.Patel@eduvo.com",
-  #    :first_name=>"Jerry",
-  #    :last_name=>"Patel",
-  #    ...,
-  #    :profile_photo=>
-  #     "https://openapply-sandbox-devel-01.s3.amazonaws.com/uploads/student/avatar/000/000/096/m_9.jpg?v=1499755604",
-  #    :profile_photo_updated_at=>"2017-07-11T14:46:44.000+08:00",
-  #    :custom_fields=>
-  #     {:language=>"Hindi",
-  #      :nationality=>"Indian (India)",
-  #      :referral_source=>"Friends",
-  #      :middle_name_s=>"Danesh",
-  #      :mobile_phone=>"852 4545 1195",
-  #      ...,
-  #      :school_file=>
-  #       {:id=>73,
-  #        :filename=>"Robert_Patel_Report.pdf",
-  #        :url=>"https://demo.openapply.com/api/v1/secure_download/files/73"},
-  #      :has_your_child_attended_school_regularly=>"Yes",
-  #      ...,
-  #      :parent_guardian=>
-  #       [{:id=>268,
-  #         :serial_number=>257,
-  #         :custom_id=>"257",
-  #         :name=>"James Patel",
-  #         :first_name=>"James",
-  #         :last_name=>"Patel",
-  #         ...,
-  #         :custom_fields=>
-  #          {:title=>"CFO",
-  #           :treat_parent_as_emergency_contact=>"Yes",
-  #           :home_telephone=>"",
-  #           ...,
-  #           :parent_residency=>"Citizen"}},
-  #        {:id=>267,
-  #         :serial_number=>256,
-  #         :custom_id=>"256",
-  #         ...,
-  #         :profile_photo=>
-  #          "https://openapply-sandbox-devel-01.s3.amazonaws.com/uploads/parent/avatar/000/000/267/patel_mom.jpg?v=1499755607",
-  #         :profile_photo_updated_at=>"2017-07-11T14:46:47.000+08:00",
-  #         :parent_id=>"256",
-  #         :custom_fields=>
-  #          {:title=>"",
-  #           :treat_parent_as_emergency_contact=>"Yes",
-  #           ...,
-  #           :parent_prior_countries_list=>nil,
-  #           :parent_residency=>"Citizen"}}],
-  #      :siblings_information=>
-  #       [{:first_name=>"Deidre",
-  #         :last_name=>"Patel",
-  #         :gender=>"Female",
-  #         :birth_date=>"2008-06-06"}],
-  #      :emergency_contact=>[],
-  #      :prior_school_list=>
-  #       [{:school_name=>"Michael Varner Elementary",
-  #         :school_country=>"United States",
-  #         :school_contact_name=>"Ann Farris",
-  #         :school_contact_phone=>"(415) 777-0876"},
-  #        {:school_name=>"ISS International School",
-  #         :school_contact_name=>"Taylor Michaels",
-  #         :school_contact_phone=>"65 6235 5844",
-  #         :school_country=>"Singapore"}],
-  #      :immunization_record=>[],
-  #      :health_information=>[]},
-  #    :parent_ids=>[268, 267]},
-  #  :linked=>
-  #     {:parents=>
-  #       [{:id=>268,
-  #         :serial_number=>257,
-  #         :custom_id=>"257",
-  #         :name=>"James Patel",
-  #         :first_name=>"James",
-  #         :last_name=>"Patel",
-  #         ...,
-  #         :address=>"1641 26th Avenue",
-  #         :address_ii=>"",
-  #         :city=>"San Francisco",
-  #         :state=>"California",
-  #         :postal_code=>"94122",
-  #         :country=>"United States",
-  #         ...,
-  #         :custom_fields=>
-  #          {:title=>"CFO",
-  #           :treat_parent_as_emergency_contact=>"Yes",
-  #           :home_telephone=>"",
-  #           ...,
-  #           :parent_residency=>"Citizen"}},
-  #        {:id=>267,
-  #         :serial_number=>256,
-  #         :custom_id=>"256",
-  #         :name=>"Jane Patel",
-  #         :first_name=>"Jane",
-  #         ...,
-  #         :profile_photo=>
-  #          "https://openapply-sandbox-devel-01.s3.amazonaws.com/uploads/parent/avatar/000/000/267/patel_mom.jpg?v=1499755607",
-  #         :profile_photo_updated_at=>"2017-07-11T14:46:47.000+08:00",
-  #         :parent_id=>"256",
-  #         :custom_fields=>
-  #          {:title=>"",
-  #           :treat_parent_as_emergency_contact=>"Yes",
-  #           ...,
-  #           :parent_residency=>"Citizen"}}]}}
   def student_by_id(student_id, options ={})
     url = "#{api_path}#{student_id}?auth_token=#{api_key}"
     return oa_answer( url, options )
@@ -127,6 +23,9 @@ module Get
   alias_method :student, :student_by_id
 
 
+  # STUDENT PAYMENT INFO
+  ######################
+
   # Payment details for ONE student
   #
   # ==== Attributes
@@ -136,17 +35,6 @@ module Get
   # ==== Example code
   #  @demo = Openapply.new
   #  @demo.payments_by_id(96)
-  #
-  # ==== Result
-  # {:payments=>
-  #   [{:invoice_status=>"Paid",
-  #     :type=>"Application",
-  #     :invoice_number=>1047,
-  #     :amount=>"90.0",
-  #     :issue_date=>"2016-03-11",
-  #     :due_date=>"2016-03-31",
-  #     :payment_method=>"check",
-  #     :payment_date=>"2013-03-07"}]}
   def payments_by_id(student_id, options={})
     url = "#{api_path}#{student_id}/payments?auth_token=#{api_key}"
     return oa_answer( url, options )
@@ -154,119 +42,73 @@ module Get
   alias_method :payments, :payments_by_id
 
 
+  # STUDENT FULL RECORD AND PAYMENTS COMBINED
+  ###########################################
+
   # 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)
   #
-  # ==== Example code
-  #  @demo = Openapply.new
-  #  @demo.student_details_by_id(96)
-  #
-  # ==== Results
-  # NOTE: gaurdian info is moved to the top level - along with ID
-  #  {student: {
-  #       id=95,
-  #       record: {},
-  #       guardians: [],
-  #       payments: []
-  #    }
-  #  }
-  #
-  # for example:
-  #
-  # {:student=>
-  #   {:id=>96,
-  #    :record=>
-  #     {:id=>96,
-  #      :serial_number=>86,
-  #      :custom_id=>"86",
-  #      :applicant_id=>"00000086",
-  #      :email=>"Jerry.Patel@eduvo.com",
-  #      :first_name=>"Jerry",
-  #      :last_name=>"Patel",
-  #      ...,
-  #      :profile_photo=>
-  #       "https://openapply-sandbox-devel-01.s3.amazonaws.com/uploads/student/avatar/000/000/096/m_9.jpg?v=1499755604",
-  #      :profile_photo_updated_at=>"2017-07-11T14:46:44.000+08:00",
-  #      :custom_fields=>
-  #       {:language=>"Hindi",
-  #        :nationality=>"Indian (India)",
-  #        :referral_source=>"Friends",
-  #        ...,
-  #        :siblings_information=>
-  #         [{:first_name=>"Deidre",
-  #           :last_name=>"Patel",
-  #           :gender=>"Female",
-  #           :birth_date=>"2008-06-06"}],
-  #        :emergency_contact=>[],
-  #        :immunization_record=>[],
-  #        :health_information=>[]},
-  #      :parent_ids=>[268, 267]},
-  #    :payments=>
-  #     [{:invoice_status=>"Paid",
-  #       :type=>"Application",
-  #       :invoice_number=>1047,
-  #       :amount=>"90.0",
-  #       :issue_date=>"2016-03-11",
-  #       :due_date=>"2016-03-31",
-  #       :payment_method=>"check",
-  #       :payment_date=>"2013-03-07"}],
-  #    :guardians=>
-  #     [{:id=>268,
-  #       :serial_number=>257,
-  #       :custom_id=>"257",
-  #       :name=>"James Patel",
-  #       :first_name=>"James",
-  #       :last_name=>"Patel",
-  #       ...,
-  #       :custom_fields=>
-  #        {:title=>"CFO",
-  #         :treat_parent_as_emergency_contact=>"Yes",
-  #         :home_telephone=>"",
-  #         ...,
-  #         :parent_residency=>"Citizen"}},
-  #      {:id=>267,
-  #       :serial_number=>256,
-  #       :custom_id=>"256",
-  #       :name=>"Jane Patel",
-  #       :first_name=>"Jane",
-  #       :last_name=>"Patel",
-  #       ...,
-  #       :profile_photo=>
-  #        "https://openapply-sandbox-devel-01.s3.amazonaws.com/uploads/parent/avatar/000/000/267/patel_mom.jpg?v=1499755607",
-  #       :profile_photo_updated_at=>"2017-07-11T14:46:47.000+08:00",
-  #       :parent_id=>"256",
-  #       :custom_fields=>
-  #        {:title=>"",
-  #         :treat_parent_as_emergency_contact=>"Yes",
-  #         :home_telephone=>"",
-  #         ...,
-  #         :parent_residency=>"Citizen"}}]}}
-  def student_details_by_id(id, flatten = 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
+  #     }
+  #   }
+  def student_details_by_id(id, flatten_keys=[], reject_keys=[])
+
+    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}" )
 
-    # be sure there is data to process
-    return {student: {id: id, empty: []}}    if student_info.nil? or
-                                                student_info[:student].nil?
-                                                student_info[:student].empty?
+    # 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?
+                                                    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?
-    # process meaningful data
-    record = student_info[:student].dup
-    # remove duplicated parental data fields
-    record[:custom_fields][:parent_guardian] = nil
+                                                    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: record,
+                record: student,
                 payments: payments,
                 guardians: guardians,
               }
@@ -274,4 +116,64 @@ module Get
   end
   alias_method :student_details, :student_details_by_id
 
+  # UTILITIES
+  ###########
+
+  # return value & remove linebreaks & trim spaces (if a string)
+  def clean_data( value )
+    return value.gsub("\n",' ').strip   if value.is_a? String
+    return value
+  end
+
+  # 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?
+  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
+
+      # put data back into hash if not to be flattened
+      answer[key] = clean_data(val)  unless flatten_keys.include? key
+
+      # if current key matches a flatten value & HAS nested data values
+      # then bring nested data to top level
+      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 flatten_keys.include?(key) and
+                                            not val.empty?
+    end
+    return answer
+  end
+
+  # Check the validity of keys to process student_details
+  #
+  # === Attributes
+  # * +flatten_keys+ - is an array of symbols
+  # * +reject_keys+ - is an array of symbols
+  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
+
 end