ps_utilities 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b53435e5d2f6da0cd21f54f5780806986b87e7ff36b963702e4cd1009862e7d
+  data.tar.gz: 0f3133a755d4f2f67e8bde12bbb3769969afe60015f609b672166582b06d2898
+SHA512:
+  metadata.gz: 0b39f2d31153c8fc135d6fc39a415c55f8a347f4c97f0de18b91bec030f99d182e9baa655de000a29996d01997b2e44023f6d55d4f0b02e6187f254fd3f555b3
+  data.tar.gz: 87407650b7062b75f4ae4158bd48103a2acc302472923ad4d0456fbb900dc4a07191588df67621f028bcdf6e8d18aadf908dcfe8c666467335ecb872f68a6ea1

data/lib/ps_utilities/api_endpoints.rb

@@ -0,0 +1,166 @@
+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

data/lib/ps_utilities/connection.rb

@@ -0,0 +1,175 @@
+require 'openssl'
+require 'base64'
+require 'json'
+require 'httparty'
+require 'ps_utilities/pre_built_get'
+require 'ps_utilities/pre_built_put'
+require 'ps_utilities/pre_built_post'
+
+# http://blog.honeybadger.io/ruby-custom-exceptions/
+class AuthError < RuntimeError
+  attr_reader :url, :credentials
+  def initialize(msg="", url="", credentials={})
+    @url         = url
+    @credentials = credentials
+    super(msg)
+  end
+end
+
+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
+
+    include PsUtilities::PreBuiltGet
+    include PsUtilities::PreBuiltPut
+    include PsUtilities::PreBuiltPost
+
+    def initialize(attributes: {}, headers: {})
+      @credentials = attr_defaults.merge(attributes)
+      @headers     = header_defaults.merge(headers)
+
+      raise ArgumentError, "missing client_secret" if credentials[:client_secret].nil?  or
+                                                      credentials[:client_secret].empty?
+      raise ArgumentError, "missing client_id"     if credentials[:client_id].nil?  or
+                                                      credentials[:client_id].empty?
+      raise ArgumentError, "missing base_uri"      if credentials[:base_uri].nil?  or
+                                                      credentials[:base_uri].empty?
+    end
+
+    # with no command it just authenticates
+    def run(command: nil, params: {}, url: nil, options: {})
+      authenticate   unless token_valid?
+      case command
+      when nil, :authenticate
+        # authenticate            unless token_valid?
+      when :get, :put, :post
+        send(command, url, options) unless url.empty?
+      else
+        send(command, params)
+      end
+    end
+
+    private
+
+    # options = {query: {}}
+    def get(url, options={})
+      max_retries = 3
+      times_retried = 0
+      options = options.merge(headers)
+      ps_url = credentials[:base_uri] + url
+      begin
+        HTTParty.get(ps_url, options)
+        # self.class.get(url, query: options[:query], headers: options[:headers])
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        if times_retried < max_retries
+          times_retried += 1
+          retry
+        else
+          { error: "no response (timeout) from URL: #{url}"  }
+        end
+      end
+    end
+
+    # options = {body: {}}
+    def put(url, options={})
+      max_retries = 3
+      times_retried = 0
+      options = options.merge(headers)
+      ps_url = credentials[:base_uri] + url
+      begin
+        HTTParty.put(ps_url, options )
+        # self.class.get(url, body: options[:body], headers: options[:headers])
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        if times_retried < max_retries
+          times_retried += 1
+          retry
+        else
+          { error: "no response (timeout) from URL: #{url}"  }
+        end
+      end
+    end
+
+    # options = {body: {}}
+    def post(url, options={})
+      max_retries = 3
+      times_retried = 0
+      options = options.merge(headers)
+      ps_url = credentials[:base_uri] + url
+      begin
+        HTTParty.post(ps_url, options )
+        # self.class.get(url, body: options[:body], headers: options[:headers])
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        if times_retried < max_retries
+          times_retried += 1
+          retry
+        else
+          { error: "no response (timeout) from URL: #{url}"  }
+        end
+      end
+    end
+
+    # In PowerSchool go to System>System Settings>Plugin Management Configuration>your plugin>Data Provider Configuration to manually check plugin expiration date
+    def authenticate
+      @headers[:headers] ||= {}
+      ps_url = credentials[:base_uri] + credentials[:auth_endpoint]
+      response = HTTParty.post(ps_url, {headers: auth_headers,
+                                        body: 'grant_type=client_credentials'})
+
+      @credentials[:token_expires] = Time.now + response.parsed_response['expires_in'].to_i
+      @credentials[:access_token]  = response.parsed_response['access_token'].to_s
+      @headers[:headers].merge!('Authorization' => 'Bearer ' + credentials[:access_token])
+
+      # throw error if no token returned -- nothing else will work
+      raise AuthError.new("No Auth Token Returned",
+                          ps_url, credentials
+                         ) if credentials[:access_token].empty?
+    end
+
+    def token_valid?(tokens = credentials)
+      return false if tokens[:access_token].nil?
+      return false if tokens[:access_token].empty?
+      return false if tokens[:token_expires].nil?
+      return false if tokens[:token_expires] <= Time.now
+      return true
+    end
+
+    def auth_headers
+      { 'ContentType' => 'application/x-www-form-urlencoded;charset=UTF-8',
+        'Accept' => 'application/json',
+        'Authorization' => 'Basic ' + encode_credentials
+      }
+    end
+
+    def encode_credentials
+      ps_auth_text = [ credentials[:client_id],
+                       credentials[:client_secret]
+                     ].join(':')
+      Base64.encode64(ps_auth_text).gsub(/\n/, '')
+    end
+
+    def attr_defaults
+      { 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'],
+        # not recommended here - it changes (ok as a parameter though)
+        # access_token:   ENV['PS_ACCESS_TOKEN'] || nil,
+      }
+    end
+
+    def header_defaults
+      { headers:
+        { 'User-Agent' => "PsUtilitiesGem - v#{PsUtilities::Version::VERSION}",
+          'Accept' => 'application/json',
+          'Content-Type' => 'application/json'}
+      }
+    end
+
+  end
+end

