Class: ProctorCam::Proctorserv::ProctorservApi

Inherits:
Object
  • Object
show all
Defined in:
lib/proctorserv_api.rb,
lib/proctorserv_api/version.rb

Constant Summary collapse

VERSION = 
"1.4.0"

Instance Method Summary collapse

Constructor Details

#initialize(api_identifier, shared_secret, service_protocol = "https", service_url = "service.proctorcam.com") ⇒ ProctorservApi

Returns a new instance of ProctorservApi.



33
34
35
36
37
38
 
# File 'lib/proctorserv_api.rb', line 33

def initialize(api_identifier, shared_secret, service_protocol = "https", service_url = "service.proctorcam.com")
  @service_protocol = service_protocol
  @service_url = service_url
  @api_identifier = api_identifier
  @shared_secret = shared_secret
end

Instance Method Details

#cancel_reservation(options) ⇒ Boolean

Cancels a reservation for a specific session_id. A session is no longer cancelable if it has already begun or the scheduled time has passed.

This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)

Parameters:

  • options (Hash{Symbol => String}) —

    Required:

    - :session_id (int) Proctorserve id for the session to be canceled

Returns:

  • (Boolean) —

    whether or not the exam was successfully canceled.



260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/proctorserv_api.rb', line 260

def cancel_reservation(options)
  requires_of options, [:session_id]
  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

  if response.code != 200
    parsed_response = JSON.parse response.body
    raise_exception_if_necessary(parsed_response) 
  end

  false
end

#create_session_event(options) ⇒ Object

Generate a session event for a testing session.

@return [Boolean] whether or not the session event was successfully created.

Parameters:

  • options (Hash{Symbol => String}) —

    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 exam revoked or emergency.
  - 2: Medium Severity, the session needs to be reviewed.
  - 3: Low Severity, common events like going through the system check.



331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/proctorserv_api.rb', line 331

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

#data_deletions(options) ⇒ Object

dataDeletions

Will delete all identifying data associated with a set of sessions
that are scoped to the smallest possible set by any of the following parameters
optional parameters:
  - ids (only delete from this list) eg [123,124,125]
  - customer_subject_id (only delete sessions associated with a customer's subject id)
  - customer_client_subject_id (only delete sessions associated with a customer's client's subject id)
  - client_code (API identifier for customer client)
  - exam_code
  - lower_bound - UTC Datetime Object (UTC seconds since epoch after which to delete sessions by reservation time. Defaults to 0)
  - upper_bound - UTC Datetime Object (UTC seconds since epoch before which to delete sessions by reservation time.
                                       Defaults to max 32 bit unsigned int)

Note that if no parameters are passed, no sessions will be deleted.

returns an array of session ids that were successfully deleted



207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/proctorserv_api.rb', line 207

def data_deletions(options) 
  url = "#{@service_protocol}://#{@service_url}/api/#{__method__}/sessions"

  # API accepts UTC Datetime Object so we must convert it to 
  # UTC seconds as that is what is required by the proctorserve api
  convert_times_to_integer options, :upper_bound if options[:upper_bound]
  convert_times_to_integer options, :lower_bound if options[:lower_bound] 
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body  
  raise_exception_if_necessary(parsed_response) if response.code != 201
  parsed_response
end

#data_retrievals(options) ⇒ Object

data_retrievals

Will return data associated with a list of sessions. 
The information returned is dependant on the elements
provided in the request

required parameters:
  - ids (session id's you would like to obtain data from)                        - Array of IDs (string)
  - elements (the type of data that you would like to retrieve for each session) - Array of elements (string)

optional elements:     Select one or more elements to receive data, if left blank no data will be returned
  - review_url         (url to proctorcam to review the past session)
  - video_url          (url to download the sessions video)
  - id_photo_url       (url to download the photo of the id provided by the sessions test taker)
  - headshot_photo_url (url to download the photo of test taker)
  - session_activity   (an array of all session events associated with the session)

 example:
  - params = {:ids => ["393", "392"], :elements => ["id_photo_url", "headshot_photo_url", "session_activity", "video_url"]}



141
142
143
144
145
146
147
148
149
 
# File 'lib/proctorserv_api.rb', line 141

def data_retrievals(options) 
  requires_of options, [:ids, :elements]
  url = "#{@service_protocol}://#{@service_url}/api/#{__method__}/sessions"
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body
  raise_exception_if_necessary(parsed_response) if response.code != 200
  parsed_response
end

#generate_jsonp_token(options) ⇒ String

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.

Parameters:

  • options (Hash{Symbol => String}) —

    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)

Returns:

  • (String) —

    the jsonp token



283
284
285
286
287
288
289
290
291
292
 
# File 'lib/proctorserv_api.rb', line 283

def generate_jsonp_token(options)
  requires_of options, [:session_id]

  options[:time] = Time.now.to_i
  options[:duration] ||= 60
  options[:duration] = 180 if options[:duration] > 180
  
  HashedAuthenticator.apply_reverse_guid_and_sign(options, @api_identifier, @shared_secret)
  options.map{|k,v| "#{k}%3D#{v}"}.join '%26'
end

#generate_secure_review_url(options) ⇒ String

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 in an iframe or a new window to grant secure access to a single user for a specified period of time

Parameters:

  • options (Hash{Symbol => String}) —

    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)

