Skip to Content

Wiki source code of 07 Schnittstelle ONYX Player

Last modified by Carina Enke on 12.12.2025
Show last authors
1 {{section}}
2 {{column width="60%"}}
3 The API between the ONYX Player and the LMS consists of the following components:
4
5 * Registration of a test with the ONYX Player through the LMS
6 * Registration of a participant with the ONYX Player through the LMS
7 * Test control
8 * Return of test results to the LMS through the ONYX Player
9 * Deregistration of the test
10 {{/column}}
11
12 {{column width="30%"}}
13 {{panel title="Content"}}
14 {{toc start="2"/}}
15 {{/panel}}
16 {{/column}}
17 {{/section}}
18
19 == General information ==
20
21 The ONYX Player defines a web service, which is accessible via the URL **<ONYXPlayer-URL>/onyx/onyxexamservices**.
22
23 Link to the WSDL of the public demo runtime: [[http:~~/~~/demo.bps-system.de/onyx/onyxexamservices?wsdl>>url:http://demo.bps-system.de/onyx/||shape="rect"]]
24
25 == Registration of a test ==
26
27 Before participants can take tests, the tests need to be registered with ONYX.
28
29 {{code language="xml" title="Registration"}}
30 @WebMethod(operationName = „registerTest")
31 public Long registerTest(
32 @WebParam(name = „testSessionId") final Long testSessionId,
33 @WebParam(name = „providerId") final String providerId,
34 @WebParam(name = „contentPackage") final byte[] contentPackage,
35 @WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
36 }
37 {{/code}}
38
39 === Parameters registerTest ===
40
41 (% class="wrapped" %)
42 |(((
43 testSessionId
44 )))|(((
45 Unique ID assigned by the LMS, which serves as an identifier for this test.
46 )))
47 |(((
48 providerId
49 )))|(((
50 Identification under which the requesting LMS is registrated with ONYX.
51 )))
52 |(((
53 contentPackage
54 )))|(((
55 The IMS QTI v2.1 CP (zip file as byte array).
56 )))
57 |(((
58 parameters
59 )))|(((
60 (% class="content-wrapper" %)
61 (((
62 (% class="TableParagraph" %)
63 List of parameters to control the test. It is also possible to set additional parameters for the individual participant (registerStudent). 
64
65 (% class="TableParagraph" %)
66 All parameters are optional. The default setting is shown in bold. 
67
68 (% class="wrapped" %)
69 |=(((
70 Paramter
71 )))|=(((
72 Description
73 )))
74 |(((
75 showSolution [true|**false**]
76 )))|(((
77 Should the correct answer be displayed to the user?
78 )))
79 |(((
80 isSynchronized [true|**false**]
81 )))|(((
82 Is the test for which the test start is synchronised across all users in the exam mode?
83 )))
84 |(((
85 continuationAllowed [true|**false**]
86 )))|(((
87 Is it allowed to continue the test session at any time? If not, each test start must be performed via the LMS.
88 )))
89 |(% colspan="1" %)(% colspan="1" %)
90 (((
91 suspendAllowed [true|**false**]
92 )))|(% colspan="1" %)(% colspan="1" %)
93 (((
94 Is it is allowed to interrupt the test? If this is the case, the button "Suspend" will additionally be displayed.
95 )))
96 |(% colspan="1" %)(% colspan="1" %)
97 (((
98 Templateid:
99 )))|(% colspan="1" %)(% colspan="1" %)
100 (((
101 Currently only supported: onyxwithoutnav - hides the navigation tree.
102 )))
103 |(% colspan="1" %)(% colspan="1" %)
104 (((
105 dontShowItemTitles [true|**false**]
106 )))|(% colspan="1" %)(% colspan="1" %)
107 (((
108 Should the titles of the questions not be displayed?
109 )))
110
111 {{note}}
112 Since ONYX version 5.15, the following parameters can be used to control the feedback and evaluation display for the participant while taking the test. A detailed description of the functionality from the user's perspective is provided in the section "Test procedure configuration".
113 {{/note}}
114
115 Questions evaluation:
116
117 (% class="wrapped" %)
118 |=(((
119 Parameter
120 )))|=(((
121 Description
122 )))
123 |(((
124 itemShowFeedback [**true**|false]
125 )))|(((
126 The question feedback defined by the author is displayed to the participant after submitting an answer to the question.
127 )))
128 |(((
129 itemShowMaxScore [**true**|false]
130 )))|(((
131 The participant is shown the maximum possible score for each question.
132 )))
133 |(% colspan="1" %)(% colspan="1" %)
134 (((
135 itemShowScore [**true**|false]
136 )))|(% colspan="1" %)(% colspan="1" %)
137 (((
138 The participant is shown the number of points achieved for the question after submitting their answer.
139 )))
140 |(% colspan="1" %)(% colspan="1" %)
141 (((
142 itemShowCorrect [**true**|false]
143 )))|(% colspan="1" %)(% colspan="1" %)
144 (((
145 The participant is shown whether their answer was correct or incorrect after submitting their answer. Implies itemShowScore=true.
146 )))
147 |(% colspan="1" %)(% colspan="1" %)
148 (((
149 itemShowSolution [**true**|false]
150 )))|(% colspan="1" %)(% colspan="1" %)
151 (((
152 The participant is shown the correct solution after submitting their answer. Implies itemShowCorrect=true and itemShowScore=true.
153 )))
154
155 Test evaluation:
156
157 (% class="wrapped" %)
158 |=(((
159 Parameter
160 )))|=(((
161 Description
162 )))
163 |(((
164 testShowFeedback [**true**|false]
165 )))|(((
166 After submitting the test, the participant is shown a test completion page, which does (not) contain the test feedback defined by the author.
167 )))
168 |(((
169 testShowScore [**true**|false]
170 )))|(((
171 After submitting the test, the participant is shown a test completion page, which does (not) contain all determined point values, such as the total test score and the points per test section, if applicable.
172 )))
173 |(((
174 testShowPassed [**true**|false]
175 )))|(((
176 After submitting the test, the participant is shown a test completion page, which does (not) contain information about whether or not the test was passed. The default is the value given in testShowScore or its default.
177 )))
178
179 {{info title="Note"}}
180 If no evaluation information is displayed on question level (itemShowFeedback = false, itemShowScore = false, itemShowCorrect = false, itemShowSolution = false), then the participant will not be shown the button to submit questions while taking the test. Instead, the answers are saved at any time and assessed after test submission.
181 {{/info}}
182
183 {{error}}
184 The following parameters are (% style="color: rgb(255,0,0);" %)__no longer__ (%%)available since **ONYX** **version 5.15**:
185 {{/error}}
186
187 * showSolution [**true **|false] - Replaced by testShowScore, testShowPassed, itemShowSolution (including implications)
188 * showFeedback [**true **|false] - Replaced by testShowFeedback and itemShowFeedback
189 )))
190 )))
191
192 === ReturnValue registerTest ===
193
194 (% class="wrapped" %)
195 |(((
196 Long
197 )))|(((
198 **One of the following values:**
199
200 * WAITING(0) – waiting for test start
201 * WORKING(1) – is processing the test
202 * FINISHED(2) – submitted the test
203 * RESUME_ALLOWED(3) – resuming allowed
204 * NOT_ENTERED(4) – has not yet entered the test
205 * CANCELED(5) – has cancelled the testing process
206 * RESUME_REQUESTED(6) – wishes to continue
207 * RESUMED(7) – has continued
208 * DISCONNECTED(8) – client is not / no longer reachable
209 * SUSPENDED(9) – testing process has been interrupted
210 * RESUME_SUSPENDED(10) – interrupted testing process is continued
211 * OK(42) – OK
212 )))
213 |(((
214
215 )))|(((
216 **Error codes:**
217
218 * ERROR_RETURN_RESULTS(0xFF01)
219 * ERROR_MULTIPLE_REGISTER_STUDENT_WITH_SAME_ID_CALLS(0xFF02)
220 * ERROR_REGISTER_STUDENT_WITH_UNKNOWN_TEST_ID(0xFF03)
221 * ERROR_REGISTER_STUDENT_WITH_EMPTY_TEST_ID(0xFF04)
222 * ERROR_REGISTER_STUDENT_WITH_EMPTY_STUDENT_ID(0xFF05)
223 * ERROR_REGISTER_STUDENT_TO_RESUME_WITHOUT_PAYLOAD(0xFF06)
224 * ERROR_REGISTER_STUDENT_FOR_UNKNOWN_PROVIDER(0xFF07)
225 * UNKNOWN(-1)
226 )))
227
228 == Registration of a student ==
229
230 Students can use a test after it has been registered, provided that they have been registered as well.
231
232 {{code title="Registration"}}
233 @WebMethod(operationName = „registerStudent")
234 public Long registerStudent(
235 @WebParam(name = „testSessionId", partName = „testSessionId") final Long test
236 SessionId,
237 @WebParam(name = „studentId", partName = „studentId") final Long studentId,
238 @WebParam(name = „payload", partName = „payload") final byte[] payload,
239 @WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
240 }
241 {{/code}}
242
243 === Parameters registerStudent ===
244
245 (% class="wrapped" %)
246 |(((
247 testSessionId
248 )))|(((
249 (% class="TableParagraph" %)
250 Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).
251 )))
252 |(((
253 studentId
254 )))|(((
255 (% class="TableParagraph" %)
256 Unique identification for test participants. ID will be returned by ONYX when status changes or results are transmitted.
257 )))
258 |(% colspan="1" %)(% colspan="1" %)
259 (((
260 payload
261 )))|(% colspan="1" %)(% colspan="1" %)
262 (((
263 (% class="TableParagraph" %)
264 Optional. Results for the participant (e. g. if interrupted tests are continued).
265 )))
266 |(% colspan="1" %)(% colspan="1" %)
267 (((
268 parameters
269 )))|(% colspan="1" %)(% colspan="1" %)
270 (((
271 (% class="TableParagraph" %)
272 List of test control parameters (all optional, bold = default):
273
274 * Language [**de**|en|fr|es]: Language of the ONYX user interface.
275 * Status: Initial status of the participant (currently only RESUME_SUSPENDED(10) is supported).
276 )))
277
278 === ReturnValue registerStudent ===
279
280 (% class="wrapped" %)
281 |(((
282 Long
283 )))|(((
284 One of the values as described under "Registration of a test".
285 )))
286
287 == Test control ==
288
289 The status of registered test participants can be controlled by the LMS, e. g. to start, finish, or continue the test for everyone after the tutor has approved of it.
290
291 {{code title="Test control"}}
292 @WebMethod(operationName = „testControl")
293 public Long testControl(
294 @WebParam(name = „testSessionId") final Long testSessionId,
295 @WebParam(name = „studentIds") final StudentIdsWrapper students,
296 @WebParam(name = „status") final Integer status,
297 @WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
298 }
299 {{/code}}
300
301 === Parameters testControl ===
302
303 (% class="wrapped" %)
304 |(((
305 testSessionId
306 )))|(((
307 Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).
308 )))
309 |(((
310 studentIds
311 )))|(((
312 List of unique IDs for test participants.
313 )))
314 |(((
315 status
316 )))|(((
317 New status to be set for the given test participants.
318 )))
319 |(((
320 parameters
321 )))|(((
322 List of test control parameters (all optional):
323
324 * addTime: Time in minutes to add to the test session.
325 )))
326
327 === ReturnValue testControl ===
328
329 (% class="wrapped" %)
330 |(((
331 Long
332 )))|(((
333 One of the values as described under "Registration of a test".
334 )))
335
336 == Clear storage ==
337
338 When all participants have finished the test, the LMS can inform ONYX to deregister the test and to clear the storage.
339
340 {{code title="Test control"}}
341 @WebMethod(operationName = „deregisterTest")
342 public Long deregisterTest(
343 @WebParam(name = „testSessionId") final Long testSessionId,
344 @WebParam(name = „providerId") final String providerId,
345 @WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
346 }
347 {{/code}}
348
349 === Parameters deregisterTest ===
350
351 (% class="wrapped" %)
352 |(((
353 testSessionId
354 )))|(((
355 Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).
356 )))
357 |(((
358 providerId
359 )))|(((
360 Identification under which the requesting LMS is registered with ONYX.
361 )))
362 |(((
363 parameters
364 )))|(((
365 Currently not used.
366 )))
367
368 === ReturnValue deregisterTest ===
369
370 (% class="wrapped" %)
371 |(((
372 Long
373 )))|(((
374 One of the values as described under "Registration of a test".
375 )))
376
377 == Test display ==
378
379 After a test has been registered with the Player, the user can display it **exactly once**. For this reason, the LMS will show an IFrame with the target URL <ONYXWebPlayer-URL>/onyx/onyxrun?id=<UID> in the browser window. The <UID> must be the unique studentId used in the test registration. The test will then be started. If the user finishes the test, the results will be returned to the LMS. The LMS then needs to define a web service API that exactly matches the WSDL available under the following URL:
380
381 {{note title="URL"}}
382 [[http:~~/~~/demo.bps-system.de/olatce/services/ReturnWSService?wsdl>>url:http://demo.bps-system.de/olatce/services/ReturnWSService?wsdl||shape="rect"]]
383 Only the URL in the lower part of the WSDL has to be adapted to the LMS.
384 {{/note}}
385
386 == Configuration of the ONYX Player ==
387
388 The ONYX Player uses a configuration file named onyxplugin.config.xml, which must be stored in the Java Classpath.
389
390 {{error title="Security"}}Both the WSDL of the ONYX Player and the LMS should not be accessible/visible "from the outside". This also applies to the respective web services. The web GUI of the LMS and the ONYX Player, in contrast, must be visible to and accessible by all users. If HTTPS is used during the test process (which is strongly recommended), then the appropriate certificate must be known to the corresponding JVM of the LMS and the ONYX Player. Otherwise web service communication will not be possible.{{/error}}
391 ~{~{/layout-cell}}
392 ~{~{/layout-section}}
393
394 {{layout-section ac:type="single"}}
395 {{layout-cell}}
396 ----
397 {{/layout-cell}}
398 {{/layout-section}}
399
400 {{layout-section ac:type="single"}}{{layout-cell}}
401 {{column}}
402 (% class="auto-cursor-target" %)
403 If you have any questions about the configuration or the use of the ONYX Testsuite in other platforms, we will be happy to help you.
404
405 {{panel title="BPS Bildungsportal Sachsen GmbH"}}
406 **[[image:attach:BPS-Logo-web.png]]**
407
408 **Phone: **+49 (0) 371 666 2739 0
409 (% style="color:#595959" %)**Email: **(%%)[[support@bps-system.de>>mailto:support@bps-system.de||shape="rect"]]
410
411 You are also welcome to use our (% style="text-align:left" %)**[[Contact form>>url:https://www.bps-system.de/cms/kontakt/||shape="rect"]]**(%%).
412 {{/panel}}
413 {{/column}}
414 {{/layout-cell}}{{/layout-section}}
415 ~{~{/layout}}