ps_utilities 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c62242e43417fc95e14b36ba194604f4dfa79aac9e45887793ab982abedeb814
-  data.tar.gz: e0cf20edad5ba754ff741a99629e4554b38a831973dbb66ca51f61cdf74afc08
+  metadata.gz: 4abd4b17bf893e811f7e920887cc881baad21ffc7b43e112de022ac5240269e2
+  data.tar.gz: da43f677c4b59e491e352894061a96290406dea47ad6c6bb0f395715ebead669
 SHA512:
-  metadata.gz: 8603dbf338731a62a39f386b6458579e4f49a3eca1eb41b2320beedafa352792f2a539cae7abc9f043934c17ccaec84085b7d1a692ba8d66b90a0116a07f70c4
-  data.tar.gz: 2a300ec71565e9e48e081740b402b87f450ca83e1effcfaf3705a0090d46938923353204a217c53538521758ba0d35c32ae5e0d8748459158385d84a4ff6b2f7
+  metadata.gz: 299bbefec900eef22d92c605838e90358f6cae6a561828ba2229d813e0e5fcdccc0df95d145c13e2e40d6b7b0b03d79e54f9c03e531ddfb90c5911a6622f1382
+  data.tar.gz: edb76484fc23806fd56b1dd67573a8e2466513023340535f79437751c808423bb0a30025a182ba4141221eb8483efc0b2f5a22d80f1d08fed2faec0f0c4ae238

data/lib/ps_utilities/connection.rb

@@ -21,16 +21,20 @@ module PsUtilities
   # The PsUtilities, makes it east to work with the Powerschool API
   # @since 0.1.0
   #
-  # @note You should use environment variables to initialize your server.
+
   class Connection
 
-    attr_reader :credentials, :headers, :base_uri, :auth_path, :auth_token
+    attr_reader :credentials, :headers, :base_uri
+    attr_reader :auth_path, :auth_token
     attr_reader :version
 
     include PsUtilities::PreBuiltGet
     include PsUtilities::PreBuiltPut
     include PsUtilities::PreBuiltPost
 
+    # @param attributes: [Hash] -  options include: { base_uri: ENV['PS_URL'], auth_endpoint: (ENV['PS_AUTH_ENDPOINT'] || '/oauth/access_token'), client_id: ENV['PS_CLIENT_ID'], client_secret: ENV['PS_CLIENT_SECRET'] }
+    # @param headers: [Hash] - allows to change from json to xml (only do this if you are doing direct api calls and not using pre-built calls) returns and use a different useragent: { 'User-Agent' => "PsUtilities - #{version}", 'Accept' => 'application/json', 'Content-Type' => 'application/json'}
+    # @note preference is to use environment variables to initialize your server.
     def initialize(attributes: {}, headers: {})
       @version     = "v#{PsUtilities::Version::VERSION}"
       @credentials = attr_defaults.merge(attributes)
@@ -46,7 +50,12 @@ module PsUtilities
                                                       credentials[:base_uri].empty?
     end
 
-    # with no command it just checks authenticates if needed
+    # this runs the various options:
+    # @param command: [Symbol] - commands include direct api calls: :authenticate, :delete, :get, :patch, :post, :put (these require api_path: and options: params) & also pre-built commands - see included methods (they require params:)
+    # @param api_path: [String] - this is the api_endpoint (only needed for direct api calls)
+    # @param options: [Hash] - this is the data body or the query options (needed for direct api calls)
+    # @param params: [Hash] - this is the data needed for using pre-built commands - see the individual command for details
+    # @note with no command an authenticatation check is done
     def run(command: nil, api_path: "", options: {}, params: {})
       authenticate   unless token_valid?
       @headers[:headers].merge!('Authorization' => 'Bearer ' + authorized_token)
@@ -72,7 +81,9 @@ module PsUtilities
       retries = 3
       ps_url  = base_uri + api_path
       options = options.merge(headers)
+      pp "api-url"
       pp ps_url
+      pp "api-options"
       pp options
       begin
         HTTParty.send(verb, ps_url, options)

data/lib/ps_utilities/pre_built_get.rb

@@ -2,15 +2,32 @@ module PsUtilities
 
   module PreBuiltGet
 
+    # return all active students within the district (special case of #get_all_matching_students) - a recursive search
+    # @param params [Hash] - ignored - only included for the api standard
+    # @return - (see #get_all_matching_students)
     def get_all_active_students(params={})
-      params[:status_code] = 0
+      params = {status_code: 0}
+      # params[:status_code] = 0
       get_all_matching_students(params)
     end
