Mettl Proctoring as a Service(MPaaS) API Documentation 

 

Document Version: ​v1.0 

Document Release Date:​ 12​th​ March, 2018 

Please contact us on ​[email protected]​ for any queries. 

----------- { 1 }---------- 
  

 
Table of Content 
1.​ ​README 3 
1.1​ ​What is M
​ PaaS   3 
1.2 How does MPaaS work 3
1.2.1 ​MPaaS Sequence Diagram ​ 4 
1.3 W
​ hat cannot be done using MPaaS APIs 5 
2. List of APIs 5 
​2.1 Init 5 
2.2​ CheckSystemCompatibility 8 
2.3​ SetEventListener 9 
2.4​ ​Set​MessageListener 10 
2.5 S
​ et​ErrorListener 10 
2.6​ ​SendMessage 11 
2.7​ ​Start 12 
2.8​ Stop 12 
2.9 Get​Report 13 
 
 

Scroll to Top   
----------- { 2 }----------   
 
1. README  
Welcome to Mettl Proctoring as a Service APIs document. This document details REST based APIs using which the API consumer can integrate with Mettl Proctoring Services.  

 1.1 What is MPaaS 

MPaaS a proctoring specific API layer built on top of Mettl systems which enables clients to easily integrate & start using Mettl Proctoring on top of their services (assessments, trainings, courses 
etc). MPaaS APIs can be integrated and used by-  

● Clients/LMS/ATS etc who already have content/courses, workflows & assessment systems in place but require proctoring.  
● Clients who create their own content and have reservations in sharing the same with Mettl but require proctoring. 
 

1.2 How does MPaaS work? 

MPaaS can be very easily integrated with client systems(HRMS, ATS, LMS, Web apps etc). For a client to start using MPaaS & enable proctoring on their systems, the below mentioned steps can be 
followed. This flow is also explained in the sequence diagram given below.  

1. Client calls MPaaS​ Init API​ to register with and to initialize Mettl’s Proctoring Service. 
2. In the ​Init​ A
​ PI ​itself, the client needs to pass certain attributes that uniquely identify the candidate, group(name of assessment, training, program tha candidate is taking ) along with 
proctoring settings(screen capture On/Off, video recording On/Off etc).  
3. If Init is successful, the it returns a ​token​ to the client. 
4. Client then calls the C ​ heckSystemCompatibility API​ along with the token generated in the init API.  
5. This launches a new tab/window where MPaaS performs the system check(camera/microphone & screen capture permissions) for candidate’s machine(laptop/desktop). (At this step, 
candidate might be requested to download & install a Chrome plugin). 
6. Upon a successful System Check, the candidate is shown a message requesting them to minimize(& Not close) this tab/window and switch to client window to continue with the 
test/training/program etc. 
7. A successful ​CheckSystemCompatibility​ call returns ​proctoringSession object​. 
8. If ​Init API​ and C ​ heckSystemCompatibility API​ are called successfully, client system can then allow the candidate to start the test/training/program. Client uses ​proctoringSession​ object 
to call S​ tart API​ and start proctoring for the candidate. 
9. When candidate finishes the test/training/program, client can then use the same p​ roctoringSession​ object to call​ Stop API​ and stop proctoring for the candidate. 
10. In between the test, p​ roctoringSession ​object can call any of the following functions depending upon the requirement: 
a. SetEventListener 
b. SetMessageListener 
c. SendErrorListener 
d. SendMessage 
11. After candidate’s test is finished, client can call the ​GetReport API​ to get the test report for the candidate as a URL or JSON data. 
 

Scroll to Top   
----------- { 3 }----------   
1.2.1 MPaaS Sequence Diagram 

Scroll to Top   
----------- { 4 }----------   
  
 
1.3 What cannot be done using Mettl Proctoring as a Service APIs 
Please note that the following activities ​cannot be done through MPaaS APIs  
● Proctoring service will not be an unlimited video recording/surveillance solution that can be deployed for online & real-time/recorded monitoring of employees/students etc.  
● Mobile devices support MPaaS until Screen Capture mode is kept off. But in future, MPaaS will work on devices irrespective of Screen Capture is kept on or off. 

