powerapi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7ca79c15ad25142ea25914fcd2d7d24f77ec5008
+  data.tar.gz: 3da80c3b78f502ef4220cdae6f78683de05ab35c
+SHA512:
+  metadata.gz: c4a88233f2b4cd8df56e2b739c5c028231957fb50b5e19c5915743f15ceb997d68722f3fad0de3f4e6f4da1ddd1dd481ee1f6f1be26e80db85c7d17dccf7e1c3
+  data.tar.gz: 3bb6dd7babbbedfa1ac0672019abcbd13892791c9b3b998bdc1bc316638d75544915ecb947f5633f3969be1e4c699cbc65bc74d8d5a67d6f6ece70ab603e6519

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/ACKNOWLEDGEMENTS.md

@@ -0,0 +1,31 @@
+# Acknowledgements
+
+## People
+* [Daniel Tomlinson](https://twitter.com/dantoml) for pointing out areas where
+  I diverged from the Ruby status-quo.
+* [Ross Penman](https://twitter.com/PenmanRoss) for always being around to
+  answer questions about Ruby oddities.
+* The PowerSchool team at Pearson School Systems for finally exposing a
+  working machine readable version of student data.
+
+## Savon
+    Copyright (c) 2010 Daniel Harrington
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in powerapi.gemspec
+gemspec

data/README.md

@@ -0,0 +1,62 @@
+[![Build Status](https://img.shields.io/travis/powerapi/powerapi-ruby.svg?style=flat-square&branch=master)](https://travis-ci.org/powerapi/powerapi-ruby)
+[![Coverage Status](https://img.shields.io/coveralls/powerapi/powerapi-ruby.svg?style=flat-square)](https://coveralls.io/r/powerapi/powerapi-ruby)
+[![Code Climate](http://img.shields.io/codeclimate/github/powerapi/powerapi-ruby.svg?style=flat-square)](https://codeclimate.com/github/powerapi/powerapi-ruby)
+[![Gem Version](https://img.shields.io/gem/v/powerapi.svg?style=flat-square)](https://rubygems.org/gems/powerapi)
+
+PowerAPI-ruby
+============
+Library for fetching information from PowerSchool SISes.
+
+Requirements
+------------
+* Ruby >= 2.0.0
+* PowerSchool 8.x; PowerSchool >= 7.1.0
+
+Installation
+------------
+You should use [RubyGems](https://rubygems.org/) to handle including/downloading
+the library for you.
+
+```
+$ gem install powerapi
+```
+
+Usage example
+-------------
+```ruby
+require "powerapi"
+
+# Trade server details and the user's credentials for a student object.
+student = PowerAPI.authenticate("http://powerschool.example", "username", "password")
+
+# Print the student's name.
+print student.information["firstName"] + " " + student.information["lastName"] + "\n"
+
+# Print the student's sections.
+student.sections.each do |section|
+  print section.name + "\n"
+end
+```
+
+
+## License
+
+    Copyright (c) 2014 Henri Watson
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => [:spec]

data/lib/powerapi/assignment.rb

@@ -0,0 +1,27 @@
+module PowerAPI
+  class Assignment
+    def initialize(details)
+      @details = details
+    end
+
+    def category
+      @details[:category]["name"]
+    end
+
+    def description
+      @details[:assignment]["description"]
+    end
+
+    def name
+      @details[:assignment]["name"]
+    end
+
+    def percent
+      @details[:score]["percent"]
+    end
+
+    def score
+      @details[:score]["score"]
+    end
+  end
+end

data/lib/powerapi/exception.rb

@@ -0,0 +1,7 @@
+module PowerAPI
+  class Exception < StandardError
+    def initialize(message)
+      super(message)
+    end
+  end
+end

data/lib/powerapi/parser.rb

@@ -0,0 +1,97 @@
+module PowerAPI
+  class Parser
+    def self.assignments(raw_assignments, assignment_categories, assignment_scores)
+      assignments = {}
+
+      raw_assignments.each do |assignment|
+        if assignments[assignment["sectionid"]] == nil
+          assignments[assignment["sectionid"]] = []
+        end
+
+        assignments[assignment["sectionid"]] << PowerAPI::Assignment.new({
+          :assignment => assignment,
+          :category => assignment_categories[assignment["categoryId"]],
+          :score => assignment_scores[assignment["id"]],
+        })
+      end
+
+      assignments
+    end
+
+    def self.assignment_categories(raw_assignment_categories)
+      assignment_categories = {}
+
+      raw_assignment_categories.each do |assignment_category|
+        assignment_categories[assignment_category["id"]] = assignment_category
+      end
+
+      assignment_categories
+    end
+
+    def self.assignment_scores(raw_assignment_scores)
+      assignment_scores = {}
+
+      raw_assignment_scores.each do |assignment_score|
+        assignment_scores[assignment_score["assignmentId"]] = assignment_score
+      end
+
+      assignment_scores
+    end
+
+    def self.final_grades(raw_final_grades)
+      final_grades = {}
+
+      raw_final_grades.each do |final_grade|
+        if final_grades[final_grade["sectionid"]] == nil
+          final_grades[final_grade["sectionid"]] = []
+        end
+
+        final_grades[final_grade["sectionid"]] << final_grade
+      end
+
+      final_grades
+    end
+
+    def self.reporting_terms(raw_reporting_terms)
+      reporting_terms = {}
+
+      raw_reporting_terms.each do |reporting_term|
+        reporting_terms[reporting_term["id"]] = reporting_term["abbreviation"]
+      end
+
+      reporting_terms
+    end
+
+    def self.sections(raw_sections, assignments, final_grades, reporting_terms, teachers)
+      sections = []
+
+      raw_sections.each do |section|
+        # PowerSchool will return sections that have not started yet.
+        # These are stripped since none of the official channels display them.
+        if DateTime.parse(section["enrollments"]["startDate"]).strftime("%s").to_i > DateTime.now.strftime("%s").to_i
+          next
+        end
+
+        sections << PowerAPI::Section.new({
+          :assignments => assignments[section["id"]],
+          :final_grades => final_grades[section["id"]],
+          :reporting_terms => reporting_terms,
+          :section => section,
+          :teacher => teachers[section["teacherID"]]
+        })
+      end
+
+      sections
+    end
+
+    def self.teachers(raw_teachers)
+      teachers = {}
+
+      raw_teachers.each do |teacher|
+        teachers[teacher["id"]] = teacher
+      end
+
+      teachers
+    end
+  end
+end

data/lib/powerapi/section.rb

@@ -0,0 +1,45 @@
+module PowerAPI
+  class Section
+    def initialize(details)
+      @details = details
+
+      # Occasionally, a section won't have any final_grades objects
+      if @details[:final_grades] != nil
+        @final_grades = {}
+
+        @details[:final_grades].each do |final_grade|
+          @final_grades[
+            @details[:reporting_terms][final_grade["reportingTermId"]]
+          ] = final_grade["percent"]
+        end
+      else
+        @final_grades = nil
+      end
+    end
+
+    def assignments
+      @details[:assignments]
+    end
+
+    def final_grades
+      @final_grades
+    end
+
+    def name
+      @details[:section]["schoolCourseTitle"]
+    end
+
+    def room_name
+      @details[:section]["roomName"]
+    end
+
+    def teacher
+      {
+        :first_name => @details[:teacher]["firstName"],
+        :last_name => @details[:teacher]["lastName"],
+        :email => @details[:teacher]["email"],
+        :school_phone => @details[:teacher]["schoolPhone"]
+      }
+    end
+  end
+end

data/lib/powerapi/student.rb

@@ -0,0 +1,73 @@
+module PowerAPI
+  class Student
+    def initialize(soap_url, soap_session, populate=true)
+      @soap_url = soap_url
+      @soap_session = soap_session
+
+      if populate
+        self.populate()
+      end
+    end
+
+    def populate()
+      transcript = self.fetch_transcript
+      self.parse_transcript(transcript)
+    end
+
+    def fetch_transcript()
+      student_client = Savon.client(
+        endpoint: @soap_url + "/pearson-rest/services/PublicPortalServiceJSON?response=application/json",
+        namespace: "http://publicportal.rest.powerschool.pearson.com/xsd",
+        digest_auth: ["pearson", "m0bApP5"]
+      )
+
+      transcript_params = {
+        userSessionVO: {
+          userId: @soap_session[:user_id],
+          serviceTicket: @soap_session[:service_ticket],
+          serverInfo: {
+            apiVersion: @soap_session[:server_info][:api_version]
+          },
+          serverCurrentTime: "2012-12-26T21:47:23.792Z", # I really don't know.
+          userType: "2"
+        },
+        studentIDs: @soap_session[:student_i_ds],
+        qil: {
+          includes: "1"
+        }
+      }
+
+      transcript = student_client.call(:get_student_data, message: transcript_params).to_xml
+
+      JSON.parse(transcript)
+    end
+
+    def parse_transcript(transcript)
+      @student_data = transcript["return"]["studentDataVOs"]
+
+      @student_data["student"].delete("@type")
+
+      assignment_categories = PowerAPI::Parser.assignment_categories(@student_data["assignmentCategories"])
+      assignment_scores = PowerAPI::Parser.assignment_scores(@student_data["assignmentScores"])
+      final_grades = PowerAPI::Parser.final_grades(@student_data["finalGrades"])
+      reporting_terms = PowerAPI::Parser.reporting_terms(@student_data["reportingTerms"])
+      teachers = PowerAPI::Parser.teachers(@student_data["teachers"])
+
+      assignments = PowerAPI::Parser.assignments(@student_data["assignments"], assignment_categories, assignment_scores)
+
+      @sections = PowerAPI::Parser.sections(@student_data["sections"], assignments, final_grades, reporting_terms, teachers)
+
+      return 0
+    end
+
+    def sections
+      @sections
+    end
+
+    def information
+      if @student_data != nil
+        @student_data["student"]
+      end
+    end
+  end
+end

data/lib/powerapi/version.rb

@@ -0,0 +1,3 @@
+module PowerAPI
+  VERSION = "1.0.0"
+end

data/lib/powerapi.rb

@@ -0,0 +1,34 @@
+require "powerapi/exception.rb"
+require "powerapi/parser.rb"
+require "powerapi/version.rb"
+
+require "powerapi/assignment.rb"
+require "powerapi/section.rb"
+require "powerapi/student.rb"
+
+require "savon"
+require "json"
+
+module PowerAPI
+  module_function
+
+  def authenticate(url, username, password, fetch_transcript=true)
+    soap_endpoint = url + "/pearson-rest/services/PublicPortalService"
+
+    login_client = Savon.client(
+      endpoint: soap_endpoint,
+      namespace: "http://publicportal.rest.powerschool.pearson.com/xsd",
+      wsse_auth: ["pearson", "pearson"]
+    )
+
+    login = login_client.call(:login, message: { username: username, password: password, userType: 2} )
+
+    if login.body[:login_response][:return][:user_session_vo] == nil
+      raise PowerAPI::Exception.new(login.body[:login_response][:return][:message_v_os][:description])
+    end
+
+    session = login.body[:login_response][:return][:user_session_vo]
+
+    return PowerAPI::Student.new(url, session, fetch_transcript)
+  end
+end

data/powerapi.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "powerapi/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "powerapi"
+  spec.version       = PowerAPI::VERSION
+  spec.authors       = ["Henri Watson"]
+  spec.email         = ["henri@henriwatson.com"]
+  spec.summary       = %q{Ruby API for PowerSchool.}
+  spec.description   = %q{Library for fetching information from Pearson PowerSchool installs.}
+  spec.homepage      = "http://powerapi.henriwatson.com/"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "coveralls"
+
+  spec.add_runtime_dependency "savon", "~> 2.0"
+  spec.add_runtime_dependency "httpclient", "~> 2.4.0"
+  spec.add_runtime_dependency "json", "~> 1.8.1"
+end

data/spec/assignment_spec.rb

@@ -0,0 +1,84 @@
+require "spec_helper"
+
+describe PowerAPI::Assignment do
+  include Savon::SpecHelper
+
+  before(:all) {
+    savon.mock!
+
+    @session = {:locale=>nil, :server_current_time=>"2014-08-24T03:01:25.007Z", :server_info=>{:api_version=>"2.1.1", :day_light_savings=>"0", :parent_saml_end_point=>nil, :raw_offset=>"-14400000", :server_time=>"2014-08-24T20:19:32.640Z", :student_saml_end_point=>nil, :teacher_saml_end_point=>nil, :time_zone_name=>"BOT", :"@xsi:type"=>"ax287:ServerInfo"}, :service_ticket=>"AAABSAX2Ex5NZXRA4/w06RyTFVkPGkFNEiI3qRAS5pMC7TQkWqT2UQYfVv0/c0SaE70JFJa17maweiMcP1u0skwbYAVPoyNvduejg61AdiePjqJPyhJyJGyGHi3UmuWI", :student_i_ds=>"1", :user_id=>"1", :user_type=>"2", :"@xsi:type"=>"ax284:UserSessionVO"}
+  }
+
+  after(:all) {
+    savon.unmock!
+  }
+
+  before(:each) {
+    fixture = File.read("spec/fixtures/transcript.json")
+    message = {
+      userSessionVO: {
+        userId: "1",
+        serviceTicket: "AAABSAX2Ex5NZXRA4/w06RyTFVkPGkFNEiI3qRAS5pMC7TQkWqT2UQYfVv0/c0SaE70JFJa17maweiMcP1u0skwbYAVPoyNvduejg61AdiePjqJPyhJyJGyGHi3UmuWI",
+        serverInfo: {
+          apiVersion: "2.1.1"
+        },
+        serverCurrentTime: "2012-12-26T21:47:23.792Z",
+        userType: "2"
+      },
+      studentIDs: "1",
+      qil: {
+        includes: "1"
+      }
+    }
+
+    savon.expects(:get_student_data).with(message: message).returns(fixture)
+
+    student = PowerAPI::Student.new("http://powerschool.example", @session)
+
+    @assignment = student.sections[0].assignments[0]
+  }
+
+  after(:each) {
+    @assignment = nil
+  }
+
+  describe "#category" do
+    it "is in the Sample category" do
+      expect(
+        @assignment.category
+      ).to eq("Sample")
+    end
+  end
+
+  describe "#description" do
+    it "has one assignment" do
+      expect(
+        @assignment.description
+      ).to eq("Sample Description")
+    end
+  end
+
+  describe "#name" do
+    it "has one assignment" do
+      expect(
+        @assignment.name
+      ).to eq("Sample Assignment")
+    end
+  end
+
+  describe "#percent" do
+    it "has one assignment" do
+      expect(
+        @assignment.percent
+      ).to eq(100)
+    end
+  end
+
+  describe "#score" do
+    it "has one assignment" do
+      expect(
+        @assignment.score
+      ).to eq(100)
+    end
+  end
+end

data/spec/fixtures/authentication/failure.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+  <soapenv:Body>
+    <ns:loginResponse xmlns:ns="http://publicportal.rest.powerschool.pearson.com/xsd">
+      <return xmlns:ax284="http://vo.rest.powerschool.pearson.com/xsd" xmlns:ax287="http://model.rest.powerschool.pearson.com/xsd" xmlns:ax285="http://util.java/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax284:ResultsVO">
+        <messageVOs xsi:type="ax284:MessageVO">
+          <description>Invalid Username or password</description>
+          <id xsi:nil="true"/>
+          <msgCode>1</msgCode>
+          <title>Invalid Login</title>
+        </messageVOs>
+        <courseRequestRulesVO xsi:nil="true"/>
+        <userSessionVO xsi:nil="true"/>
+      </return>
+    </ns:loginResponse>
+  </soapenv:Body>
+</soapenv:Envelope>

data/spec/fixtures/authentication/success.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+  <soapenv:Body>
+    <ns:loginResponse xmlns:ns="http://publicportal.rest.powerschool.pearson.com/xsd">
+      <return xmlns:ax284="http://vo.rest.powerschool.pearson.com/xsd" xmlns:ax287="http://model.rest.powerschool.pearson.com/xsd" xmlns:ax285="http://util.java/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax284:ResultsVO">
+        <courseRequestRulesVO xsi:nil="true"/>
+        <userSessionVO xsi:type="ax284:UserSessionVO">
+          <locale xsi:nil="true"/>
+          <serverCurrentTime>2014-08-24T03:01:24.992Z</serverCurrentTime>
+          <serverInfo xsi:type="ax287:ServerInfo">
+            <apiVersion>2.1.1</apiVersion>
+            <dayLightSavings>0</dayLightSavings>
+            <parentSAMLEndPoint/>
+            <rawOffset>-14400000</rawOffset>
+            <serverTime>2014-08-24T03:01:25.007Z</serverTime>
+            <studentSAMLEndPoint/>
+            <teacherSAMLEndPoint/>
+            <timeZoneName>BOT</timeZoneName>
+          </serverInfo>
+          <serviceTicket>AAABSAX2Ex5NZXRA4/w06RyTFVkPGkFNEiI3qRAS5pMC7TQkWqT2UQYfVv0/c0SaE70JFJa17maweiMcP1u0skwbYAVPoyNvduejg61AdiePjqJPyhJyJGyGHi3UmuWI</serviceTicket>
+          <studentIDs>1</studentIDs>
+          <userId>1</userId>
+          <userType>2</userType>
+        </userSessionVO>
+      </return>
+    </ns:loginResponse>
+  </soapenv:Body>
+</soapenv:Envelope>