-
-    # params = {username: "xxxxxxx"} or {local_id: "12345"}
-    # or       {enroll_status: "x"} or {status_code: "0"}
-    # or       {first_name: "John"} or {last_name: "Brown"}
-    # api_path = "/ws/v1/district/student?expansions=school_enrollment,contact&q=enroll_status==A;name.last_name==J*"
+    alias_method :all_active_students, :get_all_active_students
+    alias_method :active_students,     :get_all_active_students
+
+    # return all students within the district matching the filters are passed in -- this is a Recursive search and will collect all students
+    # @param params [Hash] - enter a match criteria in the following format (* are allowed for wildcard matching):
+    #     {username: "xxxxx*"} or {local_id: "12345"}
+    # or  {enroll_status: "x"} or {status_code: "0"}
+    # or  {first_name: "John"} or {last_name: "Br*"}
+    # or multiple field match
+    #     {status_code: "0", last_name: "Br*"}
+    # @return [Hash of an Array of Student Summaries] - see below format
+    # {students: [
+    #     {"id"=>4916, "local_id"=>112406, "student_username"=>"cccc406", "name"=>{"first_name"=>"Ssssss", "last_name"=>"CCCCC"}},
+    #     {"id"=>4932, "local_id"=>112520, "student_username"=>"jjjj520", "name"=>{"first_name"=>"Ppppppp", "last_name"=>"JJJJJJJJ"}},
+    #     {"id"=>4969, "local_id"=>112766, "student_username"=>"aaaa766", "name"=>{"first_name"=>"Sssss", "middle_name"=>"Aaaaaaaa", "last_name"=>"Aaaaaaaaaa"}}
+    #   ]
+    # }
+    # @note - the api_path sent to the api call looks like: "/ws/v1/district/student?expansions=school_enrollment,contact&q=enroll_status==A;name.last_name==J*"
     def get_all_matching_students(params)
       params[:page_size] ||= 100
       count    = get_matching_students_count(params)
@@ -26,15 +43,69 @@ module PsUtilities
       # return answer
       { students: students.flatten }
     end
-    # {students: [
-    #     {"id"=>4916, "local_id"=>112406, "student_username"=>"cccc406", "name"=>{"first_name"=>"Ssssss", "last_name"=>"CCCCC"}},
-    #     {"id"=>4932, "local_id"=>112520, "student_username"=>"jjjj520", "name"=>{"first_name"=>"Ppppppp", "last_name"=>"JJJJJJJJ"}},
-    #     {"id"=>4969, "local_id"=>112766, "student_username"=>"aaaa766", "name"=>{"first_name"=>"Sssss", "middle_name"=>"Aaaaaaaa", "last_name"=>"Aaaaaaaaaa"}}
-    #   ]
+    alias_method :all_matching_students, :get_all_matching_students
+    alias_method :matching_students,     :get_all_matching_students
+    alias_method :find_all_students,     :get_all_matching_students
+    alias_method :find_students,         :get_all_matching_students
+
+    # retrieves all individual student's details - you must use the DCID !!!
+    # @param params [Hash] - use either: {dcid: "12345"} or {id: "12345"}
+    # @return [Hash] - in the format of:
+    # { :student=>
+    #   { "@expansions"=> "demographics, addresses, alerts, phones, school_enrollment, ethnicity_race, contact, contact_info, initial_enrollment, schedule_setup, fees, lunch",
+    #     "@extensions"=> "s_stu_crdc_x,activities,c_studentlocator,u_students_extension,u_studentsuserfields,s_stu_ncea_x,s_stu_edfi_x,studentcorefields",
+    #     "_extension_data"=> {
+    #       "_table_extension"=> [
+    #         { "recordFound"=>false,
+    #           "_field"=> [
+    #             {"name"=>"preferredname", "type"=>"String", "value"=>"Guy"},
+    #             {"name"=>"student_email", "type"=>"String", "value"=>"guy@las.ch"}
+    #           ],
+    #           "name"=>"u_students_extension"
+    #         },
+    #         { "recordFound"=>false,
+    #           "_field"=> [
+    #             {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>1858},
+    #             {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"CH"},
+    #             {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"Bex"},
+    #             {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"VD"},
+    #             {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"LAS"},
+    #             {"name"=>"transcriptaddrline2", "type"=>"String", "value"=>"CP 108"}
+    #           ],
+    #           "name"=>"u_studentsuserfields"
+    #         }
+    #       ]
+    #     },
+    #     "id"=>7337,
+    #     "local_id"=>555807,
+    #     "student_username"=>"guy807",
+    #     "name"=>{"first_name"=>"Mountain", "last_name"=>"BIV"},
+    #     "demographics"=>{"gender"=>"M", "birth_date"=>"2002-08-26", "projected_graduation_year"=>2021},
+    #     "addresses"=>"",
+    #     "alerts"=>"",
+    #     "phones"=>"",
+    #     "school_enrollment"=> {
+    #       "enroll_status"=>"A",
+    #       "enroll_status_description"=>"Active",
+    #       "enroll_status_code"=>0,
+    #       "grade_level"=>9,
+    #       "entry_date"=>"2018-06-22",
+    #       "exit_date"=>"2019-08-06",
+    #       "school_number"=>2,
+    #       "school_id"=>2,
+    #       "full_time_equivalency"=>{"fteid"=>970, "name"=>"FTE Admissions"}
+    #     },
+    #     "ethnicity_race"=>{"federal_ethnicity"=>"NO"},
+    #     "contact"=>{"guardian_email"=>"guydad@orchid.ch"},
+    #     "contact_info"=>{"email"=>"guy@las.ch"},
+    #     "initial_enrollment"=>{"district_entry_grade_level"=>0, "school_entry_grade_level"=>0},
+    #     "schedule_setup"=>{"next_school"=>33, "sched_next_year_grade"=>10},
+    #     "fees"=>"",
+    #     "lunch"=>{"balance_1"=>"0.00", "balance_2"=>"0.00", "balance_3"=>"0.00", "balance_4"=>"0.00", "lunch_id"=>0}
+    #   }
     # }
