Wiki-Quellcode von 07 Schnittstelle ONYX Player

Version 364.1 von Carina Enke am 02.05.2025

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