Specifications: ExpertRating ITS Integration

Title: Specifications for Integration with ExpertRating through ITS

Author: Harry Saundh
Document #: ER_ITS/10/20160719
Status: Stable Production Version
Date: July 19, 2016

Copyright © 2008-16
Restrictions: This document contains confidential information that is protected by copyright; it is intended for
restricted use only, it is not to be disclosed to a third party. All rights reserved. No part of this document may be
photocopied or reproduced in any way without the prior written permission of the authors. The information contained
in this document is subject to change without notice. Authors make no warranty of any kind with regard to this
document. Authors shall not be liable for errors or omissions contained herein or for incidental or consequential
damages in connection with the use of this document.

Table of Contents (ctrl+click on a topic)

PREFACE 3
1.1 SCOPE 3
1.2 REVISION HISTORY 3
1.3 RELATED DOCUMENTS 3
1.4 INTENDED AUDIENCE 3
1.5 COORDINATION STRUCTURE 3
2 IMPORTANT NOTES 4
3 OVERVIEW AND EXAMPLE OF ITS 5
3.1 OVERVIEW OF ITS 5
3.2 ITS SAMPLE IMPLEMENTATION SCENARIO 5
4 LANDING PAGE & TICKET GENERATION 7
4.1 OVERVIEW 7
4.2 GENERATING THE LANDING PAGE URL 7
4.3 LANDING PAGE DEBUG MODE 9
4.4 LANDING PAGE DEVELOPMENT MODE 9
4.5 LANDING PAGE REUSE MODE 10
4.6 TEST PROCTORING 10
4.6.1 Browser Proctoring........................................................................................................................10
4.6.2 Webcam Proctoring........................................................................................................................10
4.7 TICKET VALIDATION ON THE EXPERTRATING SERVER
11
4.8 DEVELOPMENT NOTES 11
5 POSTBACK SPECIFICATIONS
(SUBMITUSERTESTRESULT API) 12
5.1 OVERVIEW 12
5.2 POSTBACK DATA 12
5.3 YOUR POSTBACK URL 13
5.4 HANDLING THE POSTED DATA ON YOUR SIDE 13
5.5 RESPONDING TO THE POST BACK 14
6 POSTING OF FEEDBACK FORM DATA
(SUBMITUSERTESTFEEDBACK API) 16
6.1 OVERVIEW 16
6.2 FEEDBACK FORM DATA 16
6.3 FEEDBACK POSTING URL 17
6.4 HANDLING THE POSTED DATA ON YOUR SIDE 17
6.5 RESPONDING TO THE TEST FEEDBACK POST 18
7 SPECIFICATION OF THE GETTESTLIST API 19
7.1 OVERVIEW 19
7.2 GETTESTLIST DATA 19
7.3 DESIGN OF THE GETTESTLIST API 19
7.3.1 The Request Body........................................................................................................................... 20
SPECIFICATIONS: EXPERTRATING ITS INTEGRATION 04/13/09

7.3.2 The Response Body.........................................................................................................................20

8 SPECIFICATION OF THE GETWEBACCESSLOG API
22
8.1 OVERVIEW 22
8.2 GETWEBACCESSLOG DATA 22
8.3 DESIGN OF THE GETWEBACCESSLOG API 23
8.3.1 The Request Body........................................................................................................................... 23
8.3.2 The Response Body.........................................................................................................................23
9 SPECIFICATION OF THE GETUSERTESTINFO API
25
9.1 OVERVIEW 25
9.2 GETUSERTESTINFO DATA 25
9.3 DESIGN OF THE GETUSERTESTINFO API 25
9.3.1 The Request Body........................................................................................................................... 25
9.3.2 The Response Body.........................................................................................................................25
10 SPECIFICATION OF THE GETALLUSERTESTSINFO
API 28
10.1 OVERVIEW 28
10.2 GETALLUSERTESTSINFO DATA 28
10.3 DESIGN OF THE GETALLUSERTESTSINFO API 28
10.3.1 The Request Body......................................................................................................................... 28
10.3.2 The Response Body.......................................................................................................................28
11 SPECIFICATION OF THE GETPROCTORINGIMAGES
API 31
11.1 OVERVIEW 31
11.2 GETPROCTORINGIMAGES DATA 31
11.3 DESIGN OF THE GETPROCTORINGIMAGES API 31
11.3.1 The Request Body..........................................................................................................................31
11.3.2 The Response Body.......................................................................................................................31
12 LANDING PAGE ERRORS 33
12.1 LANDING PAGE ERRORS 33
12.2 LANDING PAGE ERRORS 33

PROPRIETARY AND CONFIDENTIAL Page 2 of 34

Preface

1.1 Scope
This document contains the specifications for integrating your website with ExpertRating’s
testing engine for the purpose of providing seamless, custom-branded testing with SSO to
your test takers. The name of this solution is ExpertRating ITS.

1.2 Revision History