-
-    # params = {dcid: "xxxxxxx"} or {id: "12345"}
-    def get_student(params)
+    # @note the data within "u_students_extension" - is unique for each school
+    def get_one_student(params)
       # api_path = "/ws/v1/district/student/{dcid}?expansions=school_enrollment,contact&q=student_username==xxxxxx237"
       ps_dcid    = params[:dcid] || params[:dc_id] || params[:id]
       api_path   = "/ws/v1/student/#{ps_dcid.to_i}"
@@ -48,105 +119,42 @@ module PsUtilities
       answer = api(:get, api_path, options)
       { student: (answer["student"] || []) }
     end
-
-    # params = {username: "xxxxxxx"} or {local_id: "12345"}
-    def find_student(params)
-      # api_path = "/ws/v1/district/student?expansions=school_enrollment,contact&q=student_username==xxxxxx237"
-      api_path   = "/ws/v1/district/student"
-      options    = { query:
-                    {"expansions" => "contact,contact_info,phones"}}
-      query  = []
-      query << "student_username==#{params[:username]}"  if params.has_key?(:username)
-      query << "local_id==#{params[:local_id]}"          if params.has_key?(:local_id)
-
-      options[:query]["q"] = query.join(";")
-      pp options
-      return {"errorMessage"=>{"message"=>"A valid parameter must be entered."}} if query.empty?
-
-      answer = api(:get, api_path, options)
-      { student: (answer.dig("students","student") || []) }
-    end
-    alias_method :find_student_by_local_id, :find_student
-    alias_method :find_student_by_username, :find_student
-    # {student:
-    #   {"id"=>5023,
-    #    "local_id"=>112193,
-    #    "student_username"=>"xxxxxxx193",
-    #    "name"=>{"first_name"=>"Aaaaaaaaa", "last_name"=>"EEEEEEEEE"},
-    #    "school_enrollment"=>
-    #      {"enroll_status"=>"A",
-    #       "enroll_status_description"=>"Active",
-    #       "enroll_status_code"=>0,
-    #       "grade_level"=>12,
-    #       "entry_date"=>"2017-08-25",
-    #       "exit_date"=>"2018-06-09",
-    #       "school_number"=>33,
-    #       "school_id"=>6,
-    #       "entry_comment"=>"Promote Same School",
-    #       "full_time_equivalency"=>{"fteid"=>1070, "name"=>"FTE Value: 1"}
-    #      },
-    #    "contact"=>
-    #       {"guardian_email"=>"parent1@example.fr,parent2@example.ch", "mother"=>"EEEEEEE, Vvvvv", "father"=>"EEEEEEEE, Sssssss"},
-    #    "contact_info"=>{"email"=>"xxxxxxx193@xxxx.de"}
-    #   }
-    # }
+    alias_method :get_student, :get_one_student
 
     private
-    # given page_size = 100
-    # 430 kids = 5 pages
-    # 400 kids = 4 pages
+
+    # given the number of students and page size calculate pages needed to return all students
+    # @param count [Integer] - total number of students matching filter
+    # @param page_size [Integer] - total number of students to be return per page
+    # For example:
+    #     given: page_size = 100
+    #     when: 430 kids, then: 5 pages
+    #     when: 400 kids, then: 4 pages
+    # @return [Integer] - number of pages needed to return all students
     def calc_pages(count, page_size)
-      max_page  = ( (count.to_i-1) / page_size.to_i ).to_i + 1
+      ( (count.to_i-1) / page_size.to_i ).to_i + 1
     end
-    # 5
 
     # api_path = "/ws/v1/district/student/count?q=school_enrollment.enroll_status_code==0"
     # returns: {"resource"=>{"count"=>423}}
+    # @return [Integer] - the number of students matching the filter
     def get_matching_students_count(params={})
       api_path = "/ws/v1/district/student/count"
 
-      query  = []
-      query << "student_username==#{params[:username]}"  if params.has_key?(:username)
-      query << "local_id==#{params[:local_id]}"          if params.has_key?(:local_id)
-      query << "name.last_name==#{params[:last_name]}"   if params.has_key?(:last_name)
-      query << "name.first_name==#{params[:first_name]}" if params.has_key?(:first_name)
-      query << "school_enrollment.enroll_status==#{params[:enroll_status]}"    if params.has_key?(:enroll_status)
-      query << "school_enrollment.enroll_status_code==#{params[:status_code]}" if params.has_key?(:status_code)
-
-      options = {query: {"q" => query.join(";")} }
-      pp options
+      query   = build_query(params)
+      options = {query: { "q" => query } }  unless query.empty?
       return {"errorMessage"=>{"message"=>"A valid parameter must be entered."}} if query.empty?
 
-      answer  = api(:get, api_path, options)  # {"resource"=>{"count"=>423}}
+      answer  = api(:get, api_path, options)  #returns: {"resource"=>{"count"=>423}}
       answer.dig("resource", "count").to_i
     end
-    # 423
 
+    # NOT RECURSIVE - simple call to get one page of student summaries
     # params = {username: "xxxxxxx"} or {local_id: "12345"}
     # or       {enroll_status: "x"} or {status_code: "0"}
     # or       {first_name: "John"} or {last_name: "Brown"}
     # api_path = "/ws/v1/district/student?expansions=school_enrollment,contact&q=student_username==xxxxxx237"