data/lib/ps_utilities/pre_built_get.rb

@@ -0,0 +1,36 @@
+module PsUtilities
+
+  module PreBuiltGet
+
+    def get_active_students_count(params={})
+      # url = "/ws/v1/district/student/count?q=school_enrollment.enroll_status_code==0"
+      url     = "/ws/v1/district/student/count"
+      options = { query: {"q" => "school_enrollment.enroll_status_code==0"} }
+      get(url, options)
+    end
+
+    def get_active_students_info(params={})
+      # url = "/ws/v1/district/student?q=school_enrollment.enroll_status==a&pagesize=500"
+      url     = "/ws/v1/district/student"
+      options = { query:
+                  {"q"        => "school_enrollment.enroll_status_code==0",
+                   "pagesize" => "500"}
+                }
+      get(url, options)
+    end
+
+    # las-test.powerschool.com/ws/v1/district/student?expansions=school_enrollment&q=student_username==xxxxx237
+    # params = {username: "xxxxxxx"}
+    def get_one_student_record(params)
+      # url = "/ws/v1/district/student?expansions=school_enrollment,contact&q=student_username==xxxxxx237"
+      url     = "/ws/v1/district/student"
+      options = { query:
+                  {"q"          => "student_username==#{params[:username]}",
+                   "expansions" => "school_enrollment,contact,contact_info"}
+                }
+      get(url, options)
+    end
+
+  end
+
+end

data/lib/ps_utilities/pre_built_post.rb

@@ -0,0 +1,7 @@
+module PsUtilities
+
+  module PreBuiltPost
+
+  end
+
+end

data/lib/ps_utilities/pre_built_put.rb

@@ -0,0 +1,7 @@
+module PsUtilities
+
+  module PreBuiltPut
+
+  end
+
+end

data/lib/ps_utilities/version.rb

@@ -0,0 +1,5 @@
+module PsUtilities
+  module Version
+    VERSION = "0.1.0"
+  end
+end

data/lib/ps_utilities.rb

@@ -0,0 +1,6 @@
+require "ps_utilities/version"
+require "ps_utilities/connection"
+
+module PsUtilities
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: ps_utilities
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lee Weisbecker
+- Bill Tihen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.5'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+description: 'Uses oauth2 to connection to the Powerschool API. Heavily refactored
+  code (not dependent on Rails) starting with: https://github.com/TomK32/powerschool'
+email:
+- leeweisbecker@gmail.com
+- btihen@gmail.com
+executables: []
+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
+- lib/ps_utilities/pre_built_put.rb
+- lib/ps_utilities/version.rb
+homepage: https://github.com/LAS-IT/ps_utilities
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Simple ruby wrapper for Powerschool API interaction.
+test_files: []