Version Date Responsible Description of change
Person/Author
ER_ITS/08/20160415 Apr 15, Harry Saundh Changes related the simplified
2016 integration system
ER_ITS/09/20160715 July 15, Deepinder Singh Replaced all XML data with JSON
2016
ER_ITS/10/20160719 July 19, Harry Saundh Added proctoring parameters. Added
2016 section 11

1.3 Related Documents

Document Name Date

1.4 Intended Audience

 ExpertRating technical staff
 Your technical staff

1.5 Coordination Structure

The points of contact for activities scoped in this document are as follows:
ExpertRating Contacts: Primary: Harry Saundh (harry@expertrating.com)
Secondary: Deepinder Singh
(deepinder@expertrating.com)
Note: Please copy all communication to both contacts.

Your Contacts: To be informed

2 Important Notes

 You may suggest changes to the integration scheme, which can be incorporated after
mutual discussion and approval.
 Sentences in orange colored text require follow-up/discussion/exchange of information.
 Before allowing access to the production server, ExpertRating will set up the test engine
on a development server. Access to the production server will be given a few days prior
to launch of live testing. The Testing Service Agreement between your company and
ExpertRating must be signed prior to accessing the production server.
 As a mandatory requirement, the landing page, test pages, result page and feedback
page (hosted on ExpertRating) must have the tag line “Powered by ExpertRating”
displayed in the footer.
3 Overview and Example of ITS

3.1 Overview of ITS

ExpertRating ITS is the name given to ExpertRating’s integrated testing solution whereby
the ExpertRating testing engine is seamlessly integrated with your website allowing for tests
to be taken with a single sign-on (SSO). This document deals with 3 important aspects of
integration:

1. How to generate a testing ticket and how to pass on the user to the test engine from
your site.
2. How to capture the result of a candidate when the test engine posts it back to your
site at the end of the test.
3. How to call the various web service APIs for facilitating test administration.

3.2 ITS Sample Implementation Scenario

A sample ITS scenario is described below to help you understand how integration works.

1. Assume you own a website and you want your users to take some tests. Users can either
sign up on your site to take any test of their choice or you can invite certain users (by sending
out emails or otherwise) to take tests.

2. After registering/logging in to your site, a user browses through the list of available tests.
This list is hosted on your site, not on ExpertRating.

3. After selecting a test from the list, say the Excel test, the user clicks on the ‘Take Test’
button on your site. At this point of time, your server will send a request to the ExpertRating
server specifying the user id, the test id and some other information. In response, the
ExpertRating server will return a link for the test start page ( called the landing page.)
Thereafter, your server will forward the user to the landing page.

4. When the user reaches the landing page, the ExpertRating testing engine loads up the
Syllabus and Instructions of the Excel test.

5. After going through the instructions and syllabus, the user proceeds to take the test.

6. At the end of the test, the result page is displayed (optional.) At this time, the ExpertRating
server posts the test result to your server using JSON over HTTP.

7. Before exiting the testing system, the user is asked to provide optional feedback. This
feedback is posted to your server using JSON over HTTP.

8. Having completed the test, the user clicks a link that points to a page on your site (called
the return URL). Upon clicking the link, the user exits the testing system and lands on the
return URL. Thereafter, he/she can carry on browsing your site.
Notes:
1. To prevent the possibility of users tinkering with data, the landing page URL will
contain an encrypted authentication ticket.

2. All pages hosted on ExpertRating (test page, result page, feedback page, instructions
page) will follow the color scheme and branding of your website. The only compliance
requirement is that the ‘Powered by ExpertRating’ tag line is to be displayed in the
footer of all the pages hosted by ExpertRating.
3. ExpertRating will provide a GetTestList web service API that returns the complete list
of tests along with test Id, syllabus, time duration, passing score etc. You can call this
API to pull the aforementioned data and store it in your database and to display the
list of tests. You are advised to call this API at least once a month in order to refresh
the data in their database. The specs for this and other APIs are given in later
sections of this document.
4. Some programming will be required at your end (ExpertRating’s technical team will
be available for assistance). The three major aspects of programming are:

a) Sending a request to the ExpertRating server for generating a landing page URL,
capturing the response and redirecting the user to this URL.
b) Writing a page that accepts the result post from the ExpertRating server. A similar
page is required for accepting the feedback post (involves server-side scripting
and JSON.)
c) Calling the webservice APIs and collecting the data returned by them (involves
server-side scripting and JSON.)
4 Landing Page & Ticket Generation

4.1 Overview
The landing page is the page on the ExpertRating server where the user lands for taking a
test. Before sending the user to the landing page, you must send a request to the
ExpertRating server. In response, the ExpertRating server will return the landing page URL to
your server. Your server should then redirect the user to this URL. This process has to be
carried out each time before a user starts a test. The URL contains an encrypted ticket which
is used to authenticate the user when he or she lands on ExpertRating

4.2 Generating the Landing page URL