-    def get_matching_students_page(params)
-      api_path = "/ws/v1/district/student"
-      params[:page_size]   ||= 100
-      params[:page_number] ||= 1
-      pp params
-      options = { query:
-                  { "pagesize"    => "#{params[:page_size]}",
-                    "page"        => "#{params[:page_number]}"} }
-      query  = []
-      query << "student_username==#{params[:username]}"  if params.has_key?(:username)
-      query << "local_id==#{params[:local_id]}"          if params.has_key?(:local_id)
-      query << "name.last_name==#{params[:last_name]}"   if params.has_key?(:last_name)
-      query << "name.first_name==#{params[:first_name]}" if params.has_key?(:first_name)
-      query << "school_enrollment.enroll_status==#{params[:enroll_status]}"    if params.has_key?(:enroll_status)
-      query << "school_enrollment.enroll_status_code==#{params[:status_code]}" if params.has_key?(:status_code)
-
-      options[:query]["q"] = query.join(";")
-      return {"errorMessage"=>{"message"=>"A valid parameter must be entered."}} if query.empty?
-      pp options
-      api(:get, api_path, options)
-    end
+    # @return [Hash] - returns one page of students
     # {"students"=>
     #   {"@expansions"=>
     #     "demographics, addresses, alerts, phones, school_enrollment, ethnicity_race, contact, contact_info, initial_enrollment, schedule_setup, fees, lunch",
@@ -165,7 +173,38 @@ module PsUtilities
     #     ]
     #   }
     # }
+    def get_matching_students_page(params)
+      api_path = "/ws/v1/district/student"
+      params[:page_size]   ||= 100
+      params[:page_number] ||= 1
+      # pp params
+      options = { query:
+                  { "pagesize"    => "#{params[:page_size]}",
+                    "page"        => "#{params[:page_number]}"} }
+      query    = build_query(params)
+      options[:query]["q"] = query     unless query.empty?
+      return {"errorMessage"=>{"message"=>"A valid parameter must be entered."}} if query.empty?
+      # pp options
+      api(:get, api_path, options)
+    end
 
+    # build the api query - you can use splats to match any character
+    # @param params [Hash] - valid keys include: :status_code (or :enroll_status), :username, :last_name, :first_name, :student_id (or :local_id), :id (or :dcid)
+    # @return [String] - "id==345;name.last_name==BA*"
+    def build_query(params)
+      query  = []
+      query << "school_enrollment.enroll_status_code==#{params[:status_code]}" if params.has_key?(:status_code)
+      query << "school_enrollment.enroll_status==#{params[:enroll_status]}"    if params.has_key?(:enroll_status)
+      query << "student_username==#{params[:username]}"  if params.has_key?(:username)
+      query << "name.last_name==#{params[:last_name]}"   if params.has_key?(:last_name)
+      query << "name.first_name==#{params[:first_name]}" if params.has_key?(:first_name)
+      query << "local_id==#{params[:local_id]}"          if params.has_key?(:local_id)
+      query << "local_id==#{params[:student_id]}"        if params.has_key?(:student_id)
+      query << "id==#{params[:dcid]}"                    if params.has_key?(:dcid)
+      query << "id==#{params[:id]}"                      if params.has_key?(:id)
+      answer = query.join(";")
+      answer
+    end
 
   end
 

data/lib/ps_utilities/pre_built_post.rb

@@ -2,18 +2,20 @@ module PsUtilities
 
   module PreBuiltPost
 
-    # params[:students] (Array of Hashes) - kids with their attributes
-    # params = {dcid: 7531, student_id: 23456}
-    # or
-    # params = { [ {dcid: 7531, student_id: 23456},
-    #               {dcid: 9753, student_id: 65432} ] }
-    def create_students(params)
-      action   = "INSERT"
-      kids_api_array = build_kids_api_array(action, params)
-      options  = { body: { students: { student: kids_api_array } }.to_json }
-      answer = api(:post, "/ws/v1/student", options)
-    end
-    alias_method :create_student, :create_students
+    # this method CREATES or INSERTS a new student into PowerSchool
+    # @param params (Array of Hashes) - kids with their attributes
+    # example student entry
+    # @param params: { student: {dcid: 7531, student_id: 23456, email: "kid@las.ch"} }
+    # or multiple students (with ps and your school's database extensions)
+    # @param params: { students:
+    #   [ { dcid: 9753, student_id: 65432 },
+    #     { dcid: 7531, student_id: 23456, email: "kid@las.ch",
+    #       u_studentsuserfields: {transcriptaddrcity: "Bex"},
+    #       u_students_extension: {preferredname: "Joe"}
+    #     }
+    #   ]
+    # }
+    # @return [Hash]
     # { "results": {
     #     "update_count": 2
     #     "result": [
@@ -28,43 +30,152 @@ module PsUtilities
     #     ]
     #   }
     # }
+    def create_students(params)
+      action   = "INSERT"
+      kids_api_array = build_kids_api_array(action, params)
+      options  = { body: { students: { student: kids_api_array } }.to_json }
+      answer = api(:post, "/ws/v1/student", options)
+    end
+    alias_method :create_student, :create_students
 
-    # params[:students] (Array of Hashes) - kids with their attributes
+    # this updates and existing student record within PowerSchool
+    # (see #create_students)
     def update_students(params)
