ONYX REST documentation

(2025.06.1 build 202506031026)

Methods:

temporary
run
version
notify
info
registerTest
registerStudent
armSite
initiateSite
disarmSite
getResultValues
getResultVariables
testControl
deregisterTest
remainingTestTime
notificationState
testTime
sysinfo

temporary

Requests the latest temporary saved export file.

Parameter:

Name	Type	Optional?	Description
uniqueId	Long	false	Unique ID for this test run. Must be unique per student and test.
parameters	Map<String,String>	false	Generic parameter map. Keys and values are both strings. This is currently only used to filter the return values. Only the given keys are returned by the method, except some system return values, which are alwys returned.

Returns:

Key	Description
Type:	Map<String,String>
datetimepattern	Pattern to parse datetimes
onyxStartup	Datetime of ONYX system startup
lastAccess	Datetime of last user action
lastSaved	Datetime of latest export
state	Users current state ACTIVE: user did interact in timeout time INACTIVE: user did not interact in timeout time SAVED: temporary results were transmitted
resultsBase64	results.zip, file contents Base64 encoded
error	Only set in case of errors, will deliver detailled error message.

run

Starts a test (simple registration mode, deprecated). Use registerTest/registerStudent instead!

Parameter:

Name	Type	Optional?	Description
uniqueId	String	false	Unique ID for this test run. Must be unique per student and test.
contentPackage	byte[]	false	Contains the content package (test.zip file). The files contents must be transmitted as byte array without any escaping.
language	String	false	Users language for display. One of "de", "en".
templateId	String	false	ONYX template ID. This is lecacy stuff and also contains all display parameters.
serviceName	String	false	Name of the system using ONYX. Must be configured in ONYX to be able to use it.
allowShowSolution	boolean	false	Test flow parameter: May student see the correct solutions after entering the answers?
parameters	Map<String,String>	true	Additional parameters. See registerStudent documentation.

Returns:

Key	Description
Type:	HashMap<String,String>
run	true if successful, false otherwise
blocked	Execution result. Less than 0 in case of error, larger than 0 in case of success.

version

Requests the current version of ONYX REST API.

Parameter:

Name	Type	Optional?	Description
parameters	Map<String,String>	false	Generic parameter map. Keys and values are both strings. This is currently only used to filter the return values. Only the given keys are returned by the method, except some system return values, which are alwys returned.

Returns:

Key	Description
Type:	Map<String,String>
version	ONYX version
build	ONYX build date

notify

Send message to active test users

Parameter:

Name	Type	Optional?	Description
uniqueIds	List	false	List of user IDs
message	String	false	Message to display
parameters	Map<String,String>	false	Additional parameters (currently ignored)

Returns:

Key	Description
Type:	Boolean
success	True if message was displayed.

info

Requests information about the given session.

Parameter:

Name	Type	Optional?	Description
uniqueId	Long	false	Unique ID for this test run. Must be unique per student and test.
parameters	Map<String,String>	false	Generic parameter map. Keys and values are both strings. This is currently only used to filter the return values. Only the given keys are returned by the method, except some system return values, which are alwys returned.

Returns:

Key	Description
Type:	Map<String,String>
lastAccess	Datetime of last user action
datetimepattern	Pattern to parse datetimes
inactivityPeriodMs	Milliseconds to wait until users are marked as inactive
onyxStartup	Datetime of ONYX system startup
error	Only set in case of errors, will deliver detailled error message.

registerTest

Registers a test to be run for multiple students at ONYX test player.

Parameter:

Name	Type	Optional?	Description
testSessionId	Long	false	Unique ID for this test.
providerId	String	false	Name of the system using ONYX. Must be configured in ONYX to be able to use it.
contentPackage	byte[]	false	Contains the content package (test.zip file). The files contents must be transmitted as byte array without any escaping.
parameters	Map<String,String>	false	Additional parameters. showSolution: (true/false) Deprecated. Use more specific parameters for that. Show items correct solution, the correctness of users answer and item score. showFeedback: (true/false) Deprecated. Use more specific parameters for that. Show test and item feedback. testShowFeedback: (true/false) Show test feedback. Also triggers show item feedback. testShowPassed: (true/false) Show test passed information. testShowScore: (true/false) Show total test score. itemShowFeedback: (true/false) Show item feedback itemShowCorrect: (true/false) Show users answer correctness for item itemShowScore: (true/false) Show item score to user itemShowSolution: (true/false) Show correct solution for item isSurvey: (true/false) Is this a survey? suspendAllowed: (true/false) Suspend allowed for this test? dontShowItemTitles: (true/false) True = Do not show item titles. templateid: (String) Template ID (currently not used) ltiUrl: (String) URL to forward the user to after test finished. published: (true/false) Is this a published run from ONYX editor? editorltitest: (true/false) Was this run started using LTI by ONYX editor?

Returns:

Key	Description
Type:	Long
resultCode	Result code. 42 is OK, lower than zero or greater than 42 is error.

registerStudent

Registers a student to run a registered test at ONYX test player.

Parameter:

Name	Type	Optional?	Description
testSessionId	Long	false	Unique ID for the test as registered using registerTest.
studentId	Long	false	Unique identifier of the student in that test session.
payload	byte[]	true	Contains the users former results as file (results.zip file). The files contents must be transmitted as byte array without any escaping.
parameters	Map<String,String>	false	Additional parameters. language: Users language for display status: One of the test states: WAITING WORKING FINISHED RESUME_ALLOWED NOT_ENTERED CANCELED RESUME_REQUESTED RESUMED DISCONNECTED SUSPENDED RESUME_SUSPENDED Others: Override the ones given by registerTest: showSolution: (true/false) Deprecated. Use more specific parameters for that. Show items correct solution, the correctness of users answer and item score. showFeedback: (true/false) Deprecated. Use more specific parameters for that. Show test and item feedback. testShowFeedback: (true/false) Show test feedback. Also triggers show item feedback. testShowPassed: (true/false) Show test passed information. testShowScore: (true/false) Show total test score. itemShowFeedback: (true/false) Show item feedback itemShowCorrect: (true/false) Show users answer correctness for item itemShowScore: (true/false) Show item score to user itemShowSolution: (true/false) Show correct solution for item isSurvey: (true/false) Is this a survey? suspendAllowed: (true/false) Suspend allowed for this test? dontShowItemTitles: (true/false) True = Do not show item titles. templateid: (String) Template ID (currently not used) ltiUrl: (String) URL to forward the user to after test finished. published: (true/false) Is this a published run from ONYX editor? editorltitest: (true/false) Was this run started using LTI by ONYX editor?

Returns:

Key	Description
Type:	Long
resultCode	Result code. 42 is OK, lower than zero or greater than 42 is error.

armSite

Requests communication information (such as tokens) for ONYX reporter communication.

Parameter:

Name	Type	Optional?	Description
version	Integer	false	API version (currently 3)
userId	String	false	Users ID
optionalRole	Integer	true	Users role (assessor, tutor, student)
secretToShare	String	false	Shared secret as agreed before.
optionalUserLastName	String	true	Users first name for display
optionalUserFirstName	String	true	Users last name for display
additionalParams	HashMap<String,String>	false	Additional parameters providerID: provider ID as configured in ONYX to be able to send the new results back to LMS assessmentID: in case of manual assessment of single student results, to be able to send the new results back to LMS

Returns:

Key	Description
Type:	String
reporterSessionId	Reporter session ID, LMS can use this to render IFrame URL

initiateSite

Initiates ONYX reporter communication.

Parameter:

Name	Type	Optional?	Description
version	Integer	false	API version (currently 3)
sessionId	String	false	Reporter session ID
secretToShare	String	false	Shared secret as agreed before.
students	List	false
optionalContentPackage	byte[]	true	Contains the content package (test.zip file). The files contents must be transmitted as byte array without any escaping.
additionalParams	HashMap<String,String>	false	Additional parameters. csv: Do not prepare a view, return CSV export of delivered results instead. All other parameters are ignored. In that case also the follwinig parameters should be given: lang:users locale anonymize:true/false - do not print out any sensible data maxAttempts: Maximum attempts value as configured outside the ONYX system, e.g. by the LMS showSolution: (true/false) Deprecated. Use more specific parameters for that. Show items correct solution, the correctness of users answer and item score. showFeedback: (true/false) Deprecated. Use more specific parameters for that. Show test and item feedback. testShowFeedback: (true/false) Show test feedback. Also triggers show item feedback. testShowPassed: (true/false) Show test passed information. testShowScore: (true/false) Show total test score. itemShowFeedback: (true/false) Show item feedback itemShowCorrect: (true/false) Show users answer correctness for item itemShowScore: (true/false) Show item score to user itemShowSolution: (true/false) Show correct solution for item isSurvey: (true/false) Is this a survey? suspendAllowed: (true/false) Suspend allowed for this test? dontShowItemTitles: (true/false) True = Do not show item titles. templateid: (String) Template ID (currently not used) ltiUrl: (String) URL to forward the user to after test finished. published: (true/false) Is this a published run from ONYX editor? editorltitest: (true/false) Was this run started using LTI by ONYX editor?

Returns:

Key	Description
Type:	String
result	Normal mode: URL to reporter GUI to show the requested view (may be an error page). CSV mode: Base64 encoded CSV file content.

disarmSite

Ends ONYX reporter communication.

Parameter:

Name	Type	Optional?	Description
version	Integer	false	API version (currently 3)
sessionId	String	false	Reporter session ID
secretToShare	String	false	Shared secret as agreed before.
additionalParams	HashMap<String,String>	false	Additional parameters. Currently ignored.