To generate a landing page URL, a request of the following format is to be sent to the
ExpertRating server:
partnerid=1176777&password=w131dsg353f9&user_id=demoITStestuserDB&testid=668
2&returnURL=http%3A%2F%2Fpsychometric.com

The fields in the request are explained below:

Name Type Optio Description Example

nal
partnerid INT NO A unique id assigned by ExpertRating 23231212
to your account
password STRING NO Your API password AbC3d32sfd5
user_id STRING NO An Id assigned by you to uniquely johndoe11
identify each test taker. It could be a
login name or a numeric user id.
test_id INT NO The ExpertRating test id used to 435
identify the test. You can call the
GetTestList API for obtaining the
test_ids of all the tests
return_URL STRING NO The URL on your server where the http://www.abc.
user is to be sent after the test. com

debug BOOL YES Used for debugging. Can take values 0 1

(ON) or 1 (OFF). Explained in section 4.3

dev BOOL YES Explained in section 4.4 0

reuse BOOL YES Used to generate a reusable ticket. 1
Explained in section 4.5
secure_mo BOOL YES Used to enable or disable proctoring 1
de features of the test engine. Default
value is 0 (OFF). Read section 4.6 for
more information
browser_pr BOOL YES Used to enable or disable browser 0
octoring proctoring. Default value 1.
Note: This parameter is only relevant
when secure_mode is switched on.
 Read section 4.6 for more information
max_retries INT YES Used to set the number of times a 5
candidate is allowed to navigate away
from the test window. Values can
range from 0 to 20. Default value is 3.
Note: This parameter is only relevant
when secure_mode and
browser_proctoring are switched on.
Read section 4.6 for more information
webcam_pr BOOL YES Used to enable or disable Webcam 0
octoring Proctoring. When value is 1, webcam
images of the candidate are captured
at regular intervals. Default value is 0
Note: This parameter is only relevant
when secure_mode is switched on.
Read section 4.6 for more information
webcam_m BOOL YES Setting this to 1 will prevent the test 1
andatory from starting on a machine that isn't
equipped with a webcam.
When set to 0, the test will start even if
a webcam isn't detected on the test
taker's computer. The default value is
1.
extra1 STRING YES Provision for future requirements
extra2 STRING YES Provision for future requirements

The request is to be sent through HTTP_Post to the following URL:

http://www.expertrating.com/your_site_name/get_landing_URL

In response, the ExpertRating server will return the test taking URL, which will look something
like this:

http://www.expertrating.com/your_site_name/?ticket=
adfinoidfhdfnsdfnoihoweirhqwdnd2394yuhealsnkxc234rwef45324fvsdf2

The ticket parameter contains all the fields of the request string in encrypted format, along
with a timestamp. Once your server captures the above URL, you are meant to forward the
test taker to it.

Important notes:
o The test engine will initially be deployed on ExpertRating's development server and
will be ported to a production server once the integration programming is complete in
all respects
o Sample code for generating requests and capturing the responses is available in
PHP, ASP.NET and Ruby
o ExpertRating will send you your partnerid and password before starting the
integration programming.
 o ExpertRating technical staff can assist and guide your team throughout the
integration process
o The landing page URL can be masked so that it appears to the user that he or she
hasn't left your site.

4.3 Landing Page Debug Mode

To assist in debugging during integration programming, a debug feature is available. Debug
mode can be activated by passing debug=1 in the request string. When debug mode is
activated, the entire test flow will function normally, but in addition, the following will happen:
 On the landing page, the entire decrypted contents of the ticket will be dumped to the
screen
 At the end of the test, the JSON test result string (that is being posted to your server)
will be dumped to the screen. Along with this, the response that is received back from
your server will also be dumped to the screen.

Example:

http://www.expertrating.com/your_site_name/?ticket=
adfinoidfhdfnsdfnoihoweirhqwdnd2394yuhealsnkxc234rwef45324fvsdf2&debug=1

4.4 Landing Page Development Mode

A development mode feature is provided on the landing page to allow you to integrate the
ExpertRating server with your dev/staging environment. Development mode can be activated
by passing dev=1 in the request string. The differences between development mode and live
mode are as follows:

 In development mode, at the end of the test, the results will be posted (JSON over
HTTP) to your development server, rather than your production server.
 In development mode, at the end of the tests, the feedback will be posted (JSON over
HTTP) to your development server, rather than your production server.
 The development mode feature will continue to be available after the launch of live
testing. Tests taken in development mode will not be billed.

Example:

http://www.expertrating.com/your_site_name/?ticket=
adfinoidfhdfnsdfnoihoweirhqwdnd2394yuhealsnkxc234rwef45324fvsdf2&dev=1
4.5 Landing Page Reuse Mode
Ordinarily a ticket in the landing page URL can only be used once, after which it gets
invalidated. For subsequent test attempts, a fresh URL (containing a fresh ticket) has to be
generated each time. However, if you wish to generate a reusable URL for debugging or QA
purposes, you can do so by passing reuse=1 in the request string. Reusable tickets don't
carry an expiry date.

Example:

http://www.expertrating.com/your_site_name/?ticket=
adfinoidfhdfnsdfnoihoweirhqwdnd2394yuhealsnkxc234rwef45324fvsdf2&reuse=1

4.6 Test Proctoring

The ExpertRating test engine supports test proctoring features to prevent test takers from
cheating. Proctoring is switched on by setting the secure_mode parameter to 1. There are
two types of proctoring available- browser proctoring and webcam proctoring. Each of these
may be switched on or off individually. Proctoring features have wide browser and device
support but if a test taker attempts to start a test on an unsupported device, the test will not
start and an appropriate message will be displayed.

4.6.1 Browser Proctoring

This is used to prevent the test taker from navigating away from the test taking window. It will
stop the user from:
 Opening another browser tab
 Opening another browser window
 Opening another application
 Navigating to the desktop
 Minimising the test window

The max_retries parameter is used to give leeway to test takers- if max_retiries is set to 0, the
very first violation will result in the test session being terminated. If max_retries is set to 1, the
first violation will result in a warning and the second violation will result in termination.
Max_retries can take values from 0 to 20.

4.6.2 Webcam Proctoring

This is used to capture webcam images (.jpg) of the test taker at periodic intervals. The
webcam_mandatory parameter is used for choosing between making webcams mandatory or
optional. If webcam_proctoring is set to 1, the images captured by the test taker's webcam
are instantly uploaded to ExpertRating's servers. An API is available (see section 11) that
allows you to download these images in zip or pdf formats. ExpertRating will retain the
images on its servers for a period of not less than 8 weeks after which they will be
permanently deleted.
4.7 Ticket Validation on the ExpertRating Server

Given below are some scenarios of how the tickets will be used on the ExpertRating server
for validation:
1. If the user tries to start a test with a fresh ticket (one which hasn't been used
previously), the ExpertRating server will allow the test to start.
2. If a user tries to start a test using a ticket that has already been used previously, the
ExpertRating server will not allow the test to start and will display the ‘Ticket has
already been used’ message to the screen.
3. A user starts a test, leaves it midway, goes back to your site with the intention of
resuming the same test and gets a fresh ticket. In this case, the ExpertRating server
will allow the test to resume from the same point where the user had left off provided
the attempt to resume is made within 60 minutes of originally starting the test. If 60
minutes have elapsed, the test will be cancelled.
4. If a user has completed a test (pass or fail), he will not be allowed to re-take the same
test for a period of 24 hours (or some other timeframe, as per your re-take policy).
Note that if a user simply comes to the landing page and goes back your site but
doesn’t actually start the test, he or she will not be required to wait for 24 hours to
take the same test.
5. Suppose a user saves the landing page URL for later use. A ‘Ticket Expired’ error will
be generated if the ticket is more than 60 minutes old and the user will not be allowed
to start the test. If its less than 60 minutes old, the test will be allowed to start.
6. If the ticket is malformed in any way and fails to decrypt, an appropriate message will
be shown on the screen. See section 11 for error codes and messages.

4.8 Development Notes

 During the integration programming phase, ExpertRating will allow access to a limited
set of demo skill tests only. The entire test list will be opened up close to the final
launch date. The demo testids are:
6682, 6683, 6684, 6685
 The dev, reuse and debug switches can be used individually or in combination with
one another. An example of a request in which all 3 have been used is:

http://www.expertrating.com/your_site_name/?ticket=
adfinoidfhdfnsdfnoihoweirhqwdnd2394yuhealsnkxc234rwef45324fvsdf2&debug=1&reuse=1&
dev=1
5 PostBack Specifications (SubmitUserTestResult API)

5.1 Overview
When a user completes his/her test, the result will be posted to your server. PostBack will be
done using JSON over HTTP.

5.2 PostBack Data

The PostBack will pass the following data to your server:

Field Name Type Optional Description Example

user_id STRING NO The user_id that was received 41101
by the ExpertRating landing
page in the ticket t
transcript_id INT NO A unique Result Id assigned by 4234232
ExpertRating.
test_id INT NO The Id of the test (assigned by 231
ExpertRating) that the user took
test_name STRING NO Name of the test that the user ASP 3.0 Test
took
percentage INT NO The percentage score of the test 75
taker in the test
percentile INT NO The percentile rank of the test 60
taker in the given test. This is
calculated based on scores of all
ExpertRating test takers.
average_score INT NO The average score for the test 55
based on the scores of all
previous test takers for the given
test.
test_result STRING NO Will contain the values ‘PASS’ or PASS
‘FAIL’
time DATETIME NO The date and time (UTC) of 2006-04-
completing the test in ISO 8601 19T14:05:11Z
standard date notation.
5.3 Your PostBack URL
The ExpertRating server will post the results to the following URL on your server:
Production URL to be informed by you.
Dev URL to be informed by you.

HTTP Post method will be used for the post back and JSON data will be posted. Your server
should return a JSON response informing ExpertRating whether the post back was a success
or a failure.