+      pp "update students"
+      pp params
       action = "UPDATE"
       kids_api_array = build_kids_api_array(action, params)
+      pp kids_api_array
       options  = { body: { students: { student: kids_api_array } }.to_json }
+      pp options
       answer = api(:post, "/ws/v1/student", options)
     end
     alias_method :update_student, :update_students
-    # { "results": {
-    #     "update_count": 2
-    #     "result": [
-    #       {  "client_uid": 124,
-    #          "status": "SUCCESS",
-    #          "action": "INSERT",
-    #          "success_message" :{
-    #            "id": 442,
-    #            "ref": "https://server/ws/v1/student/442" }
-    #        },
-    #        { ... }
+
+    # @param action [String] - either "INSERT" or "UPDATE"
+    # @param params [Array of Hashes] - in this format -- students: [{kid_1_info}, {kid_2_info}]
+    # @return [Array of Hashes] - with data like below:
+    #[ {:action=>"UPDATE",
+    #   :id=>7337,
+    #   :client_uid=>"555807",
+    #   :contact_info=>{:email=>"bassjoe@las.ch"},
+    #   "_extension_data"=> {
+    #     "_table_extension"=>  [
+    #       { "recordFound"=>false,
+    #         "name"=>"u_students_extension",
+    #         "_field"=> [
+    #           {"name"=>"preferredname", "type"=>"String", "value"=>"Joe"},
+    #           {"name"=>"student_email", "type"=>"String", "value"=>"bassjoe@las.ch"}
+    #         ]
+    #       },
+    #       { "recordFound"=>false,
+    #         "name"=>"u_studentsuserfields",
+    #         "_field"=> [
+    #           {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"LAS"},
+    #           {"name"=>"transcriptaddrline2", "type"=>"String", "value"=>"CP 108"},
+    #           {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"Leysin"},
+    #           {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>"1854"},
+    #           {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"Vaud"},
+    #           {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"CH"}
+    #         ]
+    #       }
     #     ]
     #   }
-    # }
-
+    #   { ...another_student_data... },
+    #]
+    # @note this is then sent to the API call with a body tag
     def build_kids_api_array(action, params)
-      unless params[:students].is_a? Array
+      pp "build_kids_api_array"
+      pp params
+      students  = []
+      api_array = []
+      students <<  params[:student]  if params[:student]
+      students  =  params[:students] if params[:students]
+      unless students.is_a? Array
         return {"errorMessage"=>{"message"=>"Student Data (in Hash format) must be in an Array."}}
       end
-      kids_api_array  = []
-      params[:students].each do |kid|
-        kid[:las_extensions] = true if params[:las_extensions]
-        kids_api_array << build_kid_attributes(action, kid)
+      students.each do |kid|
+        # kid[:las_extensions] = true if params[:las_extensions]
+        api_array << build_kid_attributes(action, kid)
+      end
+      return api_array
+    end
+
+    # prepare data to update student database extensions
+    # @param data [Hash] - with the format: {u_students_extension: {field1: data1, field2: data2}}
+    # @return [Hash] - with data like below:
+    # { "name"=>"u_students_extension",
+    #   "recordFound"=>false,
+    #   "_field"=> [
+    #     {"name"=>"preferredname", "type"=>"String", "value"=>"Joe"},
+    #     {"name"=>"student_email", "type"=>"String", "value"=>"joe@las.ch"},
+    #   ]
+    # }
+    def u_students_extension(data)
+      db_extensions = { "name"=>"u_students_extension", "recordFound"=>false,
+                        "_field"=> [] }
+      data.each do |key, value|
+        db_extensions["_field"] << {"name"=>"#{key}", "type"=>"String", "value"=>"#{value}"}
+      end
+      db_extensions
+    end
+
+    # prepare data to built-in database extensions
+    # @param data [Hash] - with the format: {u_studentsuserfields: {field1: data1, field2: data2}}
+    # @return [Hash] - with data like below:
+    # { "name"=>"u_students_extension",
+    #   "recordFound"=>false,
+    #   "_field"=> [
+    #     {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>75230},
+    #     {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"United States"},
+    #     {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"dallas"},
+    #     {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"Texas"},
+    #     {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"6138 meadow rd"}
+    #   ]
+    # }
+    def u_studentsuserfields(data)
+      db_extensions = { "name"=>"u_studentsuserfields", "recordFound"=>false,
+                        "_field"=> [] }
+      data.each do |key, value|
+        db_extensions["_field"] << {"name"=>"#{key}", "type"=>"String", "value"=>"#{value}"}
       end
-      return kids_api_array
+      db_extensions
     end
 
