API to handle committees

This document covers use of APIs to create, update or delete committees in Inspera Assessment. Function to add/remove/move students and graders to/from committees is also covered in this document.

General information

Function of creating committees and assigning graders and students to the committees is Inspera standard function. Users with administrator or chief invigilator privileges can create and handle committees from monitoring or grading tool in Inspera Assessment. For more information of how this function should be used, please take a look at this article on our knowledge base: https://support.inspera.com/hc/en-us/articles/360020165858-Test-settings-Committees

APIs described in this document make it possible to use machine to machine integration to create and handle committees in the same way administrator can do in the system itself.


API endpoints to create / delete committees on a test

New API endpoints

Following API endpoints are created to make it possible to create, update or delete committees in Inspera Assessment:

API endpoint

Descripton

API endpoint

Descripton

/v1/test/{testId}/committees

POST/DELETE

Create, update or delete committee

/v1/test/{testId}/committees/candidates/move

 

POST

Move candidate from one committee to another

/v1/test/{testId}/committees/candidates/remove

POST

Remove candidate from a committee

/v1/test/{testId}/committees/contributors/move

POST

Move contributor/grader between committees

/v1/test/{testId}/committees/contributors/remove

POST

Remove contributor/grader from committee

 

API description with examples

POST

/v1/test/{testId}/committees

/v1/test/{testId}/committees?isExternal=true

*testId=Inspera Assessment internal test ID

*isExternal = true can be used to call the API with test ID in the external system.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Model

1 2 3 4 5 6 7 8 { "committees": [ { "name": "string", "type": "string" } ] }

API is an array of committees, with following information per committee:

name’ : string (50) ; mandatory field

type’ : string (50) ; values: GRADING (default, can be omitted) / REASSESSMENT (appeal, has to be present when committee is appeal committee)

Example:

POST https://iad.inspera.no/api/v1/test/3437420/committees

Create grading committee:

1 2 3 4 5 6 7 8 { "committees": [ { "name": "My test committee", "type": "GRADING" } ] }

Create appeal committee:

1 2 3 4 5 6 7 8 { "committees": [ { "name": "My appeal committee", "type": "REASSESSMENT" } ] }

DELETE

/v1/test/{testId}/committees

/v1/test/{testId}/committees?isExternal=true

*testId=Inspera Assessment internal test ID

*isExternal = true can be used to call the API with test ID in the external system.

Model

1 2 3 4 5 6 7 8 { "committees": [ { "name": "string", "type": "string" } ] }

API is an array of committees, with following information per committee:

name’ : string (50) ; mandatory field

type’ : string (50) ; values: GRADING (default, can be omitted) / REASSESSMENT (appeal, has to be present when committee is appeal committee)

Example

Remove committee from the test

DELETE https://iad.inspera.no/api/v1/test/3437420/committees

1 2 3 4 5 6 7 8 { "committees": [ { "name": "My appeal committee", "type": "REASSESSMENT" } ] }

 

 

How created committees from example above look like in Inspera Assessment:

Committees after appeal committee has been deleted:


Create committees when test is created

It is possible to create committees on a test when the test is created. API endpoint “/v1/test” for creating the tests has been extended with this information:

  • committees array added to create committees (follows same construction as committees API endpoint described earlier in this document)

  • Added field “committeeName” to candidate array to assign candidate to a committee

  • Added array “committeesName” to contributor to assign grader to one or more committees on a test

For information on API datamodel, please see our swagger documentation available here: https://ia.inspera.no/apidoc/#/test/editTest

Code example to create and assign committees through test API

API CALL:

POST https://iad.inspera.no/api/v1/test/

API BODY:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 { "externalTestId": "test committees 2", "title": "TEST COMMITTEE API ", "useShortPassword": true, "startTime": "2021-04-29T13:20:08.472Z", "endTime": "2021-07-31T13:20:08.472Z", "keepCandidates": true, "authenticationSystem":"GENERIC_SAML", "candidates": [ { "candidateId": "DEMO400", "externalId": "DEMO4001", "firstName": "DEMO400", "lastName": "DEMO400", "email": "DEMO40021@test.com" }, { "candidateId": "DEMO401", "externalId": "DEMO4011", "firstName": "DEMO401", "lastName": "DEMO401", "email": "DEMO4011@test.com" "committeeName":"My committee API" }, { "candidateId": "DEMO402", "externalId": "DEMO4021", "firstName": "DEMO402", "lastName": "DEMO402", "email": "DEMO4021@test.com" "committeeName":"My committee API" } ], "contributors": [ { "externalId": "natasa.balic3@inspera.no", "firstName": "Natasa new_1", "lastName": "Balic", "email": "natasa.balic3@inspera.no", "roles": [ "extended","userAdmin","evaluate","plan","templateadmin" ], "committeesName": [ "My committee API" ] } ], "committees": [ { "name": "My committee API" } ] }

Result in Inspera Assessment:

Candides assigned to the committee:

Grader assigned to the committee:

 


Return codes

Code

Code information

Code

Code information

200

Successful operation

400

No input data or invalid data provided

403

Permission denied

404

Could not resolve test from provided data

409

External Id of test data does not match provided data

500

Internal server error, please contact Inspera support