5.4 Handling the posted data on your side

The result data will be posted to your server as JSON as per the following example:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "SubmitUserTestResult",
"parameters": [{
"name": "user_id",
"value": "42511"
}, {
"name": "transcript_id",
"value": "4234232"
}, {
"name": "test_id",
"value": "231"
}, {
"name": "test_name",
"value": "ASP 3.0 Test"
}, {
"name": "percentage",
"value": "75"
}, {
"name": "percentile",
"value": "60"
}, {
"name": "average_score",
"value": "50"
}, {
"name": "test_result",
"value": "PASS"
}, {
"name": "time",
"value": "2006-04-19T14:05:11Z"
}]
}
}
}

Before inserting the results in to its database, you should perform the following:
  Ensure that the authentication partnerid and password are correct. The actual
partnerid and password will be communicated to you separately. The partnerid and
password are required in all APIs described in this document.
 Ensure that the post is coming from the ExpertRating server IP address range.
 Ensure that the transcript_id doesn’t already exist in your database. If the
transcript_id already exists, it signifies a duplicate post. In such a case, the data in
the current post should be ignored.
 Check if the user_id belongs to a valid user. If it doesn’t, then the post should be
ignored and an error should be returned.

5.5 Responding to the Post Back

When your server receives a post back, it should respond with a JSON stream as follows:

{
"response": {
"info": {
"success": "",
"transcript_id": "",
"error": ""
}
}
}

The <info> element will have the following attributes:

Attribute Name Optional Description Example

success NO Either 1 or 0 depending upon 1
whether the posting was a
success or a failure.
transcript_id NO The transcript_id for the result 4234232

error YES If an error occurs, the Transcript Id

description of the error will be already exists
contained in this attribute

Examples of post back responses:

 {
"response": {
"info": {
"success": "1",
"transcript_id": "34234223"
}
}
}

{
"response": {
"info": {
"success": "0",
"transcript_id": "34234223",
"error": "Incorrect user_id"
}
}
}

In case of a failed post back, the ExpertRating server will log the post back details and add
them to a queue. The ExpertRating server will process the queue on an hourly basis (24
times a day). Postings that still remain stuck will be logged for manual investigation and
subsequent re-posting.
In case your server receives a duplicate post (a test result which had already been received
earlier), it should respond as follows:

{
"response": {
"info": {
"success": "1",
"transcript_id": "34234223"
}
}
}
6 Posting of Feedback Form data (SubmitUserTestFeedback
API)

6.1 Overview

A feedback form is provided at the end of the test to allow test takers to rate the quality of the
test and to suggest improvements. The feedback collected via the form will be posted your
server using a technique similar to the result posting described in the previous section.

6.2 Feedback form data

The following data will be posted (HTTP Post method) to your server.

Field Name Type Optio Description Example

nal
user_id STRING NO The user_id that was 42511
received by ExpertRating in
the ticket t
transcript_id INT NO A unique Result Id assigned 4234232
by ExpertRating.
test_id INT NO The Id of the test (assigned 231
by ExpertRating) that the
user took
content_rating INT (1 – 5) NO Rating of the test content 4
on a scale of 1 to 5
(1=poor)
content_comments STRING NO Specific feedback regarding All questions
(1000) the test content (will be were good
URLEncoded)
procedure_rating INT (1 – 5) NO Rating of the test content 5
on a scale of 1 to 5
(1=poor)
procedure_comments STRING NO Specific feedback regarding Easy to use
(1000) the testing procedure and interface
interface (will be
URLEncoded)
errors_found YES/NO NO Whether the test taker YES
found any errors in the test
errors_details STRING YES Description of errors found, I think I saw a
(1000) if any (will be URLEncoded) spelling
mistake
time DATETIME NO The date and time (UTC) of 2006-04-
submission in ISO 8601 19T14:05:11Z
standard date notation.
6.3 Feedback Posting URL
The ExpertRating server will post the feedback to the following URL on your server:
Live URL to be informed by you
Dev URL to be informed by you

POST method will be used and JSON data will be posted. Your server will return a JSON
response informing ExpertRating whether the posting was a success or a failure.

6.4 Handling the posted data on your side

The test feedback will be posted to your server as per the following example:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "SubmitUserTestFeedback",
"parameters": [{
"name": "transcript_id",
"value": "1384111"
}, {
"name": "test_id",
"value": "34"
}, {
"name": "user_id",
"value": "42511"
}, {
"name": "time",
"value": "2007-09-25T06:32:13Z"
}, {
"name": "content_rating",
"value": "3"
}, {
"name": "content_comments",
"value": "Its+great%2Enot+bad%2E%2E%2E
%2Equite+okay"
}, {
"name": "procedure_rating",
"value": "4"
}, {
"name": "procedure_comments",
"value": "Test+procedure%2C+format%2C+performance
%2C+and%0D%0Ageneral+usability%2E%2E%2Eall+these+parameters+are+fine%2E"
}, {
"name": "errors_found",
"value": "no"
}, {
"name": "errors_details",
"value": "no%2E%2E%2E"
}]
}
}
}
6.5 Responding to the Test Feedback Post
When your server receives the test feedback post, it should respond with a JSON stream as
follows:

{
"response": {
"info": {
"success": "",
"transcript_id": "",
"error": ""
}
}
}

The <info> element will have the following attributes:

Attribute Name Optional Description Example

success NO Either 1 or 0 depending upon 1
whether the posting was a
success or a failure.
transcript_id NO The transcriptid of the result 4234232

error YES If an error occurs, the Feedback JSON

description of the error will be is not well formed
contained in this attribute

Examples of test feedback posting responses:

{
"response": {
"info": {
"success": "1",
"transcript_id": "42511"
}
}
}

{
"response": {
"info": {
"success": "0",
"transcript_id": "45531",
"error": "Incorrect user_id"
}
}
}
7 Specification of the GetTestList API

7.1 Overview
The GetTestList API is provided so that you can populate your database with the list of
available tests (test_id, test_name, total_questions, coverage, duration, passing_marks and
category). Note that all APIs return a stream of JSON data and they are all to be called
by passing a JSON data request in the form of an HTTP Post. Only requests from your
server IP addresses will be accepted (range of IP addresses to be provided by you)

7.2 GetTestList Data

The GetTestList API will return the following fields of data:

Field Name Type Description Example

test_id INT The ExpertRating assigned 221
unique test id
test_name VARCHAR( The name of the test ASP.NET 2003
200) Test

total_questions INT The number of questions that 40

a candidate will be asked in
the test
coverage VARCHAR( The list of topics covered in Introduction to
2000) the test. Semi-colon (;) will be ASP.NET;Syntax;
used as a delimiter between Advanced
the topic names Features…..

duration INT The duration of the test in 40

minutes
passing_marks INT The percentage score that a 60
candidate must attain to pass
the test. The default passing
score is 60%. You can
suggest a higher or lower
passing score. The passing
score will be the same for all
tests.
category VARCHAR( The category to which the Internet
200) test belongs. Programming
Technologies

7.3 Design of the GetTestList API

The web service endpoint for all APIs is:
http://www.expertrating.com/your_site_name/webservices

Both the request and response will be represented in JSON

7.3.1 The Request Body
You will post the following request to the web service endpoint:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "GetTestList"
}
}
}

7.3.2 The Response Body

When the request is received, the API will return the list of tests in the following
format:

{
"response": {
"result": {
"name": "GetTestList",
"records": [{
"test_id": 0,
"test_name": "",
"coverage": "",
"total_questions": 0,
"duration": 0,
"passing_marks": 0,
"category": ""
}]
}
}
}

Here is a sample of the response:

{
 "response": {
"result": {
"name": "GetTestList",
"records": [{
"test_id": 202,
"test_name": "ADO.NET 2003",
"coverage": "...",
"total_questions": 40,
"duration": 40,
"passing_marks": 60,
"category": "..."
}, {
"test_id": 124,
"test_name": "ASP.Net",
"coverage": "...",
"total_questions": 30,
"duration": 40,
"passing_marks": 60,
"category": "..."
}, {
"test_id": 1143,
"test_name": "PHP 5",
"coverage": "...",
"total_questions": 10,
"duration": 10,
"passing_marks": 60,
"category": "..."
}]
}
}
}
8 Specification of the GetWebAccessLog API

8.1 Overview

The GetWebAccessLog API is provided so that you can view visitor data. The API accepts a
date range and returns the list of visitors coming from your site to ExpertRating between the
dates.

8.2 GetWebAccessLog Data

The GetWebAccessLog API will return the following fields of data:

Field Name Type Description Example

user_id STRING The user_id that was 412101
received by ExpertRating in
the ticket t
time DATETIME Date and time that the test 2006-04-
was taken in UTC (ISO 8601) 19T04:05:11Z

ipaddress STRING IP Address of the browser 202.134.3.21

machine
url VARCHAR( Complete URL of the landing http://www.expertr
500) page along with form fields ating.com/partner
_site_name/?
t=dfinoidfhdfnsdfn
oihoweirhqwdnd2
394yuhealsnkxc2
34rwef45324fvsdf
error VARCHAR( A descriptive error message Ticket has
100) in case the user’s ticket failed already been
a validation check on the used.
landing page
errorcode INTEGER A unique errorcode relating to 201
the above error
8.3 Design of the GetWebAccessLog API

8.3.1 The Request Body

You will post the following request to the web service endpoint:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "GetWebAccessLog",
"parameters": [{
"name": "from_date",
"value": "2006-04-19T00:00:00Z"
}, {
"name": "to_date",
"value": "2006-04-19T23:59:59Z"
}, {
"name": "errorsonly",
"value": "1"
}, {
"name": "user_id",
"value": "1243121"
}]
}
}
}

