Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

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