+    # prepare an indivdual's attributes to be sent to PowerSchool
+    # @param action [String, "UPDATE" or "INSERT"] - handles what powerschool should do
+    # @param kid [Hash] - one kid's attributes within a hash
+    # @return [Hash] - returns data in the below format:
+    # Data structure to send to API (with built-in PS extensions)
+    # { :action=>"UPDATE",
+    #   :id=>7337,
+    #   :client_uid=>"555807",
+    #   :contact_info=>{:email=>"bassjoe@las.ch"},
+    #   "_extension_data"=> {
+    #     "_table_extension"=>  [
+    #       { "recordFound"=>false,
+    #         "name"=>"u_students_extension",
+    #         "_field"=> [
+    #           {"name"=>"preferredname", "type"=>"String", "value"=>"Joe"},
+    #           {"name"=>"student_email", "type"=>"String", "value"=>"bassjoe@las.ch"}
+    #         ]
+    #       },
+    #       { "recordFound"=>false,
+    #         "name"=>"u_studentsuserfields",
+    #         "_field"=> [
+    #           {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"LAS"},
+    #           {"name"=>"transcriptaddrline2", "type"=>"String", "value"=>"CP 108"},
+    #           {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"Leysin"},
+    #           {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>"1854"},
+    #           {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"Vaud"},
+    #           {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"CH"}
+    #         ]
+    #       }
+    #     ]
+    #   }
     def build_kid_attributes(action, kid)
+      pp "build_kid_attributes"
+      pp kid
       # ALWAYS NEEDED INFO
       attribs                        = {action: action}
       attribs[:id]                   = kid[:id] || kid[:dcid]
@@ -100,7 +211,26 @@ module PsUtilities
         attribs[:name][:middle_name] = kid[:middle_name] if kid[:middle_name]
       end
 
-      # OPTIONAL
+      # OPTIONAL FIELDS
+      attribs[:address] = {}
+      if kid[:physical_street] or kid[:physical_city] or kid[:physical_state_province] or
+          kid[:physical_postal_code] or kid[:physical_grid_location]
+        attribs[:address][:physical] = {}
+        attribs[:address][:physical][:street] = kid[:physical_street]      if kid[:physical_street]
+        attribs[:address][:physical][:city]   = kid[:physical_city]        if kid[:physical_city]
+        attribs[:address][:physical][:state_province] = kid[:physical_state]    if kid[:physical_state]
+        attribs[:address][:physical][:postal_code]    = kid[:physical_postal_code] if kid[:physical_postal_code]
+        attribs[:address][:physical][:grid_location]  = kid[:physical_grid_location] if kid[:physical_grid_location]
+      end
+      if kid[:mailing_street] or kid[:mailing_city] or kid[:mailing_state_province] or
+          kid[:mailing_postal_code] or kid[:mailing_grid_location]
+        attribs[:address][:mailing] = {}
+        attribs[:address][:mailing][:street] = kid[:mailing_street]      if kid[:mailing_street]
+        attribs[:address][:mailing][:city]   = kid[:mailing_city]        if kid[:mailing_city]
+        attribs[:address][:mailing][:state_province] = kid[:mailing_state]    if kid[:mailing_state]
+        attribs[:address][:mailing][:postal_code]    = kid[:mailing_postal_code] if kid[:mailing_postal_code]
+        attribs[:address][:mailing][:grid_location]  = kid[:mailing_grid_location] if kid[:mailing_grid_location]
+      end
       attribs[:contact] = {}
       if kid[:emergency_phone1] && kid[:emergency_contact_name1]
         attribs[:contact][:emergency_phone1]        = kid[:emergency_phone1]
@@ -142,126 +272,24 @@ module PsUtilities
       attribs[:school_enrollment][:exit_date]      = kid[:exit_date]     if kid[:exit_date]
       attribs[:school_enrollment][:school_number]  = kid[:school_number] if kid[:school_number]
       #
-      attribs[:contact_info]     = {email: kid[:email]}           if kid[:email]
-      attribs[:phone]            = {main: {number: kid[:mobile]}} if kid[:mobile]
+      attribs[:contact_info]     = {email: kid[:email]}                  if kid[:email]
+      attribs[:phone]            = {main: {number: kid[:mobile]}}        if kid[:mobile]
 
       # Update LAS Database Extensions as needed
-      attribs["_extension_data"] = calc_las_extensions(kid)      if kid[:las_extensions].to_s.eql?("true")
+      attribs["_extension_data"] = { "_table_extension" => [] }
+      # built-in extensions by PowerSchool
+      attribs["_extension_data"]["_table_extension"] << u_studentsuserfields(kid[:u_studentsuserfields])
+      # school defined database extensions
+      attribs["_extension_data"]["_table_extension"] << u_students_extension(kid[:u_students_extension])
+      # if no extension data present make it empty
+      attribs["_extension_data"] = {}                if attribs["_extension_data"]["_table_extension"].empty?
 
-      # return attributes - first remove, nils, empty strings and empty hashes
+      # remove, nils, empty strings and empty hashes
       answer = attribs.reject { |k,v| v.nil? || v.to_s.empty? || v.to_s.eql?("{}")}
-      pp answer
+      # pp "kid-attributes"
+      # pp answer
       return answer
     end