If the user_id element is not present, then access records for all users will be returned.
If the errorsonly parameter has a value of 1 then only error records will be returned.
Otherwise if it has a value of 0 or if the parameter is omitted from the JSON request, all rows
will be returned (error as well as without-error).

8.3.2 The Response Body

When the request is received, the API will return the list of visitors in the following
format:
{
"response": {
"result": {
"name": "GetWebAccessLog",
"records": [{
"user_id": "",
"time": "",
"ipaddress": "",
"url": "",
"errorcode": "",
"error": ""
}]
}
}
}
Here is a sample of the response:
{
"response": {
"result": {
"name": "GetWebAccessLog",
"records": [{
"user_id": "42511",
"time": "2006-07-12T04:16:27Z",
"ipaddress": "201.121.35.132",
"url":
"http://www.expertrating.com/partner_site_name/?
t=sdfaseJjghDrtGlXVCCqtEoS5PlvED2uwlabfEN2DvcaHiF49GxkjCoU/sgHFA1f9T0PBcuInKxj
+xeKUi7rEcZR0jFUQ93SWvNJIlXymrhrnIPJUnCVi3QVIbCoI",
"errorcode": "203",
"error": "Ticket already used"
}, {
"user_id": "45531",
"time": "2006-07-12T04:16:27Z",
"ipaddress": "209.128.65.130",
"url":
"http://www.expertrating.com/partner_site_name/?
t=rPFSseJjghDrtGlXVCCqtEoS5PlvED2uwlabfEN2DvcaHiF49GxkjCoU/sgHFA1f9T0PBcuInKxj
+xeKUi7rEcZR0jFUQ93SWvNJIlXymrhrnIPJUnCVi3QVIbCoI",
"errorcode": "",
"error": ""
}]
}
}
}
9 Specification of the GetUserTestInfo API

9.1 Overview
The GetUserTestInfo API is provided so that you can fetch the test results of any user on the
basis of user_id. The API accepts the user_id and returns all the test results of the specified
user.

9.2 GetUserTestInfo Data

The fields that are returned by this API are identical to the SubmitUserTestResult API, except
that in this case, the results pertain to all tests taken by the given candidate. Another
difference is that unlike SubmitUserTestResult, the user_id field is not returned by this API.
Please refer to section 4.2 for the list of fields.

9.3 Design of the GetUserTestInfo API

9.3.1 The Request Body

You will post the following request to the web service endpoint:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "GetUserTestInfo",
"parameters": [{
"name": "user_id",
"value": "42511"
}]
}
}
}

9.3.2 The Response Body

When the request is received, the API will return the results of the given user in the
following format:

{
"response": {
"result": {
"name": "GetUserTestInfo",
"records": [{
 "record": [{
"name": "user_id",
"value": ""
}, {
"name": "transcript_id",
"value": ""
}, {
"name": "test_id",
"value": ""
}, {
"name": "test_name",
"value": ""
}, {
"name": "percentage",
"value": ""
}, {
"name": "percentile",
"value": ""
}, {
"name": "average_score",
"value": ""
}, {
"name": "test_result",
"value": ""
}, {
"name": "time",
"value": ""
}]
}]
}
}
}

Here is a sample of the response:

{
"response": {
"result": {
"name": "GetUserTestInfo",
"records": [{
"record": [{
"name": "user_id",
"value": "1243121"
}, {
"name": "transcript_id",
"value": "4234232"
}, {
 "name": "test_id",
"value": "231"
}, {
"name": "test_name",
"value": "ASP 3.0 Test"
}, {
"name": "percentage",
"value": "75"
}, {
"name": "percentile",
"value": "81"
}, {
"name": "average_score",
"value": "9"
}, {
"name": "test_result",
"value": "PASS"
}, {
"name": "time",
"value": "2006-04-19T14:05:11Z"
}]
}, {
"record": [{
"name": "user_id",
"value": "1243121"
}, {
"name": "transcript_id",
"value": "423231"
}, {
"name": "test_id",
"value": "551"
}, {
"name": "test_name",
"value": "PHP 5 Test"
}, {
"name": "percentage",
"value": "31"
}, {
"name": "percentile",
"value": "1"
}, {
"name": "average_score",
"value": "9"
}, {
"name": "test_result",
"value": "FAIL"
}, {
"name": "time",
"value": "2006-04-19T14:05:11Z"
}]
}]
}
}
}
10 Specification of the GetAllUserTestsInfo API

10.1 Overview
The GetAllUserTestsInfo API is provided so that you can fetch the test results of all your users
based on a date range. The API accepts a date range and returns all the test results of all
users for tests taken between the given dates.

10.2 GetAllUserTestsInfo Data

The fields that are returned by this API are identical to the SubmitUserTestResult API, except
that in this case, the results pertain to all tests taken by all candidates within the given dates.
Please refer to section 4.2 for the list of fields.

10.3 Design of the GetAllUserTestsInfo API

10.3.1 The Request Body

