The purpose of this document is to provide the necessary information to an assessment vendor who will perform external testing against the Infinite Campus implementation of One Roster Assessment API. In order to support testing efforts this document also includes domain specific functionality, error codes, and unsupported fields.
IMS security framework: https://www.imsglobal.org/spec/security/v1p0/
Authorization - Client Credentials
Client ID:
Client Secret:
Oauth2 Endpoint: https://.infinitecampus.com/campus/oauth2/token
RESTful Endpoint Paths
Aside from roster data, there are two endpoints used to sync assessment data: LineItems (assessments) and Results (scores).
LineItems
GET all | https:// |
GET one | https:// |
PUT | https:// |
DELETE | https:// |
Results
GET all | https:// |
GET one | https:// |
PUT | https:// |
DELETE | https:// |
The following rostering endpoints can be used to look up students in the Campus system:
GET all students | https:// |
GET one student | https:// |
Interactive API Documentation
Infinite Campus uses Swagger to provide interactive documentation for the API.
Link to OneRoster Assessment API docs: |
https:// |
Link to OneRoster Rostering API docs (look under "Students Management"): |
https:// |
This API documentation aims to provide:
- Organized, high level look at all the endpoint methods.
- Info about data structures (including descriptions of supported data fields and types) through their "Schemas" Request parameter descriptions and example values.
- Example request payloads in JSON.
- Noteworthy Responses, including exception errors with what they mean, and how to resolve them Ability to "try out" the endpoints, sending requests directly within Swagger.
To use the interactive features:
- Click green "Authorize" button on the top right
- Put in the client credentials
- Check the scopes
- Click "Authorize"
- Click "Try Out" on any endpoint.
- Click "Execute" to send request, see equivalent CURL command, and the response.
Required Fields
There are a few required fields that every PUT payload is required to have.
Assessment Line Items: sourcedId, title
Assessment Results: sourcedId, lineItem.sourcedId, student.sourcedId
Campus Line Item and Result Tree Structure
Integrating assessments from OneRoster into Campus requires consideration of the existing tree structure used to store assessments and scores in Campus. Currently Campus persists and displays data to users in a tree structure, meaning there are certain rules and restrictions vendors must follow when performing CRUD operations on entries. In an effort to be as transparent as possible to prevent confusion, the following explains how these rules might affect an API user.
The tree structure of assessments in Campus.
The tree structure of assessment scores in Campus.
Creation
Assessment line items refer to one another through the parentAssessmentLineItem.sourcedId field, meaning a line item can have a parent, and that parent can itself have a parent (figure 1). Because of these linked dependencies, users are required to create line items from the root test down.
Figure 1 above is only achievable by creating the grandparent line item first, then the parent line item, then the child line item.
Assessment results follow a similar structure. Figure 2 shows 3 results for the previously created line items. As is the same with line items, a child assessment result cannot be created without first creating a score for its parent assessment line item, so they display properly in Campus. Campus allows API consumers to score a child test without scoring its parent and keep the tree structure intact; when scoring a child test that does not have its parent scored for that same student at that same time, Campus auto-creates assessment results for that line items ancestors with blank score fields so that the score may be properly displayed in Campus. Figure 2 is achievable through 2 methods:
- Method 1: Creating a result for the grandparent line item, then creating a result for the parent line item (for the same student at the same time rounded to the minute), then creating a result for the child line item (for the same student at the same time rounded to the minute).
- Method 2: Create a result for only the child line item, with results for the parent and grandparent line items auto-created by Campus.
Deletion
Assessment line items cannot be deleted if a separate entity has a reference to it. Line items can be referenced in two ways, either as a parent of another line item or as a line item of an assessment result. Before you can successfully delete a line item, all of its children line items must be deleted first, and all results of that line item must be deleted as well. NOTE: As mentioned in the creation section above, some results may be auto-created for a line item if a child line item is scored before its parent. Be aware that these auto generated results must be deleted as well. API users may want to utilize the filtering of the GetAll endpoints to find the linked records such as "where parentAssessmentLineItem.sourcedId = 'example' " for other line items or "where lineItem.sourcedId= 'example' " for results.
Campus Errors
Campus has implemented custom exception handling for the One Roster Assessment API. In addition to common errors found in an API, the errors listed below were created based on functionality of assessment line items and assessment results in the Campus product that may have not been specifically defined in the specification or IMS global documentation. These errors are here to ensure data coming in fit correctly in Campus's domain as well as provide an appropriate error message to the API consumer.
Note: Campus Errors can also be found in the Swagger documentation by their exact HTTP status code and json response body encountered.
Assessment Line Items
Error Code | Error Message | Error scenario |
422 | "Assessment Line Item's sourcedId must be in valid UUID format. "
+ sourcedId + " is not." | The user makes a PUT request to the assessment line items endpoint with the 'sourcedId' field populated with a value that is not in the correct version 4 UUID format |
422 | sourcedId + " Assessment Line Item's referenced Parent Line Item sourcedId must be in valid UUID format. " + parentAssessmentLineItem. sourcedId + " is not." | The user makes a PUT request to the assessment line items endpoint with the 'parentAssessmentLineItem.sourcedId' field populated with a value that is not in the correct version 4 UUID format |
422 | "The Assessment Line Item record you tried to delete is linked to another Assessment Line Item record, " + "and the system will not allow you to delete it until you delete the records that are linked. " + "The child records can be found by getting all Assessment Line Item records with filter " + "parentAssessmentLineItem. sourcedId='" + sourcedId | The user makes a DELETE request to the assessment line items endpoint with a sourcedId of a line item that is referenced as a parentAssessmentLineItem in another line item record in the database. The user must delete these dependencies before continuing. |
422 | "The Assessment Line Item record you tried to delete is linked to an Assessment Result (score) record, " + "and the system will not allow you to delete it until you delete the record linked to it. " + "The child records can be found by getting all Assessment Line Item records with filter " + "lineItem.sourcedId='" + sourcedId | The user makes a DELETE request to the assessment line items endpoint with a sourcedId of a line item that is referenced as a lineItem in an existing assessment result record in the database. The user must delete these dependencies before continuing. |
Assessment Results
Error Code | Error Message | Error scenario |
422 | "Assessment Result's sourcedId must be in valid UUID format. " + sourcedId + " is not." | The user makes a PUT request to the assessment results endpoint with the 'sourcedId' field populated with a value that is not in the correct version 4 UUID format |
422 | sourcedId + " Assessment Result's referenced Line Item sourcedId must be in valid UUID format. " + assessmentLineItem.sourcedId + " is not." | The user makes a PUT request to the assessment results endpoint with the 'assessmentLineItem. sourcedId' field populated with a value that is not in the correct version 4 UUID format |
422 | "Cannot put record. Attempted to modify an existing record with wrong student alignment" | The user makes a PUT request to update a previous assessment result record where the updated payload field for 'student.sourcedId' does not match that same field in the database |
422 | "Cannot put record. Attempted to modify an existing record with wrong assessmentLineItem alignment" | The user makes a PUT request to update a previous assessment result record where the updated payload field for ' assessmentLineItem.sourcedId' does not match that same field in the database |
422 | "A duplicate assessment result record exists for this line item, person and date with the UUID " + sourcedId + ". Please use this UUID to update or delete the previous record, or create a new record by updating one of these three fields." | The user makes a PUT request to create a new assessment result while an entry exist in the database for an assessment result with the same ‘student.sourcedId’, ‘assessmentLineItem.sourcedId’, and ‘scoreDate’ |
404 | "No student record exists with the GUID " + sourcedId | The user makes a PUT request to the assessment results endpoint with the 'student. sourcedId' field populated with a value that does not match any student currently in the database |
404 | "No assessment line item record exists with the GUID " + sourcedId | The user makes a PUT request to the assessment results endpoint with the 'assessmentLineItem.sourcedId' field populated with a value that does not match any line items currently in the database |
Unsupported Fields
Campus has implemented what we have determined as 'core' fields in the first iteration of our development of OneRoster Assessments. Some fields listed in the specification are not fully supported by Campus. These fields do not impact the core functionality of creating, reading, updating, and deleting assessment results and line items, but should be noted in testing and troubleshooting.
Assessment Line Items
| Assessment Results
|
