ps_utilities 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30083f1244c4e8ea1a53ab81b8f88ac3c10d177fb651218cfcbe9dca8bdc219f
-  data.tar.gz: c7f3991b61f85c224c48ca2bb3c172b8a2b24b50d28a8e14e1b80e9e5f831c4d
+  metadata.gz: 823ebc095fd0fe70b224f173aef9a951e1d1a9acd4bf14ad037895d0832f1ef6
+  data.tar.gz: 23e29507f3fc51e63cc9a640377bd2e3c437fd624652f387c9931aa93b09c720
 SHA512:
-  metadata.gz: 848cfcbb6cf7b71d1e205ac04c21ac14a7b75be92b47db43effa58d6d455ac5b20a90e0d022070e0f9c0e4e1925599fca75493ec5a8f30047205b13a758fbae3
-  data.tar.gz: f72b28802331533bb855536a2dcbf1ece95bab2fc3a4d09b7aeca883b4a1003c9d3ef1d2d403dd86d55b64ff5e641467f84125b86766370f8e10de41cdda0f66
+  metadata.gz: 512c0c6e1b8c9d5da4426c7c5e15ee4a478c24fab18521d08371e4d1c71521a58873267a7b93f7808cacfced820914e658416cc58f1e0ba4ca91cf186709abc0
+  data.tar.gz: 35875ad1cee3a496c645c76f8bcedd1a689428e51642ab7cbcab8da28cd97301026dbc9f2aa884a1073d841cfcd999163e2e42afc2ce210f2a4fb70512bfff13

data/lib/ps_utilities/connection.rb

@@ -33,10 +33,11 @@ module PsUtilities
     include PsUtilities::PreBuiltPut
     include PsUtilities::PreBuiltPost
 
-    # @param attributes: [Hash] -  options include: { base_uri: ENV['PS_BASE_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'}
+    # @param api_info: [Hash] -  allows override of api settings :base_uri (overrides ENV['PS_BASE_URI']) and :auth_path (overrides ENV['PS_ATUH_ENDPOINT'])
+    # @param client_info: [Hash] - allows override of client login values :client_id (overrides ENV['PS_CLIENT_ID']) & :client_secret (overrides ENV['PS_CLIENT_SECRET'])
     # @note preference is to use environment variables to initialize your server.
-    def initialize( header_info: {}, api_info: {}, client_info: {})
+    # def initialize( header_info: {}, api_info: {}, client_info: {})
+    def initialize( api_info: {}, client_info: {})
       @version       = "v#{PsUtilities::Version::VERSION}"
       @client        = client_defaults.merge(client_info)
       @client_id     = client[:client_id]
@@ -44,7 +45,8 @@ module PsUtilities
       @api_data      = api_defaults.merge(api_info)
       @base_uri      = api_data[:base_uri]
       @auth_path     = api_data[:auth_endpoint]
-      @headers       = header_defaults.merge(header_info)
+      @headers       = header_defaults  # Auth key is added when authenticate is executed
+      # @headers['Authorization'] = header_info['Authorization'] if header_info['Authorization']
 
       raise ArgumentError, "missing client_secret" if client_secret.nil? or client_secret.empty?
       raise ArgumentError, "missing client_id"     if client_id.nil? or client_id.empty?
@@ -78,8 +80,10 @@ module PsUtilities
       "#{auth_info['access_token']}"
     end
 
-    # verb = :delete, :get, :patch, :post, :put
-    # options = {query: {}, body: {}} - get uses :query, put and post use :body
+    # Direct API access
+    # @param verb [Symbol] hmtl verbs (:delete, :get, :patch, :post, :put)
+    # @param options [Hash] allowed keys are {query: {}, body: {}} - uses :query for gets, and use :body for put and post
+    # @return [HTTParty] - useful things to access include: obj.parsed_response (to access returned data) & obj.code to be sure the response was successful "200"
     def api(verb, api_path, options={})
       count   = 0
       retries = 3
@@ -97,6 +101,8 @@ module PsUtilities
       end
     end
 