Returns:

Key	Description
Type:	Boolean
success	Resulting state

getResultValues

Requests results values (SCORE = 2, ...) from ONYX reporter. Requires student results.

Parameter:

Name	Type	Optional?	Description
version	Integer	false	API version (currently 3)
sessionId	String	false	Reporter session ID
secretToShare	String	false	Shared secret as agreed before.
requestedValues	HashMap<String,String>	false	Filter map. Only variables with names matching keys in that map will be returned. The values (if not null) are handled as default values. If a requested parameter is not found, it is returned nontheless, with the default value as value.
additionalParams	HashMap<String,String>	false	Additional parameters. all: Requests result variables for all students which were given in initiateSite request. Key is in format studentId<space>variableName then. If not given only the last students result variables are returned.

Returns:

Key	Description
Type:	Map<String,String>
variable	Test variables, key is the variable name, value their value.

getResultVariables

Requests test variables (SCORE, ...) from ONYX reporter (not their values!). Only requires a test.

Parameter:

Name	Type	Optional?	Description
version	Integer	false	API version (currently 3)
contentPackage	byte[]	false	Contains the content package (test.zip file). The files contents must be transmitted as byte array without any escaping.
additionalParams	HashMap<String,String>	false	Additional parameters. Currently ignored.

Returns:

Key	Description
Type:	Map<String,String>
variable	Map of result vars and their type

testControl

Allows to control the test flow for students which are currently executing their tests at ONYX test player.

Parameter:

Name	Type	Optional?	Description
testSessionId	Long	false	Unique ID for the test as registered using registerTest.
studentIds	StudentIdsWrapper	false	Unique identifiers of the students to handle. All must have been registered using registerStudent.
status	Integer	false	New test state to set. One of: WAITING WORKING FINISHED RESUME_ALLOWED NOT_ENTERED CANCELED RESUME_REQUESTED RESUMED DISCONNECTED SUSPENDED RESUME_SUSPENDED
parameters	Map<String,String>	false	Additional parameters. addTime: Time to add to users test time limit in minutes. showSolution: (true/false) Deprecated. Use more specific parameters for that. Show items correct solution, the correctness of users answer and item score. showFeedback: (true/false) Deprecated. Use more specific parameters for that. Show test and item feedback. testShowFeedback: (true/false) Show test feedback. Also triggers show item feedback. testShowPassed: (true/false) Show test passed information. testShowScore: (true/false) Show total test score. itemShowFeedback: (true/false) Show item feedback itemShowCorrect: (true/false) Show users answer correctness for item itemShowScore: (true/false) Show item score to user itemShowSolution: (true/false) Show correct solution for item isSurvey: (true/false) Is this a survey? suspendAllowed: (true/false) Suspend allowed for this test? dontShowItemTitles: (true/false) True = Do not show item titles. templateid: (String) Template ID (currently not used) ltiUrl: (String) URL to forward the user to after test finished. published: (true/false) Is this a published run from ONYX editor? editorltitest: (true/false) Was this run started using LTI by ONYX editor?

Returns:

Key	Description
Type:	Long
resultCode	Result code. 42 is OK, lower than zero or greater than 42 is error.

deregisterTest

Cleans up a test session.

Parameter:

Name	Type	Optional?	Description
testSessionId	Long	false	Unique ID for this test run. Must be unique per student and test.
providerId	String	false	Name of the system using ONYX. Must be configured in ONYX to be able to use it.
parameters	Map<String,String>	false	Additional parameters. Currently ignored.

Returns:

Key	Description
Type:	Long
resultCode	Execution result. Less than 0 in case of error, greater than 0 in case of success.

remainingTestTime

Requests the remaining test time for a given test session.

Parameter:

Name	Type	Optional?	Description
uniqueIds	List	false	List of user IDs
parameters	Map<String,String>	false	Additional parameters (currently ignored)

Returns:

Key	Description
Type:	Map<String,String>
assessmentId	Map of student ID and remaining time in seconds

notificationState

State of the notification system

Parameter:

Name	Type	Optional?	Description
uniqueIds	List	false	List of user IDs
parameters	Map<String,String>	false	Additional parameters (currently ignored)

Returns:

Key	Description
Type:	Map<String,String>
assessmentId	Map of student ID and state

testTime

Requests the currently used time for a given test session.

Parameter:

Name	Type	Optional?	Description
uniqueIds	List	false	List of user IDs
parameters	Map<String,String>	false	Additional parameters (currently ignored)

Returns:

Key	Description
Type:	Map<String,String>
assessmentId	Map of student ID and remaining time in seconds

sysinfo

Requests system information.

Parameter:

Name	Type	Optional?	Description
parameters	Map<String,String>	true	Optional. If given, only the given parameters will be returned.

Returns:

Key	Description
Type:	Map<String,String>
name	Instance name
version	ONYX version
build	ONYX build info