Zum Inhalt springen

Wiki-Quellcode von 07 Schnittstelle ONYX Player

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