Zum Inhalt springen

Wiki-Quellcode von 07 Schnittstelle ONYX Player

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