2. List of MPaaS APIs 

There are 3 APIs and 6 Javascript functions that have been exposed for easier access to MPaaS. 

  2.1 Init API 

This is a S
​ erver to Server API​. Register a candidate with Mettl Proctoring Service(MPaaS) using a public/private key. Set proctoring mode for the session.  

Request URL  https://mpaas-api.mettl.pro/v1/init     

Header  Authorization: signature 

Request Method  POST 

Signature Generation  Create a json with publicKey, uniqueId, timeStamp etc.  

Example​:- {publicKey:”abcd”,uniqueId:”e08923”,timeStamp:””} 
 
Now create a hash using (SHA or PBKDF) algorithm with input as above string and salt as privateKey. 

Arguments   
 
Name  Mandatory  Type  Description 

publicKey  Yes  String  Client’s public key 

timeStamp  Optional  String  Time of Request Sent 

uniqueId  Yes  String  User’s uniqueId 

Scroll to Top   
----------- { 5 }----------   
 expiryTime  Optional  Long  Time in milliseconds in which token will expire 

groupName  Yes  String  Name of the assessment/training etc 

parentGroupId  Optional  Int  Parent of Group Name passed 

proctoringSettings  Optional  String  Json containing proctoring setting like screenCapture 

  etc.{“screenCapture”:”true”,"recordingOn": true, 
”isCandidateAuthorization”: “true”}​) 

userMetadata  Optional  String  Json containing info like userType etc. 

{“userType”:”0”,”groupId”:””} 

 
Example​:- This api is exposed through HTTP request. API can be accessed by sending post request to mettl server. 
Create json of above mentioned input parameters. Send this json as payload in post request, sample json is as below. 
{“publicKey”:”abcd”,”uniqueId”:”abcd”,”expiryTime”:”5000”,”proctoringSetting”:{“screenCapture”:”true”,”autoStart”:”true”,”isCandidateAuthorization”: 
“true”},”userMetadata”:{“userType”:”0”}} 
In headers put a custom header with name Authorization and it’s value as signature.  
Output​: JSON containing Token to be used in below mentioned APIs. 

Response  JSON containing success response for Init API 

{ "status": "SUCCESS", 
“token”:” ” 
}  
 
JSON containing failure of response for Init API 
{ 
"status": "ERROR", 
"error": { 
"errorCode": "E001", 
"message": "Signature mismatch" 
} 
} 
 

Scroll to Top   
----------- { 6 }----------   
 Error Codes   

Error Code  Message 

E000  No client for public Key 

E001  Signature mismatch 

E002  request not valid 

E003  Token expired 

E004  Token not valid 

E005  token not registered 

E006  Something went wrong 

 

   

Scroll to Top   
----------- { 7 }----------   
 2.2 CheckSystemCompatibility API   
To check candidate's system/laptop supports the minimum hardware & software requirements to support proctoring. A new child window is opened which requests for 
permissions(webcam/microphone) & check browser compatibility etc. Provides information about whether machine is compatible for proctoring. 

NOTE​: Include MP.js in your html page and through MP object invoke this function i.e. MP.launchProctoring or Mp.killProctoring 

Arguments   

Name  Mandatory  Description 

token  Yes  Token received in INIT API 

publicKey  Yes  Client’s public key given by Mettl 

successCallback  Yes  Function which will be invoked if diagnostics is successful 

(proctoringSession) 

errorCallback(error)  Yes  Function which will be invoked if diagnostic fails. Takes input parameter 
error. Structure of Error is mentioned below 

 
Example: 
This API returns proctoringSession object, which can be used to invoke Start, Stop, Send Message API. It will launch a new window.  
Define these two functions in javascript: 
function successCallback(proctoringSession){ 
} 
 
function errorCallback(error){ 
} 
MP.checkSystemCompatibility(“myToken”, ”publicKey”, successCallback, errorCallback)  

Output  proctoringSession object 