You will post the following request to the web service endpoint:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "GetAllUserTestsInfo",
"parameters": [{
"name": "from_date",
"value": "2006-04-19T00:00:00Z"
}, {
"name": "to_date",
"value": "2006-04-19T23:59:59Z"
}]
}
}
}

10.3.2 The Response Body

When the request is received, the API will return the results of the users in the
following format (this is almost identical to the GetUserTestInfo API, except that in this
case, user_id is also being returned):

{
"response": {
"result": {
"name": "GetAllUserTestsInfo",
 "records": [{
"record": [{
"name": "user_id",
"value": ""
}, {
"name": "transcript_id",
"value": ""
}, {
"name": "test_id",
"value": ""
}, {
"name": "test_name",
"value": ""
}, {
"name": "percentage",
"value": ""
}, {
"name": "percentile",
"value": ""
}, {
"name": "average_score",
"value": "7"
}, {
"name": "test_result",
"value": ""
}, {
"name": "time",
"value": ""
}]
}]
}
}
}

Here is a sample of the response:

{
"response": {
"result": {
"name": "GetAllUserTestsInfo",
"records": [{
"record": [{
"name": "user_id",
 "value": "ASPGuru10"
}, {
"name": "transcript_id",
"value": "4234232"
}, {
"name": "test_id",
"value": "231"
}, {
"name": "test_name",
"value": "ASP 3.0 Test"
}, {
"name": "percentage",
"value": "75"
}, {
"name": "percentile",
"value": "60"
}, {
"name": "average_score",
"value": "7"
}, {
"name": "test_result",
"value": "PASS"
}, {
"name": "time",
"value": "2006-04-19T14:05:11Z"
}]
}, {
"record": [{
"name": "user_id",
"value": "PHPBoss"
}, {
"name": "transcript_id",
"value": "343231"
}, {
"name": "test_id",
"value": "251"
}, {
"name": "test_name",
"value": "MySQL Test"
}, {
"name": "percentage",
"value": "41"
}, {
 "name": "percentile",
"value": "1"
}, {
"name": "average_score",
"value": "7"
}, {
"name": "test_result",
"value": "FAIL"
}, {
"name": "time",
"value": "2006-04-19T14:05:11Z"
}]
}]
}
}
}
11 Specification of the GetProctoringImages API

11.1 Overview
The GetProctoringImages API is provided so that you can fetch the webcam images that have
been captured during a proctored test. The API accepts the transcriptid of the test attempt
and retirns the download link to the image files.

11.2 GetProctoringImages Data

The API will return two download links. The first download link points to a zip file
containing all the proctoring images for the test session, and the second download
link points to a pdf file containing the same images. Once you have called the API
and saved the download links, you can download the actual zip or pdf file at your
convenience. Note that the retention period for zip and pdf files is 8 weeks, after
which the files will be permanently deleted from ExpertRating servers.

11.3 Design of the GetProctoringImages API

11.3.1 The Request Body

You will post the following request to the web service endpoint:

{
"request": {
"authentication": {
"password": "",
"partnerid": ""
},
"method": {
"name": "GetProctoringImages",
"parameters": [{
"name": "Transcriptid",
"value": "123456"
}]
}
}
}

11.3.2 The Response Body

When the request is received, the API will return the following stream:

{
"response": {
 "result": {
"name": "GetProctoringImages",
"records": [{
"transcriptid": "860934",
"zipfile":
"http://www.expertrating.com/partner_site_name/Reports/GetImgResponse.aspx?
data=5zqfA3JHh8t7EOaNZZ1DXaJdS0DQOsA93erfsUOqGgA=",
"pdffile":
"http://www.expertrating.com/partner_site_name/Reports/GetImgResponse.aspx?
data=HnVPzJPqQll7EOaNZZ1DXaJdS0DQOsA93erfsUOqGgA="
}]
}
}
}
12 Landing Page Errors

12.1 Landing page errors

The following section lists the possible error messages that could be displayed on the landing
page. Most of these errors never occur in production although there is a possibility of
occurrence during development and testing. Not all of these errors are applicable to each ITS
partner.

12.2 Landing page errors

Errorcode Error Description/Comments

201 Missing ticket parameters Ticket is not present
202 Decryption failed Ill formed ticket
203 Ticket already used
The ticket doesn't contain all the data that it is
204
Insufficient parameters supposed to
205 User_id not present The user_id field is missing in the ticket
206 Test_id not present The test_id field is missing in the ticket
The ticket does contain a test_id, but that
207
test_id doesn't match with any tests in our
Incorrect TestId database
208 Return URL not present Problem with the return URL in the ticket
209 Invalid ticket timestamp Problem with the timestamp in the ticket
210 Ticket expired
You cannot retake the test
211
before <date-time> The user is stuck in the retake wait period
The user has already taken this test up to the
212
maximum number of times allowed (in case
you have set an upper limit on the number of
Re-take limit exceeded retries)
213 An internal flag is missing An internal flag is missing from the ticket.

In each of these cases, an appropriate message will be displayed to the user along with a link
to return to your site.