ProctorCam Logo

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 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.

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 here

    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 session

    • 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.

    • ####Obtaining session details
    • dataRetrievals

    Will return data associated with a list of sessions. Users can find such information as the url to review a past session, url to download the video of a past session, url to download the photo of the id provided by the sessions test taker, a url to download the photo of test taker and a list of all session activity.

    • ####Deleting sessions
    • dataDeletions

    Will delete all identifying data associated with a set of sessions

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
Obtaining information about a list of sessions (dataRetrievals)
  • A customer wants to get information about a list of sessions
  • The integrating system makes an API request retrieve the information requested
  • The integrating system gets sent a list of all data available based on the information requested for those sessions.
Deleting a session (sessionDeletion)
  • A customer wants to delete a list of sessions
  • The integrating system makes an API request to delete a list of sessions and all associated data
  • The integrating system gets sent a list of all sessions that were sucessfully deleted

Installation

The Client API requires Ruby version >= 1.9.2. To find out what your verions is, use:

$ ruby --version

To install the client as a gem use one of the following command:

$ gem install proctorserv-api

To get the latest development version from github add the following to your Gemfile:

gem 'proctorserv-api', :git => '[email protected]:ProctorCam/proctorserv-api-rb.git'

To use our ruby API in a project

require 'proctorserv_api'

Configuration

The constructor takes two required parameters: the customer_identifier and shared_secret

What's our customer_identifier?

The Proctorserve service requires that incoming requests identify who is sending them with a customer_id parameter. Once a customer account has been set up with Proctorserve, it's customer identifier should be viewable and editable through the web interface.

What's the shared_secret for?

Proctorserve uses a secret key that is shared between customer and service as part of a two-factor authentication scheme. This is also viewable and editable through the web interface. It is important to keep this secure, otherwise a man in the middle can make requests on the integrating system's behalf.

Usage

proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret")
options = {
  :lower_bound => Time.now,
  :upper_bound => scheduling_window_start + 24 * 60 * 60, # tomorrow at this time
  :test_length => 60 # minutes
}
available_timeslots = proctorserv_api.get_available_timeslots_between options
# returns a list of available timeslots between now and 24 hours from now.

Interface

The following methods are supported

proctorserv_api = ProctorCam::Proctorserv::ProctorservApi.new("our_customer_identifier", "our_shared_secret") 
proctorserv_api.get_available_timeslots_between 
proctorserv_api.get_available_timeslots_around
proctorserv_api.make_reservation
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
proctorserv_api.data_deletions
proctorserv_api.data_retrievals

Full Documentation

Complete documentation can be found in our online developers guide located here. You will be able to find complete details regarding our api's, concepts, and getting started code recipes.