-    # Data structure to send to API
-    # options = {body: {
-    #      "students":{
-    #         "student":[
-    #            {
-    #               "client_uid":"124",
-    #               "action":"UPDATE",
-    #               "id":"442",
-    #               "name":{
-    #                  "first_name":"Aaronia",
-    #                  "last_name":"Stephaniia"
-    #               },
-    #            },
-    #            { ... }
-    #         ]
-    #      }
-    #   }
-    # }
-
-    def calc_las_extensions(kid)
-      # attribs = {}
-      # attribs["_table_extension"] = []
-      attribs = { "_table_extension" => [] }
-      if kid[:email] or kid[:preferred_name]
-        db_extensions =
-          { "recordFound"=>false,
-            "name"=>"u_students_extension",
-            "_field"=> [ ]
-          }
-        if kid[:email]
-          db_extensions["_field"] << {"name"=>"student_email", "type"=>"String", "value"=>"#{kid[:email]}"}
-        end
-        if kid[:preferredname]
-          db_extensions["_field"] << {"name"=>"preferredname", "type"=>"String", "value"=>"#{kid[:preferredname]}"}
-        end
-        if kid[:preferred_name]
-          db_extensions["_field"] << {"name"=>"preferredname", "type"=>"String", "value"=>"#{kid[:preferred_name]}"}
-        end
-        attribs["_table_extension"] << db_extensions
-        # { "recordFound"=>false,
-        #   "name"=>"u_students_extension",
-        #   "_field"=> [
-        #     {"name"=>"preferredname", "type"=>"String", "value"=>"Niko"},
-        #     {"name"=>"student_email", "type"=>"String", "value"=>"#{kid[:email]}"}
-        #   ]
-        # }
-      end
-      if kid[:transcriptaddrline1] or kid[:transcriptaddrline2] or
-          kid[:transcriptaddrcity] or kid[:transcriptaddrstate] or
-          kid[:transcriptaddrzip]  or kid[:transcriptaddrcountry]
-        db_extensions =
-          { "recordFound"=>false,
-            "name"=>"u_studentsuserfields",
-            "_field"=> [ ]
-          }
-        if kid[:transcriptaddrline1]
-          db_extensions["_field"] << {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"#{kid[:transcriptaddrline1]}"}
-        end
-        if kid[:transcriptaddrline2]
-          db_extensions["_field"] << {"name"=>"transcriptaddrline2", "type"=>"String", "value"=>"#{kid[:transcriptaddrline2]}"}
-        end
-        if kid[:transcriptaddrcity]
-          db_extensions["_field"] << {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"#{kid[:transcriptaddrcity]}"}
-        end
-        if kid[:transcriptaddrzip]
-          db_extensions["_field"] << {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>"#{kid[:transcriptaddrzip]}"}
-        end
-        if kid[:transcriptaddrstate]
-          db_extensions["_field"] << {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"#{kid[:transcriptaddrstate]}"}
-        end
-        if kid[:transcriptaddrcountry]
-          db_extensions["_field"] << {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"#{kid[:transcriptaddrcountry]}"}
-        end
-        attribs["_table_extension"] << db_extensions
-        # { "recordFound"=>false,
-        #   "name"=>"u_studentsuserfields",
-        #   "_field"=> [
-        #     {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>75230},
-        #     {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"United States"},
-        #     {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"dallas"},
-        #     {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"Texas"},
-        #     {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"6138 meadow rd"}
-        #   ]
-        # }
-      end
-      pp attribs
-      attribs
-    end
-    # to inject into _extension_data
-    # { "_table_extension"=> [
-    #     { "recordFound"=>false,
-    #       "name"=>"u_students_extension",
-    #       "_field"=> [
-    #         {"name"=>"preferredname", "type"=>"String", "value"=>"Jimmy"},
-    #         {"name"=>"student_email", "type"=>"String", "value"=>"bbaaccdd@las.ch"}
-    #       ]
-    #     },
-    #     { "recordFound"=>false,
-    #       "name"=>"u_studentsuserfields",
-    #       "_field"=> [
-    #         {"name"=>"transcriptaddrzip", "type"=>"String", "value"=>8154},
-    #         {"name"=>"transcriptaddrcountry", "type"=>"String", "value"=>"Switzerland"},
-    #         {"name"=>"transcriptaddrcity", "type"=>"String", "value"=>"Leysin"},
-    #         {"name"=>"transcriptaddrstate", "type"=>"String", "value"=>"Vaud"},
-    #         {"name"=>"transcriptaddrline1", "type"=>"String", "value"=>"6789 linden st"}
-    #       ]
-    #     }
-    #   ]
-    # }
 
   end
 

data/lib/ps_utilities/version.rb

@@ -1,5 +1,5 @@
 module PsUtilities
   module Version
-    VERSION = "0.3.1"
+    VERSION = "0.3.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ps_utilities
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Lee Weisbecker
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-26 00:00:00.000000000 Z
+date: 2018-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -77,7 +77,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/ps_utilities.rb
-- lib/ps_utilities/api_endpoints.rb
 - lib/ps_utilities/connection.rb
 - lib/ps_utilities/pre_built_get.rb
 - lib/ps_utilities/pre_built_post.rb

data/lib/ps_utilities/api_endpoints.rb