Scroll to Top   
----------- { 8 }----------   
 Response  No JSON Response​, this API returns proctoringSession object. 

   
 
Name  Type  Description 
 
  type  String  Error type  
Error 
  message  String  Human understandable error description 
 
  errorCode  String  Error code 

 
 
2.3 SetEventListener   
To register with MPaaS and listen for incoming events from Proctor. To be set using proctoringSession object: 

Arguments  N/A 

Object of event   

Name  Mandatory  Description 

type  Yes  start/stop/sendMessage etc. 

status  No  success/error 

errorCode  No  errorCode 

message  No  message 

 
Example:​ ​create a callback function in javascript: 
function eventListenerMethod(event){ 
} 
Then set this callback in​ p​ roctoringSession.setEventListener(eventListenerMethod) 

Scroll to Top   
----------- { 9 }----------   
 
 
2.4 SetMessageListener 
To register with MPaaS and listen for incoming messages from Proctor. To be set using proctoringSession object: 

Arguments  N/A 

Object of msg   

Name  Mandatory  Description 

from  Yes  Who sent this message 

message  Yes  message 

 
Example: 
Create a callback function in javascript: 
function messageCallback(msg){ 
 
} 
 
Then set this callback in proctoringSession.setMessageCallback(messageCallback); 

 
 
2.5 SetErrorListener 
To register with MPaaS and listen for incoming error from Proctor. To be set using proctoringSession object: 

Arguments  N/A 

Object of error   

Name  Mandatory  Description 

Scroll to Top   
----------- { 10 }----------   
 errorCode  Yes  Error Code 

message  Yes  Human understandable error description 

 
Example: 
Callback Method - To handle incoming error messages 
Create a callback function in js. 
function ErrorCallback(error){ 
 
} 
Then set this callback in proctoringSession.setErrorCallback(ErrorCallback); 

 
 
2.6 SendMessage 
To send a chat message from candidate to MPaaS(proctor). To be invoked using proctoringSession object: 

Arguments   

Name  Mandatory  Description 

message  Yes  Message (plain text) 

 
Example:   
​proctoringSession.sendMessage(“Hi! I need help”);  

Output  Message sent to the proctor 

Scroll to Top   
----------- { 11 }----------   
 
 
2.7 Start 
Start proctoring. To be invoked using proctoringSession object: 

Pre-Conditions  Initialize & CheckSystemCampatibility has been successful. 

Arguments  Zero argument API 

Example: 
successCallback here is that which got returned in launch-proctoring API. 
function successCallback(proctoringSession){ 
proctoringSession.start(); 
} 

Output  Proctoring Starts 

 2.8 Stop 
​Stop proctoring. To be invoked using proctoringSession object: 

Arguments  Zero Argument API 

Example: 
proctoringSession.stop(); 

Output  Proctoring stops 

Scroll to Top   
----------- { 12 }----------   
 2.9 GetReport API 
This is a S
​ erver to Server API​. To fetch proctoring report for a particular candidate by sending a GET request on the following URL:  

Request URL  https://mpaas.mettl.com​/v1/report/ 

Request Method  GET 

Header  Authorization​:- Signature 

Arguments   

Name  Mandatory  Type  Description 

publicKey  Yes  String  Client’s public key 

uniqueId  Yes  String  Candidate’s unique id 

groupName  Yes  String  Name of the assessment/training etc 

parentGroupID  Optional  Int  Parent of Group Name passed 

reportFormat  Mandatory  Int   

0  JSON 

1  HTML 
 

Output  Report gets generated either in JSON format or an HTML page can be generated. 

Error Codes   

Error Code  Message 

E000  No client for public Key 

Scroll to Top   
----------- { 13 }----------   
 E001  Signature mismatch 

E002  request not valid 

E006  Something went wrong 

 

   

Scroll to Top   
----------- { 14 }----------   
  

End of Mettl Proctoring as a Service(MPaaS) API Document 

Please contact us on s​ [email protected]​ for any queries. 

Mettl.com – Online Assessments Made Easy 

Scroll to Top   
----------- { 15 }----------