proctorserv-api 1.0.4 → 1.0.5

data/README.md

@@ -1,73 +1,102 @@
+![ProctorCam Logo](http://i.imgur.com/vp5bSXc.png)
+
 ### ProctorservApi Client
 
 A ruby wrapper around the Proctorserve scheduling API, which allows a web service to manage various scheduling actions. This gem is framework agnostic -- it will work as part of a Rails or Sinatra project as easily as from a stand-alone script.
 
-Creating a session through the scheduling API sets up a future or immediate opportunity for a user of an integrating system to take their examination in a proctored and recorded environment. Important identifiers (eg. user or test instance) are required so that an integrating web service can request an individual session or a more involved list (like all test sessions for an exam or all test sessions for a specific user/subject) to playback. However, Proctorserve does not serve as a database of record - the integrating system is responsible for housing test taker and test information as well as keeping Proctorserve up to date. Optionally, when creating a reservation, the integrating system can opt to scope that session to a particular client of theirs -- Proctorserve can organize data by customer as well as that customer's clients.
+Creating a session through the scheduling API sets up a future or immediate opportunity for a user of an integrating system to take their examination in a proctored and recorded environment. Important identifiers (eg. user or exam instance) are required so that an integrating web service can request an individual session or a more involved list (like all sessions for an exam or all exam sessions for a specific user/subject) to playback. However, Proctorserve does not serve as a database of record - the integrating system is responsible for housing test taker and exam information as well as keeping Proctorserve up to date. Optionally, when creating a reservation, the integrating system can opt to scope that session to a particular client of theirs -- Proctorserve can organize data by customer as well as that customer's clients.
 
 **Note:** If you do not currently have a ProctorCam account, you will need one to actually use the code contained in this repo. You may create an account by calling 877­-TES-T127.
 
-#### Example workflows
-
-**Scheduling ahead of time (future reservation)**
-
-- A test taker in the integrating system needs to select a time to take their examination. 
-- The integrating system makes an API request to Proctorserve to get a list of schedulable times 
-- The test taker chooses a schedulable time, triggering an API request to Proctorserve to make a reservation for that user at that time 
-- On test day, the integrating system presents the test taker with the Proctorserve launch session component 
-- The test taker downloads the ProctorApp desktop application and completes their session
-
-*Required Parameters:*
-
-- :time (Time) - Time around which to find slots 
-- :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this test 
-- :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this test 
-- :client_code (String) - Unique identifier for API customer's client 
-- :reservation_id (String) - Unique identifier representing this test instance in API customer's system 
-- :session_duration (int) - length in minutes allotted for this examination 
-- :exam_code (String) - Unique identifier representing the group of tests this specific test instance belongs to
-
-*Optional Parameters:*
-
-- :complete_url (String) - URL that the candidate is redirected to after exam completion 
-- :first_name (String) - First name of the candidate taking the exam 
-- :last_name (String) - Last name of the candidate taking the exam
-
-**Scheduling for now (immediate reservation)**
-
-- A test taker in the integrating system is ready to take their examination
-- The integrating system makes an API request to Proctorserve to make an immediate reservation 
-- The integrating system presents the test taker with the Proctorserve launch session component 
-- The test taker downloads the ProctorApp desktop application and completes their session
-
-*Required Parameters:*
-
-- :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this test 
-- :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this test 
-- :client_code (String) - Unique identifier for API customer's client 
-- :reservation_id (String) - Unique identifier representing this test instance in API customer's system 
-- :session_duration (int) - length in minutes allotted for this examination presents the test taker with the Proctorserve launch session component 
-- :exam_code (String) - Unique identifier representing the group of tests this specific test instance belongs to
-
-*Optional Parameters:*
-
-- :complete_url (String) - URL that the candidate is redirected to after exam completion 
-- :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)
+The workflow involves
+ - ####Finding available session times
+  - getAvailableTimeslotsBetween
+
+    Getting the available session timeslots between two time-specific dates
+    
+  - getAvailableTimeslotsAround 
+    
+    Getting the available session timeslots around one time-specific date
+ 
+ - ####Making a session reservation 
+  - makeReservation 
+  
+    Making a future reservation based on a time-specific date
+ 
+  - makeImmediateReservation
+ 
+    Making an immediate reservation
+    
+ - ####Canceling a reservation 
+ 
+  - cancelReservation
+ 
+    Canceling a reservation based on a session ID which is created when making a reservation
+    
+ - ####Launching a session
+ 
+  - generateJsonpToken
+ 
+    Generating a JSONP token that renders a 'Download' button for ProctorApp and grants temporary JSONP access for the web browser the    user is using to launch the session. 
+    
+ - ####Creating a session event
+  
+  - createSessionEvent
+  
+    Creating a severity-defined session event based on regular and irregular session activity such as irregular eye movement, checking into a session, etc. A list of session events can be found in SessionEvent.php. 
+  
+    Session events are documented by the proctor and can be seen in the web interface after logging in with one's customer account. 
+ 
+    
+ - ####Reviewing the sesison
+ 
+   - generateSecureReviewUrl 
+   
+    Generating a secure URL that grants temporary customer access to the review screen of one of their users' sessions. The review screen consists of the exam taker's audio, video, and desktop activity as recorded by ProctorApp. It can be accessed live or after the session has ended. 
+
+
+### Example workflow 
+
+***Note:*** Required and optional parameters for each method can be found in the included documentaiton
+
+#####*Finding available session times* (getAvailableTimeslotsBetween, getAvailableTimeslotsAround)
+An exam taker in the integrating system is searching for a time to schedule a session
+
+  - The integrating system makes an API request to Proctorserve to search for available timeslots
+  - The integrating system presents the exam taker with a list of schedulable times 
+
+#####*Making a session reservation* (makeReservation, makeImmediateReservation)
+
+  - An exam taker in the integrating system either schedules a future exam or an immediate exam 
+  
+    - **Future Reservation**
+      - The integrating system makes an API request to Proctorserve to get a list of schedulable times
+      - The exam taker chooses a schedulable time, triggering an API request to Proctorserve to make a    reservation for that user at that time
+  - **Immediate Reservation**
+      - The integrating system makes an API request to Proctorserve to make an immediate reservation
+  - On exam day, the integrating system presents the exam taker with the Proctorserve launch session component
+  - The exam taker downloads the ProctorApp desktop application and completes their session
+
+#####*Canceling a reservation* (cancelReservation)
+  
+  - A exam taker in the integrating system cancels a reserved session
+  - The integrating system make an API request with the exam taker's unique session ID to cancel the reservation
+
+#####*Launching a session* (generateJsonpToken)
+
+ - A exam taker in the integrating system is ready to start his session
+ - The integrating system makes an API request to generate a JSONP token
+ - The integrating system can generate the token and implement the session launcher component wherever seems fit in the system
+  
+#####*Creating a session event* (createSessionEvent)
+
+- A session reviewer wants to create a session event
+- The integrating system makes an API request to the session's proctor along with the event type and severity
+
+#####*Reviewing a session* (generateSecureReviewUrl)
+- A customer wants to review a live or recorded session 
+- The integrating system makes an API request to generate a secure review URL for the customer
+- The secure review URL can be loaded into an iframe or a new window
 
 #### Installation
 
@@ -118,5 +147,6 @@ proctorserv_api.generate_jsonp_token
 proctorserv_api.generate_secure_review_url
 proctorserv_api.create_session_event
 ```
+### Full Documentation
 
 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,7 +3,6 @@ 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
@@ -30,7 +29,7 @@ module ProctorCam
   module Proctorserv
     class ProctorservApi
 
-      VERSION = "1.0.4"
+      VERSION = "1.0.5"
       
       def initialize(api_identifier, shared_secret, service_protocol = "https", service_url = "service.proctorcam.com")
         @service_protocol = service_protocol
@@ -40,9 +39,9 @@ module ProctorCam
       end
 
       # Get a list of schedulable timeslots (represented as Time objects) between two
-      # times for a given test that needs to be scheduled. This API request takes the
+      # times for a given exam that needs to be scheduled. This API request takes the
       # provided session_duration into account when comparing Proctorserve business hours.
-      # The timeslots returned are specific for a test of duration provided.
+      # The timeslots returned are specific for an exam of duration provided.
       #
       # This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)
       #
@@ -51,7 +50,7 @@ module ProctorCam
       #    - :lower_bound (Time or int seconds since epoch) - the earlier of two timestamps to find available timeslots between
       #    - :upper_bound (Time or int seconds since epoch) - the later of two timestamps to find available timeslots between
       #    - :session_duration (int) - is the length in minutes alloted for this examination
-      # @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
+      # @return [Array<Time>] list of Time objects that represent schedulable timeslots in Proctorserve for an exam 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}/api/scheduling/#{__method__}"
@@ -64,19 +63,19 @@ module ProctorCam
       end
 
       # Get a list of schedulable timeslots (represented as Time objects) around the
-      # time for a given test that needs to be scheduled. This API request takes the
+      # time for a given exam that needs to be scheduled. This API request takes the
       # provided session_duration into account when comparing Proctorserve business hours.
-      # The timeslots returned are specific for a test of duration provided. At most
+      # The timeslots returned are specific for an exam of duration provided. At most
       # 20 slots will be returned
       #
       # This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)
       #
       # @param [Hash{Symbol => String}] options
       #   Required:
-      #    - :time (Time or int seconds since epoch) - time around which to find slots
+      #    - :time (Time or int seconds since epoch) - time around which to find schedulable slots
       #    - :num_slots (int) - number of slots to return
       #    - :session_duration (int) - length in minutes alloted for this examination
-      # @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
+      # @return [Array<Time>] list (length num_slots or 20) of Time objects that represent schedulable timeslots in Proctorserve for an exam 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}/api/scheduling/#{__method__}"
@@ -95,17 +94,17 @@ module ProctorCam
       # @param [Hash{Symbol => String}] options
       #   Required:
       #    - :time (Time or int seconds since epoch) - Scheduable time for examination, as obtained by get_available_timeslots_between or get_available_timeslots_around
-      #    - :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this test
-      #    - :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this test
+      #    - :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this exam
+      #    - :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this exam
       #    - :client_code (String) - Unique identifier for API customer's client
-      #    - :reservation_id (String) - Unique identifier representing this test instance in API customer's system
+      #    - :reservation_id (String) - Unique identifier representing this exam instance in API customer's system
       #    - :session_duration (int) - Session length in minutes
-      #    - :exam_code (String) - Unique identifier representing the group of tests this specific test instance belongs to
+      #    - :exam_code (String) - Unique identifier representing the group of exams this specific exam instance belongs to
       #   Optional:
       #    - :complete_url (String) - URL that the candidate is redirected to after exam completion
       #    - :first_name (String) - First name of the candidate taking the exam
       #    - :last_name (String) - Last name of the candidate taking the exam
-      # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not scheduable.
+      # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not schedulable.
       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}/api/scheduling/#{__method__}"
@@ -126,17 +125,17 @@ module ProctorCam
       #
       # @param [Hash{Symbol => String}] options
       #   Required:
-      #    - :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this test
-      #    - :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this test
+      #    - :customer_subject_id (String) - Unique identifier in API customer's system for the person taking this exam
+      #    - :customer_client_subject_id (String) - Unique identifier in API customer's client's system for the person taking this exam
       #    - :client_code (String) - Unique identifier for API customer's client
-      #    - :reservation_id (String) - Unique identifier representing this test instance in API customer's system
+      #    - :reservation_id (String) - Unique identifier representing this exam instance in API customer's system
       #    - :session_duration (int) - Session length in minutes
-      #    - :exam_code (String) - Unique identifier representing the group of tests this specific test instance belongs to
+      #    - :exam_code (String) - Unique identifier representing the group of exams this specific exam instance belongs to
       #   Optional:
       #    - :complete_url (String) - URL that the candidate is redirected to after exam completion
       #    - :first_name (String) - First name of the candidate taking the exam
       #    - :last_name (String) - Last name of the candidate taking the exam
-      # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not scheduable.
+      # @return [int] session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not schedulable.
       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}/api/scheduling/#{__method__}"
@@ -158,7 +157,7 @@ module ProctorCam
       # @param [Hash{Symbol => String}] options
       #   Required:
       #    - :session_id (int) Proctorserve id for the session to be canceled
-      # @return [Boolean] whether or not the test was successfully canceled.
+      # @return [Boolean] whether or not the exam was successfully canceled.
       def cancel_reservation(options)
         requires_of options, [:session_id]
         url = "#{@service_protocol}://#{@service_url}/api/scheduling/#{__method__}"
@@ -177,8 +176,11 @@ module ProctorCam
       # Generate a secure token that can be used to grant temporary jsonp access to a session for a web browser user to take a session.
       #
       # @param [Hash{Symbol => String}] options
-      #   - :session_id (int) Proctorserve id for the session to grant access to
-      #   - :duration (int) Number of minutes to grant access for (defaults to 1 hour, maximum 3 hours)
+      #   Required:
+      #    - :session_id (int) Proctorserve id for the session to grant access to
+      #   Optional:
+      #    - :duration (int) Number of minutes to grant access for (defaults to 1 hour, maximum 3 hours)
+      # @return [String] the jsonp token
       def generate_jsonp_token(options)
         requires_of options, [:session_id]
 
@@ -191,12 +193,15 @@ module ProctorCam
       end
 
       # Generate a secure token that can be used to grant temporary access to a session for a web browser user to review a session.
-      # Can be loaded an iframe or a new window to grant secure access to a single user for a specified period of time
+      # Can be loaded in an iframe or a new window to grant secure access to a single user for a specified period of time
       #
       # @param [Hash{Symbol => String}] options
-      #   - :session_id (int) Proctorserve id for the session to grant review access to
-      #   - :proctor_id (String) unique identifier representing the user to grant access to. This will determine the user's display name in Proctorserve interfaces.
-      #   - :duration (int) Number of minutes link stays active for (defaults to 5 minutes)
+      #   Required:
+      #    - :session_id (int) Proctorserve id for the session to grant review access to
+      #    - :proctor_id (String) unique identifier representing the user to grant access to. This will determine the user's display name in Proctorserve interfaces.
+      #   Optional:
+      #    - :duration (int) Number of minutes link stays active for (defaults to 5 minutes)
+      # @return [String] a URL to review the session
       def generate_secure_review_url(options)
         requires_of options, [:proctor_id, :session_id]
 
@@ -220,7 +225,7 @@ module ProctorCam
       #    - :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.
+      #      - 1: Highest Severity, may be used for events like exam 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.

data/spec/proctorserv_api_spec.rb

@@ -179,14 +179,14 @@ describe ProctorCam::Proctorserv::ProctorservApi do
     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}
+      options = {:session_id => 427, :event_type => "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}
+      options = {:session_id => -1, :event_type => "completed", :proctor_id => "foo", :severity => 2}
       result = proctorserv_api.create_session_event options
       result.should be_false
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proctorserv-api
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-22 00:00:00.000000000 Z
+date: 2013-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -57,7 +57,6 @@ 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

data/lib/proctorserv_api/session_event.rb

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