+    # by this code sends and recieves json data - only overide if building your own data and sending directly via the API methods :get, :put, :post, etc.
+    # @note do not override these Settings - if using the pre-build commands
     def header_defaults
       { headers:
         { 'User-Agent' => "PsUtilities - #{version}",
@@ -106,11 +112,18 @@ module PsUtilities
       }
     end
 
-    # In PowerSchool go to System>System Settings>Plugin Management Configuration>your plugin>Data Provider Configuration to manually check plugin expiration date
+    # gets API auth token and puts in header HASH for future requests with PS server
+    # @return [Hash] - of auth token and time to live from powerschol server
+    # {'access_token' => "addsfabe-aads-4444-bbbb-444411ffffbb",
+    #  'token_type' => "Bearer",
+    #  'expires_in' => "2504956"
+    #  'token_expires' => (Time.now + 3600)}
+    # @note - to enable PS API - In PowerSchool go to System>System Settings>Plugin Management Configuration>your plugin>Data Provider Configuration to manually check plugin expiration date
     def authenticate
       ps_url   = base_uri + auth_path
-      response = HTTParty.post(ps_url, {headers: auth_headers,
-                                        body: 'grant_type=client_credentials'})
+      response = HTTParty.post( ps_url,
+                                { headers: auth_headers,
+                                  body: 'grant_type=client_credentials'} )
       if response.code.to_s.eql? "200"
         @auth_info = response.parsed_response
         @auth_info['token_expires'] = Time.now + response.parsed_response['expires_in'].to_i
@@ -142,8 +155,8 @@ module PsUtilities
 
     def encode64_client(credentials = client)
       ps_auth_text = [ credentials[:client_id], credentials[:client_secret] ].join(':')
-      Base64.encode64(ps_auth_text).chomp
-      # Base64.encode64(ps_auth_text).gsub(/\n/, '')
+      Base64.encode64(ps_auth_text).gsub(/\n/, '')
+      # Base64.encode64(ps_auth_text).chomp
     end
 
     def client_defaults
@@ -153,7 +166,7 @@ module PsUtilities
     end
 
     def api_defaults
-      { base_uri:       ENV['PS_BASE_URL'],
+      { base_uri:       ENV['PS_BASE_URI'],
         auth_endpoint:  ENV['PS_AUTH_ENDPOINT'] || '/oauth/access_token',
       }
     end

data/lib/ps_utilities/pre_built_post.rb

@@ -3,11 +3,12 @@ module PsUtilities
   module PreBuiltPost
 
     # 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"} }
+    # @param params (Array of Hashes) - kids with their attributes use format:
+    # one kid
+    # params: { students: [{dcid: 7531, student_id: 23456, email: "kid1@las.ch"}] }
+    #
     # or multiple students (with ps and your school's database extensions)
-    # @param params: { students:
+    # params: { students:
     #   [ { dcid: 9753, student_id: 65432 },
     #     { dcid: 7531, student_id: 23456, email: "kid@las.ch",
     #       u_studentsuserfields: {transcriptaddrcity: "Bex"},
@@ -30,9 +31,9 @@ module PsUtilities
     #     ]
     #   }
     # }
-    # @note create_students REQUIRED params are: :id
-    # @note create_students OPTIONAL params are:
-    # @note create_students INVALID params are:
+    # @note create_students REQUIRED params are: :student_id (chosen by the school same as local_id within PS), :last_name, :first_name, :entry_date, :exit_date, :school_number, :grade_level
+    # @note create_students OPTIONAL params include: :school_id, :username, :middle_name, physical address objects, mailing address objects, demographics objects, contacts objects, schedule setup objects, intial enrollment objects (disctrict and school), :contact_info, :phone, :u_studentsuserfields (powerschool defined extensions) & :u_students_extension (school defined db extensions)
+    # @note create_students INVALID (ignored) params are: :id (dcid - chosen by the PS system)
     def create_students(params)
       action   = "INSERT"
       kids_api_array = build_kids_api_array(action, params)
@@ -45,9 +46,8 @@ module PsUtilities
 
     # this updates and existing student record within PowerSchool
     # (see #create_students)
-    # @note update_students REQUIRED params are: :last_name, :first_name, :entry_date, :exit_date, :school_number, :grade_level
-    # @note update_students OPTIONAL params are: :
-    # @note update_students INVALID params are:
+    # @note update_students REQUIRED params are: **:id** (dcid) and **:student_id** (local_id)
+    # @note update_students INVALID (ignored) params are: :grade_level, :entry_date, :exit_date, :school_number, :school_id
     def update_students(params)
       action = "UPDATE"
       kids_api_array = build_kids_api_array(action, params)
@@ -189,7 +189,7 @@ module PsUtilities
       attribs[:name]                 = {}
       case action
       when 'INSERT'
-        # must be set on creation
+        # must be set on creation (INSERT)
         attribs[:local_id]  = kid[:oa_id].to_i
         # to create an account both first and last name must be present
         attribs[:name][:last_name]   = kid[:last_name]   if kid[:last_name] or kid[:first_name]
@@ -265,16 +265,11 @@ module PsUtilities
       attribs[:schedule_setup][:next_school] = kid[:next_school]   if kid[:next_school]
       attribs[:schedule_setup][:sched_next_year_grade] = kid[:sched_next_year_grade] if kid[:sched_next_year_grade]
       #
-      attribs[:school_enrollment] = {}
-      if kid[:enroll_status_code]
-        attribs[:school_enrollment][:enroll_status_code]  = kid[:enroll_status_code]
-      elsif kid[:status_code]
-        attribs[:school_enrollment][:status_code]         = kid[:status_code]
-      end
-      attribs[:school_enrollment][:grade_level]    = kid[:grade_level]   if kid[:grade_level]
-      attribs[:school_enrollment][:entry_date]     = kid[:entry_date]    if kid[:entry_date]
-      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[:initial_enrollment] = {}
+      attribs[:initial_enrollment][:school_entry_date]          = kid[:school_entry_date]          if kid[:school_entry_date]
+      attribs[:initial_enrollment][:school_entry_grade_level]   = kid[:school_entry_grade_level]   if kid[:school_entry_grade_level]
+      attribs[:initial_enrollment][:district_entry_date]        = kid[:district_entry_date]        if kid[:district_entry_date]
+      attribs[:initial_enrollment][:district_entry_grade_level] = kid[:district_entry_grade_level] if kid[:district_entry_grade_level]
       #
       attribs[:contact_info]     = {email: kid[:email]}                  if kid[:email]
       attribs[:phone]            = {main: {number: kid[:mobile]}}        if kid[:mobile]
@@ -296,5 +291,4 @@ module PsUtilities
     end
 
   end
-
 end

data/lib/ps_utilities/version.rb

@@ -1,5 +1,5 @@
 module PsUtilities
   module Version
-    VERSION = "1.0.0"
+    VERSION = "1.0.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ps_utilities
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Lee Weisbecker
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-28 00:00:00.000000000 Z
+date: 2018-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty