Adaptive Assessment API

The Adaptive Assessment API lets you create an adaptive assesment engine that can control the order of presented assessment questions to a student as he or she is taking the assessment. The engine uses inputs such as student responses to previous questions to determine which question to give next. The engine can also assign scores for the assessment. You host the adaptive assessment code on your own server, which is external to the BrainHoney server.

To customize individual question rendering within the standard exam player, see Custom Questions.

Configuring Adaptive Assessments

You define an adaptive assessment name using the <adaptiveassements> element in a domain customization. The url attribute of each adaptiveassement element is the entry point into the external website that contains the adaptive assessment engine logic.

To configure a course assessment item to use your adaptive assessment engine, include in the assessment's Item Data an adaptiveassessment element whose value is either a url or a predefined name as described above. The BrainHoney Syllabus editor does not provide a way to create this element, so you must call the PutItems DLAP command yourself to create the element.

Creating an Adaptive Assessment Engine

The adpative assessment engine is a web service that responds to HTTP POST requests from BrainHoney. When BrainHoney encounters an assessment item that is configured with the adaptiveassessment element as described above, it calls the adaptive assessment engine before presenting a question. As the learner answers each question, BrainHoney calls the engine to determine what action to take. Ultimately, BrainHoney is assembling a Submission and Response to submit for the student's assessment. BrainHoney calls the adaptive assessment engine both to display appropriate questions to the student and to assemble the Submission and Response.

Each request's data is a series of name-value pairs in the POST data as defined in Request Parameters. The adaptive assessment engine responds with an answer in the Response Data XML format. BrainHoney processes the response to determine what to do next.

For security, you can have BrainHoney sign each request using the OAuth protocol, which is an industry-standard way of verifying that the request is coming from BrainHoney and has not been tampered with. To sign the requests, you must set up a key-and-secret combination for your adaptive assessment engine hostname as outlined in Launching Links with Basic Learning Tools Interoperability. For example, if the URL to your engine is, you'd configure a key-secret combination for

Receiving BrainHoney Requests

BrainHoney Request Parameters include, among other things, the current submission and response being assembled for the student, state data that your engine controls, and an action parameter describing the action the student is taking. Your engine must respond with a display mode and display-specific data. These are the possible request actions and their typical responses:


Start the assessment. If the assessment supports "save and continue", the request data can also include the pre-existing submission and state for the user. The engine initializes itself and returns a question to display.


Go to the next question. The engine returns either a new question or done if there are no more questions.


Go to the previous question. The engine returns the previous question's submission to display. This action can occur only if the engine has enabled the "previous" button in one of its responses.


Submit the assessment. This action occurs when the user clicks the submit button, or, if the exam is timed, the time has expired and BrainHoney is automatically submitting for the student. In all cases the engine should return done.

Responding to Requests

The engine responds with XML in the Response Data format, which BrainHoney processes to determine how to proceed. The response includes the display mode, optional display data, and a list of buttons to display. The response can optionally include a submission and/or response that then becomes the current submission and response being assembled for the student. These are the possible display mode responses and their associated BrainHoney behaviors:


Display a new question from the Request Parameter's questionlist. The question is identified by the partid attribute in the Response Data. BrainHoney appends the question to the Submission being assembled for the student. It then displays that question to the user. Note that the partid in the questionlist may be different than the partid in the Submission being assembled.


Display a question from the current Submission. The question is identified by the partid attribute in the response.


Displays the HTML returned in the html element. BrainHoney replaces any domain or course variables in the HTML with their appropriate values before displaying the HTML. This HTML is for things like information messages and instructional text.


BrainHoney submits the current Submission and Response to the DLAP server and then displays the assessment review page (or the summary page if review is disabled) to the student.

See Also
<adaptiveassessments> Request Parameters Response Data Sample Scenario Sample Code