@@ -1,166 +0,0 @@
-module PsUtilities
-
-  module ApiEndpoints
-
-    API_PATHS = {
-      ws: '/ws/v1',
-      ptg: '/powerschool-ptg-api/v2/',
-      xte: '/ws/xte'
-    }
-
-    def initialize(api_credentials, options = {})
-      self.client = Class.new(Powerschool::Client) do |klass|
-        uri = api_credentials['base_uri'] || Powerschool::Client::BASE_URI
-        klass.base_uri(uri)
-
-        # options like `verify: false` (to disable ssl verification)
-        options.each do |k, v|
-          default_options.update({k => v})
-        end
-      end.new(api_credentials)
-    end
-
-    class << self
-      [:get, :post, :put, :delete].each do |command|
-        define_method(command.to_s) do |method, api, path = nil|
-          if path.nil?
-            path, api = api, nil
-          end
-          define_method(method) do |options = {}|
-            return self.client.class.send(command, prepare_path(path.dup, api, options), self.client.options.merge(options))
-          end
-        end
-      end
-    end
-
-    def prepare_path(path, api, options)
-      options = options.dup
-      options.each_pair do |key, value|
-        regexp_path_option = /(:#{key}$|:#{key}([:&\/-_]))/
-        if path.match(regexp_path_option)
-          if value.blank?
-            raise "Blank value for parameter '%s' in '%s'" % [key, path]
-          end
-          path.gsub!(regexp_path_option, "#{value}\\2")
-          options.delete(key)
-        end
-      end
-      if parameter = path.match(/:(\w*)/)
-        raise "Missing parameter '%s' in '%s'. Parameters: %s" % [parameter[1], path, options]
-      end
-      if api
-        path = (API_PATHS[api] + path).gsub('//', '/')
-      end
-      path
-    end
-
-    # retreive max_page_size from metadata. Defaults to 100
-    def get_page_size(resource)
-      @metadata ||= self.metadata()
-      @metadata['%s_max_page_size' % resource.split('/').last.singularize] rescue 100
-    end
-
-    # Process every object for a resource.
-    def all(resource, options = {}, &block)
-      page_size = (options[:query][:pagesize] rescue nil) || get_page_size(resource)
-      _options = options.dup
-      _options[:query] ||= {}
-      _options[:query][:pagesize] ||= page_size
-
-      page = 1
-      results = []
-      begin
-        _options[:query][:page] = page
-        response = self.send(resource, _options)
-        results = response.parsed_response || {}
-        if !response.parsed_response
-          if response.headers['www-authenticate'].match(/Bearer error/)
-            raise response.headers['www-authenticate'].to_s
-          end
-        end
-
-        if results.is_a?(Hash)
-          plural = results.keys.first
-          results = results[plural][plural.singularize] || []
-        end
-        if results.is_a?(Hash)
-          # a rare(?) case has been observed where (in this case section_enrollment) did return a single
-          # data object as a hash rather than as a hash inside an array
-          results = [results]
-        end
-        results.each do |result|
-          block.call(result, response)
-        end
-        page += 1
-      end while results.any? && results.size == page_size
-    end
-
-    # client is set up per district so it returns only one district
-    # for urls with parameters
-    get :district, :ws, '/district'
-    get :schools, :ws, '/district/school'
-    get :teachers, :ws, '/staff'
-    get :student, :ws, '/student/:student_id'
-    get :students, :ws, '/student'
-    get :school_teachers, :ws, '/school/:school_id/staff'
-    get :school_students, :ws, '/school/:school_id/student'
-    get :school_sections, :ws, '/school/:school_id/section'
-    get :school_courses, :ws, '/school/:school_id/course'
-    get :school_terms, :ws, '/school/:school_id/term'
-    get :section_enrollment, :ws, '/section/:section_id/section_enrollment'
-
-    # PowerTeacher Gradebook (pre Powerschool 10)
-    get :assignment, :ptg, 'assignment/:id'
-    post :post_section_assignment, :ptg, '/section/:section_id/assignment'
-    put :put_assignment_scores, :ptg, '/assignment/:assignment_id/score'
-    put :put_assignment_score, :ptg, '/assignment/:assignment_id/student/:student_id/score'
-
-    # PowerTeacher Pro
-    post :xte_post_section_assignment, :xte, '/section/assignment?users_dcid=:teacher_id'
-    put :xte_put_assignment_scores, :xte, '/score'
-    get :xte_section_assignments, :xte, '/section/assignment?users_dcid=:teacher_id&section_ids=:section_id'
-    get :xte_section_assignment, :xte, '/section/assignment/:assignment_id?users_dcid=:teacher_id'
-    get :xte_teacher_category, :xte, '/teacher_category'
-
-    get :metadata, :ws, '/metadata'
-    get :areas, '/ws/schema/area'
-    get :tables, '/ws/schema/table'
-    get :table_records, '/ws/schema/table/:table?projection=:projection'
-    get :table_metadata, '/ws/schema/table/:table/metadata'
-    get :area_table, '/ws/schema/area/:area/table'
-
-    get :queries, '/ws/schema/query/api'
-
-    def start_year
-      offset = Date.today.month <= 6 ? -1 : 0
-      year = self.client.api_credentials['start_year'] || (Date.today.year + offset)
-    end
-
-    # Special method to filter terms and find the current ones
-    def current_terms(options, today = nil)
-      terms = []
-      today ||= Date.today.to_s(:db)
-      self.all(:school_terms, options) do |term, response|
-        if term['end_date'] >= today
-          terms << term
-        end
-      end
-      if terms.empty?
-        options[:query] = {q: 'start_year==%s' % start_year}
-        self.all(:school_terms, options) do |term, response|
-          if term['end_date'] >= today
-            terms << term
-          end
-        end
-      end
-      # now filter again for the start date and if there isn't one matching we have to return the most recent one
-      in_two_weeks = (Date.parse(today) + 2.weeks).to_s(:db)
-      active_terms = terms.select{|term| term['start_date'] <= in_two_weeks }
-      if active_terms.any?
-        return active_terms
-      end
-      return terms
-    end
-
-  end
-end