Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

Version 395.1 von Carina Enke am 19.12.2023
Zeige letzte Bearbeiter
1
2 {{layout}}
3 {{layout-section ac:type="single"}}
4 {{layout-cell}}{{/layout-cell}}
5 {{/layout-section}}
6
7 {{layout-section ac:type="two_right_sidebar"}}
8 {{layout-cell}}
9 \\
10 {{/layout-cell}}
11
12 {{layout-cell}}
13
14 {{panel borderColor="#ddd" bgColor="#f0f0f0" borderStyle="solid" title="Inhalt"}}
15
16
17 {{toc/}}
18 {{/panel}}
19
20 {{/layout-cell}}
21 {{/layout-section}}
22
23 {{layout-section ac:type="single"}}
24 {{layout-cell}}
25 == Allgemeines ==
26
27 Über die Schnittstelle zum ONYX WebReporter erfolgt jede Kommunikation zwischen dem LMS und dem Reporter. Dazu erfolgt eine Reihe von Aufrufen:
28
29 (% class="wrapped" %)
30 |(((
31 armSite
32 )))|(((
33 Anmeldung von Folgerequests beim ONYX Reporter.
34 )))
35 |(((
36 initiateSite
37 )))|(((
38 Initiiert die Reporter-Session (Übertragung des CPs).
39 )))
40 |(((
41 disarmSite
42 )))|(((
43 Freigabe von allen Reporter-Ressourcen für diese Session.
44 )))
45 |(((
46 getResultValues
47 )))|(((
48 Gibt alle bzw. die angeforderten Resultate für den Test zurück. Voraussetzung: Es ist nur exakt ein Student in der bei initiateSite übertragenen Liste.
49 )))
50 |(% colspan="1" %)(% colspan="1" %)
51 (((
52 getResultVariables
53 )))|(% colspan="1" %)(% colspan="1" %)
54 (((
55 Gibt alle bzw. die angeforderten Outcome-Variablen für den Test zurück. Hierfür sind kein armSite, initiateSite oder disarmSite erforderlich.
56 )))
57
58 == Anmeldung des LMS ==
59
60 {{code language="xml" title="Anmeldung des LMS"}}
61 @WebMethod(operationName = „armSite")
62 public String armSite(
63 @WebParam(name = „version") final Integer version,
64 @WebParam(name = „userId") final String userId,
65 @WebParam(name = „optionalRole") final Integer role,
66 @WebParam(name = „secretToShare") final String secretToShare,
67 @WebParam(name = „optionalUserLastName") final String userLastName,
68 @WebParam(name = „optionalUserFirstName") final String userFirstName,
69 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
70 }
71 {{/code}}
72
73 === Parameter armSite ===
74
75 (% class="wrapped" %)
76 |(((
77 version
78 )))|(((
79 Angefragte Version: 1
80 )))
81 |(((
82 userId
83 )))|(((
84 UserId des anfragenden Reporter-Benutzers
85 )))
86 |(((
87 optionalRole
88 )))|(((
89 Optional. Rolle des Benutzers. 0 = Student, 1= Tutor
90 )))
91 |(((
92 secretToShare
93 )))|(((
94 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
95 )))
96 |(((
97 optionalUserLastName
98 )))|(((
99 Optional. Nachname des Benutzers.
100 )))
101 |(% colspan="1" %)(% colspan="1" %)
102 (((
103 optionalUserFirstName
104 )))|(% colspan="1" %)(% colspan="1" %)
105 (((
106 Optional. Vorname des Benutzers.
107 )))
108 |(% colspan="1" %)(% colspan="1" %)
109 (((
110 additionalParams
111 )))|(% colspan="1" %)(% colspan="1" %)
112 (((
113 Reserved for future use.
114 )))
115
116 === ReturnValue armSite ===
117
118 (% class="wrapped" %)
119 |(((
120 String
121 )))|(((
122 Session ID, mit der alle weiteren Reporter-Aufrufe gekennzeichnet werden müssen.
123 )))
124
125 == Initialisierung durch LMS ==
126
127 {{code language="xml" title="Initialisierung durch LMS"}}
128 @WebMethod(operationName = „initiateSite")
129 public String initiateSite(
130 @WebParam(name = „version") final Integer version,
131 @WebParam(name = „sessionId") final String sessionId,
132 @WebParam(name = „secretToShare") final String secretToShare,
133 @WebParam(name = „students") final ArrayList<ResultsForStudent> students,
134 @WebParam(name = „optionalContentPackage") final byte[] contentPackage,
135 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
136 }
137 {{/code}}
138
139 === Parameter initiateSite ===
140
141 (% class="wrapped" %)
142 |(((
143 version
144 )))|(((
145 Angefragte Version: 1
146 )))
147 |(% colspan="1" %)(% colspan="1" %)
148 (((
149 sessionId
150 )))|(% colspan="1" %)(% colspan="1" %)
151 (((
152 SessionId, wie von armSite zurück geliefert.
153 )))
154 |(((
155 secretToShare
156 )))|(((
157 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
158 )))
159 |(((
160 students
161 )))|(((
162 Liste der Studenten mit ihren Resultaten. Siehe unten.
163 )))
164 |(((
165 optionalContentPackage
166 )))|(((
167 Optional. Content Package (gezippt) als Byte-Array.
168 )))
169 |(((
170 additionalParams
171 )))|(((
172 Reserved for future use.
173 )))
174
175 === ReturnValue initiateSite ===
176
177 (% class="wrapped" %)
178 |(((
179 String
180 )))|(((
181 Absolute URL der Reporter-Seite für den IFrame. Dieser ist vom LMS durch die folgenden URL-Parameter anzureichern:
182
183 * sid: Session ID, wie von armSite zurück gegeben
184 * uid: Student ID, wie in initiateSite beim Reporter angemeldet
185 )))
186
187 {{code language="xml"}}
188 public class ResultsForStudent {
189    private String studentId = „";
190    private String firstname = „";
191    private String lastname = „";
192    private String groupname = „";
193    private String tutorname = „";
194    private File contentFile = null;
195    private byte[] resultsFile = null;
196 }
197 {{/code}}
198
199 == Abmeldung durch LMS ==
200
201 \\
202
203 {{code}}
204 @WebMethod(operationName = „disarmSite")
205 public Boolean disarmSite(
206 @WebParam(name = „version") final Integer version,
207 @WebParam(name = „sessionId") final String sessionId,
208 @WebParam(name = „secretToShare") final String secretToShare,
209 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
210 }
211 {{/code}}
212
213 \\
214
215 === Parameter disarmSite ===
216
217 (% class="wrapped" %)
218 |(((
219 version
220 )))|(((
221 Angefragte Version: 1
222 )))
223 |(% colspan="1" %)(% colspan="1" %)
224 (((
225 sessionId
226 )))|(% colspan="1" %)(% colspan="1" %)
227 (((
228 SessionId, wie von armSite zurück geliefert.
229 )))
230 |(((
231 secretToShare
232 )))|(((
233 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
234 )))
235 |(((
236 additionalParams
237 )))|(((
238 Reserved for future use.
239 )))
240
241 === ReturnValue disarmSite ===
242
243 (% class="wrapped" %)
244 |(((
245 Boolean
246 )))|(((
247 True bei Erfolg, sonst false.
248 )))
249
250 == Abfrage von Lernerresultaten durch LMS ==
251
252 {{code language="xml" title="Abfrage von Lernerresultaten durch LMS"}}
253  @WebMethod(operationName = „getResultValues")
254 public HashMapWrapper getResultValues(
255 @WebParam(name = „version") final Integer version,
256 @WebParam(name = „sessionId") final String sessionId,
257 @WebParam(name = „secretToShare") final String secretToShare,
258 @WebParam(name = „requestedValues") final HashMap<String, String>
259 requestedValues,
260 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
261 }
262 {{/code}}
263
264 === Parameter getResultValues ===
265
266 (% class="wrapped" %)
267 |(((
268 version
269 )))|(((
270 Angefragte Version: 1
271 )))
272 |(% colspan="1" %)(% colspan="1" %)
273 (((
274 sessionId
275 )))|(% colspan="1" %)(% colspan="1" %)
276 (((
277 SessionId, wie von armSite zurück geliefert.
278 )))
279 |(((
280 secretToShare
281 )))|(((
282 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
283 )))
284 |(((
285 requestedValues
286 )))|(((
287 Kann leer sein, dann werden alle Result-Variables zurück geliefert. Sind Keys enthalten, so kommen nur diese zurück.
288 )))
289 |(((
290 additionalParams
291 )))|(((
292 Reserved for future use.
293 )))
294
295 === ReturnValue getResultValues ===
296
297 (% class="wrapped" %)
298 |(((
299 HashMap<String, String>
300 )))|(((
301 Map der Result-Variables, Key ist der Variablenname, Value der jeweilige Wert (HashMap ist gewrappt)
302 )))
303
304 == Abfrage von Ergebnisvariablen durch LMS ==
305
306 {{code language="xml" title="Abfrage von Ergebnisvariablen durch LMS"}}
307  @WebMethod(operationName = „getResultVariables")
308 public HashMapWrapper getResultVariables(
309 @WebParam(name = „version") final Integer version,
310 @WebParam(name = „contentPackage") final byte[] contentPackage,
311 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
312 }
313 {{/code}}
314
315 === Parameter getResultVariables ===
316
317 (% class="wrapped" %)
318 |(((
319 version
320 )))|(((
321 Angefragte Version: 1
322 )))
323 |(((
324 contentPackage
325 )))|(((
326 Content Package (gezippt) als Byte-Array.
327 )))
328 |(((
329 additionalParams
330 )))|(((
331 Reserved for future use.
332 )))
333
334 === ReturnValue getResultVariables ===
335
336 (% class="wrapped" %)
337 |(((
338 HashMap<String, String>
339 )))|(((
340 Map der Result-Variables, Key ist der Variablenname, Value der jeweilige Wert (HashMap ist gewrappt)
341 )))
342
343 == Wrapper ==
344
345 Da die Übertragung von Maps und Listen über JAX-WS Probleme machen kann, müssen diese gewrappt werden.
346
347 === Wrapper für die HashMap<String, String> ===
348
349 HashMapWrapper.java:
350
351 [[image:attach:HashMapWrapperjava.png]]
352
353 [[image:attach:HashMapWrapperjava2.png]]
354
355 === Wrapper für die ArrayList<ResultsForStudent> ===
356
357 ResultsForStudentsWrapper.java:
358
359 [[image:attach:ResultsForStudentsWrapperjava.png]]
360 {{/layout-cell}}
361 {{/layout-section}}
362
363 {{layout-section ac:type="two_right_sidebar"}}
364 {{layout-cell}}
365 \\
366 {{/layout-cell}}
367
368 {{layout-cell}}
369 ====== relevante Links: ======
370
371 * [[doc:ONYX Player Interface]]
372 {{/layout-cell}}
373 {{/layout-section}}
374 {{/layout}}
375
376
377
378 {{layout}}
379 {{layout-section ac:type="two_equal"}}
380 {{layout-cell}}
381 ====== Content: ======
382
383
384
385 {{toc maxLevel="5" outline="true" absoluteUrl="true" style="square"/}}
386 {{/layout-cell}}
387
388 {{layout-cell}}
389
390 {{/layout-cell}}
391 {{/layout-section}}
392
393 {{layout-section ac:type="single"}}
394 {{layout-cell}}
395 == General information ==
396
397 The API to the ONYX WebReporter enables the communication between the LMS and the Reporter. Therefore, a couple of commands will be executed:
398
399 |(((
400 armSite
401 )))|(((
402 Registration of sequence requests at the ONYX Reporter
403 )))
404 |(((
405 initiateSite
406 )))|(((
407 Initiates the Reporter session (transmission of the CP).
408 )))
409 |(((
410 disarmSite
411 )))|(((
412 Release of all Reporter resources for this session.
413 )))
414 |(((
415 getResultValues
416 )))|(((
417 Returns all (requested) results for the test. Condition: There is only one student in the list transmitted with initiateSite.
418 )))
419 |(% colspan="1" %)(% colspan="1" %)
420 (((
421 getResultVariables
422 )))|(% colspan="1" %)(% colspan="1" %)
423 (((
424 Returns all (requested) outcome variables for the test. No armSite, initiateSite, or disarmSite is required.
425 )))
426
427 == Login through the LMS ==
428
429 {{code language="xml" title="Login through the LMS"}}
430 @WebMethod(operationName = „armSite")
431 public String armSite(
432 @WebParam(name = „version") final Integer version,
433 @WebParam(name = „userId") final String userId,
434 @WebParam(name = „optionalRole") final Integer role,
435 @WebParam(name = „secretToShare") final String secretToShare,
436 @WebParam(name = „optionalUserLastName") final String userLastName,
437 @WebParam(name = „optionalUserFirstName") final String userFirstName,
438 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
439 }
440 {{/code}}
441
442 === Parameter armSite ===
443
444 |(((
445 version
446 )))|(((
447 Requested version: 1
448 )))
449 |(((
450 userId
451 )))|(((
452 UserId of the requested Reporter user
453 )))
454 |(((
455 optionalRole
456 )))|(((
457 Optional. User role. 0 = student, 1 = tutor
458 )))
459 |(((
460 secretToShare
461 )))|(((
462 A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
463 )))
464 |(((
465 optionalUserLastName
466 )))|(((
467 Optional. Last name of the user.
468 )))
469 |(% colspan="1" %)(% colspan="1" %)
470 (((
471 optionalUserFirstName
472 )))|(% colspan="1" %)(% colspan="1" %)
473 (((
474 Optional. First name of the user.
475 )))
476 |(% colspan="1" %)(% colspan="1" %)
477 (((
478 additionalParams
479 )))|(% colspan="1" %)(% colspan="1" %)
480 (((
481 Reserved for future use.
482 )))
483
484 === ReturnValue armSite ===
485
486 |(((
487 String
488 )))|(((
489 Session ID which has to be used to mark any other Reporter call.
490 )))
491
492 == Initialisation through LMS ==
493
494 {{code language="xml" title="Initialisation through LMS"}}
495 @WebMethod(operationName = „initiateSite")
496 public String initiateSite(
497 @WebParam(name = „version") final Integer version,
498 @WebParam(name = „sessionId") final String sessionId,
499 @WebParam(name = „secretToShare") final String secretToShare,
500 @WebParam(name = „students") final ArrayList<ResultsForStudent> students,
501 @WebParam(name = „optionalContentPackage") final byte[] contentPackage,
502 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
503 }
504 {{/code}}
505
506 === Parameter initiateSite ===
507
508 |(((
509 version
510 )))|(((
511 Requested version: 1
512 )))
513 |(% colspan="1" %)(% colspan="1" %)
514 (((
515 sessionId
516 )))|(% colspan="1" %)(% colspan="1" %)
517 (((
518 SessionId, as returned by armSite.
519 )))
520 |(((
521 secretToShare
522 )))|(((
523 A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
524 )))
525 |(((
526 students
527 )))|(((
528 List of students and their results. See below.
529 )))
530 |(((
531 optionalContentPackage
532 )))|(((
533 Optional. Content package (zipped) as byte array.
534 )))
535 |(((
536 additionalParams
537 )))|(((
538 Reserved for future use.
539 )))
540
541 === ReturnValue initiateSite ===
542
543 |(((
544 String
545 )))|(((
546 Absolute URL of the Reporter site for the IFrame. The URL has to be amended by the LMS with the following URL parameters:
547
548 * sid: Session ID, as returned by armSite
549 * (((
550 uid: Student ID, as registrated in the initiateSite at the ONYX Reporter
551 )))
552 )))
553
554 {{code language="xml"}}
555 public class ResultsForStudent {
556    private String studentId = „";
557    private String firstname = „";
558    private String lastname = „";
559    private String groupname = „";
560    private String tutorname = „";
561    private File contentFile = null;
562    private byte[] resultsFile = null;
563 }
564 {{/code}}
565
566 == Logout through the LMS ==
567
568
569
570 {{code}}
571 @WebMethod(operationName = „disarmSite")
572 public Boolean disarmSite(
573 @WebParam(name = „version") final Integer version,
574 @WebParam(name = „sessionId") final String sessionId,
575 @WebParam(name = „secretToShare") final String secretToShare,
576 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
577 }
578 {{/code}}
579
580
581
582 === Parameter disarmSite ===
583
584 |(((
585 version
586 )))|(((
587 Requested version: 1
588 )))
589 |(% colspan="1" %)(% colspan="1" %)
590 (((
591 sessionId
592 )))|(% colspan="1" %)(% colspan="1" %)
593 (((
594 SessionId, as returned by armSite.
595 )))
596 |(((
597 secretToShare
598 )))|(((
599 A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
600 )))
601 |(((
602 additionalParams
603 )))|(((
604 Reserved for future use.
605 )))
606
607 === ReturnValue disarmSite ===
608
609 |(((
610 Boolean
611 )))|(((
612 True in the case of success, otherwise false.
613 )))
614
615 == Request of learner results through the LMS ==
616
617 {{code language="xml" title="Request of learner results through the LMS"}}
618  @WebMethod(operationName = „getResultValues")
619 public HashMapWrapper getResultValues(
620 @WebParam(name = „version") final Integer version,
621 @WebParam(name = „sessionId") final String sessionId,
622 @WebParam(name = „secretToShare") final String secretToShare,
623 @WebParam(name = „requestedValues") final HashMap<String, String>
624 requestedValues,
625 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
626 }
627 {{/code}}
628
629 === Parameter getResultValues ===
630
631 |(((
632 version
633 )))|(((
634 Requested version: 1
635 )))
636 |(% colspan="1" %)(% colspan="1" %)
637 (((
638 sessionId
639 )))|(% colspan="1" %)(% colspan="1" %)
640 (((
641 SessionId, as returned by armSite.
642 )))
643 |(((
644 secretToShare
645 )))|(((
646 A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
647 )))
648 |(((
649 requestedValues
650 )))|(((
651 Can be empty, in which case all result variables are returned. If keys are included, only the keys will be returned.
652 )))
653 |(((
654 additionalParams
655 )))|(((
656 Reserved for future use.
657 )))
658
659 === ReturnValue getResultValues ===
660
661 |(((
662 HashMap<String, String>
663 )))|(((
664 Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)
665 )))
666
667 == Request of result variables through the LMS ==
668
669 {{code language="xml" title="Request of result variables through the LMS"}}
670  @WebMethod(operationName = „getResultVariables")
671 public HashMapWrapper getResultVariables(
672 @WebParam(name = „version") final Integer version,
673 @WebParam(name = „contentPackage") final byte[] contentPackage,
674 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
675 }
676 {{/code}}
677
678 === Parameter getResultVariables ===
679
680 |(((
681 version
682 )))|(((
683 Requested version: 1
684 )))
685 |(((
686 contentPackage
687 )))|(((
688 Content package (zipped) as byte array.
689 )))
690 |(((
691 additionalParams
692 )))|(((
693 Reserved for future use.
694 )))
695
696 === ReturnValue getResultVariables ===
697
698 |(((
699 HashMap<String, String>
700 )))|(((
701 Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)
702 )))
703
704 == Wrapper ==
705
706 Since the transmission of maps and lists via JAX-WS can cause problems, they have to be wrapped.
707
708 === Wrapper for HashMap<String, String> ===
709
710 HashMapWrapper.java:
711
712 [[image:attach:HashMapWrapperjava.png]]
713
714 [[image:attach:HashMapWrapperjava2.png]]
715
716 === Wrapper for the ArrayList<ResultsForStudent> ===
717
718 ResultsForStudentsWrapper.java:
719
720 [[image:attach:ResultsForStudentsWrapperjava.png]]
721 {{/layout-cell}}
722 {{/layout-section}}
723 {{/layout}}