Zum Inhalt springen

Wiki-Quellcode von 07 Schnittstelle ONYX Player

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