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.

1 General information
2 API endpoints to create / delete committees on a test
3 Return codes

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

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

{
  "committees": [
    {
      "name": "My test committee",
      "type": "GRADING"
    }
  ]
}

Create appeal committee:

{
  "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

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

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: Inspera Open API Documentation

Code example to create and assign committees through test API

API CALL:

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

API BODY:

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