Returns:

  • (String) —

    a URL to review the session



304
305
306
307
308
309
310
311
312
313
 
# File 'lib/proctorserv_api.rb', line 304

def generate_secure_review_url(options)
  requires_of options, [:proctor_id, :session_id]

  options[:time] = Time.now.to_i
  options[:duration] ||= 5
  options[:duration] = 180 if options[:duration] > 180
  
  HashedAuthenticator.apply_reverse_guid_and_sign(options, @api_identifier, @shared_secret)
  "#{@service_protocol}://#{@service_url}/review?secure_token=#{options.map{|k,v| "#{k}%3D#{v}"}.join '%26'}#watch/#{options[:session_id]}"
end

#get_access_code(options) ⇒ Object

get_access_code

Will return a hash containing access code and its expiration date time based
on a session ID provided in the request

required parameters:
- session_id     Integer



158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/proctorserv_api.rb', line 158

def get_access_code(options) 
  requires_of options, [:session_id]
  url = "#{@service_protocol}://#{@service_url}/api/access_code/#{__method__}"
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body
  raise_exception_if_necessary(parsed_response) if response.code != 200

  return parsed_response["message"] if parsed_response["message"]
  parsed_response["access_code"]
end

#get_available_timeslots_around(options) ⇒ Array<Time>

Get a list of schedulable timeslots (represented as Time objects) around 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 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)

Parameters:

  • options (Hash{Symbol => String}) —

    Required:

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

Returns:

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



78
79
80
81
82
83
84
85
86
87
 
# File 'lib/proctorserv_api.rb', line 78

def get_available_timeslots_around(options)
  requires_of options, [:time, :num_slots, :session_duration]
  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
  raise_exception_if_necessary(parsed_response) if response.code != 200

  parsed_response.map{|timestamp| Time.at(timestamp)}
end

#get_available_timeslots_between(options) ⇒ Array<Time>

Get a list of schedulable timeslots (represented as Time objects) between two 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 an exam of duration provided.

This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)

Parameters:

  • options (Hash{Symbol => String}) —

    Required:

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

Returns:

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



53
54
55
56
57
58
59
60
61
62
 
# File 'lib/proctorserv_api.rb', line 53

def get_available_timeslots_between(options)
  requires_of options, [:lower_bound, :upper_bound, :session_duration]
  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
  raise_exception_if_necessary(parsed_response) if response.code != 200

  parsed_response.map{|timestamp| Time.at(timestamp)}
end

#make_immediate_reservation(options) ⇒ int

Makes a reservation for a session if now is a schedulable time.

This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)

Parameters:

  • options (Hash{Symbol => String}) —

    Required:

    - :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 exam instance in API customer's system
- :session_duration (int) - Session length in minutes
- :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

Returns:

  • (int) —

    session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not schedulable.



238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/proctorserv_api.rb', line 238

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__}"
  convert_times_to_integer options, :time
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body
  raise_exception_if_necessary(parsed_response) if response.code != 200

  return -1 if response.code == 404

  parsed_response["session_id"]
end

#make_reservation(options) ⇒ int

Makes a reservation for a session if the time passed in options is a schedulable time.

This method will raise exceptions related to authentication (InvalidClientException, InvalidSignatureException, InvalidIpException) or not providing required data (MissingRequiredParameterException)

Parameters:

  • options (Hash{Symbol => String}) —

    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 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 exam instance in API customer's system
- :session_duration (int) - Session length in minutes
- :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

Returns:

  • (int) —

    session_id - the Proctorserve id for the created session. Will return -1 if the time passed is not schedulable.



107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/proctorserv_api.rb', line 107

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__}"
  convert_times_to_integer options, :time
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body
  raise_exception_if_necessary(parsed_response) if response.code != 200

  return -1 if response.code == 404

  parsed_response["session_id"]
end

#reset_access_code(options) ⇒ Object

reset_access_code

Will return a hash containing new access code for a session
based on a session ID provided in the request

required parameters:
- session_id     Integer



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/proctorserv_api.rb', line 177

def reset_access_code(options) 
  requires_of options, [:session_id]
  url = "#{@service_protocol}://#{@service_url}/api/access_code/#{__method__}"
  response = RestRequestClient.new.make_post_request url, @api_identifier, @shared_secret, options

  parsed_response = JSON.parse response.body
  raise_exception_if_necessary(parsed_response) if response.code != 200
  
  return parsed_response if parsed_response["message"]
  parsed_response["access_code"]
end