Wiki-Quellcode von 07 Schnittstelle ONYX Player

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