proctorserv-api 1.0.3 → 1.0.4

data/README.md

@@ -54,6 +54,21 @@ Creating a session through the scheduling API sets up a future or immediate oppo
 - :first_name (String) - First name of the candidate taking the exam 
 - :last_name (String) - Last name of the candidate taking the exam - The tast taker downloads the ProctorApp desktop application and completes their session
 
+**Creating a session event**
+Creates a session event that is specified by session_id (int), event_type (String), severity (int), and proctor_id (String). 
+
+
+*Required Parameters:*
+
+ - :session_id (int) - Proctorserve id for the session to grant access to
+ - :event_type (String) - The type of event which can be found in session_event.rb
+
+*Optional Parameters:*
+
+ - :severity (int) - The importance-by-color of the session event  (0-> grey (system event),1-> red, 2-> yellow, and 3-> green
+ - :proctor_id (String) - unique identifier representing the user to grant access to. This will determine the user's display name in Proctorserve interfaces.
+ - :time (Time) - Time at which to create the event (defaults to now if not set)
+
 #### Installation
 
     $ gem install proctorserv-api
@@ -101,6 +116,7 @@ proctorserv_api.make_immediate_reservation
 proctorserv_api.cancel_reservation
 proctorserv_api.generate_jsonp_token
 proctorserv_api.generate_secure_review_url
+proctorserv_api.create_session_event
 ```
 
 Further documentation for these methods can be found [here](http://rubydoc.info/github/ProctorCam/proctorserv-api-rb/master/frames)

data/lib/proctorserv_api.rb

@@ -3,6 +3,7 @@ require 'proctorserv_api/exceptions/invalid_client_exception'
 require 'proctorserv_api/exceptions/invalid_ip_exception'
 require 'proctorserv_api/exceptions/invalid_signature_exception'
 require 'proctorserv_api/exceptions/missing_required_parameter_exception'
+require 'proctorserv_api/session_event.rb'
 
 #
 # proctorserv_api.rb
@@ -29,7 +30,7 @@ module ProctorCam
   module Proctorserv
     class ProctorservApi
 
-      VERSION = "1.0.3"
+      VERSION = "1.0.4"
       
       def initialize(api_identifier, shared_secret, service_protocol = "https", service_url = "service.proctorcam.com")
         @service_protocol = service_protocol
@@ -53,7 +54,7 @@ module ProctorCam
       # @return [Array<Time>] list of Time objects that represent schedulable timeslots in Proctorserve for a test of length session_duration between lower_bound and upper_bound
       def get_available_timeslots_between(options)
         requires_of options, [:lower_bound, :upper_bound, :session_duration]
-        url = "#{@service_protocol}://#{@service_url}/#{__method__}"
+        url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
         convert_times_to_integer options, :lower_bound, :upper_bound
         response = RestRequestClient.new.make_get_request url, @api_identifier, @shared_secret, options
         parsed_response = JSON.parse response.body
@@ -78,7 +79,7 @@ module ProctorCam
       # @return [Array<Time>] list (length num_slots or 20) of Time objects that represent schedulable timeslots in Proctorserve for a test of length session_duration around time passed in options hash
       def get_available_timeslots_around(options)
         requires_of options, [:time, :num_slots, :session_duration]
-        url = "#{@service_protocol}://#{@service_url}/#{__method__}"
+        url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
         convert_times_to_integer options, :time
         response = RestRequestClient.new.make_get_request url, @api_identifier, @shared_secret, options
         parsed_response = JSON.parse response.body
@@ -107,7 +108,7 @@ module ProctorCam
       # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not scheduable.
       def make_reservation(options)
         requires_of options, [:time, :customer_subject_id, :customer_client_subject_id, :client_code, :reservation_id, :session_duration, :exam_code]
-        url = "#{@service_protocol}://#{@service_url}/#{__method__}"
+        url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
         convert_times_to_integer options, :time
         response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
 
@@ -138,7 +139,7 @@ module ProctorCam
       # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not scheduable.
       def make_immediate_reservation(options)
         requires_of options, [:customer_subject_id, :customer_client_subject_id, :client_code, :reservation_id, :session_duration, :exam_code]
-        url = "#{@service_protocol}://#{@service_url}/#{__method__}"
+        url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
         convert_times_to_integer options, :time
         response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
 
@@ -160,7 +161,7 @@ module ProctorCam
       # @return [Boolean] whether or not the test was successfully canceled.
       def cancel_reservation(options)
         requires_of options, [:session_id]
-        url = "#{@service_protocol}://#{@service_url}/#{__method__}"
+        url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
         response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
 
         return true if response.code == 204
@@ -207,6 +208,40 @@ module ProctorCam
         "#{@service_protocol}://#{@service_url}/review?secure_token=#{options.map{|k,v| "#{k}%3D#{v}"}.join '%26'}#watch/#{options[:session_id]}"
       end
 
+
+      # Generate a session event for a testing session.
+      #
+      # @param [Hash{Symbol => String}] options
+      #   Required:
+      #    - :session_id (int) - Proctorserve id for the session the event will be added to
+      #    - :event_type(String) The event to be added, acceptable events are contained in SessionEvent.rb
+      #   Optional:
+      #    - :proctor_id (String) - Unique identifier representing the user to grant access to. This will determine the user's display name in Proctorserve interfaces.
+      #    - :time (String) (Time or int seconds since epoch) Date and Time that the session event happened at
+      #    - :severity (int) (Defaults to 0) The severity of the session_event being created.
+      #      - 0: Lowest severity
+      #      - 1: Highest Severity, may be used for events like test revoked or emergency.
+      #      - 2: Medium Severity, the session needs to be reviewed.
+      #      - 3: Low Severity, common events like going through the system check.
+      #  @return [Boolean] whether or not the session event was successfully created.
+      def create_session_event(options)
+        requires_of options, [:session_id, :event_type]
+        url = "#{@service_protocol}://#{@service_url}/api/session_events/create"
+        response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options
+
+        return true if response.code == 201
+
+        if response.code != 200
+          parsed_response = JSON.parse response.body
+          raise_exception_if_necessary(parsed_response) 
+        end
+
+        false
+      end
+
+
+
+
       protected 
 
       def raise_exception_if_necessary(response)

data/lib/proctorserv_api/session_event.rb

@@ -0,0 +1,51 @@
+#
+# session_event.rb
+# ProctorservApi
+#
+# Copyright 2013 ProctorCam, Inc
+#
+# Licensed under the Apache License, Version 2.0 (the "License") 
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Created by Pat Durgin on 7/19/13.
+#
+module SessionEvent
+
+    ERROR = "ERROR"
+    CHECK_IN_BEGUN = "CHECK_IN_BEGUN"
+    APP_CONNECTED = "APP_CONNECTED"
+    STARTED = "STARTED"
+    COMPLETED = "COMPLETED"
+    APP_WORKFLOW = "APP_WORKFLOW"
+    APP_HARDWARE_ISSUE = "APP_HARDWARE_ISSUE"
+    APP_ISSUE = "APP_ISSUE"
+    APP_STREAMING_STARTED = "APP_STREAMING_STARTED"
+    APP_STREAMING_STOPPED = "APP_STREAMING_STOPPED"
+    APP_READY_FOR_GREET = "APP_READY_FOR_GREET"
+    SERVICE_TEST_RELEASED = "SERVICE_TEST_RELEASED"
+
+    ACCESS_CODE_RESET = "ACCESS_CODE_RESET"
+    UNAPPROVED_RESOURCE = "UNAPPROVED_RESOURCE"
+    VOICE_HEARD = "VOICE_HEARD"
+    PUSHED_TO_COMPLETE = "PUSHED_TO_COMPLETE"
+    USING_PHONE = "USING_PHONE"
+    LEFT_THE_ROOM = "LEFT_THE_ROOM"
+    EMERGENCY = "EMERGENCY"
+    UNUSUAL_EYE_MOVEMENT = "UNUSUAL_EYE_MOVEMENT"
+    OTHER = "OTHER"
+    APP_SUBJECT_HAND_RAISED = "APP_SUBJECT_HAND_RAISED"
+    SERVICE_TEST_PAUSED = "SERVICE_TEST_PAUSED"
+    SERVICE_TEST_RESUMED = "SERVICE_TEST_RESUMED"
+    SERVICE_TEST_REVOKED = "SERVICE_TEST_REVOKED"
+    SERVICE_PROCTOR_OUTREACH = "SERVICE_PROCTOR_OUTREACH"
+
+end

data/spec/proctorserv_api_spec.rb

@@ -25,18 +25,18 @@ require 'rspec'
 describe ProctorCam::Proctorserv::ProctorservApi do
 
   before :all do
-    @proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("api_identifier", "shared_secret", "http", "localhost:3000/api/scheduling")
+    @proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("test", "shared_secret", "http", "localhost:3000")
   end
 
   describe "when passed improper credentials" do
 
     it "raises an invalid_client_exception when api_identifier is wrong" do
-      proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("wrong", "shared_secret", "http", "localhost:3000/api/scheduling")
+      proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("wrong", "shared_secret", "http", "localhost:3000")
       expect{proctorserv_api.get_available_timeslots_between({:lower_bound => Time.now.to_i, :upper_bound => Time.now.to_i + 24*60*60, :session_duration => 60})}.to raise_error ProctorCam::Proctorserv::InvalidClientException
     end
 
     it "raises an invalid_signature_exception when shared_secret is wrong" do
-      proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("api_identifier", "wrong", "http", "localhost:3000/api/scheduling")
+      proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("test", "wrong", "http", "localhost:3000")
       expect{proctorserv_api.get_available_timeslots_between({:lower_bound => Time.now.to_i, :upper_bound => Time.now.to_i + 24*60*60, :session_duration => 60})}.to raise_error ProctorCam::Proctorserv::InvalidSignatureException
     end
 
@@ -141,4 +141,60 @@ describe ProctorCam::Proctorserv::ProctorservApi do
 
   end
 
+  describe "generate_jsonp_token" do
+
+    it "raises missing_required_parameter_exception when not passed session_id in options hash" do
+     expect{@proctorserv_api.generate_jsonp_token({})}.to raise_error ProctorCam::Proctorserv::MissingRequiredParameterException
+    end
+
+    it "generates a secure token that can be used to grant temporary jsonp access to a session for a web browser user to take a session" do
+      options = {:session_id => 400, :duration => 60}
+      jsonp_token = @proctorserv_api.generate_jsonp_token options
+      resultant_hash = Hash[jsonp_token.split('%26').map{|sub_hash|sub_hash.split('%3D')}]
+      resultant_hash['session_id'].should == options[:session_id].to_s
+      resultant_hash['duration'].should == options[:duration].to_s
+    end
+  end
+
+  describe "generate_secure_review_url" do
+
+    it "raises missing_required_parameter_exception when not passed proctor_id and session_id" do
+      expect{@proctorserv_api.generate_secure_review_url({})}.to raise_error ProctorCam::Proctorserv::MissingRequiredParameterException
+    end
+
+    it "generate a secure token that can be used to grant temporary access to a session for a web browser user to review a session." do
+      options = {:proctor_id => "foo", :session_id => 500, :duration => 60}
+      generated_url = @proctorserv_api.generate_secure_review_url options
+      resultant_hash = Hash[generated_url.match(/secure_token=(.*)#watch\/[1-9]*/)[1].split('%26').map{|sub_hash|sub_hash.split('%3D')}]
+      resultant_hash['session_id'].should == options[:session_id].to_s
+      resultant_hash['proctor_id'].should == options[:proctor_id].to_s
+      resultant_hash['duration'].should == options[:duration].to_s
+    end
+  end
+
+  describe "create_session_event" do
+
+    it "raises a missing_required_parameter_exception when not passed session_id and event_type" do
+      expect{@proctorserv_api.create_session_event({})}.to raise_error ProctorCam::Proctorserv::MissingRequiredParameterException
+    end
+
+    it "returns true if it generates a session event for a testing session if options hash contains correct values" do 
+      options = {:session_id => 471, :event_type => SessionEvent::COMPLETED, :proctor_id => "foo", :severity => 2}
+      result = @proctorserv_api.create_session_event options
+      result.should be_true
+    end
+
+    it "returns false if the customer does not have the session_id passed" do
+      proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("test", "shared_secret", "http", "localhost:3000")
+      options = {:session_id => -1, :event_type => SessionEvent::COMPLETED, :proctor_id => "foo", :severity => 2}
+      result = proctorserv_api.create_session_event options
+      result.should be_false
+    end
+
+    it "returns false if the event_type is not a valid event type" do
+      options = {:session_id => 450, :event_type => 'this isnt an event', :proctor_id => "foo", :severity => 2}
+      result = @proctorserv_api.create_session_event options
+      result.should be_false
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proctorserv-api
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-15 00:00:00.000000000 Z
+date: 2013-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -57,6 +57,7 @@ files:
 - lib/proctorserv_api/exceptions/missing_required_parameter_exception.rb
 - lib/proctorserv_api/hashed_authenticator.rb
 - lib/proctorserv_api/rest_request_client.rb
+- lib/proctorserv_api/session_event.rb
 - lib/proctorserv_api.rb
 - LICENSE
 - README.md